Skip to main content
Glama
Sign In
immich-photo-manager

immich-photo-manager

by drolosoft
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

List people

list_people
Read-only

Browse all recognized people (face clusters) in your Immich library to see who appears in photos or retrieve a person's ID; use search_people to find someone by name.

Instructions

List all recognized people (face clusters) in the library. Use this to browse who appears in the photo library or find a person's ID. For searching by name, use search_people instead. Read-only.

Args:
    page: Page number, starting from 1 (default 1).
    size: Results per page (default 50).
    with_hidden: Include people marked as hidden (default false).

Returns: JSON with total count, page, and people array (each with id, name, thumbnailPath, photoCount).

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": "list_people"
  }
}

Input Schema

NameRequiredDescriptionDefault
pageNo
sizeNo
with_hiddenNo

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv1.2.1

TDQS

A4.7/5.0
Behavior4/5

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

Annotations already declare this is read-only and non-destructive, so the safety profile is covered. The description adds useful behavioral context: it operates on recognized face clusters, includes a hidden-person toggle, and paginates results. It does not discuss permissions or rate limits, but those are less critical for this simple read tool.

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 description is front-loaded and structured with clear Args and Returns sections. It is efficient, though the read-only statement and Returns section slightly duplicate the annotations and output schema.

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 paginated list tool with annotations and an output schema, the description is complete enough to call correctly. It covers purpose, when to use it versus search_people, all parameters, hidden filtering, and a brief result shape.

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. It documents all three parameters with practical meaning and defaults: page starts at 1, size is results per page, and with_hidden includes hidden people.

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 states a specific verb and resource: list recognized people, explicitly defined as face clusters. It distinguishes this browsing tool from search_people and notes that the ID can be obtained here, so the agent can separate it from siblings without inspecting 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 Guidelines5/5

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

It explicitly says to use this tool to browse people or find a person's ID, and directs name-based lookup to search_people. That is concrete when-to-use guidance plus a named alternative.

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

Deploy Server

Other Tools