wp_update_term: update a taxonomy term
Renames a term, changes its description, moves it under a different parent, or changes its slug.
Arguments
| Argument | Required | Meaning |
|---|---|---|
term_id |
Yes | The term to update |
taxonomy |
Yes | Its taxonomy |
name |
No | New name |
slug |
No | New slug |
description |
No | New description |
parent |
No | New parent term ID |
dry_run |
No | Report without writing |
Only the fields you pass are changed.
Permissions
Allow content writes open, and manage_categories.
Renaming keeps every post attached
This is the key property, and the reason renaming is usually the right operation.
Renaming "News" to "Company news" leaves every post in that term. Nothing is reclassified, nothing is lost, and the archive keeps its contents.
Compare with the alternative an assistant might reach for — creating a new term and moving posts across — which leaves the old term behind and touches every post. If the goal is "call this something else", rename.
Changing the slug changes a public URL
The slug is not regenerated when the name changes, so a rename alone does not move the archive page. Passing slug does.
That breaks any link to the term archive: internal links, menu items pointing at the archive, external links and search results.
If a slug must change, plan the redirect first. Leaving the slug alone after a rename is usually the right call — a mismatch between a term's name and its slug is invisible to visitors and harmless.
Moving a term under a new parent
Passing parent re-parents the term. On a hierarchical taxonomy that changes the archive URL structure and the term's position in the site's navigation.
It also affects children: moving a parent moves its whole subtree.
Because term listings report no hierarchy, check the current structure in the WordPress admin before re-parenting. The tools cannot show you what you are about to move.
The dry run shows only what you passed
dry_run returns the fields it would write. It does not show the term's current values, so it cannot tell you what you are replacing.
Read the term first if you want the old values:
List the categories and show me the current name, slug and description for term 42. Then rename it to "…".
Keeping those in the conversation is your undo — terms have no revision history.
Merging terms is not available
There is no merge tool. Combining two terms means reassigning every post from one to the other and then deleting the empty one, which is a multi-step job with a destructive ending.
For anything beyond a handful of posts, that is better done with a purpose-built plugin than through MCP. See wp_delete_term for why the final step deserves care.
What it returns
The updated term's identifiers, or an error.
Read the listing back to confirm the visible result:
Apply it, then list the categories and show me term 42.
Common problems
| Symptom | Cause |
|---|---|
| The write is refused | Content write gate closed |
pom_ai_mcp_forbidden |
No manage_categories |
| The archive URL changed | slug was passed |
| Child terms moved too | Re-parenting moves the subtree |
| An error about a duplicate | The new name or slug collides with an existing term |
| The site still shows the old name | Cache not purged |