Run a database query

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

The description goes far beyond the sparse annotations (readOnlyHint: false, destructiveHint: false). It discloses the two-phase mutation protocol (preview + confirm_token required even with allow_mutation: true), the 'stacked statements are always refused' rule, the enforced row limit on safe statements, and the side effects of bypassing hooks: caches not invalidated and plugin logic skipped. No contradiction — destructiveHint: false is consistent with the default-deny-plus-confirmation design.

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?

Four sentences (~90 words) with zero redundancy: what the tool does, how safe statements execute, the mutation safety protocol, and the routing caveat all earn their place. The description is front-loaded with the core purpose and flows logically from behavior to risk, with no repeated information.

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?

Operationally complete for an agent: execution model, row limit, confirmation flow, stacked-statement refusal, and side effects are all covered. The only gap is the return shape of query results and the preview response, which matters because no output schema exists — though the confirm_token parameter description ('Token returned by the preview') partially bridges the preview format question.

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 schema already documents all five parameters, including the interplay between allow_mutation and confirm_token. The description adds only framing — 'enforced row limit' echoes max_rows and 'stacked statements are always refused' constrains query — but no significant new semantics beyond the schema's own parameter descriptions. Baseline 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?

States a specific verb and resource: 'Run a SQL query against the WordPress database through the companion plugin.' The scope is unambiguous and the closing sentence explicitly frames raw SQL as a last resort beyond the REST API and WP-CLI, which maps to siblings rest_api and run_wp_cli — so an agent can tell this tool apart without opening schemas.

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?

'Reach for this only when the REST API and WP-CLI cannot get at the data' is an explicit when-condition that names the alternatives and implies the when-not: do not use it when standard APIs suffice. It also explains why ('raw SQL bypasses WordPress hooks, so caches are not invalidated and plugin logic does not run'), giving the agent a decision rule rather than a vague preference.

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