Run a WP-CLI command

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

Beyond the annotations (which only indicate readOnlyHint=false, openWorldHint=true, no idempotence, and destructiveHint=false), the description adds substantial behavioral detail: commands are emulated in PHP (no binary/SSH needed), only allowlisted commands run (everything else refused), writing commands need admin, and search-replace is dry-run first. This fully discloses the operational constraints and side effects, exceeding what 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 three concise sentences with no filler. It leads with the core purpose, then adds essential operational details (emulation, allowlist, admin, dry run). Every sentence contributes unique information, and the structure is efficient and immediately 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?

For a generic command-runner tool, the description covers all necessary context: what it does, how it works (emulated), authorization requirements (admin for writes), safety (dry-run for search-replace), and the allowlist mechanism with a reference to list_cli_commands. The lack of an output schema is mitigated by the format parameter, and no critical usage aspect appears missing. It is a complete and self-contained definition.

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% — every parameter (command, format, site_id, confirm_token) has a descriptive text in the schema. The tool description does not add additional parameter-level insight beyond what the schema already states. It provides context about the command parameter's allowlist and admin requirements, but that is more behavioral than parameter-specific. Given the high schema coverage, a baseline of 3 is appropriate.

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 purpose: 'Run a WP-CLI command against the site.' The verb is specific, the resource is clear (WordPress site via WP-CLI), and it distinguishes itself from the many dedicated sibling tools by positioning itself as a generic command runner. There is no ambiguity about what this tool does.

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 key usage guidance: commands must be allowlisted (pointing to list_cli_commands), writing commands require an Administrator account, and search-replace always dry-runs first. It does not explicitly state when to prefer a dedicated sibling tool over this one, but the instruction to check list_cli_commands effectively tells the agent to verify command availability. This is adequate context for selection, though a direct alternative-routing statement would earn a 5.

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