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

# Per-Tool Token Budgets

> Configure token limits per tool for fine-grained output control

Per-tool budgets allow setting different token limits for each tool, enabling fine-grained control over tool output sizes.

## Quick Start

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import ContextManager

manager = ContextManager(model="gpt-4o-mini")

# Set per-tool budgets
manager.set_tool_budget("file_read", max_tokens=5000, protected=True)
manager.set_tool_budget("web_search", max_tokens=2000)
manager.set_tool_budget("code_execute", max_tokens=10000)

# Truncate output according to budget
output = manager.truncate_tool_output("file_read", large_file_content)
```

## Architecture

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    A[Tool Output] --> B{Per-Tool Budget?}
    B -->|Yes| C[Tool-Specific Limit]
    B -->|No| D[Default Limit]
    C --> E[Truncate if Over]
    D --> E
    E --> F[Truncated Output]
    F --> G[Add to Context]
```

## Configuration

### Via ManagerConfig

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import ManagerConfig, PerToolBudget

config = ManagerConfig(
    default_tool_output_max=10000,  # Default for all tools
    tool_budgets={
        "file_read": PerToolBudget(
            tool_name="file_read",
            max_output_tokens=5000,
            protected=True,
        ),
        "web_search": PerToolBudget(
            tool_name="web_search",
            max_output_tokens=2000,
            protected=False,
        ),
    },
    protected_tools=["file_read"],  # Won't be pruned
)
```

### Via Environment

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
export PRAISONAI_CONTEXT_TOOL_OUTPUT_MAX=10000
```

## PerToolBudget

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
@dataclass
class PerToolBudget:
    tool_name: str           # Tool identifier
    max_output_tokens: int   # Token limit for output
    protected: bool          # If True, won't be pruned
```

## Methods

### set\_tool\_budget()

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
manager.set_tool_budget(
    tool_name="file_read",
    max_tokens=5000,
    protected=True,  # Won't be pruned during optimization
)
```

### get\_tool\_budget()

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
budget = manager.get_tool_budget("file_read")  # 5000
budget = manager.get_tool_budget("unknown")    # default_tool_output_max
```

### truncate\_tool\_output()

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Automatically truncates to tool's budget
truncated = manager.truncate_tool_output("file_read", large_output)

# Adds truncation marker
# "...[output truncated]..."
```

## Protected Tools

Protected tools are not pruned during optimization:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Set as protected
manager.set_tool_budget("critical_tool", max_tokens=5000, protected=True)

# Or via config
config = ManagerConfig(
    protected_tools=["critical_tool", "another_tool"],
)
```

## Integration with Composer

The composer uses per-tool budgets during context composition:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import ContextComposer

composer = ContextComposer(
    budget=budget_allocation,
    tool_budgets={
        "file_read": 5000,
        "web_search": 2000,
    },
)

result = composer.compose(
    system_prompt=system,
    history=messages,
    tools=tool_schemas,
)
```

## Tool Output Pipeline

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TD
    A[Tool Execution] --> B[Raw Output]
    B --> C{Check Tool Budget}
    C --> D[Get Per-Tool Limit]
    D --> E{Over Limit?}
    E -->|Yes| F[Truncate]
    E -->|No| G[Keep Full]
    F --> H[Add Truncation Marker]
    H --> I[Track in Ledger]
    G --> I
    I --> J[Add to History]
```

## CLI Usage

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# View tool budgets in config
praisonai chat
> /context config

# Shows:
# Budget:
#   default_tool_max:       10,000
#   tool_budgets:
#     file_read: 5,000 (protected)
#     web_search: 2,000
```

## Best Practices

1. **Set lower limits for verbose tools** - Web search, file reads
2. **Higher limits for code execution** - Need full output
3. **Protect critical tools** - Don't prune important outputs
4. **Monitor tool output usage** - Check ledger stats