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

Annotations only declare readOnlyHint=true and openWorldHint=true, but the description goes far beyond: it discloses that the returned card includes exact precomputed counts, that top_creatives are the most re-uploaded creatives with media stripped, and that category counts are only for AI-labeled ads. It also discloses quota (1 token) and the top_creatives contract regarding market-wide reuse. No contradiction with annotations; the description adds rich behavioral context that annotations alone do not 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?

The description is long, but most content is essential given the tool's complexity (many fields, nested contracts, interpretation rules). It is front-loaded with the core purpose and a list of fields, then procedural nuances. Some redundancy (e.g., repeating 'top_creatives' explanations) could be trimmed, but overall it is packed with actionable detail and avoids fluff. Not as succinct as possible, but justified.

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?

Despite an output schema existing (indicated by context), the description explains return contents thoroughly: the list of fields, the special semantics of counts (exact vs labeled), the top_creatives contract, and quota. It covers all practical aspects an agent needs to call the tool correctly, including id resolution and interpretation of metrics. No missing information is apparent for a correct invocation.

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?

The input schema describes 'id' only as 'the resource id to fetch' (generic). The description vastly enhances meaning: id can be an advertiser UUID or a Facebook page id, and provides multiple sources (ad's advertiser_id, get_trends dimension, get_creative's fanpages, page_id, or pasted Facebook link). It also explains automatic resolution of page ids and links. This far exceeds schema coverage and gives an agent concrete guidance on constructing the id value.

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 explicitly states the tool fetches a single advertiser's full card by id and enumerates all contained fields (name, external_id, avatar_url, page_url, total_ads, active_ads, etc.). It distinguishes itself from search_ads by positioning itself as the exact-count source and mentions alternatives like get_media and search_ads for other purposes. The verb 'Fetch' and resource 'advertiser's full card' make the purpose unambiguous.

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 provides explicit usage directives: it is the cheap way to get exact ad counts, and warns against paginating search_ads for that. It also instructs to call search_ads when listing an advertiser's ads, explains how to resolve IDs (UUID, page id, Facebook link), and details how to interpret category counters and ai_coverage. It includes a clear exclusion (do not compare category counts to total_ads directly) and naming of alternatives, satisfying the 'when-not' criterion.

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