immich-photo-manager

Overview Schema Related Servers Score Discussions

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v1.4.0
Disambiguation5/5
Each tool targets a distinct operation (albums, assets, tags, people, shared links, duplicates, trash, server info) with clear descriptions. Overlaps are minimal and well-differentiated (e.g., single vs batch thumbnails, specific vs bulk trash restore), so selection ambiguity is very low.
Naming Consistency5/5
Virtually all tools follow a consistent verb_noun pattern (e.g., create_album, list_tags, update_person). There are no mixed conventions like camelCase or inconsistent verb styles. The few exceptions (ping, rotate_assets) are still predictable and don't break the overall pattern.
Tool Count4/5
With 50 tools, the server covers a broad feature set (albums, assets, people, tags, sharing, duplicates, trash, metadata editing). While somewhat high, each tool is justified by Immich's capabilities. A few tools could be merged (e.g., restore_assets and restore_trash are distinct but related), but the count is reasonable for the scope.
Completeness4/5
The surface covers core CRUD operations, search (metadata and visual), duplicate resolution, sharing, and trash management. Minor gaps exist: no direct 'list all assets without filters' (list_assets requires at least one filter), and no batch move between albums (requires add/remove steps). These are workable but leave room for improvement.
Average 4.6/5 across 50 of 50 tools scored. Lowest: 3.8/5.
See the Tool Scores section below for per-tool breakdowns.
- 1 of 1 community issues answered or closed in the last 6 months
- 18 commits in the last 12 weeks
- Last stable release on July 27, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is failing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
This repository includes a glama.json configuration file.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
View related servers

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions 'Side effect: creates a new tag in Immich' and describes the return format, but it lacks details on authorization needs, rate limits, or other behavioral traits. The description is minimal for a creation tool without annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with only a few sentences. It front-loads the purpose, then provides usage hints, parameter details, and return information. No unnecessary words.
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?
The description covers purpose, usage hint, parameter semantics, and return value. Given the low complexity (2 params, one required) and the existence of an output schema (return fields mentioned), it provides sufficient context for an agent to use the tool correctly, despite missing annotations.
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?
Schema description coverage is 0%, but the description adds meaning by providing examples for 'name' (e.g., 'Vacation') and 'color' (e.g., '#FF5733'), and states that name must be unique. This compensates for the lack of schema descriptions.
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 clearly states 'Create a new tag for categorizing assets.' This is a specific verb+resource, and it differentiates itself from sibling tools like delete_tag, update_tag, and list_tags by being the creation operation.
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 description advises 'Use list_tags first to avoid duplicates,' providing clear guidance on when to use this tool and a prerequisite action. It does not explicitly mention when not to use it, but the given hint is valuable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry full behavioral burden. It mentions the side effect of creating an album in Immich but does not disclose potential errors (e.g., duplicate names), permissions required, or whether the operation is reversible. For a creation tool, this is adequate but not comprehensive.
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 concise (4 sentences) and includes a structured parameter breakdown. However, the parameter list could be integrated more seamlessly into the main description to be more front-loaded. No unnecessary words but slightly fragmented.
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?
Given the simple nature of the tool (create album with optional fields and pre-population), the description covers the main use case and return values. It lacks details on error handling or constraints (e.g., name uniqueness) but is sufficient for a basic creation operation. Siblings provide contrast.
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 fully compensates. It provides clear semantics for each parameter: name with an example format, description as optional text, asset_ids as optional list of UUIDs. It also explains the return value structure (id, name, asset count), which is not 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 description clearly states the tool creates a new album, optionally pre-populated with assets, distinguishing it from siblings like add_assets_to_album (adds to existing) or update_album. The verb 'create' and resource 'album' are specific and unambiguous.
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 description explicitly notes using the tool to organize photos into collections and mentions optional pre-population. However, it lacks explicit guidance on when not to use it (e.g., for adding assets to an existing album, use add_assets_to_album) or alternatives. Still, the context is clear enough for an AI agent to infer basic usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Declares 'Read-only' and describes return shape. No annotations exist, so description carries burden. Lacks details on permissions or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Short, front-loaded purpose, uses clear sections for Args and Returns. Every sentence adds value.
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?
Describes return format despite no output schema. Lacks error handling or permission details but adequate for a simple read operation.
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?
The schema provides no description for asset_id. The description adds 'The asset's UUID,' clarifying the parameter. This adds value beyond the raw 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?
Clearly states it retrieves detected faces with person assignments. Differentiates from siblings like reassign_face (modifies) and get_person (single person).
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?
Explicitly guides to use for seeing who is in a photo or finding face IDs for reassign_face. Lacks 'when not to use' but positive context is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description clearly states the side effect (only removes association, not the tag) and the return structure (tag_id, count, per-asset results). It also notes the constraint that asset_ids must not be empty. With no annotations, it carries the full burden but omits permissions or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short paragraphs with clear separation for Args and Returns. Every sentence provides necessary information without redundancy.
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?
The tool is simple and the description covers the core function, side effect, parameter constraints, and output shape. Given the output schema exists, the description is complete enough, though it could mention potential errors or rate limits for a higher score.
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 coverage, the description adds meaning: it specifies that tag_id is a UUID, asset_ids are UUIDs, and asset_ids must not be empty. This is more informative than the schema's type/title alone.
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 explicitly states the action 'Remove a tag from multiple assets', names the key resources (tag and assets), and distinguishes from sibling tools like 'delete_tag' (which deletes the tag itself) and 'tag_assets' (which adds the association).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (untagging many assets) but does not explicitly say when to choose this over alternatives, such as if a single asset needs untagging or if the tag should be deleted instead. No 'when-not' guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that changes are permanent (a key side effect) but does not cover authorization needs, rate limits, or error handling (e.g., what happens if asset_id is invalid).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a summary sentence, a list of use cases, a side effect note, and a parameter list. Every sentence adds value, and there is no fluff.
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?
Given the tool's complexity (7 parameters, mutation, output schema exists), the description covers purpose, param details, side effects, and return type. It lacks error handling or validation notes but is largely complete for a mutation tool without annotations.
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 compensates well by explaining each parameter: asset_id as UUID, date_time_original as ISO 8601 with example, lat/lon ranges, description as free-text, etc. This adds significant meaning beyond the schema types and defaults.
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 clearly identifies the tool as updating metadata on a specific asset, with explicit use cases (fix dates, correct GPS, etc.). It distinguishes from sibling tools which operate on albums, tags, or people, thus avoiding ambiguity.
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 description states when to use the tool (to fix dates, GPS, etc.) and notes that only provided fields are modified. However, it does not explicitly mention when not to use it or provide alternatives among sibling tools, which would strengthen guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It mentions a side effect ('changes person metadata in Immich') and states that only provided fields are modified. However, it does not discuss permissions, rate limits, or reversibility of actions like hiding a person.
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 well-structured with a brief overview paragraph followed by an Args list. It is front-loaded with purpose and every sentence is useful. However, the Args section could be slightly more concise, but overall efficient.
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?
Given the 7 parameters and lack of annotations, the description covers all parameters with context and explains the side effect. The return type is mentioned as 'JSON with the updated person object,' which is sufficient given the presence of an output schema (context signals indicate one exists). The description is fairly complete for a moderate-complexity 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?
The input schema has 0% description coverage, but the description provides detailed semantics for each of the 7 parameters in the Args section, including examples (e.g., '1990-05-15' for birth_date) and specific guidance (e.g., set name to name unnamed face clusters). This adds significant meaning beyond 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 description clearly states 'Update a person's profile details' and lists specific use cases like naming unnamed faces, setting birth dates, hiding clutter faces, and changing the thumbnail. This distinguishes it from sibling tools such as get_person or search_people.
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 description explicitly says 'Use this to name unnamed faces, set birth dates, hide clutter faces, or change the representative thumbnail.' This provides clear context for when to use the tool, though it does not mention when not to use it or suggest alternatives explicitly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses side effect of creating a publicly accessible URL, but lacks details on permissions, reversibility, or rate limits. Adequate but not exhaustive.
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?
Concise with front-loaded purpose and parameter list. Could be slightly more structured (e.g., separate sections), but no waste.
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?
Given parameter count, required fields, and output schema, description provides complete context for agent to invoke tool correctly, including side effect and return fields.
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 coverage is 0%, but description explains each parameter's purpose (e.g., 'allow_download: Allow visitors to download original files') and return value, adding meaning beyond 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?
Description clearly states the verb 'Create' and resource 'public shared link for an album', differentiating it from siblings like 'update_shared_link' and 'get_shared_link'.
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?
Explicitly says 'Use this to publish a gallery for external viewing', providing a clear use case. Does not mention when not to use or contrast with alternatives, but context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses side effect: 'Side effect: deletes all edit records for the assets.' No annotations provided, so description carries the full burden. This is sufficient for a revert operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is moderately concise, but includes a separate 'Args:' section that largely repeats parameter info from the schema description (which is absent). Could be tightened, but structure is logical: purpose, usage, args, returns.
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?
Given no output schema, the description provides return format ('JSON with reverted/failed counts'). Mentions side effect and mutual exclusivity. No annotations, but behavioral side effect is covered. Lacks error handling info, but acceptable.
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 coverage is 0%, but description adds full meaning: asset_ids (list of UUIDs, mutually exclusive with album_id) and album_id (revert all in album). Also clarifies the mutual exclusivity and provides argument context.
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?
Description uses specific verb 'remove' and resource 'non-destructive edits (rotation, crop, mirror) from assets', clearly distinguishing from siblings like rotate_assets. It explicitly states the restoration of original appearance.
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?
Provides explicit usage context: 'Use this to undo rotate_assets or any other display transforms.' Also explains mutual exclusivity of asset_ids and album_id. Lacks explicit when-not-to-use, but the non-destructive scope is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Mentions 'Side effect: adds tag association to assets' which is good, but lacks details on idempotency, error handling, or prerequisites. With no annotations, more behavioral context would be beneficial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences plus structured Args and Returns sections. No redundant information, every part is useful and front-loaded with purpose.
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?
Covers purpose, side effects, parameter details, and return format. Lacks error handling or limits, but for a straightforward bulk-operation tool, it is largely complete given the output schema exists.
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 coverage is 0%, but description includes a detailed Args section explaining each parameter's origin (tag_id from list_tags/create_tag) and constraints (asset_ids must not be empty), adding significant value.
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?
Description clearly states 'Apply a tag to multiple assets at once' with a specific verb and resource. It distinguishes from siblings like untag_assets and create_tag by noting bulk application.
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?
Provides a clear use case (bulk-categorize vacation photos) and lists required args. However, it does not explicitly discuss exclusions or when to use alternatives, though the context differentiates it from untag_assets.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses a side effect: 'modifies album membership.' This adds behavioral context beyond the schema. However, it does not mention authentication needs, rate limits, or other potential consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a clear action statement, usage context, side effect, then parameter details. Every sentence adds value with no redundancy.
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?
Given the simple nature of the tool (add assets to album), the description covers the core functionality. The return summary is helpful even though an output schema exists. However, it omits prerequisites like album existence and potential error handling details.
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?
The input schema has 0% coverage (no descriptions). The description's Args section provides clear semantics: 'Target album UUID' for album_id and 'List of asset UUIDs to add to the album' for asset_ids. This compensates for the schema's lack of descriptions.
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 clearly states the action: 'Add existing assets to an album.' It provides a specific use case: 'Use this to curate albums from search results or other asset lists.' This distinguishes it from sibling tools like 'create_album' (create new) and 'remove_assets_from_album' (remove).
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 description says when to use the tool (curate albums from lists) and notes that assets can belong to multiple albums simultaneously, which guides decision-making. It does not explicitly state when not to use it or list alternatives, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Declares 'Read-only' and describes the return format (JSON with total count and tags array). With no annotations provided, this sufficiently discloses the tool's non-destructive nature and output structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences: purpose, usage guidance, return format. No extraneous words, well-structured, and front-loaded with key information.
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?
Covers what, when, and return format. For a zero-parameter tool with an output schema, this is sufficient. Missing details on error handling or edge cases, but acceptable for a simple list operation.
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?
The input schema has 0 parameters, so baseline is 4. The description adds no parameter details, but none are needed. It appropriately implies no inputs.
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 clearly states 'List all tags in the library' with a specific verb and resource. It further explains usage context ('discover existing tags before creating new ones or to find a tag ID'), effectively distinguishing it from sibling tools like create_tag or get_tag.
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?
Explicitly advises using it to discover existing tags before creating new ones or to find tag IDs. While alternatives are not named, the context implies when to use this tool vs. others (e.g., get_tag for a single known tag).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses side effect: 'permanently changes face-to-person mapping' and return type. Lacks details on permissions or reversibility but acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences with clear structure: purpose, usage, args, returns. No wasted words; front-loaded with main action.
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 simple mutation tool with 2 required params and output schema present, description covers purpose, usage, side effect, and parameter semantics. Could mention error conditions or idempotency, but adequately complete.
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?
Schema coverage is 0% (only titles), so description compensates well. Explains face_id as 'from get_asset_faces results' and person_id as 'correct person UUID', adding meaning beyond 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?
Description clearly states the verb 'reassign' and the resource 'face to person', with explicit use case for correcting recognition mistakes. Distinguishes from sibling tools like 'merge_people' or 'update_person' which operate on different entities.
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?
Specifies when to use: 'correct face recognition mistakes' and provides prerequisite: 'Get face_id from get_asset_faces first'. Lacks explicit when-not-to-use or alternatives, but context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description mentions a side effect ('changes public link behavior immediately') but no annotations exist. It lacks disclosure on authorization needs or other behavioral traits, leaving some gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with a clear purpose, side effect note, and formatted Args/Returns sections. No unnecessary sentences.
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?
Given the output schema exists, description doesn't need to detail returns. It covers all 6 parameters, required field, and behavior, making it fully complete for the tool's complexity.
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 description coverage, the description fully compensates by explaining each parameter, including edge cases like empty string clearing values and removing expiry, adding significant meaning beyond 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 description clearly states it updates a shared link's permissions or expiry, using specific verb and resource. It distinguishes from related tools like create_shared_link and delete_shared_link.
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 description explains when to use the tool ('to tighten/loosen access or set an expiration date') but does not explicitly state when not to use it or provide alternatives, though context from sibling tools implies those.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses side effect 'changes apply to all assets using this tag' and optional parameters. No annotations provided, so description bears burden; it reasonably covers mutation behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise: two-sentence summary followed by parameter list. Every sentence adds value without redundancy.
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?
With low complexity (3 params), no annotations, and existing output schema, the description sufficiently covers purpose, side effects, and parameter meaning. No gaps.
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?
Input schema has 0% description coverage; description compensates fully by explaining tag_id as UUID, name as optional new name, and color as hex format with 'Omit to keep current'.
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?
Description clearly states 'Update a tag's name or color' with a specific verb and resource. The side effect mentions global application, distinguishing it from create_tag or delete_tag.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance. The description implies modification context but lacks direct comparison to sibling tools like create_tag or delete_tag.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavioral traits: default soft-delete, permanent deletion with force=true, side effect of moving/deleting, and return format.
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 well-structured with an Args section and clear separation of modes. It could be slightly more concise but remains efficient.
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?
Given the tool's complexity and lack of annotations, the description covers essential aspects: behavior, parameters, side effects, and return value. The existing output schema is referenced.
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?
Despite 0% schema coverage, the description adds meaning by explaining asset_ids as UUIDs and force default false, plus its effect on deletion permanence.
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 clearly states the tool deletes assets with two modes (soft-delete and permanent), and distinguishes it from restoring assets via restore_assets.
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 explains when to use (remove unwanted photos/videos) and provides context for the two modes, but doesn't explicitly state when not to use or alternative tools beyond restore_assets.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses side effects (permanently removes the link), scope (album and photos unaffected), and immediate impact (URL inaccessible). It lacks info on error handling for invalid link_id but is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence contributes value: purpose, side effects, parameter description, return value. No redundancy or filler. Efficiently structured.
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?
Given the simple tool (one parameter) and presence of an output schema, the description covers all necessary aspects: action, side effects, parameter, and return. Nothing essential 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?
The schema has no descriptions (0% coverage), but the description adds 'The shared link's UUID to delete', explaining the parameter's purpose and format. This compensates well for the missing schema details.
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 clearly states the action (delete/revoke a shared link) and the resource, with specific details like making the public URL immediately inaccessible. It distinguishes from sibling tools like create_shared_link or list_shared_links by its purpose.
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 description implies when to use the tool (to revoke a link) without explicitly naming alternatives or stating when not to use it. The context of siblings provides differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description effectively discloses read-only nature and the intentional masking of the API key. It also mentions thumbnails use base64 data URIs, adding useful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Five sentences, each serving a distinct purpose: main function, use case, security reason, read-only note, and return format. No waste.
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?
Given no parameters and presence of output schema, the description fully explains what the tool returns and why, making it complete for an agent to use correctly.
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?
No parameters exist, so the description does not need to add parameter info. It correctly focuses on the return values and usage.
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 clearly states it returns the Immich base URL and a masked API key, with a specific use case of populating gallery template placeholders. It is distinct from all sibling tools, which serve different purposes.
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 explicitly says when to use it (populate template placeholders) and explains the key masking for security. Could be more precise about when not to use, but the use case is well-defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description declares 'Read-only' and specifies return format (JSON with 'data' and 'type'). Adequate disclosure for a simple read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two paragraphs plus parameter description, each sentence adds value. No fluff, well structured.
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?
Simple operation with one parameter; description covers purpose, usage context, parameter, and output format completely.
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?
Schema description coverage is 0%, but description adds 'The person's UUID' to the parameter, clarifying its purpose beyond type/title.
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?
Specific verb+resource: 'Get a base64-encoded face crop thumbnail for a person.' Clear distinction from siblings like get_person or merge_people.
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?
Explicit when-to-use: 'Use this to visually identify a person before merging or renaming.' Lacks explicit when-not-to or alternatives, but context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It explicitly states 'Read-only' and describes the return format (major, minor, patch). This is adequate disclosure for a nondestructive, safe operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences with no wasted words. It front-loads the purpose and includes important details (read-only, return format) efficiently.
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 zero-parameter tool with an output schema, the description is complete. It explains the tool's purpose, behavior, and return structure, leaving no gaps for an AI agent to misunderstand.
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?
The input schema has no parameters and schema coverage is 100%, so the baseline is 4. The description does not need to add any parameter information, and it appropriately avoids redundancy.
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 clearly states the action ('Get') and resource ('Immich server version'), and provides specific use cases (check compatibility, report version), distinguishing it well from sibling tools like 'ping' or others.
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 description explicitly mentions when to use the tool ('to check compatibility or report the running server version'). It does not provide when-not-to-use or alternatives, but the context is sufficiently clear for a simple read-only operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description declares read-only and describes return format (photo count, video count, storage usage). Adequate disclosure for a simple statistics tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, front-loaded with purpose, then usage, then return format. No wasted words.
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?
Given the tool's simplicity and presence of output schema, the description covers purpose, usage context, and return structure fully. No missing information for a read-only statistics tool.
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?
No parameters in schema, so baseline 4 applies. Description does not need to add parameter info.
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 clearly states the verb-resource (Get library statistics) and distinguishes from siblings by noting it's for a quick overview without listing individual assets.
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?
Explicitly states when to use (quick overview) and implies when not (if you need individual assets, use list_assets). No explicit exclusions, but sufficient for context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the tool is 'Read-only,' a key behavioral trait. It also outlines the return structure, though it could mention that tag_id is required and must be valid.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with three lines covering purpose, usage, and return value. Every sentence adds value without redundancy.
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?
Given the tool's simplicity (one parameter, output schema present), the description fully covers what the tool does, how to use the parameter, and what is returned.
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 compensates by explaining that tag_id is 'The tag's UUID (from list_tags),' guiding the agent on how to obtain the ID.
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 clearly states 'Get details for a specific tag,' specifying the precise verb and resource. This distinguishes it from sibling tools like list_tags (list all tags) and create_tag.
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 description advises 'Use this to inspect a tag's properties. Read-only,' clearly indicating the tool's context. It does not explicitly exclude other tools, but the purpose is clear enough for appropriate selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses 'Read-only' nature, which is a key behavioral trait. Also describes return format (JSON with total count and links array with fields). Lacks details on authentication, rate limits, etc., but for a simple list operation, this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: two sentences plus a return description. Every sentence adds value. No fluff, front-loaded with purpose.
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?
Given no parameters and a simple list operation, the description fully covers purpose, behavior (read-only), and output format. Context signals indicate output schema exists, but description already details return fields. No gaps.
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?
Input schema has no parameters, so baseline is 4. Description does not add parameter info because none are needed. Schema coverage is 100%, so no gaps to compensate.
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?
Clearly states verb 'List' and resource 'shared links (public gallery URLs)'. Specifies use cases: see what's shared or find link ID for updates/deletion. Distinguishes sufficiently from siblings like get_shared_link, create_shared_link.
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?
Explicitly states when to use it: to see currently shared links or find link ID for updates/deletion. Does not explicitly mention when not to use or alternatives, but the context of list vs get is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It clearly states side effects: 'modifies album membership' and confirms no deletion. It also describes the return value structure. This adequately discloses behavior for a non-destructive operation.
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 relatively short (three sentences plus Args and Returns sections). Every sentence adds value: purpose, side effect, parameter details, output. Could be slightly more compact, but no filler.
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?
Given no annotations and no provided output schema, the description covers all necessary aspects: what the tool does, parameter roles, side effects, and return value. It is self-contained and sufficient for correct selection and invocation.
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?
The input schema has 0% coverage (no descriptions). The description fully explains both parameters: album_id as 'Album UUID' and asset_ids as 'List of asset UUIDs'. It also describes the output, adding significant meaning beyond 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 description clearly states the action: 'Remove assets from an album without deleting them.' It specifies the resource (album), verb (remove), and key constraint (assets remain in library and other albums). This distinguishes it from siblings like delete_assets and add_assets_to_album.
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 provides a clear use case: 'Use this to un-curate mistakenly added assets.' While it doesn't explicitly list when not to use or alternative tools, the use case is specific and implies context. Sibling differentiation is not explicit but is evident from the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions a side effect ('modifies album metadata in Immich') and describes parameter behavior ('Leave empty to keep current name/description'). It could disclose more about authorization or reversibility, but the provided context is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (4 lines plus Args and Returns sections) and front-loaded with the purpose. Every sentence adds value, and the structure is clear.
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?
Given the tool's simplicity (3 params, 1 required) and the presence of an output schema, the description covers the essential behavior and parameter details. It could mention error scenarios or additional effects, but it is complete enough for correct invocation.
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 description coverage, the description compensates fully by explaining each parameter: album_id as 'The album's UUID,' name and description with 'Leave empty to keep current.' This adds critical meaning absent from 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 description clearly states 'Update an album's name or description' and 'Use this to rename or re-describe an existing album,' providing a specific verb and resource. It distinguishes itself from sibling tools like create_album and delete_album.
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 description explicitly says 'Use this to rename or re-describe an existing album,' providing clear when-to-use guidance. It lacks explicit when-not-to-use or alternative tool mentions, but the context is sufficient for this straightforward tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses read-only nature and return format (JSON with fields). It lacks details on error handling or behavior for invalid IDs, but covers the essential behavioral trait of being non-destructive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a clear structure: purpose, usage guidelines, parameter explanation, and return summary. Every sentence adds value without redundancy.
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?
Given the tool's simplicity (one param, output schema exists), the description covers input, output, and usage context. It does not mention error cases, but for a read operation the essentials are present.
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?
The schema has 0% description coverage, but the description adds meaning by explaining asset_id is the UUID and where to obtain it (from search results, albums). This compensates well, though a bit more format specification could help.
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 explicitly states 'Get full metadata for a single asset.' and lists specific fields like EXIF, GPS, camera info, making the purpose highly clear. It also distinguishes from sibling tools by mentioning search_metadata and search_smart for finding assets.
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?
The description provides clear usage context: use when needing metadata for a known asset ID. It explicitly advises against using for finding assets and names alternatives (search_metadata, search_smart), offering excellent guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description labels the operation as read-only and notes the ML service dependency. Since no annotations are present, this covers essential behavioral traits without contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each serving a purpose: stating the action, providing usage context, and explaining the return format. No wasted words.
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?
Given zero parameters and an existing output schema, the description fully covers the tool's purpose and output structure, leaving no gaps.
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 zero parameters, the description adds value by detailing the return structure (JSON array with duplicateId, assets, similarity scores), going beyond the empty 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 description explicitly states it gets ML-detected duplicate asset groups, distinguishing it from sibling tools like resolve_duplicates by noting it is for review.
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 specifies to use this before resolving duplicates with resolve_duplicates and mentions the Immich ML service requirement, providing clear context but no explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does well: it states 'Read-only' (safety), 'Returns up to 500 markers' (limit), and includes a Returns section describing the output structure. It could additionally mention pagination or authentication requirements, but for a simple read operation, these are sufficient. The description provides key behavioral traits beyond what annotations might have covered.
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 well-structured: a main sentence, use case, sibling reference, read-only and limit statements, followed by an Args/Returns section. It is concise but not sparse. The pseudo-docstring format adds clarity though some information (like read-only) is repeated. Overall, it uses space efficiently and is easy to parse.
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?
Given the tool's low complexity (3 optional parameters, no required, no enums, output schema exists), the description covers all essential aspects: purpose, usage context, parameters, return structure, and limits. The output schema exists, so detailed return description isn't needed, but the description still outlines the output. The sibling differentiation also adds contextual completeness. There are no gaps that would hinder an AI agent from using the tool correctly.
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?
Schema description coverage is 0%, so the description must compensate. It lists all three parameters with explanations: file_created_after and file_created_before get ISO date examples, and is_favorite is described as 'If true, only return favorites.' This adds meaningful context beyond the schema, which only provides types and defaults. The descriptions are clear but could be slightly more detailed (e.g., date inclusivity), hence a 4.
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 clearly states the tool's purpose: 'Get GPS map markers for all geotagged assets.' It includes specific use cases (discover photo locations, build travel maps) and explicitly distinguishes from the sibling tool 'search_metadata' by noting that the sibling is for city/country searches. This provides a clear, specific verb+resource combination with sibling differentiation.
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?
The description gives explicit guidance: 'Use this to discover where photos were taken or to build travel maps. For searching by city/country name, use search_metadata instead.' This clearly states when to use the tool and when not to, with an alternative tool named, fulfilling the usage guidelines dimension fully.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states the tool is read-only, which discloses a key behavioral trait. It also describes the return content (JSON with details, permissions, expiry, assets). Since annotations are absent, this carries the full burden, and the description is sufficient for a simple retrieval operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of three efficient sentences plus an 'Args' and 'Returns' section. It is front-loaded with the purpose and reads naturally without unnecessary words.
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?
Given the tool's simplicity (one parameter, read-only, with an output schema), the description is complete. It explains the return content and parameter source, and no additional information (error handling, pagination) is expected for such a straightforward operation.
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?
The description provides explicit meaning for the single parameter, 'The shared link's UUID (from list_shared_links),' which adds value beyond the schema (only indicates type string). With 0% schema description coverage, the description fully compensates.
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 clearly states the tool retrieves full details of a shared link, including specific properties like permissions, expiry, and linked assets. It distinguishes from siblings like create_shared_link, update_shared_link, and list_shared_links by emphasizing inspection of a specific link.
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 description says 'Use this to inspect a specific link's configuration,' providing clear context for when to use it. It also mentions the link_id comes from list_shared_links, guiding the workflow. However, it does not explicitly state when not to use it or list alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully bears the burden of behavioral disclosure. It clearly labels the operation as 'DESTRUCTIVE and IRREVERSIBLE' and explains that merged persons are permanently deleted with faces transferred. It could mention if the operation is atomic or logged, but the core warning is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with no unnecessary words. It presents purpose first, then guidelines, then parameter details in a clear, structured manner. Every sentence adds value.
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?
Given 2 parameters, no annotations, and no output schema details, the description covers all necessary context: when to use, what happens to data, and what each parameter does. It is complete for an agent to select and invoke the tool correctly.
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 must explain parameters. It does so thoroughly: person_id as 'target person UUID to keep' and merge_ids as 'List of person UUIDs to absorb into the target' with their behavioral effects (permanently deleted). The description adds essential context beyond 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 description clearly states the action 'Merge multiple person clusters into one' and specifies the precise use case: when the same real person has been split into multiple face clusters. This distinguishes it from sibling tools like reassign_face or update_person.
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 description explicitly says when to use this tool ('Use this when the same real person has been split into multiple face clusters') and warns about destructiveness, providing clear context. It does not explicitly state when not to use, but the purpose is narrow enough that it's clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses a key side effect: moving rejected duplicates to trash. It also notes recoverability via restore_assets. This provides essential behavioral insight beyond basic mutation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences plus a structured Args block. Every sentence adds value, and the purpose is front-loaded. No redundant information.
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?
Given the single parameter and presence of an output schema, the description covers all necessary aspects: purpose, when to use, parameter structure, side effects, and return format. It references sibling tools appropriately.
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?
The input schema has zero description coverage (only 'type: object, additionalProperties: true'). The description fully compensates by detailing the exact fields required: duplicateId, assetIds, trashIds, with data types and source references. This is indispensable for correct invocation.
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 clearly states the tool resolves duplicate groups by choosing which assets to keep and trash, explicitly referencing the parent tool get_duplicates, which distinguishes it from sibling tools like merge_people or delete_assets.
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 provides clear context to use this after reviewing results from get_duplicates, and mentions that trashed assets can be recovered via restore_assets. While it doesn't explicitly state when not to use, the guidance is sufficient for typical workflows.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Declares 'Read-only' and describes return structure (total count, page, assets with IDs, filenames, dates). No annotations provided, so description effectively carries the burden.
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?
Well-structured with front-loaded purpose, guidelines, parameter details, and returns. Slightly verbose but every sentence adds value.
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?
Covers tool use, parameter meanings, and return format. With 11 params, no required, and output schema mentioned, description is comprehensive enough.
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 has 0% description coverage, but description explains all 11 parameters with examples (e.g., 'Barcelona', 'Apple', 'EOS R5'), hints (ISO date), and defaults (page=1, size=50).
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?
Description clearly states 'Search assets by EXIF metadata fields', specifying verb and resource. It distinguishes from siblings like 'search_smart' (natural language) and 'list_assets' (browsing).
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 tells when to use ('know specific criteria like city, camera model, or date range') and when not ('for natural language... use search_smart', 'for browsing... use list_assets').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description fully discloses that deletion is permanent and cannot be undone, and clarifies that photos remain. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences plus Args/Returns, no fluff. Essential information front-loaded.
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?
Given the simple tool with one param and an output schema, the description covers purpose, effects, and return format completely.
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?
The single parameter 'album_id' is described as 'The album's UUID to delete', adding meaning beyond the schema's 'Album Id' title. Schema coverage is 0%, but description compensates well.
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 clearly states 'Delete an album container' and emphasizes that photos inside are not deleted, distinguishing it from asset deletion tools.
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 says 'Use this to remove unwanted album groupings', providing usage context. It mentions permanence but lacks explicit alternatives like 'remove_assets_from_album'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It declares the operation as read-only, which is key. It also describes the return format. However, it does not mention potential pagination limits if 'all' is large, but given the context, this is minor.
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 concise and well-structured with a clear purpose and Args/Returns sections. However, the Args section slightly duplicates information already in the description, but overall efficient.
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?
Given the low complexity (1 optional param) and the presence of an output schema, the description covers all essential aspects: purpose, usage guidance, parameter behavior, and return format. No gaps.
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?
The description adds significant meaning for the single parameter 'shared': true for shared, false for non-shared, omit for all. This is much more informative than the schema's type (boolean or null) and covers all possible values.
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 clearly states the tool lists all albums with summary info. It distinguishes from siblings by specifying it's for discovery and finding album IDs, which contrasts with other tools like get_album for details or create_album for adding.
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 states when to use: to discover existing albums before creating new ones or to find an album ID. Also declares it's read-only, implicitly guiding away from mutation tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It clearly states the operation is read-only and describes the return format ('server' status with 'pong' if healthy). This fully informs the agent about behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with no wasted words. It front-loads the purpose and provides necessary details in just three lines.
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?
Given the tool's simplicity (0 parameters, straightforward output), the description covers all needed aspects: purpose, usage timing, read-only nature, and return format. It is fully complete.
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?
The input schema is empty (no parameters). The description adds no parameter details but compensates by explaining the return value, which is relevant since the agent must understand what the tool outputs.
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 clearly states the verb 'check' and the resource 'Immich server connectivity'. It distinguishes itself from sibling tools by indicating it's a readiness check, not a data manipulation operation.
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 description explicitly says to use this to verify reachability before other operations, providing clear context. It does not mention alternatives, but due to the tool's simplicity, this is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses the side effect of moving assets out of trash. However, no annotations are present, so the description carries the full transparency burden. Could mention error handling or permissions, but the side effect is a key behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences plus structured Args/Returns. Front-loaded with main purpose, no wasted words. The important guidance about selective recovery is placed early.
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?
Covers the essential information: what it does, when to use, side effect, parameter, and return value. Could be improved by mentioning validation or whether the operation is idempotent, but it's sufficient for safe usage.
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?
The description explains that 'asset_ids' is a list of asset UUIDs currently in trash, which adds context beyond the schema's type definition (array of strings). With 0% schema description coverage, the tool description effectively documents the parameter.
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?
Clearly states the verb 'restore', resource 'assets from trash', and destination 'active library'. Distinguishes from sibling 'restore_trash' by specifying selective recovery vs mass restore.
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 tells when to use this tool (selective recovery) and when not to use it (use restore_trash for everything at once), directly naming the alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description discloses side effect (moves all trashed assets back to active library) and return format (JSON success confirmation). Could mention if operation is reversible or requires permissions, but adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences with no wasted words. First sentence states purpose, second provides usage guidance, third adds behavioral detail and return info.
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 parameterless tool with an output schema, the description covers purpose, use case, side effect, and return format. No obvious gaps.
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?
Input schema has no parameters; description clarifies that it acts on all trashed assets globally, implying no user choice. No param info needed, baseline high.
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?
Description clearly states 'Restore ALL trashed assets back to the library' with specific verb and resource, and distinguishes from sibling tool 'restore_assets' which restores specific assets only.
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 (undo accidental bulk deletion) and provides alternative (restore_assets for specific assets).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description fully discloses behavioral traits: non-destructive, no file modification, display transform only, edits are written to Immich and accumulate, side effect of persisting rotation. With no annotations provided, the description carries the full burden and meets it exceptionally.
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 well-structured with a clear purpose statement, usage guidance, and an Args section. It is front-loaded with key information. However, a few extra words ('Provide EITHER...') could be trimmed without losing meaning.
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?
Given no annotations, three parameters with mutual exclusivity, and an output schema (implied), the description covers purpose, behavior, parameter usage, return value, and side effects. It is complete and leaves no significant gaps for an agent to invoke the tool correctly.
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?
The input schema has 0% description coverage, so the description compensates fully by explaining each parameter: angle (multiples of 90, default 90), asset_ids (list of UUIDs, mutually exclusive with album_id), album_id (string, mutually exclusive with asset_ids). It adds constraints and defaults not present 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 description clearly states the action (non-destructive clockwise rotation), the target (one or more assets), and the purpose (fix orientation issues). It distinguishes from related tools like revert_asset_edits and delete_assets, making its role unambiguous.
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 description explicitly states when to use the tool ('fix orientation issues') and mentions revert_asset_edits as an alternative for undoing. It also clarifies mutual exclusivity of asset_ids and album_id. However, it does not explicitly state when not to use it or compare to other rotation-like tools (none exist among siblings).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, description adds important behavioral details: read-only, returns results ranked by visual similarity, requires specific service. Does not cover potential limits or error conditions, but sufficient for typical use.
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?
Well-structured with front-loaded purpose and usage, followed by a clear Args list. Slightly verbose due to parameter explanations, but no unnecessary sentences.
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?
Given the complexity (8 parameters, 10+ siblings), the description covers prerequisites, usage distinctions, return format, and parameter details. Output schema exists, so return format info is supplementary.
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 coverage is 0%, but description provides thorough explanations for each parameter in the Args section, adding meaning beyond schema fields—e.g., defining query as natural language description and clarifying optional filters.
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?
Description clearly states it's an AI-powered visual search using CLIP embeddings for natural language descriptions, and distinguishes from search_metadata for structured criteria.
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 tells when to use this tool (describing photo appearance) vs alternative (search_metadata for structured criteria), and mentions the requirement: Immich ML service with Smart Search enabled.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses behavioral traits: permanent deletion, removal from all assets, and that assets themselves are unaffected. This is transparent and complete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences: first states action, second highlights side effect, third lists arguments and returns. Front-loaded with purpose, no unnecessary words.
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?
Given the tool's simplicity (one required parameter, no nested objects), the description covers purpose, parameters, side effects, and return value completely. Output schema exists but is not needed for completeness.
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?
The description adds meaning beyond the input schema by specifying that tag_id is a UUID, which is not implied by the schema's string type. It also clearly documents the argument and return format.
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 clearly states the verb 'Delete' and resource 'tag', and distinguishes from sibling tools like create_tag, update_tag, and untag_assets by specifying that it removes the tag from all assets and deletes it permanently.
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 description includes a side effect warning ('permanently deletes the tag (cannot be undone)'), which guides usage by emphasizing irreversibility. It lacks explicit alternatives but provides sufficient context for when to use the tool compared to other tag operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description declares 'Read-only' as a behavioral trait, which is clear. No annotations exist, so the description carries full burden. It adequately discloses it returns JSON with metadata and asset IDs, but does not mention potential side effects or permissions, which is acceptable for a simple getter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: front-loaded with purpose, then usage guidance, then parameter details. Every sentence is informative with no fluff.
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?
Given the tool's simplicity and existence of an output schema, the description is complete. It covers the purpose, usage context, parameter source, and return value overview. No gaps remain for typical usage.
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?
The schema has 0% description coverage, but the description adds meaning: 'album_id: The album's UUID (from list_albums or create_album).' This fully explains the parameter's nature and origin, adding significant value beyond 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 description clearly states 'Get full details for a specific album including all its asset IDs.' It uses a specific verb and resource, and distinguishes from sibling by mentioning 'For listing all albums, use list_albums instead.'
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?
Provides explicit context: 'Use this to inspect album contents or retrieve asset IDs for further operations.' Also gives when-not-to-use and alternative tool, and indicates where the album_id comes from (list_albums or create_album).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description reveals the read-only nature and the return format (JSON with 'data' and 'type'). It does not mention potential error scenarios but adequately discloses core behavior beyond what annotations would provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: purpose sentence, usage guidance, parameter details, return format. Every sentence adds value with no extraneous text.
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?
The description is complete for this simple tool, covering purpose, when to use, parameters, returns, and behavioral read-only trait. Even with an output schema existing, the description provides necessary context for an agent.
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?
Despite 0% schema description coverage, the description adds full meaning: asset_id is a UUID, size has two options with pixel dimensions and a default. This compensates entirely for the schema's lack of descriptions.
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 clearly states the tool retrieves a base64-encoded thumbnail for a single asset, using a specific verb and resource. It distinguishes itself from siblings by naming alternative tools for batch or album thumbnails.
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?
The description explicitly says when to use ('visually inspect one photo') and when not to (multiple photos: use get_thumbnails_batch or get_album_thumbnails). It also marks the operation as read-only, providing clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Declares 'Read-only' which is key behavioral disclosure. With no annotations, the description carries full burden; it also lists return fields. However, it does not mention potential errors or authorization, but for a simple read operation it is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no fluff: purpose, usage context, args/returns. Front-loaded with key information, every sentence earns 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?
Given a simple single-parameter tool with an output schema, the description adds necessary context about the person_id source and the fields included in the response, making it fully self-contained.
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?
Even though schema description coverage is 0%, the description adds crucial meaning: 'The person's UUID (from list_people or search_people)' explains the expected format and source, fully compensating for the schema gap.
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 clearly states the verb 'Get' and resource 'full details for a specific person including name, birth date, and photo count'. It distinguishes from siblings like list_people and search_people by focusing on a single person's detailed retrieval.
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 states 'Use this after finding a person via list_people or search_people', providing clear context for when to use and sourcing for the required person_id parameter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Mentions read-only nature and return format. No annotations provided, so description carries burden. Could add details on authentication or rate limits, but covers key behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, well-structured with Args and Returns sections. Every sentence adds value; no fluff.
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?
Complete for a batch thumbnail tool with output schema. Explains return structure and parameter constraints. No missing context.
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?
All three parameters are explained with details not in schema: asset_ids as UUIDs, size with pixel dimensions, limit with range and behavior. Compensates for 0% schema description coverage.
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?
Clearly states it retrieves base64-encoded thumbnails for arbitrary asset IDs without needing an album. Distinguishes from siblings like get_album_thumbnails and get_asset_thumbnail.
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 describes when to use (visual display of search results or ad-hoc sets) and when not to (use album-based for albums, single for single photos). Names alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states the tool is 'Read-only' and describes the return format, but does not disclose potential rate limits, authentication requirements, or any side effects beyond the listed behavior. However, for a simple read operation, the level of disclosure is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise yet comprehensive, with a clear structure: purpose, usage note, parameter block, and return note. Every sentence adds value, and the length is appropriate for the tool's complexity.
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?
Given the low complexity and the presence of an output description (though no formal output schema), the description covers all contextual needs: what the tool does, when to use it, parameters, and return format. It is fully self-contained.
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?
The description adds meaningful descriptions for each parameter (page, size, with_hidden) beyond the schema's basic type/default definitions. The schema had 0% coverage, but the description fully compensates by explaining the semantics.
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 clearly states the action ('list'), the resource ('all recognized people'), and the context (face clusters in the library). It also distinguishes the tool from its sibling `search_people`, avoiding ambiguity.
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?
The description explicitly tells when to use this tool ('browse who appears... or find a person's ID') and when not to ('For searching by name, use search_people instead'). This provides clear usage context and alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Declares 'Read-only' and describes return fields. No annotations provided, so description carries full burden. Missing details on potential errors or pagination, but sufficient for a simple search tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Five well-structured sentences, including an Args section. No wasted words.
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?
Covers purpose, usage, parameters, return format, and sibling differentiation. Output schema exists but description already mentions return fields. Complete for a simple tool with 2 parameters.
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 coverage is 0%, but description adds meaning for both parameters: name is case-insensitive partial match, with_hidden includes hidden people and default false. This goes beyond 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?
Description clearly states 'Search for people by name (partial match)' with a specific verb and resource. It distinguishes from sibling 'list_people' by noting that list_people is for browsing all.
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 'Use this when you know the person's name. For browsing all people, use list_people instead.' Provides clear when-to-use and alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses side effects: persists to disk, hot-swaps live connection, and validates credentials. Also mentions return structure (success status, counts, persistence path). No annotations provided, so description fully covers behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise with no wasted words. Structured in clear paragraphs: purpose, when to use, side effects, args, returns. Front-loaded with purpose.
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?
Covers all necessary aspects: purpose, usage, behavior, parameters, and return. Output schema exists, so return details are sufficient.
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 has 0% description coverage, but the description adds detailed explanations for both parameters, including expected format and example for base_url, and origin for api_key.
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?
Clearly specifies the verb 'Update' and the resource 'Immich connection credentials'. Distinct from sibling tools like get_connection_info (read-only).
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?
Explicitly states when to use: when API key is rotated or server URL changed. Does not mention when not to use, but the use case is specific enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and delivers thoroughly. It explains side effects (creates new asset), security restrictions (symlinks rejected), and that the original file is untouched. The return format is also described.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized, starting with a clear purpose, followed by constraints in a bullet-like format, and parameter details. Every sentence adds value with no redundancy.
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?
Given the tool's complexity, the description covers all necessary aspects: purpose, usage context, behavioral details, parameter semantics, and return value. No gaps are evident.
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?
Despite the input schema having no parameter descriptions (0% coverage), the description adds rich meaning: file_path is an absolute path that must exist, and album_id is an optional UUID for immediate album assignment. This fully compensates for the schema's lack of detail.
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 clearly states the verb 'Upload' and the resource 'local photo or video file to Immich', and specifies its use for ingesting new media. It distinguishes itself from sibling tools which perform other operations like album management or search.
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 provides explicit constraints (max 25MB, allowed types, symlinks rejected) and context for when to use the tool. However, it does not explicitly mention when not to use it or suggest alternatives, though the context of siblings makes it clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Labels as 'DESTRUCTIVE and IRREVERSIBLE' and describes side effects (permanently destroys trashed assets, frees storage). No annotations were provided, so description fully covers behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences plus a return line, all essential. Front-loaded with purpose and warning. No wasted words.
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 tool with no parameters and an output schema exists (return value described), the description is fully sufficient. Covers purpose, usage, side effects, and result.
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?
No parameters in input schema, so description need not explain them. It adds return value description ('Returns: JSON with success confirmation'). Baseline for 0 params is 4.
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 clearly states the verb 'permanently delete' and the resource 'ALL assets currently in trash'. It distinguishes from siblings like 'delete_assets' and 'restore_trash'.
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 advises to use only after user confirmation and provides an alternative tool ('delete_assets') for deleting specific items.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description states the tool is read-only, describes the return format (JSON with album info and thumbnails array including asset_id, base64 data, filename, date), and clarifies parameter behavior (size options with pixel dimensions, limit range). This full context compensates for the lack of annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise yet comprehensive: a clear purpose sentence, usage guidelines, read-only note, and structured parameter list with return details. No unnecessary words.
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?
Despite the tool having 53 siblings, the description sufficiently differentiates it and covers all needed context: input, output, behavior, and use case. The output schema exists, but the description still clarifies return structure, which is helpful.
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?
The input schema has 0% description coverage, but the description fully explains all three parameters: album_id (UUID), size (two options with default and pixel dimensions), and limit (range 1-50, default 20). This adds complete semantic meaning beyond 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 description clearly states the tool's purpose: 'Get base64-encoded thumbnails for photos in an album.' It explicitly distinguishes from the sibling tool get_thumbnails_batch, ensuring proper differentiation.
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?
Provides explicit guidance: 'Use this to generate visual HTML galleries from an existing album. For thumbnails from search results (no album), use get_thumbnails_batch instead.' This tells both when and when not to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden. It declares 'Read-only', explains each filter's behavior (true/false/omit), pagination defaults, and return format (total count, page, assets array with fields). This fully discloses behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a clear 'Args' section and 'Returns' section. Every sentence provides necessary information without redundancy. It is front-loaded with the core purpose.
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?
Given the tool's simplicity (6 optional params, pagination, no nested objects), the description fully covers input details, usage context, and return structure. Even though output schema exists, the description adds valuable return field names.
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 coverage is 0%, but the description thoroughly explains all 6 parameters: is_favorite (true/false/omit), is_archived, is_trashed, asset_type (IMAGE/VIDEO), page (starting 1), size (1-200, default 50). This adds extensive meaning beyond the schema's bare type definitions.
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 clearly states 'List assets with simple filters (no search query needed).' It specifies the verb (list) and resource (assets) with scope (filters by status/type). It distinguishes from siblings like search_metadata and search_smart by contrasting browsing versus specific search.
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?
The description explicitly says 'Use this to browse the library by status (favorites, archived, trashed) or type. For finding specific content, use search_metadata (structured) or search_smart (visual AI).' This provides clear when-to-use and when-not-to-use, naming specific alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![immich-photo-manager MCP server](https://glama.ai/mcp/servers/drolosoft/immich-photo-manager/badges/card.svg)](https://glama.ai/mcp/servers/drolosoft/immich-photo-manager)

Score Badge

Copy to your README.md:

[![immich-photo-manager MCP server](https://glama.ai/mcp/servers/drolosoft/immich-photo-manager/badges/score.svg)](https://glama.ai/mcp/servers/drolosoft/immich-photo-manager)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/drolosoft/immich-photo-manager'

If you have feedback or need assistance with the MCP directory API, please join our Discord server