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

Annotations already establish readOnlyHint, openWorldHint, and idempotentHint, covering the safety profile with no contradiction from the description. Beyond that, the description adds substantive behavioral context: it states the return format ('curated summaries (title, date, museum, thumbnail URL, CC0 flag) with the total match count'), the cc0_only filter's media-presence-not-license semantics, online_only's surrogate vocabulary behavior, and the record_id threading to three downstream tools. Even with strong annotations, this description adds real value beyond the structured fields.

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?

Three sentences with zero waste, and the most decision-relevant fact — role as first discovery step — is front-loaded ahead of the filter list and alternative routing. Every sentence earns its place: purpose, filter capability, return format, cross-tool linkage, and the exclusion are each collapsed into one efficient clause. No redundancy with the schema's own descriptions.

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?

Given the complexity (4 top-level params plus a nested 8-field filters object), the presence of an output schema, and strong annotations, the description is complete. The schema exhaustively documents every parameter, the output schema covers return values, and the description positions the tool as a discovery entry point and links it to downstream tools. For a search tool whose safety profile (read-only, idempotent, open-world) is already declared, nothing an agent needs to invoke 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 description coverage is 100%, and the schema itself carries exceptionally rich parameter definitions — date-term vocabulary forms, name vocabulary discrepancies, topic hard-constraint counts, object_type case-sensitivity behavior. With coverage above 80%, the baseline of 3 applies: the description carries the load via the schema rather than its own text. The description does add light framing ('optional exact filters' signals exact-match semantics, record_id linkage tells the agent how to thread results), but parameter-level meaning lives almost entirely in the schema, so 3 is the fair score.

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 opens with a specific verb-plus-resource statement — 'free-text search across 14.5 million Smithsonian objects, with optional exact filters' — and immediately frames the tool's role ('Recommended first step for open-ended or topic discovery'). It names the sibling it is not by routing exact-category browsing to smithsonian_browse_category, making the distinction explicit. Nothing about what this tool does is ambiguous.

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?

Explicit when-to-use guidance is front-loaded ('Recommended first step for open-ended or topic discovery') and the when-not-to-use case is stated outright: 'To browse one exact category — a single museum, culture, date term, object type, or topic — use smithsonian_browse_category instead.' The alternative tool is named and the selection condition is concrete, leaving no inference required.

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