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

Annotations already declare a safe read-only, idempotent, non-destructive operation, so the safety bar is lower. The description adds genuinely valuable behavior beyond that: performanceScore/scoreTiers are a longevity+duplication heuristic and must never be presented as spend/ROAS, locked fields return null and are named in `locked`, and the call is data-only until sightglass_show is invoked with resultId. It does not describe pagination size limits (left to schema) or result ordering guarantees beyond search relevance, so it stops short of a top score.

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?

Content is front-loaded with purpose and every clause carries operational information, but it is delivered as one dense block of roughly 250 words covering search behavior, filters, scoring caveats, plan gating and the show flow. It would scan better with structure, and the performanceScore caveat is partly duplicated in the schema description of scoreTiers.

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 16 optional parameters and no output schema, the description carries the full burden of explaining return shape (metadata plus ready-to-view media URLs), the null/locked-field convention on lower plans, and the required follow-up show call. Nothing an agent needs to invoke this correctly or report results honestly 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 88%, so the baseline is 3 and the schema already documents most parameters including CSV enum values. The description still adds real meaning: it clarifies that `search` first does all-words matching on headline/copy/advertiser then fills with semantic matches, that a plain description of angle/offer/visual style works, and that tag-based filters read creative interpretation stored in `tags` (null until read).

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?

Opening sentence names a specific verb and resource — searching a library of real Meta ads and the landing pages they drive to — and later explicitly separates itself from sightglass_get_ad (single ad detail) and sightglass_get_site_page (destination page). An agent can identify this as the bulk discovery tool 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?

It states what `search` does, how to combine it with companyIds/displayFormats/pageTypes/technologies to narrow versus hookTypes/angleTypes/offerTags/funnelStages to filter, and routes to the sibling calls for detail views. It also explains the follow-up show flow via resultId, which is the key invocation sequence an agent would otherwise get wrong.

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