Research tool search support: Claude tool search tool and other harnesses

pti commented

2026-10-08 10:31:36 +02:00

Owner

Research Claude's tool search tool and decide whether wraptool should do anything to support it, and how well other harnesses handle it.

Why it matters for wraptool

wraptool registers one MCP tool per allowed subcommand, so a well-stocked policy produces a long tool list. A claude in the sbx test connected to 48 tools. Every tool definition a harness loads up front costs context. With tool search, the model sees a search tool and loads definitions on demand. Claude Code already does this for MCP tools: in a recent session, wraptool's tools showed up as deferred and were loaded through its ToolSearch before first use.

Questions

What exactly is offered: the tool search tool on the Claude API and how tools are marked for deferred loading, including for MCP servers. Separately, how Claude Code decides what to defer, and whether a server can influence it.
What wraptool controls: do tool names and descriptions need to be written so a search finds them? They are generated from introspection today (introspect, design/introspect/tool-descriptions-from-help.md). Does wraptool_discover overlap with tool search or complement it?
Hot reload: policy changes emit notifications/tools/list_changed. Does a deferred-tool index pick that up, or does a newly approved capability stay invisible until the session restarts?
Other harnesses: for each harness in internal/harness (opencode, pi, agy, omp), does it support deferred or searched tool loading, and if not, how does it cope with a long tool list? Find any limits on tool count or definition size.
Outcome: documentation only, a change to how tools are named or described, or a server-side option, for example registering fewer tools up front.

Done when

A short design note under design/ with the findings per harness and a recommendation, plus follow-up issues for any implementation work.

🤖 Generated with Claude Code

Research Claude's **tool search tool** and decide whether wraptool should do anything to support it, and how well other harnesses handle it. ## Why it matters for wraptool wraptool registers one MCP tool per allowed subcommand, so a well-stocked policy produces a long tool list. A `claude` in the sbx test connected to 48 tools. Every tool definition a harness loads up front costs context. With tool search, the model sees a search tool and loads definitions on demand. Claude Code already does this for MCP tools: in a recent session, wraptool's tools showed up as deferred and were loaded through its `ToolSearch` before first use. ## Questions - **What exactly is offered:** the tool search tool on the Claude API and how tools are marked for deferred loading, including for MCP servers. Separately, how Claude Code decides what to defer, and whether a server can influence it. - **What wraptool controls:** do tool names and descriptions need to be written so a search finds them? They are generated from introspection today (`introspect`, `design/introspect/tool-descriptions-from-help.md`). Does `wraptool_discover` overlap with tool search or complement it? - **Hot reload:** policy changes emit `notifications/tools/list_changed`. Does a deferred-tool index pick that up, or does a newly approved capability stay invisible until the session restarts? - **Other harnesses:** for each harness in `internal/harness` (opencode, pi, agy, omp), does it support deferred or searched tool loading, and if not, how does it cope with a long tool list? Find any limits on tool count or definition size. - **Outcome:** documentation only, a change to how tools are named or described, or a server-side option, for example registering fewer tools up front. ## Done when A short design note under `design/` with the findings per harness and a recommendation, plus follow-up issues for any implementation work. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

pti commented

2026-10-08 10:50:13 +02:00

Author

Owner

Hot reload finding from a Claude Code session on 2026-10-08. Four capability approvals, each followed by a policy reload. The first three, fj issue create, then issue search, view and edit, showed up in Claude Code as new deferred tools without a reconnect. The fourth, fj issue comment, did not: the server registered the tool, wraptool_discover listed it and a direct MCP tools/list returned it, but Claude Code never saw the change. So list_changed handling works in Claude Code but not reliably. Next step: find out whether the notification was not sent, not delivered, or not acted on, starting with the server log around that reload.

pti referenced this issue

2026-10-08 10:53:06 +02:00

bug: tools/list_changed after a policy reload sometimes never reaches Claude Code #53

Rows
Columns

Research tool search support: Claude tool search tool and other harnesses #50

Why it matters for wraptool

Questions

Done when