doc_search

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden and does well: it discloses that results are 'verbatim' (not summarized), that output is 'packed into a token budget' (tied to budget_tokens), and that omitting doc_id searches the entire corpus. This gives an agent a clear picture of side-effect-free read behavior, though it omits error handling and ranking details.

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?

Three sentences with a striking analogy; every sentence carries information. The purpose is front-loaded, the usage nuance follows, and the parameter hint lands last. The manual-vs-index analogy, while colorful, earns its place by making the search-vs-paging tradeoff instantly understandable.

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?

For a search tool with no output schema and no annotations, the description covers the essential behavioral contract: what is searched, what is returned, and how the token budget applies. It doesn't specify default values for limit or budget_tokens, but optional parameters and the schema make that a minor gap. Overall it's complete enough to call correctly.

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 100%, so the schema already documents each parameter. The description adds value by introducing the 'token budget' concept that clarifies budget_tokens and by restating doc_id omission as a scoping rule. This goes beyond the schema without duplicating it, showing good use of the complementary role.

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?

The description opens with a clear verb and resource: 'Find the chunks of a document most relevant to a query and return them verbatim, packed into a token budget.' This makes the tool's purpose unmistakable. It gestures at a distinction from 'paging' through documents, though it doesn't name a specific sibling, so differentiation is strong but not explicit.

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?

The description explicitly instructs when to use the tool: 'Prefer this over paging when you know what you are looking for,' and reinforces it with the manual-vs-index analogy. It guides the agent away from using it for exploratory browsing and gives a concrete scoping rule ('Omit doc_id to search across every ingested document'). It falls short of naming the exact sibling tool to use instead, keeping this from a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.