Compare your page with competitor pages

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

Annotations already establish that the tool is read-only, idempotent, and non-destructive. The description goes further by disclosing that it fetches multiple pages and computes a concrete list of metrics (fetch time, HTML size, term extraction, content-gap terms). This is sufficient behavioral context for a safe audit tool, though it does not mention network failure or latency behavior.

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 dense but efficient: one sentence lists the audit dimensions and a second explains the content-gap feature. It front-loads the core purpose before metrics, and there is no filler or repetition of the title.

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?

Since there is no output schema, the description carries the burden of explaining what the agent can expect. It lists the measured fields and the term-gap output in enough detail to set expectations. It does not describe error cases or output formatting, but for a read-only audit tool the listed output scope is largely sufficient.

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 schema has 0% description coverage, so the description must compensate, but it only loosely maps to parameters. It explains the general idea of yourUrl and competitorUrls by mentioning 'yours plus pages ranking above you', and the content-gap phrasing hints at gapTerms, but it never explicitly defines gapTerms as the number of terms to return or explains the maximum of six competitor URLs. An agent would have to infer these semantics from names and schema constraints.

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 ('Audit') and resource ('several URLs side by side') and enumerates exactly what is compared: word count, headings, links, schema, etc. It also emphasizes the competitive angle ('yours plus pages ranking above you'), which clearly differentiates it from single-page audit tools like page_audit or pagespeed.

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 phrase 'yours plus pages ranking above you' gives a clear context: use this when you want a competitive content/SEO comparison against pages that outrank you. It does not explicitly name alternatives or state when not to use it, but the side-by-side framing is enough for an agent to select it over single-page audit siblings.

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