search_md_docs

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

With no annotations, the description carries the full burden. It explicitly states the tool does not mutate the MD scene, declares the local index dependency, and warns that documentation can lag the runtime. It does not cover behavior when the index is missing, but the key safety and operational traits are disclosed.

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 description is three tight sentences. Purpose is front-loaded, followed by the safety guarantee, then the prerequisite and caveat. No sentence is wasted or redundant.

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?

An output schema exists, so return-value details are already covered. The description supplies the essential context: what is searched, that it is read-only, the required index update step, and the staleness caveat. It is missing explicit sibling differentiation, but for a simple two-parameter search tool this is adequate.

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 compensate, but it provides no per-parameter guidance for 'query' or 'limit'. The mention of BM25 implies query is free-text, but limit semantics, formatting, and defaults are left entirely to the schema.

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 uses a specific verb ('Search'), names the resource ('local official MD docs'), identifies the mechanism ('BM25'), and states the outputs ('signatures and sources'). This clearly differentiates it from scenario search and mutation tools like search_md_scenarios and create_pattern.

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 provides a clear prerequisite ('Requires local index: md-mcp update-docs') and implies this is the tool for local doc search, but it does not explicitly say when to use this versus siblings like get_md_doc or search_md_scenarios. No exclusions or alternative conditions are given.

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