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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds useful behavioral context beyond those hints: it ranks by spend, joins ad copy, and flags Thought Leadership ads, which tells the agent what returned data will look like without contradicting the annotations.

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 a compact two-sentence definition that front-loads the core metrics and ranking behavior, then adds a clear use case. Every clause earns its place, including the Thought Leadership clarification, which prevents misinterpretation of a specialized flag. There is no filler or redundancy.

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 compensates by listing the metrics returned corrected, including 'joined with the ad copy' and the Thought Leadership flag behavior. It also clarifies the analytical use case relative to organic reach. It does not specify the sort direction beyond 'rank by spend' or describe response pagination, but most operational details (limits, date defaults) are already encoded in the input schema.

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 already documents all seven parameters and defaults clearly (e.g., 'Defaults to 30', 'YYYY-MM-DD'). The description adds no param-specific guidance or contextual meaning beyond the schema, so the baseline of 3 applies.

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 uses a specific verb-resource combination and immediately states a precise behavior: 'Rank individual ads by spend' with a detailed list of metrics (impressions, clicks, CTR, CPC, engagement, leads, cost per lead, video views). It also distinguishes this tool from siblings like get_ads_performance by emphasizing 'per-ad' granularity and 'joined with the ad copy', making the tool's unique scope clear.

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 explicitly says when to use it: 'Use to work out which ads are working' and 'to compare cost per outcome against the organic reach the team's profiles produce for free'. It provides clear application context but does not name alternative tools or state when not to use it, such as when aggregate campaign performance is needed instead of per-ad breakdowns.

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