Submit a wp-admin settings form

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

Annotations already flag destructiveHint=true and idempotentHint=false, but the description goes substantially beyond them: it discloses the two-phase safety mechanism (dry-run preview, diff + confirm_token, fresh-nonce re-fetch, verification that other fields are unchanged before submit), automatic nonce/referer handling, correct unchecked-checkbox semantics, refusal of unknown fields with suggestions, and explicitly warns that force_incomplete_form 'can wipe plugin or site settings.' Nothing about the tool's side effects or guardrails is left hidden.

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 dense — one long paragraph of roughly 180 words — but every sentence earns its place: purpose, two-phase flow, safety mechanics, refusals, and danger warnings. The purpose is front-loaded in the first line. The main weakness is structural: a single em-dash-heavy paragraph is harder to scan than short sentences or bullets, which a tool with this many behavioral caveats would benefit from.

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 high-complexity tool with no output schema, the description covers nearly everything an agent needs: what the dry run returns (diff + confirm_token), what the submit call returns (notices like 'Settings saved.' and new values), refusal conditions, the dangerous flag, and the multi-site selection mechanism. The only minor gap is unspecified behavior when the second call discovers fields changed since preview (it implies refusal but doesn't state the response shape). This is negligible against the tool's overall complexity.

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 genuine value beyond the schema: it explains that `changes` are merged on top of the current field values with hidden fields/nonce/referer handled automatically (the schema only says 'Field name → new value'), and it gives lifecycle meaning to `confirm_token` by describing the two-call protocol. It does not redundantly re-explain each parameter, which is appropriate at full schema coverage.

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 opens with a specific verb and resource ('Fill in and submit a form on a wp-admin screen as the administrator') and immediately adds scope: it is the mechanism for changing plugin settings that live only on a wp-admin page with no REST route. This crisply differentiates it from siblings like run_wp_cli, rest_api, update_plugin_settings, and admin_page — an agent can tell which tool applies 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?

Explicit when-to-use: settings reachable only via a wp-admin form with no REST route. Explicit when-not: forms with file inputs, and screens managing plugins/themes/users/exports/core updates are refused, with a note that dedicated tools exist. It names alternatives only generically ('dedicated tools with proper guardrails') rather than pointing to specific siblings, though in a 170-tool list that is a minor gap. The two-call dry-run/confirm protocol is also clearly spelled out as the required usage sequence.

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