WordPress taxonomy tool reference
Eleven tools for categories, tags, custom taxonomies and their metadata.
The tools
Reading terms
| Tool | Does |
|---|---|
wp_get_taxonomies |
List public taxonomies |
wp_get_categories |
List categories |
wp_get_tags |
List tags |
wp_count_terms |
Count terms in a taxonomy |
Changing terms
| Tool | Does |
|---|---|
wp_create_term |
Create a term |
wp_update_term |
Rename or re-describe a term |
wp_delete_term |
Delete a term |
wp_add_post_terms |
Set a post's terms in one taxonomy |
Term metadata
| Tool | Does |
|---|---|
wp_get_term_meta |
Read term meta |
wp_update_term_meta |
Write term meta |
wp_delete_term_meta |
Delete term meta |
Read this before using wp_add_post_terms
Despite the name, it replaces every existing term in that taxonomy unless you pass append: true.
Asking an assistant to "add the seasonal tag" and letting it call this tool with one term removes every other tag on the post. See wp_add_post_terms.
Permissions
Reading terms needs no WordPress capability — only the mcp:read and wp:content:read scopes. Taxonomies and their terms are public data, and listing them is as open as reading a published post.
Reading term meta is different. It requires manage_categories, the same capability as writing terms.
Every write needs Allow content writes open, plus:
| Tool | Capability |
|---|---|
| Create, update, delete a term | manage_categories |
| Term meta writes | manage_categories |
wp_add_post_terms |
edit_post on the target post |
That last row is the exception worth noting: assigning terms is treated as editing the post, not as managing the taxonomy. A user who can edit posts but not manage categories can still change which existing terms a post carries.
Two different listing shapes
Term listings return items only — no total, unlike post and media listings. The number of results is limited by per_page, clamped to 1–100, and nothing tells you how many exist beyond that page.
Use wp_count_terms when you need the size. This is the main practical difference from the content and media chapters, and it catches people who assume the listing shape is uniform.
The term shape
Term listings return id, taxonomy, name, slug, description and count.
count is how many published items use the term. It is the field that tells you whether deleting a term is a cleanup or a structural change.
Dry runs
All five write tools support dry_run. They report the payload or the identifier they would act on, not a before-and-after — so a dry run here confirms the arguments were built correctly, but does not show you what you are about to overwrite.
For that, read the term first.
Related
- Create terms and organize content — the workflow
- Content tools
- Comment and meta tools for post meta