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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered and the '[read-only]' tag plus the GET endpoint mention are largely redundant. The one genuinely additive piece is the finding taxonomy (new, resolved, worse, better, unchanged, plus metric deltas), which stands in for the missing output schema. No information about error behavior when a run id does not exist or belongs to another brand.

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?

Two sentences, zero waste. The core operation and its output semantics are front-loaded, and the bracketed read-only tag plus endpoint reference sit compactly at the edges without disrupting the read.

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 three simple string parameters, no nested objects and no output schema, the description supplies exactly the missing piece: what a comparison returns. It stops short of describing the delta format or how findings are keyed for matching, but an agent can call this correctly from what is given.

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%, including the brandId default and the pointer to GET /api/v2/brands, so the schema already carries the parameter burden. The description only reinforces the before/after temporal mapping already stated in the schema. Baseline 3 applies since the schema does the heavy lifting.

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?

Specific verb ('Compare') plus a precisely scoped resource ('an older and a newer saved run'), and it names the output shape (new/resolved/worse/better/unchanged with metric deltas). This is clearly distinguishable from sibling tools like ads_deep_dive_get or ads_deep_dive_run, which operate on a single run rather than a pair.

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?

Usage is implied: call it to diff two previously saved runs, with the ordering constraint (older vs newer) made explicit. There is no explicit when-not guidance or reference to the alternatives (ads_deep_dive_get for a single run, ads_deep_dive_run to create one), so the agent must infer routing from the sibling names.

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