immich-photo-manager

Overview Schema Source Related Servers Discussions Admin

Update person

update_person

Destructive

Update a person's Immich profile to name unnamed faces, set birth dates, hide clutter, or change the representative thumbnail; only supplied fields are modified.

Instructions

Update a person's profile details. Use this to name unnamed faces, set birth dates, hide clutter faces, or change the representative thumbnail. Only provided fields are modified. Side effect: changes person metadata in Immich.

Args:
    person_id: The person's UUID.
    name: Display name (e.g. 'John Smith'). Set to name unnamed face clusters.
    birth_date: ISO date (e.g. '1990-05-15').
    is_hidden: Hide from the People view (useful for strangers/clutter).
    is_favorite: Mark as a favorite person.
    feature_face_asset_id: Asset UUID whose face crop becomes the person's thumbnail.
    color: Hex color label for UI grouping.

Returns: JSON with the updated person object.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "person_id": "<person_id>"
    },
    "name": "update_person"
  }
}

Input Schema

Name	Required	Description	Default
`name`	No
`color`	No
`is_hidden`	No
`person_id`	Yes
`birth_date`	No
`is_favorite`	No
`feature_face_asset_id`	No

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv1.2.1May 17, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Goes beyond the annotations by disclosing the partial-update contract ("Only provided fields are modified") and the concrete effect ("changes person metadata in Immich"), and explains what feature_face_asset_id actually does to the thumbnail. It is consistent with destructiveHint=true. It does not address reversibility, permissions, or what happens when an empty string is sent for name/birth_date/color — a real ambiguity given the schema defaults of "".

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 and usage before the argument list, and the per-argument lines are compact. Minor redundancy: "Set to name unnamed face clusters" restates the earlier "Use this to name unnamed faces," and the docstring-style Args/Returns headers are a little ceremonial for a tool description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter mutation tool this is close to complete: purpose, use cases, partial-update semantics, per-field meaning, and a note that a person object is returned (with an output schema present, return details are not needed). The gap is edge-case behavior around empty-string defaults and clearing vs. setting fields, which matters for a destructiveHint tool.

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 it: every one of the 7 parameters gets meaning plus format or example (person_id UUID, birth_date ISO '1990-05-15', name 'John Smith', is_hidden for strangers/clutter, feature_face_asset_id as the asset whose face crop becomes the thumbnail, color as a hex UI label). This adds substantially more than the bare schema titles.

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?

States a specific verb and resource ("Update a person's profile details") and then enumerates concrete jobs it does: naming unnamed faces, setting birth dates, hiding clutter faces, changing the representative thumbnail. That is enough for an agent to distinguish it from list_people, get_person, merge_people, and reassign_face without opening 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?

Gives explicit when-to-use scenarios ("Use this to name unnamed faces, set birth dates, hide clutter faces") and partial-update guidance ("Only provided fields are modified"). It does not name an exclusion or alternative — e.g. when to use merge_people instead, or that reassign_face is needed to move a face between people — so it stops short of full routing guidance.

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

Deploy Server