> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cascadeflow.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools

> Tool calling framework — ToolConfig, ToolExecutor, and the @tool decorator for agent function calling.

# Tools

cascadeflow provides a tool calling framework for agent loops. Define tools, execute them, and track tool call budgets.

## ToolConfig

Define a tool with its schema and handler function.

```python theme={null}
from cascadeflow.tools import ToolConfig

search_tool = ToolConfig(
    name="search",
    description="Search the web for information",
    parameters={"query": {"type": "string", "description": "Search query"}},
    handler=lambda query: f"Results for: {query}",
)
```

| Field | Type | Description |
| - | - | - |
| `name` | `str` | Tool name |
| `description` | `str` | What the tool does (sent to the model) |
| `parameters` | `dict` | JSON Schema for tool parameters |
| `handler` | `Callable` | Function to execute when tool is called |

## ToolExecutor

Executes tool calls and returns results.

```python theme={null}
from cascadeflow.tools import ToolExecutor

executor = ToolExecutor(tools=[search_tool, calc_tool])

result = await agent.run(
    "Search for Python tutorials",
    tools=[search_tool, calc_tool],
    tool_executor=executor,
    max_steps=10,
)
```

## @tool Decorator

Define tools using a decorator for cleaner syntax.

```python theme={null}
from cascadeflow.tools import tool

@tool
def calculator(expression: str) -> str:
    """Evaluate a math expression."""
    return str(eval(expression))

@tool
async def web_search(query: str) -> dict:
    """Search the web."""
    return {"results": await fetch_results(query)}
```

## Tool Call Limits

Use `max_tool_calls` in `cascadeflow.run()` to cap tool usage:

```python theme={null}
with cascadeflow.run(budget=1.00, max_tool_calls=5) as session:
    result = await agent.run(
        "Research and calculate",
        tools=tools,
        tool_executor=ToolExecutor(tools=tools),
        max_steps=15,
    )
    print(f"Tool calls: {session.summary()['tool_calls']}/5")
```

When the cap is reached, cascadeflow issues a `deny_tool` action — the agent continues with what it has.

## ToolResult

Returned by `ToolExecutor.execute()`.

| Field | Type | Description |
| - | - | - |
| `tool_name` | `str` | Name of the tool that was called |
| `result` | `Any` | Return value from the handler |
| `error` | `str \| None` | Error message if execution failed |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.