Tools

Tools give agents the ability to interact with the world — call APIs, run code, query databases, search the web, and more. The model decides which tools to call and in what order.

How tools work

1. You register tools with the agent
2. The SDK sends their schemas (name, description, parameters) to the model
3. The model requests a tool call with specific arguments
4. The SDK executes the tool and sends the result back to the model
5. The model continues reasoning with the new information

Tool types

Type	How to use
Python functions	Decorate with @tool
MCP servers	Connect via MCPClient
Directory tools	Auto-load from ./tools/
Pre-built tools	Install elsai-agents-tools
Agent as tool	Call agent.as_tool()

Python function tools

from elsai import Agent, tool

@tool
def search_database(query: str, limit: int = 10) -> list[dict]:
    """Search the product database for matching items.

    Args:
        query: The search query string.
        limit: Maximum number of results to return.

    Returns:
        A list of matching product dictionaries.
    """
    # Your implementation here
    return [{"name": f"Result for '{query}'", "id": i} for i in range(limit)]

agent = Agent(tools=[search_database])

Pre-built tools

from elsai_tools import calculator, current_time, python_repl

agent = Agent(tools=[calculator, current_time, python_repl])
agent("What time is it? And what's 15% of 847?")

MCP server tools

from elsai import Agent
from elsai.tools.mcp import MCPClient
from mcp import stdio_client, StdioServerParameters

client = MCPClient(
    lambda: stdio_client(StdioServerParameters(
        command="uvx",
        args=["mcp-server-fetch"]
    ))
)

with client:
    agent = Agent(tools=client.list_tools_sync())
    agent("Fetch the content from https://example.com")

Directory hot-reload

Place tool files in ./tools/ and they load automatically:

agent = Agent(load_tools_from_directory=True)
# Tools in ./tools/*.py are loaded and reloaded on change

Registering multiple tool types together

from elsai import Agent, tool
from elsai_tools import calculator
from elsai.tools.mcp import MCPClient

@tool
def my_custom_tool(x: str) -> str:
    """My custom tool.

    Args:
        x: Input string.
    """
    return x.upper()

agent = Agent(tools=[
    my_custom_tool,    # decorated function
    calculator,        # pre-built tool
    # mcp_client.list_tools_sync()  # spread MCP tools
])

Listing available tools

print(agent.tool_names)
# ['my_custom_tool', 'calculator', ...]

Calling tools directly

You can invoke tools directly without going through the LLM:

result = agent.tool.calculator(expression="2 + 2")
print(result)  # 4

Related

• Function Tools — detailed guide to building tools
• MCP Tools — connecting MCP servers