immich-photo-manager

Overview Schema Source Related Servers Discussions Admin

Search metadata

search_metadata

Read-only

Find photos and videos by EXIF metadata such as city, country, camera model, date range, favorites, OCR text, people, tags, or albums when you know the exact criteria to match.

Instructions

Search assets by EXIF metadata fields. Use this when you know specific criteria like city, camera model, or date range. For natural language visual queries (e.g. 'sunset at the beach'), use search_smart instead. For browsing without criteria, use list_assets. Read-only.

Args:
    city: City name from EXIF GPS reverse-geocoding (case-sensitive, e.g. 'Barcelona').
    state: State or region name.
    country: Country name (e.g. 'Spain', 'Egypt').
    make: Camera manufacturer (e.g. 'Apple', 'Canon', 'Sony').
    model: Camera model string (e.g. 'iPhone 14 Pro', 'EOS R5').
    taken_after: ISO date — return only assets captured after this date.
    taken_before: ISO date — return only assets captured before this date.
    is_favorite: If true, only return favorites.
    asset_type: 'IMAGE' or 'VIDEO'. Omit for both.
    ocr: Text recognized inside the image (tickets, signs, documents). Needs
        OCR enabled on the server — check with get_capabilities.
    person_ids: Only assets showing ALL of these people (ids from list_people).
    tag_ids: Only assets carrying these tags (ids from list_tags).
    album_ids: Only assets inside these albums.
    page: Page number, starting from 1 (default 1).
    size: Results per page (1-200, default 50).

Returns: JSON with total match count, current page, and assets array with IDs, filenames, and dates.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "search_metadata"
  }
}

Input Schema

Name	Required	Description	Default
`ocr`	No
`city`	No
`make`	No
`page`	No
`size`	No
`model`	No
`state`	No
`country`	No
`tag_ids`	No
`album_ids`	No
`asset_type`	No
`person_ids`	No
`is_favorite`	No
`taken_after`	No
`taken_before`	No

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv2.0.2Sep 3, 2026

addedInput schema / properties / album_ids

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Album Ids"
+}

addedInput schema / properties / ocr

Added value: +{
+  "default": "",
+  "title": "Ocr",
+  "type": "string"
+}

addedInput schema / properties / person_ids

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Person Ids"
+}

addedInput schema / properties / tag_ids

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Tag Ids"
+}

First observedv1.0.0Apr 14, 2026

TDQS

A4.5/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the 'Read-only' line repeats structured data rather than adding to it. Beyond that it does disclose two real behavioral constraints: city matching is case-sensitive, and OCR requires a server capability that must be verified first. It does not cover result-ordering or what happens when criteria conflict (AND vs OR across fields), which matters for a 15-param conjunction filter.

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 routing guidance, then a scannable Args block — the right structure for a 15-param tool. The per-parameter prose is mostly tight, though a few entries (state, taken_after/taken_before) add little beyond a restatement of the field name.

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 wide conjunction filter with zero schema documentation this is close to complete: all 15 parameters are addressed, prerequisites are flagged, and pagination is described. An output schema exists, so the one-line return summary is a bonus rather than a necessity.

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?

With 0% schema coverage the description carries the full burden and mostly delivers: it supplies worked examples for city, country, make and model, documents the asset_type enum ('IMAGE' or 'VIDEO', omit for both) that the schema leaves as a bare string, states page/size bounds (1-200, default 50), and clarifies AND semantics for person_ids. The ocr parameter is the one soft spot — the prose implies a text query while the schema types it as a plain string with an empty default.

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 ('Search assets by EXIF metadata fields') and immediately separates itself from the two nearest siblings, search_smart for natural-language visual queries and list_assets for unfiltered browsing. An agent can route correctly without opening any schema.

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?

Explicitly says when to use this tool ('when you know specific criteria like city, camera model, or date range') and names the alternatives with the condition that selects each. It also gives a prerequisite path for the OCR path (check with get_capabilities).

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

Deploy Server