immich-photo-manager

Overview Schema Source Related Servers Discussions Admin

Update assets metadata

update_assets_metadata

Destructive

Apply the same metadata fields to many Immich assets in one call, such as setting a scanned album's real date, adding trip GPS coordinates, or marking a selection as favorites.

Instructions

Update the same metadata fields on many assets in ONE call — the whole roll of a scanned album gets its real date, a trip's photos get their GPS, a selection becomes favorites. Same fields as update_asset_metadata; only the provided ones change. Side effect: permanently changes the metadata of every listed asset.

Args:
    asset_ids: The assets to update.
    date_time_original: ISO 8601 datetime applied to all of them.
    latitude: GPS latitude, decimal degrees.
    longitude: GPS longitude, decimal degrees.
    description: Description/caption applied to all of them.
    is_favorite: Set favorite status on all of them.
    rating: -1 to reject them, or 1 to 5 stars. A rating cannot be cleared
        from here, and 0 is not a rating Immich 3.x accepts.

Returns: JSON with success and the number of assets updated.

Input Schema

Name	Required	Description	Default
`rating`	No
`latitude`	No
`asset_ids`	Yes
`longitude`	No
`description`	No
`is_favorite`	No
`date_time_original`	No

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv2.0.2Sep 3, 2026

TDQS

A4.3/5.0

Behavior4/5

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so irreversibility is partially covered; the description still adds real context by stating the partial-update contract ("only the provided ones change") and scoping the side effect to every listed asset. It also surfaces non-obvious behavioral limits — rating cannot be cleared here, and 0 is invalid on Immich 3.x. It does not mention permission requirements or whether per-asset failures are reported, which is the remaining gap for a bulk mutation.

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?

The first sentence front-loads the essential distinction (batch, one call, only provided fields change), followed by illustrative examples, then Args/Returns sections. The Args block largely restates parameter names already present in the schema, but with 0% coverage that restatement is load-bearing rather than wasteful. Minor trimming of the 'Args:' framing would make it tighter.

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 bulk mutation with zero schema documentation, the description covers purpose, the partial-update contract, every parameter's meaning, and the irreversibility of the write. The Returns line is somewhat redundant given an output schema exists, and the empty-string-vs-null semantics for description/date_time_original are unaddressed, but nothing critical to invoking it correctly is missing.

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

Parameters4/5

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

With 0% schema description coverage, the description carries the full burden and mostly succeeds: it documents all seven parameters including formats (ISO 8601 for date_time_original, decimal degrees for lat/long) and a genuinely non-inferable rating contract (-1 rejects, 1-5 stars, no clearing, 0 invalid). It leaves one real ambiguity — description and date_time_original default to empty string, so it is unclear whether an empty string means 'no change' or 'clear the field', which conflicts with the 'only provided ones change' promise.

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?

"Update the same metadata fields on many assets in ONE call" gives a specific verb, resource, and batch scope, and the phrase "Same fields as update_asset_metadata" explicitly distinguishes it from the single-asset sibling. The three concrete examples (scanned album roll, trip GPS, selection favorites) remove any ambiguity about what 'many assets' means in practice.

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?

The scenario examples give clear conditions for reaching for this tool (bulk date correction, bulk geotagging, bulk favoriting), and naming update_asset_metadata as the field-equivalent sibling implicitly points at the single-asset alternative. There is no explicit 'use X instead when' statement or exclusion (e.g., don't use for a single asset), so the routing 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