Per-Tool Token Budgets

Configure token limits per tool for fine-grained output control

from praisonaiagents import Agent

agent = Agent(
    name="budgeted-agent",
    instructions="Use tools without flooding context.",
)
agent.start("Search the web and keep only the most relevant snippets.")

Per-tool budgets cap how much of each tool’s output enters agent context — noisy tools get tighter limits, critical tools stay protected.

The user caps noisy tool output; per-tool budgets truncate oversized results before they fill the context window.

How It Works

Quick Start

1. Enable context on the agent

   from praisonaiagents import Agent, ManagerConfig
   
   agent = Agent(
       name="researcher",
       instructions="Research topics efficiently",
       context=ManagerConfig(default_tool_output_max=10000),
   )
   
2. Set per-tool budgets

   agent.context_manager.set_tool_budget("web_search", max_tokens=2000)
   agent.context_manager.set_tool_budget("file_read", max_tokens=5000, protected=True)
   agent.context_manager.set_tool_budget("code_execute", max_tokens=10000)
   
   agent.start("Summarise the latest WebAssembly news")
   
3. Truncate output manually

   truncated = agent.context_manager.truncate_tool_output(
       "file_read", large_file_content
   )
   # Appends "...[output truncated]..." when over budget
   

How It Works

Each tool call checks get_tool_budget(tool_name) — falling back to default_tool_output_max when no per-tool rule exists. Protected tools skip pruning during context optimisation.

Configuration

Via ManagerConfig

from praisonaiagents import Agent, ManagerConfig

agent = Agent(
    name="researcher",
    context=ManagerConfig(
        default_tool_output_max=10000,
        protected_tools=["file_read"],
    ),
)
agent.context_manager.set_tool_budget("web_search", max_tokens=2000)

Via environment

export PRAISONAI_CONTEXT_TOOL_OUTPUT_MAX=10000

Methods

Method	Purpose
set_tool_budget(name, max_tokens, protected=False)	Set limit for one tool
get_tool_budget(name)	Read limit (falls back to default)
truncate_tool_output(name, output)	Truncate to the tool’s budget

Truncated outputs are persisted to disk so the agent can retrieve them — see Tool Output Store.

CLI Usage

praisonai chat
> /context config

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

Best Practices

Set lower limits for verbose tools

Web search and file reads return large payloads — cap them at 2,000–5,000 tokens so they do not crowd out conversation history.

Give code execution higher limits

Code tools often need full stack traces or build logs — 10,000+ tokens prevents losing error context mid-debug.

Mark critical tools as protected

protected=True keeps a tool’s output from being pruned during context optimisation, even when the window is tight.

Monitor usage via the ledger

Run /context in chat or call get_stats() on the context manager to see which tools consume the most tokens.

Related

Context Manager

Unified facade for budgeting, compaction, and monitoring.

Tool Output Store

Retrieve full outputs after truncation.