Thematic MCP: Theme Editing feature group

The Theme Editing feature group lets you edit your theme structure by talking to an AI assistant through the Thematic MCP Server. It works alongside the Analysis feature group, which reads your results.

With Theme Editing on, the assistant can read your themes, find problems in them, propose fixes, test a change against your real data, and publish it. You can ask things like "which of our themes overlap?" or "what would happen if I mapped the phrase 'delivery' to Late Delivery?" and the assistant will work through it with you.

Before you start

Your organization allows theme editing

Theme Editing is off for every organization until an administrator turns it on. Someone with the manage workspace permission opens Manage workspace > MCP access in the Thematic portal and switches on Allow theme editing. Changes can take up to 5 minutes to reach assistants that are already connected. See Thematic MCP Server for details.

You turn it on for yourself

When you connect the Thematic MCP you choose which feature groups you want enabled. If you didn't choose Theme Editing then, ask your assistant to turn it on. You don't need to reconnect.

You need theme editing permissions

The built-in Dataset Administration role has theme editing permissions for every survey and lens. Without them Thematic refuses every edit. Ask whoever manages your Thematic users for a role that allows editing themes. See Permissions Glossary and Roles for how permissions and roles work.

Draft and live

Every change goes into a draft. A draft changes nothing your dashboards, reports or exports show.

   your edits  ──►  draft  ──►  apply_themes  ──►  live themes + full re-tag
                     ▲                                       │
                     └──────────  reset_draft  ◄─────────────┘

• Stack changes until ready. Until apply_themes , none of it is visible to anyone reading your dashboards.
• One draft per source, shared by your organization. It is not private to you. A colleague editing the same survey or lens is working on the same draft.
• Publishing is expensive. apply_themes  starts a full re-tag of the source's data. It runs in the background, takes a while, and is not easy to undo, so it requires an explicit confirmation.

This is the same draft that the Manage themes area uses, so a draft you build here is visible there and vice versa. Because applying themes changes analysis other people may already have seen, it is worth reading Theme discovery changing themes before your first publish.

The usual sequence

1. list_playbooks , then get_playbook  for the one that matches the task: the written procedure, before any tool call.
2. get_draft  to see the current themes; get_quality_score  and get_tagging_stats  to find where the problems are.
3. Run one of the AI checks for suggestions.
4. preview_phrase  on anything uncertain.
5. apply_transform : the change lands in the draft, nothing is live yet.
6. diff_draft  to review the whole change.
7. apply_themes  to publish; get_apply_status  to follow the re-tag.

The two rules that matter

Preview single words before mapping them. A phrase matches on concept, not sentiment: map "service" and it tags "the service was excellent" and "the service was appalling" alike. That is fine for a theme named by topic ("Staff service") and wrong for one named by direction ("Unhelpful staff"). A bare single word on a directional theme is the usual cause of a theme that grows to cover everything. Ask for preview_phrase  and you see the split before you commit.

Review the diff before every publish. diff_draft  is the only place an unintended change shows up while it is still cheap to undo. Read the removed themes especially.

Everything in Theme editing best practices applies here too: what makes a good taxonomy, when to merge rather than delete, and why overly generic phrases cause trouble.

Available tools

You don't need to call these directly. Ask for what you want in conversation and the assistant will choose the right tools. The list is here so you know what is possible.

Find the right procedure

A playbook is a written procedure for a theme task: which tools to use, in what order, what to check before publishing, and what goes wrong quietly. The other tools describe what each one does; a playbook says when to use it. They are written and kept current by Thematic's Customer Success team, so an assistant that reads one is following the same method Thematic uses on customer data rather than working it out as it goes.

You do not have to do anything to get this. An assistant will read the playbook that matches what you asked for. You can also ask for one by name: "what does the theme loop playbook say?"

See what you have

Ask AI what to change

All six are read-only. A suggestion normally arrives with the exact change attached, so applying it is one further step rather than fresh work, apart from the two-step case noted under Things that can look odd.

Two more work on a single theme and return phrases rather than a change:

• suggest_phrases_for_theme  works from a theme's title and existing phrases, so it suits a new or nearly empty theme.
• extract_phrases_from_comments  draws phrases from comments you name, which keeps them grounded in real wording. The assistant can find comment ids by reading your comments first.

discover_phrases  is the one to reach for once a theme set is already populated.

These are the same checks that power AI Suggestions in the Themes Editor. If you prefer to review suggestions as cards in the portal rather than in conversation, that is the same work in a different interface.

Check, then change

apply_transform  covers eight changes: AddTheme , ChangeThemeTitle , DeleteThemes  (cascading to sub-themes), MoveTheme , MergeTheme , UnmergeTheme , AddPhrases , DeletePhrases .

• Merge or delete? If a redundant theme's phrases are still catching useful comments, MergeTheme  keeps them working against the surviving theme. DeleteThemes  throws them away with the theme.
• Undoing a merge. UnmergeTheme  lifts out only the theme you name; anything folded in alongside it stays merged. Use restore_version  to undo a whole merge.

Publish and undo

restore_version  is the real undo: every version you apply is kept, so you can always bring back an earlier structure, review it, and publish it.

Things that can look odd

• preview_phrase  numbers are part exact, part sample. The response count is exact for the source you are working on; the sentence counts and examples come from a sample of up to 100 comments, with up to two examples per sentiment. It matches case-insensitively as a substring, so testing "service" also catches "services".
• get_tagging_stats  reads a sample of 200 comments. A sentence carrying three or more themes counts as crowded, and it reports the ten themes appearing most often on crowded sentences.
• suggest_phrases_for_theme  returns at most 25 phrases, and says so when there were more.
• Some suggestions take two steps. A suggestion that creates a theme and then targets that same theme cannot be applied in one go, because the new theme's id only exists once it has been created: the theme has to be created first, its id read back, and the rest applied against that id. Such a suggestion arrives with a note saying so.

Troubleshooting

If a theme tool behaves in a way this article does not explain, ask your assistant to send feedback to Thematic.

Related articles

• Thematic MCP Server: connecting, feature groups and troubleshooting
• Analysis feature group: exploring your feedback from an assistant
• Theme editing best practices: what a good theme taxonomy looks like