Modify Tags
tags.modifyUpdate a note's frontmatter tags by adding, removing, or replacing them. Manage tag lists idempotently, with automatic # stripping, leaving inline tags untouched.
Instructions
Mutate the frontmatter tags list of a single note. Four ops are supported: add unions the incoming tags with the existing list (duplicates dropped); remove drops any incoming tag currently present; replace overwrites the list entirely; merge is an alias for add. Leading # on incoming tags is stripped automatically. This tool only touches the frontmatter block — inline #tag occurrences in the body are left untouched. Idempotent: repeated calls with the same op and tags converge on the same result. Returns {changed, target, summary, op, tagsAfter}.
Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.
Examples:
Example 1 — Add two tags to a note (idempotent):
{
"path": "Projects/Alpha.md",
"op": "add",
"tags": [
"in-progress",
"priority/high"
]
}Example 2 — Replace a note's entire tag set:
{
"path": "Inbox/today.md",
"op": "replace",
"tags": [
"processed"
]
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| op | Yes | The mutation to apply to the note's frontmatter `tags` field: - `add` — union existing + incoming (duplicates dropped). - `remove` — drop any incoming tag that currently exists. - `replace` — overwrite the tag list entirely with `tags`. - `merge` — alias for `add` (kept for naming clarity; behaves identically). | |
| path | Yes | Vault-relative note path to mutate. | |
| tags | Yes | Tags to add/remove/replace with. Leading `#` is stripped automatically. Max 50 per call. | |
| vaultPath | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| op | Yes | The mutation to apply to the note's frontmatter `tags` field: - `add` — union existing + incoming (duplicates dropped). - `remove` — drop any incoming tag that currently exists. - `replace` — overwrite the tag list entirely with `tags`. - `merge` — alias for `add` (kept for naming clarity; behaves identically). | |
| target | Yes | ||
| changed | Yes | ||
| summary | Yes | ||
| tagsAfter | Yes | The full tag list after the mutation. | |
| tagsBefore | No |