Skip to main content
The @tool decorator converts Python functions into tools that agents can use. It automatically generates JSON schemas from type hints and docstrings.

​
Basic Usage

from agno.tools import tool

@tool
def get_weather(city: str) -> str:
    """Get the weather for a city.
    
    Args:
        city: The name of the city
    """
    return f"Weather in {city}: Sunny"

​
Parameters

​
name
str
default:"None"
Custom name for the tool (uses function name if not provided).
​
description
str
default:"None"
Description of what the tool does (extracted from docstring if not provided).
​
instructions
str
default:"None"
Additional instructions for using the tool.
​
show_result
bool
default:"False"
If True, shows the tool result to the user.
​
stop_after_tool_call
bool
default:"False"
If True, stops the agent after this tool executes.
​
requires_confirmation
bool
default:"False"
If True, requires user confirmation before execution.
​
external_execution
bool
default:"False"
If True, the tool will be executed outside the agent’s control.
​
cache_results
bool
default:"False"
Enable result caching.
​
cache_ttl
int
default:"3600"
Cache time-to-live in seconds.

​
Schema Generation

The decorator automatically generates JSON schemas from:
  1. Type hints: Function parameter and return types
  2. Docstrings: Parameter descriptions using Google, NumPy, or Sphinx style
  3. Default values: Optional parameters vs required
@tool
def search_web(query: str, max_results: int = 10) -> str:
    """Search the web for information.
    
    Args:
        query: The search query
        max_results: Maximum number of results to return
    """
    # Implementation
    return "Search results"

​
Agent Context Injection

Tools can access the agent, team, or run context: 
@tool
def search_memory(query: str, agent: Agent) -> str:
    """Search the agent's memory.
    
    Args:
        query: Search query
        agent: The agent instance (injected automatically)
    """
    memories = agent.get_user_memories()
    # Search through memories
    return "Memory results"
Available context parameters:
  • agent: The Agent instance
  • team: The Team instance
  • run_context: The RunContext with session state
  • images, videos, audios, files: Media from the message

​
Hooks

def log_call(fc):
    print(f"Calling: {fc.function.name}")

@tool(pre_hook=log_call)
def my_tool(arg: str) -> str:
    return arg.upper()

​
HITL (Human-in-the-Loop)

@tool(requires_confirmation=True, show_result=True)
def delete_file(path: str) -> str:
    """Delete a file from disk.
    
    Args:
        path: Path to the file to delete
    """
    os.remove(path)
    return f"Deleted {path}"

​
Async Tools

@tool
async def fetch_data(url: str) -> str:
    """Fetch data from a URL.
    
    Args:
        url: The URL to fetch
    """
    async with aiohttp.ClientSession() as session:
        async with session.get(url) as resp:
            return await resp.text()

​
Example Usage

from agno import Agent
from agno.tools import tool

@tool
def calculate(expression: str) -> str:
    """Evaluate a mathematical expression.
    
    Args:
        expression: The expression to evaluate (e.g., "2+2")
    """
    result = eval(expression)
    return str(result)

agent = Agent(model="gpt-4o", tools=[calculate])
response = agent.run("What's 15 * 23?")

​
Best Practices

  1. Type hints: Always provide type hints for parameters and return values
  2. Docstrings: Write clear docstrings with parameter descriptions
  3. Descriptive names: Use clear, descriptive function names
  4. Error handling: Handle errors gracefully and return informative messages
  5. Side effects: Use confirmation for tools with side effects
  6. Context: Leverage agent/team context when needed
  7. Async: Use async for I/O-bound operations

Build docs developers (and LLMs) love

Get started for freeTalk to us