Tools API

The Tools API covers SDK primitives for defining, registering, and executing agent tools: @tool, MCPClient, tool executors, and ToolProvider.

For the separate elsai-agents-tools package (file I/O, shell, web search, AWS, multi-agent, and more), see the dedicated Prebuilt Tools API.

---

@tool

from elsai import tool

@tool
def function_name(param: type) -> return_type:
    """Tool description.

    Args:
        param: Parameter description.
    """
    ...

Decorator that converts a Python function into an agent tool.

• Name: taken from the function name
• Description: taken from the first line of the docstring
• Parameters: derived from type hints and Args docstring section
• Supports sync and async functions
• Supports optional parameters with default values
• Injects agent parameter automatically if present in the signature

---

MCPClient

from elsai.tools.mcp import MCPClient

Connects to an MCP server and exposes its tools to an agent.

MCPClient.__init__

MCPClient(client_factory)

Parameter	Type	Description
client_factory	Callable	A zero-argument lambda that returns an MCP client context manager

MCPClient.list_tools_sync

tools = client.list_tools_sync()  # list[AgentTool]

Synchronously list all tools from the MCP server.

MCPClient.list_tools

tools = await client.list_tools()  # list[AgentTool]

Async version of list_tools_sync.

Context manager

# Sync context manager
with MCPClient(factory) as client:
    tools = client.list_tools_sync()

# Async context manager
async with MCPClient(factory) as client:
    tools = await client.list_tools()

---

ToolRegistry

Internal API

ToolRegistry is an internal implementation module (elsai.tools.registry). Prefer agent.tool_registry at runtime rather than importing it directly in application code.

# Internal — accessed via agent.tool_registry, not typically imported directly
from elsai.tools.registry import ToolRegistry

Internal registry that manages all tools registered to an agent. Accessed via agent.tool_registry.

# Get all registered tools
tools = agent.tool_registry.get_all_tools_config()

# Clean up (closes MCP connections etc.)
agent.tool_registry.cleanup()

---

Tool executors

from elsai.tools.executors import ConcurrentToolExecutor, SequentialToolExecutor

ConcurrentToolExecutor (default)

Executes multiple tool calls from the same model response concurrently using asyncio.

from elsai.agent import AgentConfig

agent = Agent(config=AgentConfig(tool_executor=ConcurrentToolExecutor()))

SequentialToolExecutor

Executes tool calls one at a time in order.

agent = Agent(config=AgentConfig(tool_executor=SequentialToolExecutor()))

---

Direct tool invocation

Call tools directly (bypasses LLM):

result = agent.tool.tool_name(param1="value", param2=42)

The agent.tool property returns a _ToolCaller that dispatches to registered tools by name.

---

ToolProvider

Implement ToolProvider to create managed tool collections:

from elsai.tools import AgentTool, ToolProvider

class MyToolProvider(ToolProvider):
    def get_tools(self) -> list[AgentTool]:
        return [my_tool_1, my_tool_2]

    def cleanup(self) -> None:
        pass  # Release any resources

agent = Agent(tools=[MyToolProvider()])