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.

Default model is Amazon Bedrock

Agent() with no model= uses Amazon Bedrock (Claude Sonnet 4.6 in us-west-2). Configure AWS credentials or pass model= — see Installation.

Copy-paste kit

pip install --extra-index-url https://elsai-agents.elsai.ai/root/ elsai-agents==0.3.1
pip install --extra-index-url https://core-packages.elsai.ai/root/ "elsai-model[bedrock]==2.1.0"

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.
    """
    return [{"name": f"Result for '{query}'", "id": i} for i in range(limit)]

agent = Agent(tools=[search_database])
result = agent("Find items matching 'red sneakers'")
print(result)

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
Prebuilt tools	Install elsai-agents-tools and register ready-made tools
MCP servers	Connect via MCPClient
Directory tools	Auto-load from ./tools/
Agent as tool	Call agent.as_tool()

Python function tools

Same pattern as the kit above — decorate a function and pass it to Agent(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.
    """
    return [{"name": f"Result for '{query}'", "id": i} for i in range(limit)]

agent = Agent(tools=[search_database])
result = agent("Find items matching 'red sneakers'")
print(result)

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())
    result = agent("Fetch the content from https://example.com")
    print(result)

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.mcp import MCPClient

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

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

@tool
def add(a: float, b: float) -> float:
    """Add two numbers."""
    return a + b

agent = Agent(tools=[
    my_custom_tool,
    add,
    # mcp_client.list_tools_sync()  # spread MCP tools
])

Listing available tools

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

Calling tools directly

You can invoke tools directly without going through the LLM:

result = agent.tool.add(a=2, b=2)
print(result)  # 4

Prebuilt tools package

For ready-made tools — file I/O, shell, web search, AWS, multi-agent orchestration, and more — install the optional elsai-agents-tools package:

pip install --extra-index-url https://elsai-agents.elsai.ai/root/ elsai-agents-tools==0.3.0

See Prebuilt Tools for the full tool list, optional extras, and usage examples.

Related

• Prebuilt Tools — ready-made tools package
• Function Tools — detailed guide to building tools
• MCP Tools — connecting MCP servers