site.request.v1

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

No annotations are provided, so the description carries full burden for behavioral disclosure. The phrase 'with write safety guards' hints at some protective mechanism but is vague—it doesn't explain what guards exist, whether they relate to the dry_run and require_approval fields, or what happens on write attempts. There's no mention of authentication requirements, rate limits, or intended effect for GET vs mutation methods.

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 short sentence, which is concise and front-loaded, but it's under-specified rather than efficiently concise. 'Universal WP REST request' repeats the tool's generic intent without adding discriminating detail, and the 'write safety guards' clause is imprecise without elaboration. It earns a pass for brevity but loses points for vagueness.

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 passthrough tool with 5 parameters, 33 siblings, no annotations, and an output schema, the description is underdeveloped. It fails to clarify the relationship between dry_run/require_approval and the claimed safety guards, doesn't explain when to prefer this over specialized tools like wp_request or update_option, and leaves the agent to guess request shaping. While an output schema exists, the description's low value overall means the tool is incomplete for safe invocation.

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 only 20%—of 5 parameters, only 'path' has a schema-level description. The description compensates minimally by hinting at 'write safety guards' which may relate to dry_run and require_approval, but this is too indirect. Variables like body, method, dry_run, and require_approval receive no clarification in the description; the agent must infer their semantics from naming and schema types alone.

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 identifies the tool as a 'Universal WP REST request to /wp-json path' which is reasonably clear about what it does (make arbitrary WordPress REST API requests). 'Universal' hints at its generic nature, distinguishing it from the many specialized siblings. However, it lacks a specific verb+resource pattern and leaves ambiguity about scope beyond the wp-json prefix, though 'Universal' and the path schema provide some differentiation from sibling tools like wp_request.

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 gives no guidance on when to use this generic tool versus the specialized alternatives (content.publish.v1, site.update_option.v1, etc.). With 33+ sibling tools offering targeted operations, an agent cannot determine when 'Universal...request' is appropriate versus using a purpose-built tool. No exclusions, no prerequisites, no when-not-to-use guidance are provided.

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