immich-photo-manager

Overview Schema Source Related Servers Discussions Admin

Merge people

merge_people

Destructive

Merge duplicate face clusters for the same person into one target, previewing which person clusters are kept or deleted before confirming the irreversible merge.

Instructions

Merge multiple person clusters into one. Use this when the same real person has been split into multiple face clusters. DESTRUCTIVE and IRREVERSIBLE: merged persons are permanently deleted and all their faces transfer to the target. Without confirm=true nothing happens: the call returns who would be kept and who would disappear, so the user can check the names before the merge. Side effect: with confirm=true, permanently deletes the merged persons; without it the call only previews and changes nothing.

Args:
    person_id: The target person UUID to keep (receives all merged faces).
    merge_ids: List of person UUIDs to absorb into the target. These persons are permanently deleted.
    confirm: Pass true only after the user has seen the preview and agreed.

Returns: JSON with the preview (confirm_required, keep, merge, failed) or the
merge result.

Input Schema

Name	Required	Description	Default
`confirm`	No
`merge_ids`	Yes
`person_id`	Yes

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv2.0.2Sep 3, 2026

addedInput schema / properties / confirm

Added value: +{
+  "default": false,
+  "title": "Confirm",
+  "type": "boolean"
+}

Addedv1.2.1May 17, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Although annotations already declare readOnlyHint=false and destructiveHint=true, the description adds substantive detail beyond them: irreversibility, that merged persons are permanently deleted, that faces transfer to the target, and the two-mode behavior (preview with no confirm vs. destructive merge with confirm). The return shape (preview fields: confirm_required, keep, merge, failed) is also disclosed.

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

Conciseness4/5

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

Front-loaded with purpose, then the destructive warning, then the confirm workflow, then per-argument notes. However, the "Side effect:" sentence largely restates the earlier "DESTRUCTIVE and IRREVERSIBLE" sentence, and the Returns line partially duplicates the output schema, so a small amount of text does not earn its place.

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 destructive, multi-parameter mutation tool this covers what an agent needs: what is destroyed, what is preserved, how the preview mode works, and which parameter is the safe entry point. The presence of an output schema means the Returns line is optional rather than necessary, so nothing material is missing.

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 description coverage is 0%, so the description carries the full burden and does so: person_id is the target UUID that receives merged faces, merge_ids is the list of UUIDs that will be permanently deleted, and confirm gates whether anything is actually destroyed. This adds meaning well beyond the bare boolean/array/string types in the schema.

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 first sentence gives a specific verb and resource ("Merge multiple person clusters into one"), and the second disambiguates the exact scenario (one real person split across face clusters). This clearly separates it from siblings like get_person, list_people, update_person, and reassign_face without needing the schema.

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

Usage Guidelines4/5

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

It states a clear trigger condition (duplicate face clusters for the same real person) and an explicit precondition for the confirm flag (only after the user has seen the preview and agreed). It does not name a sibling alternative such as reassign_face for the single-face case, so the guidance is strong but not fully closed.

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

Deploy Server