Search sandboxed tool outputs with BM25 to retrieve matching IDs, snippets, and byte sizes by query, optionally filtered by tool, session, or project.
BM25 search across sandboxed tool outputs. Returns id, snippet, bytes.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max rows (default 20). | |
| query | Yes | FTS5 query (terms ANDed by default). | |
| tool_name | No | Restrict to a single source tool. | |
| session_id | No | ||
| project_root | No |
Changes observed during successful MCP inspections.
v4.0.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the retrieval mechanism (BM25) and the result fields (id, snippet, bytes), which is useful behavioral context, but says nothing about ranking behavior, pagination, or what tokens the FTS5 query accepts.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the mechanism and scope, and the return fields are stated compactly. Nothing is padded, though it is arguably terse to the point of leaving gaps rather than being efficiently complete.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description does useful work by naming the return fields. However, for a 5-parameter tool it omits how the capture store is populated, how session_id/project_root scope results, and how it relates to its capture_* siblings, leaving the definition only minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 60%, and session_id and project_root have no schema descriptions at all. The description adds no parameter meaning and does not compensate for the undocumented fields, so an agent cannot tell how scoping by session or project works.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and algorithm (BM25 search) and a scope (sandboxed tool outputs), which separates it from capture_get/capture_list. It does not, however, distinguish it from the other search siblings such as memory_search, search_codebase, or corpus_query, so an agent must infer which search corpus applies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use or when-not-to-use guidance, and no reference to alternative tools. Given several search-shaped siblings (memory_search, corpus_query, search_codebase, ts_search), the absence of routing guidance is a real gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.