Skip to main content
Glama

royal-mcp__wp_add_post_terms

Destructive

Add terms to a post in any taxonomy, or replace the terms it has. By default the terms are added and the existing ones stay; pass replace: true to make the post have exactly the terms you send (an empty list then removes them all). Accepts term IDs (integers), slugs (for hierarchical taxonomies like category), or names (for non-hierarchical like post_tag). The reply lists the terms before and after, which were added, removed and newly created. dry_run true previews the result (terms before, after, added, removed and created) and changes nothing. A write that changes the terms returns an undo token: undo puts back the earlier terms exactly and deletes terms the call created when nothing else uses them; it is refused with edited_since_write when the post's terms in that taxonomy changed since, unless forced. (site: demo.royalplugins.com) Through Royally: waits for a person to approve it in Royally; nothing on the site changes until then.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "post_id": "<post_id>",
      "terms": "<terms>",
      "taxonomy": "<taxonomy>"
    },
    "name": "royal-mcp__wp_add_post_terms"
  }
}

Input Schema

NameRequiredDescriptionDefault
termsYesArray of term IDs (integers) OR term slugs/names (strings). Must be an array — pass ["my-tag"] not "my-tag".
dry_runNotrue previews (default false).
post_idYes
replaceNofalse (default): add these terms and keep the existing ones. true: the post ends up with exactly these terms.
site_idNoSite to run this tool on: 8ef2e52b-bd07-4671-a363-ebe8b480b65c (https://demo.royalplugins.com)
taxonomyYesTaxonomy slug (e.g. category, post_tag, product_cat)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / dry_run
      Added value: +{
      +  "description": "true previews (default false).",
      +  "type": "boolean"
      +}
  2. Changed1 schema field changed
    • addedInput schema / properties / replace
      Added value: +{
      +  "description": "false (default): add these terms and keep the existing ones. true: the post ends up with exactly these terms.",
      +  "type": "boolean"
      +}
  3. Added
  4. Removed
  5. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Despite annotations already flagging destructiveHint and non-idempotency, the description adds substantial context: the reply shape (before/after/added/removed/created), the undo token with its exact-restore semantics, deletion of newly created terms when unused, and the edited_since_write refusal with a force override. It also discloses the Royally human-approval gate, which is a behavioral trait no annotation conveys.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The paragraph is front-loaded with the add-versus-replace decision before the mechanics, and each sentence carries information. The trailing '(site: demo.royalplugins.com)' is redundant with the site_id enum and adds noise to an otherwise tight definition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

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 describing the return payload for both the write and dry_run paths. Undo, approval, and term-creation side effects are all covered, so an agent has everything needed to invoke this destructive, approval-gated tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 83%, but the description adds real meaning: the hierarchical/non-hierarchical distinction for slugs versus names goes beyond the schema's 'IDs OR slugs/names' wording, and it spells out the replace-with-empty-list consequence. It does not explain post_id or site_id, though those are largely self-evident or enum-constrained.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence states a specific verb and resource ('Add terms to a post in any taxonomy') and immediately covers the second mode ('or replace the terms it has'). An agent can distinguish this mutation tool from the read-side siblings (wp_get_post_terms, wp_get_terms) without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It clearly explains the default add-and-keep behavior versus replace: true with an exact-set result, and notes that an empty list under replace removes all terms. It also explains dry_run as a preview path. What it lacks is any explicit pointer to a sibling for reading terms first, so the routing guidance is contextual rather than exhaustive.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources