wp_update_settings

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

No annotations are provided, so the description carries the full burden. It states 'Update safe' which hints at non-destructive behavior, but it does not disclose other behavioral traits such as whether changes take effect immediately, validation errors, or side effects. A mutation tool should provide more transparency about its impact.

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, concise sentence that effectively communicates the tool's purpose. It is front-loaded with the primary verb and resource. However, it could include a bit more detail on parameter usage without becoming overly verbose, hence slightly above average.

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?

Given the tool has 6 parameters, no annotations, no output schema, and low schema description coverage, the description is insufficiently complete. It does not explain how to set the front page (requires combining show_on_front and page_on_front), or handle optional parameters. An agent lacks critical context for correct 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?

The description adds some value by mapping 'title' to blogname, 'tagline' to blogdescription, etc., covering 4 of the 6 parameters. However, schema description coverage is only 33%, and the description does not explain the remaining parameters (show_on_front, page_on_front) or their interplay. It partially compensates for the schema gap but is not comprehensive.

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 'Update safe WordPress site settings' and lists specific settings (title, tagline, posts per page, front page), making the tool's purpose very clear. It distinguishes from sibling tools like wp_get_settings (read) and other update tools (e.g., wp_update_post), so an agent can easily identify it as the correct tool for site-level setting updates.

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 usage for updating site-level settings but does not explicitly state when to use this tool versus alternatives. It lacks guidance on when not to use it (e.g., for post-level settings) or any prerequisites. However, the context of sibling tools provides some implicit differentiation, so the score is adequate but not explicit.

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