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

Annotations already cover readOnly/idempotent/non-destructive, yet the description adds real behavioral context: it costs nothing, requires a completed audit, older audits carry no ad data, an empty result is a real answer rather than a failure, and it does not start new work. It also flags which outputs are measured vs. model judgement.

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?

Front-loaded with 'Costs nothing' and the core return statement, and every sentence adds routing or caveat value. It is a dense single paragraph of roughly 150 words, so slightly heavy for one parameter, but not padded.

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 carries the full burden and does so: it enumerates every returned element, distinguishes measured figures from written judgements, and notes when captures are attached. Nothing needed to call it correctly appears 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?

Only one parameter (audit_id) with 0% schema description coverage. The description implies the source via 'Needs a completed audit' but never states the expected format or where the audit_id comes from. Adequate for a single obvious lookup key, but it does not fully compensate for the coverage gap.

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?

States a specific verb and resource ('Returns the competitor layer of a finished audit') and enumerates the actual contents: rivals bidding on the same clicks, live ads with keyword/volume/CPC, landing pages, top advertiser, and the customer's own keyword count. It also explicitly distinguishes itself from the sibling ask_audit, so an agent can route without opening another 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?

Gives the exact prerequisite ('Needs a completed audit') and names the alternative with the selecting condition: 'ask_audit with topic:competitors is the one for the written comparison; this is the one for the numbers.' It even handles the edge case where an audit found nobody.

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