apple-photos-mcp

Overview Schema Source Related Servers Discussions Admin

set-keywords

Add or remove keywords on a photo while preserving existing tags. Provides before/after lists and shows only actual changes.

Instructions

Use when: you want to add and/or remove keywords (tags) on a photo — tagging workflows, fixing a mis-tag — without disturbing its other keywords. Returns: uuid, before/after keyword lists (revert by re-running with the diff inverted), added and removed (what actually changed — adding an existing keyword or removing an absent one is a no-op), and changed. Do not use when: you want to browse keywords — use list-keywords; or find photos by keyword — use query. A keyword passed in both add and remove is rejected. Safety: WRITE tool — disabled unless APPLE_PHOTOS_MCP_ENABLE_WRITES=1 (run doctor to check). UNION semantics — the photo's current keywords are read first and edits are merged in, so existing keywords you don't mention are ALWAYS preserved (never a blind replace). Metadata only — the image asset is untouched; the target photo is validated to exist first. Drives Photos.app via AppleScript (requires macOS Automation permission). Writes target the library currently open in Photos.app.

Input Schema

TableJSON Schema

Name	Required	Description
`add`	No	Keywords to add (created in Photos if new)
`uuid`	Yes	Photo UUID (hex-with-dashes, as returned by query)
`remove`	No	Keywords to remove from this photo (exact match)

Output Schema

TableJSON Schema

Name	Required	Description	Default
`uuid`	No
`added`	No
`after`	No
`before`	No
`changed`	No
`removed`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv2.1.13Sep 24, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Changed1 schema field changedv2.1.9Aug 7, 2026
- changedOutput schema / additionalProperties
```
Previous value: -falseNew value: +true
```
Addedv2.0.0Jul 10, 2026

TDQS

A5/5.0

Behavior5/5

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

With no annotations, the description carries full burden and does so exceptionally: it flags the WRITE nature, the environment variable gate, UNION semantics (no blind replace), metadata-only operation, pre-validation, AppleScript dependency, and permission requirement. This is comprehensive disclosure.

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

Conciseness5/5

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

The description is structured with clear sections (Use when, Do not use when, Safety) and every sentence adds value. It is dense but not rambling, and the most important guidance is front-loaded.

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?

For a write tool with side effects and external dependencies, it explains return fields (uuid, before/after, added/removed, changed), safety gates, and operational prerequisites. Nothing essential is missing for an agent to call it correctly.

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

Parameters5/5

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

Schema coverage is 100% but the description adds meaningful semantics: 'adding an existing keyword is a no-op', 'exact match' for remove, and the rejection of a keyword in both arrays. These are not in the schema and materially affect invocation.

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 description clearly states a specific verb ('add and/or remove keywords') and resource ('on a photo'), and explicitly distinguishes itself from siblings like list-keywords and query. It also provides use cases (tagging workflows, fixing mis-tags) which immediately conveys purpose.

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

Usage Guidelines5/5

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

Explicit 'Use when' and 'Do not use when' sections name the alternatives (list-keywords, query) and the conditions that route to them. It also warns about a specific edge case (keyword in both add and remove) which is actionable guidance.

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