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

Annotations already declare readOnlyHint, idempotentHint and closed-world behavior, and the description still adds substantial operational detail: server-side matching on lowercased body and title, a cap of 10 results, an explicit ranking rule that demotes archived teaching prompts, and the exact shape of each hit (path, title, first 10 headings, match excerpt). It even explains why full bodies are omitted (~30 KB), which preempts an agent trying to work around the truncation.

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 core behavior and the result cap are front-loaded in the first two lines, with ranking and return shape following. It is somewhat dense and the closing justification about 30 KB bodies is meta-commentary, but that clause does real work by explaining the excerpt-only design.

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 takes on the return-value burden and discharges it: hit count, ordering, per-result fields, and where to get the full document. The remaining gap is the version parameter's accepted format, which matters because it is required.

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 carries the full burden. It compensates well for `query` by explaining that matching is full-text, lowercased, and covers body plus title. It only partially covers `forVersion`, saying results are scoped to 'the given version' without stating the expected version format or pointing at ailang_versions for valid values.

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?

Opens with a specific verb and resource: 'Full-text search across doc Markdown for the given version.' It further pins down the scope (server-side filter on lowercased body + title, top 10 matches) and names the sibling that retrieves full pages, so an agent can tell it apart from docs_nav and example_get without opening a 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?

The description makes the search-then-fetch workflow explicit: this tool returns headings and an excerpt, while 'the full page is a docs_nav / example_get away.' That gives clear usage context and a named follow-up. It stops short of stating when not to use it (e.g., for stdlib or design docs, which have their own siblings), so it is not a full 5.

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