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

Annotations already declare readOnly/idempotent/non-destructive, and the description layers on substantial behavior: sections are returned whole and never truncated, results are packed best-first into ~9,000 characters, sections_omitted_for_size reports overflow, and score is cosine similarity. It also names an error condition and its fallback, which annotations never convey.

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?

Purpose and scope are front-loaded, and essentially every clause carries information an agent needs. It is a dense, semicolon-chained single block rather than structured prose, which slightly hurts scannability, but there is little true filler.

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?

Though no output schema exists, the description enumerates the returned fields (model, object_pk with its downstream get_detail_* usage, object_title, object_url, category_code, section_heading, section_text, is_faq_question, score). Combined with the size-packing and error notes, an agent has everything needed to call and interpret it.

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?

With 100% schema coverage the baseline is 3, but the description adds real meaning: the model names are glossed (article = how reproductions are made, policies, art history; artist/artwork = biographies and descriptions), and category_code is explained as article-only with Support/Website flagged for service and policy questions. It also clarifies the query should be a natural-language question.

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+resource ("semantic search of the texts of our site") and immediately distinguishes itself from keyword search ("by meaning rather than shared words"). It enumerates the searched models (article/museum/artist/artwork) so an agent can tell it apart from siblings like search_articles or search_objects_semantically.

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 concrete usage conditions: ask in a full sentence, any language works while texts are English, default is all indexed models, and on the index_unavailable error fall back to the search_* full-text tools. It does not explicitly contrast with search_objects_semantically or search_article_sections, so a sibling-differentiation gap remains.

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