> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Add Tools to Recipes
> Step-by-step guide to adding and configuring tools in recipes
Register built-in or custom tools on recipe agents so templates can act on real data.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, tool
@tool
def lookup_order(order_id: str) -> str:
"""Look up order status."""
return f"Order {order_id} is shipped."
agent = Agent(name="Support", tools=[lookup_order])
agent.start("Check order 12345.")
```
The user adds tools to YAML or Python templates, then runs the recipe with those capabilities enabled.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
subgraph "Add Tools"
U[📋 Tool Config] --> A[🔧 Recipe Agent]
A --> O[✅ Action Taken]
end
classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
classDef output fill:#10B981,stroke:#7C90A0,color:#fff
class U input
class A process
class O output
```
## How It Works
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
participant User
participant Recipe
participant Tool
User->>Recipe: Run with tools listed in agents.yaml
Recipe->>Tool: Resolve and call the tool
Tool-->>Recipe: Result
Recipe-->>User: Answer using the tool output
```
***
## How to Add Built-in Tools
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai tools list
```
```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# agents.yaml
framework: praisonai
topic: "{{task}}"
roles:
researcher:
role: Research Agent
goal: Research topics thoroughly
tools:
- internet_search
- shell_tool
- file_read_tool
tasks:
search_task:
description: "Search for {{topic}}"
```
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai recipe run ./my-recipe --var topic="AI agents"
```
## How to Add Custom Tools via tools.py
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# tools.py
def my_custom_tool(query: str) -> str:
"""Custom tool that processes a query.
Args:
query: The input query to process
Returns:
Processed result as string
"""
return f"Processed: {query}"
def another_tool(data: str) -> dict:
"""Another custom tool.
Args:
data: Input data
Returns:
Dictionary with results
"""
return {"result": data, "status": "success"}
```
```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
roles:
processor:
role: Data Processor
tools:
- my_custom_tool
- another_tool
tasks:
process_task:
description: "Process the data"
```
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai recipe run ./my-recipe
```
## Tool Resolution Order
| Priority | Source | Description |
| -------- | ---------- | ------------------------------ |
| 1 | `tools.py` | Recipe-local tools.py |
| 2 | Built-in | praisonaiagents built-in tools |
| 3 | Package | `praisonai_tools` package |
## Best Practices
`tools.py` in the recipe directory wins resolution, so bundle recipe-specific tools there to keep them portable.
The agent reads the docstring to decide when and how to call a tool. Describe the arguments and return value so calls are accurate.
Give each role the minimum tool set in `agents.yaml` so the agent stays focused and avoids unintended actions.
***
## Related
Build a recipe from scratch
Troubleshoot tool resolution