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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds substantial extra behavior: the exact shape of each result item, what best_score and score_sum actually measure, the matched_vectors_count meaning, and the 'any language query works even though texts are English' quirk. It also discloses the index_unavailable error and the recovery route, which is the kind of operational detail annotations never carry.

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 objects-not-passages distinction is front-loaded, and the result-field enumeration and error advice each earn their place. Sentences are long and dash-heavy, making it denser than it needs to be, but no clause is padding.

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 itself and does so completely — result fields, scoring semantics, and the error case are all covered. For a 5-parameter read-only search with full schema coverage, nothing an agent needs to call it correctly is missing.

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 baseline is 3; the description nonetheless adds real meaning by explaining the tradeoff between the two rank_by modes in retrieval terms (many matching passages vs one closest passage) rather than restating the enum. It also reinforces that object_pk feeds the matching get_detail_* tool, linking parameters to downstream calls.

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 ('semantic search') and a precise resource set (artworks, artists, museums, articles), and immediately draws the boundary against the sibling search_sections_semantically by declaring it returns OBJECTS, not passages. An agent can route between the two semantic tools without opening either 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?

Gives concrete selection guidance — use rank_by='best_score' to find the exact work a text is about, default 'score_sum' when many passages match — and names a fallback path to the search_* full-text tools on index_unavailable. It does not explicitly state when to prefer this over search_sections_semantically beyond the objects-vs-passages framing, so it stops short of the top score.

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