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

Goes well beyond the annotations: top-level merge with nested replacement, sanitisation via the widget's own update() and widget_update_callback, permission-dependent HTML filtering, credential fields preserved when omitted (including inside nested settings), explicit error conditions that save nothing, and that no undo point is recorded. This is exactly the context needed for a destructive, non-idempotent write.

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?

Front-loaded with the core action and mutation semantics, then return values, then failure modes. Dense but justified by the tool's complexity; slight redundancy in the credential sentence ('when it is left out … leaves it out too') keeps it from a 5.

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 two-parameter destructive mutation with no output schema, it covers return values ('updated, id and the stored settings'), failure modes, permission-related filtering, and undo absence. An agent has everything needed to call it correctly and safely.

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 real meaning by explaining that settings is a shallow top-level merge, that a nested value replaces the stored one, and that shapes the widget does not keep are refused. That goes beyond the schema's generic 'fields to merge' wording.

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?

Opens with a specific verb and resource — 'Update the settings of an existing widget instance' — and 'existing' implicitly separates it from wp_add_widget. It also specifies the merge semantics, so the agent knows exactly what the operation does before reading the schema.

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 word 'existing' makes clear this is for modifying an already-created widget rather than creating one (wp_add_widget), and the reference to wp_get_widgets tells the agent where ids come from. It stops short of explicitly naming alternatives or excluding misuse cases.

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