Skip to content

Recipe: Custom Tools with @tool

Goal

Expose Python functions as tools and let the model call them.

Example

from doc_processing_toolkit import Agent, tool

@tool
def add(a: int, b: int) -> int:
    return a + b

agent = Agent(
    model="gpt-4o",
    instructions="Use tools for arithmetic.",
    tools=[add],
    max_iterations=5,
)

result = await agent.run("Add 5 and 3 together")
print(result.output)
print(result.tools_used)

All supported tool input types

tools=[
    add,  # 1) @tool function
    "tools/my_tools.py",  # 2) file path
    "tools/",  # 3) directory path
    fastmcp_server,  # 4) FastMCP server object
    {"type": "mcp_script", "path": "tests/fixtures/sample_mcp_server.py", "name": "script-server"},  # 5)
    {"type": "mcp_command", "command": "python", "args": ["-m", "tests.fixtures.sample_mcp_server"], "name": "command-server"},  # 6)
    {"type": "mcp", "server_label": "deepwiki", "server_url": "https://mcp.deepwiki.com/mcp"},  # 7) provider connects
    {"session": existing_mcp_session, "name": "prebuilt-session"},  # 8)
    {"type": "mcp_remote_client", "url": "https://mcp.deepwiki.com/mcp", "name": "deepwiki"},  # 9) dpt connects
]

Formats 7 and 9 both point at a remote server: 7 hands it to the provider's connector, 9 opens the session from this process so the tools run client-side on any provider. See Tools.

What to validate

  • "add" appears in result.tools_used
  • response contains expected arithmetic result
  • tool metadata exists on decorated function (_tool_metadata)

Notes

  • Prefer explicit type hints for all tool params.
  • Provide concise docstrings so parameter descriptions propagate to tool schema.

Test sources

  • tests/e2e/test_agent_e2e.py (test_tool_calling_with_decorated_function)
  • tests/e2e/test_tool_formats.py (test_format_1_plain_function)