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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), but the description adds real operational context: the return payload shape (excerpts, sections, source offsets, revisions) and a degradation signal the agent must check ("inspect semantic.status for coverage/fallback"). It does not mention pagination or the cap of 12 results, which is the remaining gap.

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, front-loaded with the purpose and method, then returns, then the caution. Dense but every sentence carries information; the only mild cost is the technical jargon in sentence one, which slows first-pass comprehension.

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 6-parameter tool with no output schema and zero schema descriptions, the description covers return contents and a fallback signal reasonably well, but half the inputs remain opaque. An agent can call it with the two required params, yet cannot confidently use mode, limit, result_offset, or include_archive from this text alone.

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 description coverage is 0%, so the description must carry all parameter meaning, and it does not. It hints at the mode enum via "hybrid lexical and local multilingual semantic retrieval," but never explains mode, limit, result_offset, or include_archive — notably include_archive is unmentioned despite the description asserting content exclusions, leaving the agent to guess how archiving interacts with results.

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 resource ("Find relevant passages in the project's published documentation") plus the retrieval method (hybrid lexical + local multilingual semantic). It also explicitly delimits itself against a sibling: "Search is not a full document read," which an agent can use to separate it from read_document/read_outline without opening either schema.

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?

Gives explicit scope exclusions ("Pending proposals and the virtual access register are excluded") and an explicit when-not plus alternative path ("Search is not a full document read: read the contract and relevant sources before acting or editing"). The routing decision between searching and reading full documents is fully stated.

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