traffic_drops

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

With no annotations provided, the description carries the full burden — and it delivers. It mandates data fidelity ('Base your analysis ONLY on the data returned... Report exact numbers'), forbids speculation ('Do not speculate about causes'), requires honest uncertainty ('say so clearly rather than guessing'), specifies presentation format via artifacts, and, critically, discloses the position metric's caveats (impression-weighted average, not rank-tracker rank, sparse data beyond page one, prefer deltas over absolutes). This is exceptional behavioral disclosure that prevents realistic misuse.

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 (~180 words) but every block earns its place and is clearly labeled (IMPORTANT, PRESENTATION, POSITION), making it scannable. The core purpose is front-loaded in the first sentence, and the later blocks address distinct agent behaviors: analysis discipline, output formatting, and metric interpretation. Slightly verbose, but density is high and there is minimal 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?

For a single-parameter tool with no output schema, the description is remarkably complete: it implies the returned data (pages, period-over-period metrics, diagnosis categories, position values) and explains how to interpret and present it. The main gap is that the exact response shape/fields are never enumerated — the agent learns about position and diagnosis categories only by inference — but the behavioral and interpretative coverage compensates strongly.

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%: the single 'days' parameter is already documented as 'Number of days per period to compare.' The description's 'Compares current period vs prior period' lightly reinforces this period-pairing semantics but adds no new parameter-level detail. Baseline 3 is correct 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?

The first sentence states a specific verb and resource: 'Find pages that lost the most traffic recently.' It then adds the diagnostic scope — distinguishing 'ranking loss, CTR collapse, or demand decline' — which separates it from siblings like content_decay (slow decline over time) and ctr_opportunities (upside-focused). The purpose is concrete and unambiguously framed.

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 gives clear usage context: when an agent needs to identify recently declining pages and determine which mechanism (ranking, CTR, demand) drove the loss. It doesn't explicitly name alternatives or exclusion criteria, but the 'recently' + diagnosis framing is specific enough that an agent can distinguish it from siblings without guessing. A small gap: no explicit 'use content_decay instead for older/gradual declines' routing.

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