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

Goes well past the annotations by disclosing the async contract (returns a scanId at once, poll get_scan every 10 seconds, stop when done is true) and the billing consequence (consumes 1 page of the monthly allowance, free accounts limited to 2 pages/month). That is exactly the operational and cost context an agent needs before invoking a non-idempotent, open-world tool.

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?

Three sentences, zero filler, and ordered by importance: what it checks, when to use it, then the mechanics and cost. Every sentence earns its place and nothing is front-loaded incorrectly.

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?

An output schema exists so return values needn't be explained, yet the description still supplies the one thing the schema cannot: how the async result is retrieved and what the call costs. For a one-parameter, fully-described tool this leaves no practical gap.

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% and the single url parameter is already fully documented there ('The public page URL to proofread'). The description only adds the indirect hint that the page must be published/live; it offers no syntax, format, or constraint detail beyond the schema, so the baseline 3 applies.

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 precise verb+resource+scope: 'Check one published web page for spelling, grammar, punctuation, and leftover placeholder text.' The scope word 'one published web page' cleanly separates it from the sibling proofread_site, and the check categories tell the agent exactly what the tool produces.

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 clear trigger conditions ('when the user gives a page URL or asks to proofread, spell-check, or find typos on a live page') and describes the follow-up workflow with get_scan. It never explicitly says when NOT to use it or names proofread_site as the alternative for multi-page jobs, so sibling routing is left to inference.

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