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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, yet the description adds substantive context: no API key/account needed, the exact scoring formula, the 1-10/default-3 limit, and the caveat that scores are cosine similarity rather than probabilities and results are suggestions, not confirmed matches. It stops short of describing error behavior or missing-token handling.

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?

The purpose is front-loaded and the length is justified because there is no output schema and the score semantics are non-obvious. The scoring rules (code prefixes, three-or-more-digit numbers, '1 200 read as 1200') are dense and border on over-specification, but they are load-bearing for interpreting results.

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 usefully enumerates returned fields (note_id, key, text, score) and the score's meaning, and confirms the auth model. It omits failure modes (invalid token, unknown collection) and the max length of query, leaving a couple of gaps for a 4-parameter tool.

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 50% (limit and query are undocumented in the schema), and the description compensates well: it states the limit range and default, and explains how query tokens (identifiers, code prefixes, multi-digit numbers) affect scoring. That meaningfully exceeds what the schema provides for those two parameters.

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 ('Search the notes by meaning') plus the credential used, which distinguishes it from read_semantic_search and add_semantic_search_notes. It does not explicitly name the sibling tools, so an agent must infer the routing from the shared prefix.

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 gives implicit usage context (ranked suggestions, compare to read_semantic_search only by inference) and warns to read the text before acting, but never states when this tool should be chosen over read_semantic_search or add_semantic_search_notes, and offers no exclusions.

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