Compare pages

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

Even though annotations already say destructiveHint=true and idempotentHint=false, the description explains the concrete consequences: the first call records a baseline, save_baseline replaces it, and repeated calls keep the same comparison point. It also discloses non-obvious behavior like only reporting a verdict when min-max ranges do not overlap, flagging Lighthouse version changes, and returning a job ID for async collection. This far exceeds what the annotations alone convey.

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 longer than average, but every sentence carries high-value operational information: baseline recording, overlap-based verdicts, guaranteed figures, field-data exclusion, and async slowness. It is front-loaded with the tool's core purpose and ends with the critical job-ID/check_status detail. 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?

For a non-trivial async comparison tool with destructive baseline behavior, this description is remarkably complete. It covers what the tool measures, how to use it correctly across multiple calls, what a verdict means statistically, what it does not cover (field data), and how to retrieve the result. There is no output schema, so the description's explanation of verdict semantics is essential and 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?

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantic context beyond the schema: strategy is part of the baseline identity, first-call behavior is integrated with save_baseline's semantics, and the same URL/strategy pairing is what ties the comparison together. It does not add much about runs or urls, but the baseline-related clarification is genuinely valuable.

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 opens with a concrete question the tool answers ('did that change actually help') and immediately states the mechanism: measure now and compare against a saved baseline for the same URL and strategy. This clearly distinguishes it from sibling tools like field_data, report, and check_status, which would be used at different stages or for different data.

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?

It gives explicit, actionable usage rules: the first call records the baseline and compares nothing, then you make the change and call again. It also warns that field data is not compared, that the tool is slow and returns a job ID, and that check_status is used to collect the verdict. This is strong when-to-use guidance that prevents misuse.

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