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

Annotations already flag destructiveHint=true, idempotentHint=false and openWorldHint=true, so the bar is lower, yet the description adds a genuinely important trait: the write is gated on human approval in Royally and nothing changes on the site until then. It also discloses the HTML allow-list and the sanitizer filter hook, though it omits whether an existing key is silently overwritten.

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 act is front-loaded in the first sentence and the following clauses deliver concrete, usable detail rather than filler. The plugin-key list is dense but earns its space; the site identifier and approval sentence are appended boilerplate-style but still informative.

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 destructive, approval-gated mutation with no output schema, the description covers the risky parts: what gets written, permitted value content, sanitization hooks, and the approval gate. Only the post-write result shape and the overwrite behavior on an existing key are left unstated.

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 only 25% (only site_id is documented), so the description must carry the load and largely does: it explains the format and real-world values of `key` across three SEO plugins and clarifies that `value` accepts HTML within a content-equivalent allow-list and multiple scalar types. `term_id` and the upsert semantics of re-writing an existing key remain unexplained.

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+resource ('Update term meta data'), which cleanly separates it from wp_get_term_meta, wp_delete_term_meta and the post-meta counterparts. It never names a sibling explicitly, so the differentiation is implied by the resource noun rather than stated.

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 SEO-key crib sheet (Yoast/Rank Math/AIOSEO) tells the agent when this tool is the right one for SEO metadata, but there is no explicit 'use this instead of wp_update_post_meta' routing or stated precondition such as the term needing to exist. Usage context is implied rather than prescribed.

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