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

The description goes far beyond annotations: it discloses the destructive nature (body replaced in place, previous version not kept), the 1-3 minute synchronous wait, the cost of 1 AI brain credit charged after work and not refunded, the 'Out of Sync' side effect for published articles, and the failure-without-charge behavior. It also states return values (previous_score, new_score, instructions). This is thorough and consistent with the annotations.

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 but every sentence carries necessary information. It is well-structured, starting with the main action, then exclusions, timing, destructive nature, side effects, returns, cost, confirm, and website_id. No redundancy; it earns its length given the tool's complexity.

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 tool with 4 parameters and significant behavioral caveats, the description covers all necessary aspects: purpose, process, exclusions, timing, destructive effects, side effects, costs, confirm requirement, locale handling, and return values. An agent has everything needed to call it correctly and interpret results.

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 context: locale is for translations, confirm must be true to proceed (otherwise only cost/balance returned), and website_id is optional for single-website accounts. This clarifies usage beyond the schema descriptions.

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 clearly states the tool rewrites the article body with AI to fix failing on-page SEO checks, and outlines the entire process (score, rewrite, re-score). It explicitly excludes title, meta description, slug, links, and images, and directs users to update_* tools for those, effectively differentiating from siblings like update_article_content or edit_article_with_ai.

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 provides explicit when-to-use and when-not-to-use guidance: use it for body-level SEO improvement, but use update_* tools for title/meta/etc. It also covers prerequisites (active subscription/trial), the need to pass confirm=true to acknowledge charges, and website_id for multi-website accounts. It notes the tool is slow and advises waiting rather than retrying.

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