Set term meta

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

Goes well beyond the destructiveHint/idempotentHint annotations: warns that all stored values of the key are replaced, that no undo point is recorded, that WordPress strips backslashes from the value, what permission is required, and what error an unknown term produces. This is exactly the mutation context an agent needs before calling.

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?

A single dense paragraph where each clause carries information: purpose, refusal rules, permissions, side effects, returns, errors and the sibling alternative. Front-loaded with the operation, though the run-on length makes it slightly harder to scan than a split into purpose/behavior/returns sentences.

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?

With no output schema, the description compensates by naming the return fields ('updated, term_id and key') and the not-found error, plus permissions, refusals and reversibility. An agent has everything needed to invoke it correctly and predict the outcome.

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 for the key parameter (prefix refusals, full replacement of stored values) but says little extra about value or term_id beyond what the schema already documents.

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 and resource ('Create or overwrite one meta value of a term') with explicit scope ('category, tag or any taxonomy') and clarifies replacement semantics. It also distinguishes itself from the similarly named wp_update_term by noting that name/slug/description change there, not here.

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?

Explicitly routes the agent to wp_update_term for name/slug/description edits and states the guard conditions (keys starting with '_' and credential-like keys are refused; needs manage_categories and edit rights). It lacks a direct pointer to the read counterpart wp_get_term_meta, so it stops just short of full when/when-not coverage.

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