wp_seo_fix

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

No annotations are provided, so the description bears the transparency burden. 'Add' clearly indicates a write operation, and the two modes are disclosed. However, the dry_run parameter is not mentioned in the description—a notable gap since it controls whether changes are actually made. The description also doesn't state whether existing descriptions are overwritten or only missing ones. This makes it moderately transparent but not fully explicit.

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 a single, front-loaded sentence with a clear verb and resource. Every phrase adds value—no filler or repetition. It efficiently conveys the core purpose and both operational modes, making it highly concise while remaining informative.

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 annotations and no output schema, the description must provide complete context. It covers the main actions but omits important behavioral details such as dry_run's effect, what happens to existing descriptions, and what the tool returns/outputs. Given the 5-parameter schema and nested object, the description is adequate but not complete—an agent would need to rely on the schema for dry_run semantics and still might miss side effects. A score of 3 reflects this 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 description coverage is 100%, with each parameter (mode, dry_run, site_id, post_type, descriptions) clearly documented in the schema itself. The description adds minimal extra meaning beyond summarizing the two modes. Since the schema carries the parameter detail, a baseline score of 3 is appropriate; the description does not meaningfully enrich parameter understanding.

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's function: 'Add meta descriptions to pages/posts.' It distinguishes itself from sibling tools like wp_seo_check by focusing on fixing (adding/updating) rather than checking. The two modes (auto-generate from content or set specific descriptions) further clarify its purpose.

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 implies when to use each mode: 'auto-generate from content' for bulk fixing, and 'set specific descriptions for specific post IDs' for targeted edits. It does not explicitly mention wp_seo_check as an alternative or provide exclusion criteria, but the mode breakdown gives practical usage context. Lacks explicit 'when not to use' guidance, so a 4 is appropriate.

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