SDKTool search

Tool search

Tool search is meant to keep a run’s context small when many tools are available. Instead of sending every tool’s full definition on every turn, the run sends only the names, and the agent loads a definition when it needs one. This page explains when that happens and how to keep a run lean.

The Syntic Code SDK packages are not released yet. This page describes the behaviour of the syntic command today.

When tools are deferred

When the tool list is large (many MCP servers), or when ENABLE_TOOL_SEARCH is set to true, a request carries only the core tools in full. The other tools are named in the ToolSearch tool’s description, and a tool’s full definition joins the request once the agent asks for it through ToolSearch. The agent can only load tools the run already has; a tool a deny rule refuses cannot be loaded. An MCP server set to alwaysLoad keeps its tools out of the deferral. Models that do not support tool search get the full list.

Keep the tool list short

Deferral lowers the cost of a long tool list, but a short list is still cheaper. Control it with flags:

ToUse
Remove specific tools or commands--disallowed-tools "WebFetch"
Pre-approve some tools so they do not need a question--allowed-tools "Bash(npm test:*),Read"
Use only the MCP servers you name--mcp-config servers.json --strict-mcp-config
Skip everything from settings and plugins--bare

A run that only reads code needs very few of them:

syntic -p "explain how the retry queue works" --disallowed-tools "Write,Edit,Bash,WebFetch"

Keep MCP servers lean

Each MCP server adds all of its tools to the run. Pass a server only to the runs that need it, and prefer a server with a few focused tools over one with dozens. A server’s instructions are added to the system prompt as well, so a long set of instructions costs tokens on every turn. See MCP for programs.

  • Custom tools covers how to add a tool through an MCP server.
  • Context window explains what fills the context and how to measure it.