> ## Documentation Index
> Fetch the complete documentation index at: https://agno-v2-docs-scavio-google-v2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# What are Tools?
> Give agents functions they can call to read data and take actions in external systems.
Agents use tools to take actions, like looking up records, calling APIs, updating systems, and completing work for users. Add a Python function or toolkit to `tools`, and the model can select it when a request requires it.
```python order_agent.py theme={null}
from agno.agent import Agent
from agno.models.openai import OpenAIResponses
def lookup_order(order_id: str) -> dict:
"""Return the status and delivery date for an order.
Args:
order_id: The order ID to look up.
"""
return {
"order_id": order_id,
"status": "shipped",
"delivery_date": "2026-07-22",
}
agent = Agent(
model=OpenAIResponses(id="gpt-5.4-mini"),
tools=[lookup_order],
instructions="Use the order tool when a customer asks about a delivery.",
)
agent.print_response("When will order ORD-123 arrive?")
```
Agno builds a tool definition from the function name, docstring, and type hints. The model receives that definition, chooses the tool and arguments, then uses the result to produce its response.
## Choose a Tool Source
| Use case | Tool source |
| -------------------------------------------------------------- | -------------------------------------------------------------- |
| Call application code or an internal API | [Python function](/tools/creating-tools/python-functions) |
| Add a packaged integration with related operations | [Toolkit](/tools/toolkits/overview) |
| Connect to a service exposed through Model Context Protocol | [MCPTools](/tools/mcp/overview) |
| Give an agent a compact interface to a complex external system | [Context Provider](/context-providers/overview) |
| Select tools for each user or session at run time | [Callable factory](/agents/building-agents#callable-factories) |
## Tool Execution
The execution flow:
1. The agent sends the model its context and available tool definitions.
2. The model returns a response or requests one or more tool calls.
3. Agno validates the arguments and executes each requested tool.
4. Tool results are added to the model context.
5. The loop continues until the model returns a final response.
When a model requests multiple tool calls, `arun()` and `aprint_response()` can execute them concurrently. The selected model must support parallel tool calls.
## Design Tools for Reliable Calls
The model uses the tool schema to decide when and how to call a function.
| Practice | Why it matters |
| ----------------------------------------- | ----------------------------------------------- |
| Use a specific function name | Helps the model select the correct operation |
| Write a concise docstring | Explains when the tool should be used |
| Add type hints and argument descriptions | Produces a precise input schema |
| Expose only the tools needed for the task | Reduces ambiguous choices and limits access |
| Return structured, relevant results | Gives the model useful context for its response |
Use `include_tools` and `exclude_tools` to limit operations exposed by a toolkit. See [Including and Excluding Tools](/tools/selecting-tools).
## Control Tool Execution
| Requirement | Configuration |
| ---------------------------------------- | -------------------------------------------------------------------------- |
| Limit calls during one run | Set [`tool_call_limit`](/tools/tool-call-limit) |
| Review a sensitive action | Mark the tool with [`requires_confirmation=True`](/hitl/user-confirmation) |
| Collect missing fields from a user | Use [`requires_user_input=True`](/hitl/user-input) |
| Execute an operation in your application | Use [`external_execution=True`](/hitl/external-execution) |
| Handle failures from custom tools | Configure [tool exceptions](/tools/exceptions) |
Runs with human-in-the-loop requirements pause until your application resolves the active requirement and continues the run.
## Tool Built-in Parameters
Agno strips built-in parameters from the schema sent to the model and injects them when the tool runs.
| Parameter | Use |
| ------------------------------------- | ------------------------------------------------------------------------------------- |
| `run_context` | Access the current user, session state, dependencies, metadata, and knowledge filters |
| `agent` | Access the active Agent from an agent tool |
| `team` | Access the active Team from a team tool |
| `images`, `videos`, `audios`, `files` | Access media attached to the run |
### Access Run Context
Add a `run_context: RunContext` parameter when a tool needs the current user, session state, dependencies, metadata, or knowledge filters. Agno injects the value at execution time and omits it from the schema sent to the model.
```python theme={null}
from agno.run import RunContext
def add_item(run_context: RunContext, item: str) -> str:
"""Add an item to the current session's shopping list."""
if run_context.session_state is None:
run_context.session_state = {}
shopping_list = run_context.session_state.setdefault("shopping_list", [])
shopping_list.append(item)
return f"Shopping list: {shopping_list}"
```
See the [RunContext reference](/reference/run/run-context) and [State Management](/state/overview).
## Return Tool Results
Functions can return strings, numbers, dictionaries, lists, and other serializable values. Use `ToolResult` when a tool needs to return media or files alongside text.
## Next Steps
Add functions and toolkits to an agent.
Browse integrations by data source and operation.
Build Python functions and reusable toolkits.
Connect agents to Model Context Protocol servers.
Add or replace tools after initialization.
Run logic before and after tool calls.