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

Goes well past the annotations: discloses the signature-reduction normalization (paths, addresses, ids, times, keys replaced), the match tiering with match.kind/match.similarity, that only the signature is retained, and the empty-result behavior. The domain-coverage caveat (strongest on Node, PostgreSQL, Redis, Docker, nginx, GitHub Actions, npm, LLM API timeouts) is exactly the kind of expectation-setting an agent needs.

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?

Front-loads the action and result in the first sentence, then layers matching behavior, fallback, and coverage. The final catalog-coverage sentence is long but pays for itself by preventing futile calls; overall density is high with little waste.

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?

No output schema exists, and the description compensates by naming the returned fields (match.kind, match.similarity) and describing previews and the empty case. For a free, read-only lookup tool, an agent has everything needed to call it and interpret results.

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 baseline is 3, but the description adds meaning beyond the schema: it explains that the error text is normalized to a signature before matching, which tells an agent that exact formatting doesn't matter. It also documents the per-result preview semantics that the schema cannot express.

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 concrete verb+resource: paste an error, get published knowledge units covering it (fix, workaround, post-mortem). The mechanism — reducing the error to a signature and matching — makes it unmistakably distinct from generic search_knowledge.

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?

Explicitly says 'Use it before debugging an error from scratch' and routes empty results to post_request, which is real when-to-use guidance. It never contrasts directly with the nearest sibling, search_knowledge, so an agent must infer that one is keyword-based and this is error-signature-based.

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