Skip to main content

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.

Tool Search enables progressive disclosure of tools when agents have many MCP or plugin tools, reducing context overhead and improving performance.

​
Quick Start

1

Simple Usage

Enable Tool Search with auto mode to activate progressive disclosure when needed:
from praisonaiagents import Agent

agent = Agent(
    name="MCP Agent",
    instructions="You can search Slack, Google Drive, and GitHub",
    tool_search=True  # Auto mode - activates when tool schemas exceed threshold
)

agent.start("Find the design review thread on Slack")
2

With Configuration

Use ToolSearchConfig for fine-grained control:
from praisonaiagents import Agent, ToolSearchConfig

agent = Agent(
    name="Heavy MCP Agent", 
    instructions="You have access to many enterprise tools",
    tool_search=ToolSearchConfig(
        enabled="auto",
        threshold_pct=15.0,  # Activate when tools use >15% of context
        search_default_limit=8,
        max_search_limit=25
    )
)

agent.start("Search for quarterly reports in our systems")

​
How It Works

When bridge mode activates, the model sees three lightweight tools instead of potentially hundreds of MCP tool schemas:
Bridge ToolPurpose
tool_search(query, limit)BM25 search over deferred tool names and descriptions
tool_describe(tool_name)Returns full OpenAI function schema for the named tool
tool_call(tool_name, tool_args)Executes the real tool with unwrapping for traces/hooks

​
When to Use It

Use Tool Search when:
  • Your agent connects to 10+ MCP servers
  • You have 50+ tools from plugins/integrations
  • Context window usage is a concern
  • LLM responses are slow due to large tool schemas
Skip Tool Search when:
  • You have fewer than 10 tools total
  • All tools are frequently used core operations
  • Tool discovery latency is critical

​
Configuration Options

OptionTypeDefaultDescription
enabledUnion[bool, str]"auto"Mode: "auto", "on", "off", True, False. Auto only activates when deferrable schema tokens cross threshold.
threshold_pctfloat10.0Percentage of model context window that deferrable schemas must occupy before auto mode kicks in.
search_default_limitint5Default number of results returned by tool_search.
max_search_limitint20Upper cap on results per tool_search call.
core_toolsOptional[FrozenSet[str]]NoneOverride the default set of tools that never defer.

​
Precedence Ladder

Tool Search supports multiple configuration levels: 
# Level 1: Bool (simplest)
Agent(tool_search=True)              # auto mode
Agent(tool_search=False)             # disabled (default)

# Level 2: String shorthand
Agent(tool_search="auto")            # explicit auto
Agent(tool_search="on")              # always bridge
Agent(tool_search="off")             # disabled

# Level 3: Dict
Agent(tool_search={"enabled": "auto", "threshold_pct": 15})

# Level 4: Config class (full control)
from praisonaiagents import Agent, ToolSearchConfig
Agent(tool_search=ToolSearchConfig(
    enabled="auto",
    threshold_pct=10,
    search_default_limit=5,
    max_search_limit=20,
))

​
Core vs Deferrable Tools

​
Core Tools (Never Defer)

These 16 essential tools always remain visible:
CategoryTools
File operationsread_file, write_file, list_files, get_file_info, copy_file, move_file, delete_file
Shell operationsexecute_command, list_processes, kill_process, get_system_info
Web operationssearch_web, web_search, internet_search, web_crawl, crawl_web
Schedulingschedule_add, schedule_list, schedule_remove
Memorystore_memory, search_memory
Clarifyclarify

​
Deferrable Tools

  • MCP tools: Automatically marked with __praisonai_deferrable__ = True
  • Custom tools: Add deferrable: True to function metadata
  • MCP-prefixed: Tools starting with mcp_

​
Common Patterns

​
MCP-Heavy Agent

For agents with many MCP servers: 
from praisonaiagents import Agent

agent = Agent(
    name="Enterprise Agent",
    instructions="Access Slack, Jira, GitHub, Google Drive, and Salesforce",
    tool_search=True,  # Auto mode handles the complexity
    tools=[slack_mcp, jira_mcp, github_mcp, gdrive_mcp, salesforce_mcp]
)

​
Force-On for Testing

Always use bridge mode for testing or high-tool-count scenarios: 
agent = Agent(
    name="Test Agent",
    instructions="Testing tool search with all MCP tools",
    tool_search="on"  # Always bridge, regardless of count
)

​
Custom Threshold

Adjust when bridge mode activates: 
from praisonaiagents import Agent, ToolSearchConfig

agent = Agent(
    name="Conservative Agent", 
    instructions="More aggressive tool deferral",
    tool_search=ToolSearchConfig(
        enabled="auto",
        threshold_pct=5.0,  # Activate with less tool overhead
        search_default_limit=3  # Fewer search results
    )
)

​
Best Practices

The default 10% threshold works well for most scenarios. Lower it to 5-7% for aggressive context saving, or raise it to 15-20% if you prefer fewer bridge interactions. Monitor your context usage and adjust based on your model’s window size.
More capable models (GPT-4, Claude-3.5-Sonnet) write better tool search queries. They understand semantic relationships and can find tools by functionality rather than just name matching. Smaller models may need more explicit tool naming or descriptions.
Don’t use Tool Search for agents with fewer than 10 tools, or when all tools are frequently used core operations. The 1-2 extra round trips for cold tool access aren’t worth it for small, stable toolsets.

​
Trade-offs

Benefits:
  • Reduces context window usage by 60-80% for tool-heavy agents
  • Improves LLM response speed with fewer schemas to process
  • Scales to hundreds of MCP tools without context bloat
  • Auto mode provides zero overhead when not needed
Costs:
  • Cold tool access requires 1-2 extra round trips (search → describe → call)
  • tool_describe results enter conversation history, growing context
  • Bridge mode invalidates existing tool schemas between sessions
  • Smaller models may write less effective search queries

MCP Integration

Connect to Model Context Protocol servers

Allowed Tools

Filter and control tool availability