immich-mcp

Server Quality Checklist

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

Latest release: v0.1.0
Disambiguation4/5
Tools are well-organized by resource categories (e.g., assets, albums, people, duplicates), with clear distinctions within each group. However, some potential overlap exists between 'immich.assets.list' and 'immich.search.metadata' for filtering assets, though their primary purposes differ (general listing vs. targeted search).
Naming Consistency5/5
Naming follows a highly consistent pattern: all tools use snake_case with a clear 'immich.resource.action' structure (e.g., 'immich.albums.create', 'immich.people.update'). This uniformity makes the toolset predictable and easy to navigate across all 43 tools.
Tool Count3/5
With 43 tools, the count is high and may feel heavy for an MCP server, potentially overwhelming for agents. While the domain (photo management) is broad, the toolset could benefit from consolidation or scoping down to core workflows to improve usability.
Completeness5/5
The toolset provides comprehensive coverage for photo management, including full CRUD operations for assets, albums, people, tags, and shared links, plus advanced features like duplicates handling, search, and statistics. No obvious gaps are present; agents can perform end-to-end workflows without dead ends.
Average 3.6/5 across 43 of 43 tools scored. Lowest: 2.9/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 11 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
Add a LICENSE file by following GitHub's guide. Once GitHub recognizes the license, the system will automatically detect it within a few hours.
If the license does not appear after some time, you can manually trigger a new scan using the MCP server admin interface.
MCP servers without a LICENSE cannot be installed.
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.
Add a glama.json file to provide metadata about your server.
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.
Add related servers to improve discoverability.

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?
Annotations only provide a title ('Create Activity'), so the description carries the burden of behavioral disclosure. It mentions the action ('Add a comment or like') but does not disclose key traits like authentication needs, rate limits, whether it's idempotent, or what happens on success/failure. This is inadequate for a mutation tool with minimal annotation coverage.
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 a single, efficient sentence that directly states the tool's purpose without unnecessary words. It is front-loaded and wastes no space, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a mutation tool with no output schema and minimal annotations, the description is insufficient. It lacks details on behavioral traits, error handling, or return values, leaving gaps in understanding how to use the tool effectively in context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75%, with parameters like 'album_id' and 'type' well-described in the schema. The description adds minimal value by implying 'album or specific asset' relates to 'album_id' and 'asset_id', but it does not clarify semantics beyond what the schema provides, such as format details or dependencies between parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add a comment or like') and the target resources ('album or specific asset within an album'), which is specific and actionable. However, it does not explicitly differentiate from sibling tools like 'immich.activities.delete' or 'immich.activities.list', which handle deletion and listing of activities respectively, so it misses full sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as when to choose 'immich.activities.create' over other activity-related tools or when not to use it (e.g., for updates or deletions). It lacks explicit context, prerequisites, or exclusions, offering only a basic functional statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only provide a title ('Create Album'), so the description carries full burden. It states the tool creates an album, implying a write operation, but lacks details on permissions, side effects (e.g., if asset IDs must exist), error handling, or response format. This is inadequate for a mutation tool with no annotation coverage.
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 a single, efficient sentence that front-loads the core action ('Create a new album') and includes key optional feature ('with an optional list of asset IDs'). There is no wasted text, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 3 parameters, low schema coverage (33%), no output schema, and minimal annotations, the description is incomplete. It lacks details on behavioral aspects, parameter usage, and expected outcomes, failing to compensate for the structured data gaps, which could hinder effective tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low (33%), with only 'album_name' documented. The description mentions 'optional list of asset IDs,' which hints at 'asset_ids' parameter, adding some value. However, it doesn't explain 'description' parameter or provide deeper semantics like format constraints, leaving gaps despite partial compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create a new album') and resource ('album'), which is specific and unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'immich.albums.update' or 'immich.shared_links.create' that might also create related resources, missing full sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. For example, it doesn't mention prerequisites (e.g., needing asset IDs from other tools), when to use 'immich.albums.update' instead for modifications, or any context-specific triggers, leaving usage unclear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only provide a title ('Create Shared Link'), offering no structured hints about behavior. The description adds that it creates shareable links with optional expiry and password settings, but fails to disclose critical behavioral traits: whether this requires authentication, what permissions are needed, if links are publicly accessible, rate limits, or what the response contains. For a creation tool with minimal annotations, this leaves significant 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 a single, efficient sentence that front-loads the core purpose and mentions key optional features. Every word earns its place with zero redundancy or unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 9 parameters, low schema coverage (22%), no output schema, and minimal annotations, the description is inadequate. It doesn't explain the relationship between parameters (e.g., how 'type' affects 'album_id' and 'asset_ids'), what the tool returns, error conditions, or authentication requirements. The context signals indicate high complexity that isn't addressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low at 22%, with only 2 of 9 parameters having descriptions. The description adds minimal context by mentioning 'album or specific assets' (mapping to 'type') and 'expiry and password' (mapping to two parameters), but doesn't explain the semantics of other key parameters like 'allow_download', 'allow_upload', or 'show_metadata'. It partially compensates for the schema gap but not sufficiently.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create a shareable link') and the target resources ('for an album or specific assets'), which provides a specific verb+resource combination. However, it doesn't explicitly distinguish this tool from its sibling 'immich.shared_links.update' which might also create or modify links, leaving some ambiguity about when to use create versus update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'immich.shared_links.update' or 'immich.shared_links.get'. It mentions optional features (expiry and password) but doesn't explain prerequisites, dependencies, or contextual constraints for creating shared links.
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?
Annotations provide readOnlyHint=true, indicating this is a safe read operation. The description adds context about what can be searched (metadata filters) but doesn't disclose behavioral traits like pagination behavior (implied by page/page_size parameters), rate limits, authentication requirements, or what happens with partial/null filters. No contradiction with annotations.
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?
Single sentence efficiently lists the search scope and filter types. No wasted words, though it could be more structured by grouping related filters or mentioning pagination. Appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with 13 parameters, 38% schema coverage, no output schema, and read-only annotations, the description is minimally adequate. It covers the search intent and filter categories but lacks details on parameter interactions, result format, pagination behavior, and usage context. Completeness is borderline given the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 38%, with most parameters having only titles. The description lists general filter categories (date range, type, location, camera model, person, filename) which maps to some parameters (type, city/country, make/model, person_id, taken_after/before) but doesn't explain semantics for query, is_favorite, is_archived, page, or page_size. It adds some value but doesn't fully compensate for the low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/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: 'Search assets using metadata filters' with specific filter types listed (date range, type, location, camera model, person, filename). It distinguishes from siblings like 'immich.search.smart' and 'immich.search.explore' by specifying metadata-based search, but doesn't explicitly contrast with them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'immich.search.smart' or 'immich.search.explore'. The description lists filter types but doesn't provide context about when metadata search is preferred over other search methods or what prerequisites might exist.
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?
Annotations provide idempotentHint=true, indicating safe retries, but the description adds no behavioral context beyond what's implied by 'Update.' It doesn't disclose permission requirements, rate limits, or effects on existing settings. However, it doesn't contradict annotations (idempotency aligns with update operations), so it earns a baseline score for adding minimal value beyond structured data.
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 a single, efficient sentence that front-loads the core action and key parameters. Every word contributes directly to understanding the tool's function, with no redundant or vague phrasing. It's appropriately sized for a mutation tool with multiple parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/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 operation) and lack of output schema, the description is insufficient. It omits critical context: no mention of required permissions, error conditions, response format, or how null values are handled for optional parameters. Annotations cover idempotency but not other behavioral traits, leaving significant gaps for agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low (29%), with only 'shared_link_id' and 'expires_at' documented. The description mentions 'expiry, password, download permission,' covering 3 of 7 parameters but lacking details on 'allow_upload,' 'show_metadata,' and 'description.' It adds some meaning beyond the schema (e.g., clarifying 'download permission' relates to 'allow_download'), but doesn't fully compensate for the coverage gap, aligning with the baseline for partial compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update') and resource ('shared link settings'), specifying three key fields (expiry, password, download permission). It distinguishes from sibling tools like 'immich.shared_links.create' (creation) and 'immich.shared_links.remove' (deletion), though it doesn't explicitly mention these distinctions. The purpose is specific but could be slightly more precise about the full scope of settings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an existing shared link), exclusions, or comparisons to sibling tools like 'immich.shared_links.create' for initial setup or 'immich.shared_links.remove' for deletion. Usage is implied from the verb 'Update,' but explicit context is missing.
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?
Annotations already indicate destructiveHint=true and idempotentHint=true, so the agent knows this is a destructive but idempotent operation. The description adds minimal context by specifying what gets deleted ('a comment or like'), but doesn't cover aspects like authentication needs, rate limits, or error conditions. No contradiction with 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 a single, clear sentence with no wasted words. It's front-loaded with the key action ('Delete') and efficiently conveys the purpose without unnecessary elaboration, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (simple deletion with one parameter), high schema coverage (100%), and annotations covering destructive/idempotent hints, the description is minimally adequate. However, without an output schema, it doesn't explain return values or potential errors, leaving some gaps for agent understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the parameter 'activity_id' fully documented as 'Activity UUID'. The description adds no additional meaning beyond the schema, such as format details or examples. Baseline 3 is appropriate when the schema handles parameter documentation effectively.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete') and the resource ('a comment or like by activity ID'), providing specific verb+resource. However, it doesn't explicitly differentiate from sibling tools like 'immich.activities.create' or 'immich.activities.list', which would require a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'immich.activities.create' or 'immich.activities.list'. It lacks context about prerequisites, such as needing an existing activity ID, and doesn't mention any exclusions or specific scenarios for 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?
Annotations already declare readOnlyHint=true and idempotentHint=true, indicating this is a safe, repeatable read operation. The description adds some context by specifying what's listed (comments and likes) and the optional filtering capability, but doesn't disclose behavioral traits like pagination, rate limits, or authentication needs beyond what annotations 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 a single, efficient sentence that front-loads the core purpose ('List comments and likes for an album') and includes the optional filtering detail without waste. Every word earns its place, making it appropriately sized and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (3 parameters, 1 required), annotations cover safety (read-only, idempotent), but no output schema exists. The description explains the resource and filtering, yet lacks details on return format, error handling, or integration with sibling tools. It's adequate but has clear gaps for a list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67%, with parameters 'album_id' and 'type' having descriptions, while 'asset_id' lacks one. The description mentions 'optionally filtered by asset,' which loosely relates to 'asset_id,' but doesn't add meaningful semantics beyond what the schema provides. With moderate schema coverage, the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/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: 'List comments and likes for an album, optionally filtered by asset.' It specifies the verb ('List'), resource ('comments and likes'), and scope ('for an album'). However, it doesn't explicitly differentiate from sibling tools like 'immich.albums.list' or 'immich.activities.statistics', which would require a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides minimal guidance with 'optionally filtered by asset,' but doesn't explain when to use this tool versus alternatives like 'immich.activities.statistics' or 'immich.albums.get' for album details. No explicit when/when-not scenarios or prerequisites are mentioned, leaving usage context vague.
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?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the agent knows this is a safe, repeatable read operation. The description adds minimal behavioral context beyond this—it specifies what data is retrieved (comment count) but doesn't cover aspects like rate limits, authentication needs, or error conditions. With annotations covering key safety traits, the description adds some value but lacks depth.
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 a single, efficient sentence that front-loads the core purpose without unnecessary words. Every part earns its place by specifying the action, resource, and scope, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/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 (2 parameters, no output schema) and annotations covering safety, the description is minimally complete. It states what the tool does but lacks details on usage context, parameter nuances, or behavioral traits. For a simple read operation, this is acceptable but leaves gaps that could hinder optimal agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (only 'album_id' has a description), and the description mentions both parameters ('album' and 'specific asset') but doesn't elaborate on their semantics beyond what's implied. It adds marginal value by clarifying that 'asset_id' is optional for counting comments at the album level, but doesn't explain format or constraints. Given the partial schema coverage, this is adequate but not compensatory.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/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 comment count for an album or specific asset within an album.' It specifies the verb ('Get'), resource ('comment count'), and scope ('album or specific asset within an album'), making the function unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'immich.assets.statistics' or 'immich.people.statistics', which prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, exclusions, or compare it to related tools like 'immich.activities.list' or other statistics tools in the sibling list. The agent must infer usage from the purpose alone, which is insufficient for optimal selection.
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?
Annotations provide idempotentHint=true, indicating safe retry behavior. The description adds minimal behavioral context beyond this, stating the basic action but not covering aspects like permission requirements, rate limits, or what happens if assets are already in the album. It doesn't contradict annotations, but adds limited value given the annotation coverage.
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 a single, clear sentence that efficiently communicates the core functionality without any wasted words. It's appropriately sized and front-loaded with the essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with idempotentHint annotation but no output schema, the description is minimally adequate. It covers the basic action but lacks details about return values, error conditions, or the broader context of album-asset relationships that would help an agent use it effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, both parameters are well-documented in the schema (album UUID and asset UUIDs list). The description doesn't add any meaningful parameter semantics beyond what's already in the structured schema, so it meets the baseline of 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add') and target resources ('one or more assets to an album'), providing a specific verb+resource combination. However, it doesn't explicitly differentiate from its sibling 'immich.albums.remove_assets' beyond the opposite action, missing explicit sibling distinction that would warrant a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There's no mention of prerequisites (e.g., album must exist), when not to use it, or comparison with related tools like 'immich.albums.create' or 'immich.albums.update' for album management.
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?
Annotations already declare readOnlyHint=true and idempotentHint=true, indicating this is a safe, repeatable read operation. The description adds minimal behavioral context by specifying that it retrieves 'full details' and 'including its assets,' which clarifies scope beyond just basic album info. However, it doesn't disclose additional traits like rate limits, authentication needs, or response format, 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 a single, efficient sentence that front-loads the core purpose ('Get full details of an album') and adds a key detail ('including its assets') without any wasted words. Every part earns its place, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (2 parameters, no output schema), annotations cover safety (read-only, idempotent), but the description lacks details on return values, error conditions, or asset inclusion nuances. It's adequate for a basic read operation but incomplete for full agent understanding, especially without an output schema to clarify response structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (only 'album_id' has a description), and the description doesn't add any parameter-specific details beyond what the schema provides. It implies asset inclusion but doesn't explain the 'without_assets' parameter's effect or usage. With moderate schema coverage, the baseline score of 3 is appropriate as the description doesn't compensate for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/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 of an album including its assets'), making the purpose specific and understandable. However, it doesn't explicitly differentiate from sibling tools like 'immich.albums.list' (which likely lists albums without full details) or 'immich.assets.get' (which gets individual assets), so it misses full sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an album ID), exclusions, or comparisons to siblings like 'immich.albums.list' for listing albums or 'immich.assets.get' for asset details, leaving usage context implied at best.
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?
Annotations provide 'idempotentHint: true', indicating safe retries, but the description adds minimal behavioral context. It mentions updating metadata fields, which aligns with annotations, but does not disclose permissions needed, rate limits, or effects on existing data. No contradiction with annotations exists, but the description lacks depth beyond the basic 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 a single, efficient sentence that directly states the tool's purpose and scope. It is front-loaded with the core action and includes no unnecessary details, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (4 parameters, mutation operation) and lack of output schema, the description is minimally adequate. It covers what can be updated but lacks details on behavior, error handling, or return values. With annotations providing idempotency, it meets a baseline but could be more informative for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low (25%), with only 'album_id' documented. The description lists updatable fields (name, description, cover asset), which correspond to parameters 'album_name', 'description', and 'album_thumbnail_asset_id', adding some meaning. However, it does not explain parameter formats, constraints, or interactions, leaving gaps in understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update') and resource ('album metadata'), specifying the fields that can be updated (name, description, cover asset). It distinguishes from sibling tools like 'immich.albums.create' (for creation) and 'immich.albums.delete' (for deletion), but does not explicitly differentiate from 'immich.albums.get' (for retrieval) or 'immich.albums.list' (for listing).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., needing an existing album), exclusions (e.g., not for adding/removing assets), or refer to sibling tools like 'immich.albums.add_assets' or 'immich.albums.remove_assets' for related operations.
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?
Annotations already declare readOnlyHint=true and idempotentHint=true, indicating safe, repeatable read operations. The description adds value by specifying 'full metadata' (implying comprehensive data retrieval) and 'single asset' (clarifying scope), but doesn't disclose additional behavioral traits like rate limits, authentication needs, or error handling. No contradiction with annotations exists.
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 a single, front-loaded sentence that efficiently conveys the core purpose without unnecessary words. Every part ('Get full metadata', 'for a single asset', 'by its ID') contributes directly to understanding, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/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 (single parameter, no output schema) and rich annotations (readOnlyHint, idempotentHint), the description is adequate but incomplete. It lacks details on output format (e.g., what 'full metadata' includes), error cases, or integration with sibling tools, which could enhance agent decision-making despite the annotations covering safety aspects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the parameter 'asset_id' fully documented as 'Asset UUID'. The description adds minimal semantic context by implying the ID is used to fetch metadata, but doesn't provide extra details like format examples or validation rules. Baseline 3 is appropriate given high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get full metadata') and resource ('for a single asset by its ID'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'immich.assets.list' (which retrieves multiple assets) or 'immich.assets.view' (which might serve a different purpose), missing full sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention scenarios like retrieving detailed metadata for a specific asset versus listing multiple assets, nor does it reference sibling tools like 'immich.assets.list' for broader queries, leaving usage context implied at best.
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?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the agent knows this is a safe, repeatable read operation. The description adds that it 'Returns paginated results,' which is useful behavioral context not covered by annotations. However, it doesn't describe error conditions, rate limits, authentication requirements, or what constitutes an 'asset' in this system.
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 perfectly concise: two sentences with zero waste. The first sentence states the core purpose, the second adds critical behavioral information (paginated results). Every word earns its place, and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with read-only/idempotent annotations, the description is minimally adequate. It covers the pagination behavior but doesn't explain what an 'asset' represents in this system, doesn't describe the return format (no output schema exists), and doesn't clarify filter semantics. Given 6 parameters with only 50% schema coverage, the description should do more to compensate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (3 of 6 parameters have descriptions). The description mentions 'optional filters' which aligns with parameters like is_favorite, is_archived, is_trashed, and type, but doesn't explain what these filters mean or their relationships. It adds minimal value beyond the schema, which already documents page, page_size, and type parameters adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/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: 'List assets with optional filters.' This specifies the verb ('List') and resource ('assets'), and mentions filtering capability. However, it doesn't differentiate from sibling tools like 'immich.assets.get' (single asset) or 'immich.search.*' tools, which could also retrieve assets in different ways.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'immich.assets.get' (for single assets), 'immich.search.*' tools (for different search methods), or 'immich.albums.list' (for album-based asset grouping). The agent must infer usage context from the tool name alone.
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?
Annotations provide 'idempotentHint: true', indicating safe retry behavior, but the description doesn't add behavioral context beyond this. It doesn't disclose whether this requires specific permissions, if changes are reversible, rate limits, or what happens to unspecified fields (e.g., are they preserved or reset?). With annotations covering idempotency, the bar is lower, but the description adds minimal value—it only confirms the update action without enriching behavioral understanding.
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 a single, efficient sentence that front-loads the core action ('Update metadata for a single asset') and specifies the fields without unnecessary words. Every part earns its place by clarifying scope and parameters, making it easy to parse quickly. There's no redundancy or wasted verbiage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (5 parameters, mutation operation) and annotations covering idempotency, the description is adequate but has gaps. It lacks output schema, so return values aren't explained, and it doesn't address error cases or dependencies. For a metadata update tool, it should ideally mention permission requirements or side effects, but with annotations providing some safety context, it meets a baseline level of completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low at 20%, with only 'asset_id' and 'rating' having descriptions. The description lists the updatable fields (favorite, archived, description, rating), which helps clarify what each parameter controls, adding meaning beyond the schema's titles. However, it doesn't explain semantics like how 'null' values are handled for optional fields or the implications of updating specific metadata, so it partially compensates but doesn't fully bridge the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Update') and resource ('metadata for a single asset'), and specifies the exact fields that can be updated (favorite, archived, description, rating). It distinguishes this tool from other asset tools like 'immich.assets.bulk_update' by specifying 'single asset' and from 'immich.assets.delete' by focusing on metadata updates rather than deletion. However, it doesn't explicitly differentiate from 'immich.assets.get' or 'immich.assets.list' in terms of purpose, though the update action is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when to choose this over 'immich.assets.bulk_update' for multiple assets, or how it relates to other asset operations like 'immich.assets.get' or 'immich.assets.delete'. There's no context about prerequisites, such as needing the asset ID, or any exclusions. Usage is implied by the action but not explicitly stated.
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 annotations already provide readOnlyHint=true and idempotentHint=true, so the agent knows this is a safe, repeatable read operation. The description adds minimal behavioral context beyond this - it specifies 'by ID' which clarifies the lookup mechanism, but doesn't mention what details are returned, error handling for invalid IDs, or any rate limits. No contradiction with annotations exists.
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 perfectly concise at 7 words - a single sentence that gets straight to the point with zero wasted words. It's front-loaded with the core action and resource, making it immediately scannable and understandable. Every word earns its place in this minimal but complete statement of function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with good annotations (readOnlyHint, idempotentHint) and full schema coverage, the description is adequate but minimal. Without an output schema, the description doesn't explain what 'details' are returned (person name, metadata, relationships, etc.), which would be helpful context. The tool's simplicity keeps it from being incomplete, but it doesn't provide rich contextual information about the returned data structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the input schema already fully documents the single 'person_id' parameter as a 'Person UUID'. The description adds no additional parameter information beyond what's in the schema - it doesn't clarify UUID format, provide examples, or explain where to obtain person IDs. The baseline of 3 is appropriate when the schema does all the parameter documentation work.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get details') and resource ('for a specific person by ID'), making the purpose immediately understandable. However, it doesn't differentiate from its sibling 'immich.people.list' beyond the singular vs. plural distinction, missing an opportunity to clarify this is for retrieving individual person records rather than listing multiple people.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives. The description doesn't mention its sibling 'immich.people.list' for listing multiple people or 'immich.people.update' for modifying person details. There's no context about prerequisites, error conditions, or typical use cases for retrieving individual person records.
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?
Annotations already provide readOnlyHint=true and idempotentHint=true, indicating this is a safe, repeatable read operation. The description adds minimal behavioral context by specifying 'asset count statistics', but doesn't disclose details like rate limits, authentication needs, or what 'statistics' entails. No contradiction with annotations, but it doesn't enrich beyond them significantly.
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 a single, efficient sentence that directly states the tool's function without unnecessary words. It's front-loaded and wastes no space, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/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 (1 parameter, no nested objects) and rich annotations (readOnlyHint, idempotentHint), the description is adequate but incomplete. It lacks output details (no schema provided) and doesn't clarify the scope of 'statistics', leaving gaps in understanding the full behavior and results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, clearly documenting the single required parameter 'person_id' as a UUID. The description adds no additional meaning beyond this, such as format examples or constraints, so it meets the baseline for high schema coverage without compensating value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/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 with a specific verb ('Get') and resource ('asset count statistics for a specific person'), making it easy to understand what it does. However, it doesn't differentiate from sibling tools like 'immich.assets.statistics' or 'immich.people.get', which could have overlapping functionality, so it doesn't reach the highest score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as 'immich.assets.statistics' for broader asset statistics or 'immich.people.get' for general person info. It lacks explicit context, prerequisites, or exclusions, leaving the agent to infer usage based on the name alone.
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?
Annotations provide 'idempotentHint: true', indicating safe retries, but the description adds minimal behavioral context. It mentions updating 'visibility (hidden/visible)', which hints at a toggle-like behavior, but doesn't disclose permissions needed, rate limits, or effects on related data (e.g., assets). With annotations covering idempotency, the description adds some value but lacks depth on mutation risks or system impact.
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 a single, efficient sentence that front-loads the core action ('Update a person's') and specifies the updatable fields. There is no wasted language or redundancy, making it easy to parse quickly. Every word contributes directly to understanding the tool's function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a mutation tool with annotations (idempotency) but no output schema, the description is minimally complete. It covers what the tool does but lacks context on prerequisites, side effects, or error handling. For a 3-parameter tool with low schema coverage, it should provide more guidance on usage and behavioral nuances to compensate, making it adequate but with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low at 33%, with only 'person_id' documented. The description adds meaning by specifying that 'name' and 'is_hidden' correspond to updating a person's name or visibility, clarifying their purposes beyond the schema's generic titles. However, it doesn't detail constraints (e.g., name length, visibility effects) or explain that 'null' values might skip updates, leaving gaps in parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update') and the resource ('a person's name or visibility'), making the purpose immediately understandable. It specifies what can be updated (name or hidden/visible status), which distinguishes it from general person-update tools. However, it doesn't explicitly differentiate from sibling tools like 'immich.people.merge' or 'immich.assets.update', which could handle related but different operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing a person_id from 'immich.people.list' or 'immich.people.get'), exclusions (e.g., not for merging people), or comparisons to sibling tools like 'immich.people.merge' for combining people or 'immich.assets.update' for asset-related updates. Usage is implied only by the action itself.
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?
Annotations already indicate readOnlyHint=true and idempotentHint=true, so the agent knows this is a safe, repeatable read operation. The description adds minimal behavioral context beyond this, such as specifying it retrieves 'details' of a link, but doesn't elaborate on error handling, permissions, or rate limits. No contradiction with annotations exists.
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 a single, direct sentence that front-loads the core action ('Get details') without unnecessary words. It efficiently communicates the essential information, making it easy to parse and understand quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/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 (1 parameter, no output schema) and rich annotations (readOnlyHint, idempotentHint), the description is minimally adequate. However, it lacks details on return values or error cases, which could be helpful despite annotations covering safety aspects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the parameter 'shared_link_id' fully documented as a 'Shared link UUID'. The description adds no extra meaning beyond implying the ID is used to fetch details, aligning with the baseline score when schema coverage is high.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get details') and resource ('specific shared link by ID'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'immich.shared_links.list' or 'immich.shared_links.update' beyond the basic verb, missing explicit comparison that would warrant a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'immich.shared_links.list' for listing all links or 'immich.shared_links.update' for modifying one. It lacks any mention of prerequisites, context, or exclusions, leaving usage decisions to inference.
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?
Annotations already declare destructiveHint=true and idempotentHint=true, so the agent knows this is a destructive but idempotent operation. The description adds no behavioral context beyond this, such as what happens to associated assets, confirmation requirements, or error conditions. It doesn't contradict annotations, but offers minimal value beyond them.
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 a single, direct sentence with zero wasted words. It's front-loaded with the core action and resource, making it highly efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's destructive nature (per annotations), one parameter with full schema coverage, and no output schema, the description is minimally adequate. However, it lacks context about effects (e.g., whether deletion is permanent, impacts on assets) or usage guidance, leaving gaps for an agent to infer safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the single parameter 'tag_id' documented as 'Tag UUID'. The description adds no additional meaning about the parameter, such as format examples or where to obtain the ID. Baseline 3 is appropriate since the schema fully covers the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete') and resource ('a tag by ID'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'immich.assets.delete' or 'immich.activities.delete' beyond specifying the resource type, which is a minor gap.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing the tag ID from 'immich.tags.list' or 'immich.tags.get'), nor does it specify when deletion is appropriate versus updating or other operations.
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?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the agent knows this is a safe, repeatable read operation. The description adds minimal behavioral context beyond this, specifying it retrieves 'details' for a specific tag ID, but doesn't elaborate on what those details include or any constraints like authentication needs or rate limits.
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 a single, direct sentence that efficiently conveys the core functionality without any wasted words. It's appropriately sized for a simple read operation and front-loads the essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with good annotations (readOnlyHint, idempotentHint) and full schema coverage, the description is adequate but minimal. It doesn't explain return values (no output schema provided) or potential error cases, leaving some gaps in completeness for agent usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the parameter 'tag_id' fully documented as a 'Tag UUID'. The description adds no additional semantic meaning beyond what the schema provides, such as format examples or usage notes, so it meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get details') and resource ('specific tag by ID'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'immich.tags.list' (which lists all tags) or 'immich.tags.create' (which creates tags), so it falls short of a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'immich.tags.list' for listing all tags or 'immich.tags.create' for creating new ones, leaving the agent to infer usage context from the tool name alone.
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?
Annotations provide 'idempotentHint: true', indicating safe retries, which the description doesn't repeat—this is good. However, the description adds minimal behavioral context beyond the annotations: it implies a mutation (updating) but doesn't disclose permissions needed, error conditions, or what happens if 'name' or 'color' are set to null. With annotations covering idempotency, the description adds some value but lacks depth on other 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 a single, efficient sentence that directly states the tool's function without unnecessary words. It's front-loaded with the core action ('Update'), making it easy to parse. Every word earns its place, and there's no redundancy or fluff, achieving optimal conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (a mutation with 3 parameters) and lack of output schema, the description is minimally adequate. It covers the basic action and parameters but misses key context: no output details, no error handling, and incomplete parameter guidance. Annotations help with idempotency, but the description doesn't fully compensate for the gaps in schema coverage and missing output information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low (33%), with only 'tag_id' documented in the schema. The description mentions 'name or color', which aligns with two of the three parameters, adding some semantic meaning beyond the schema. However, it doesn't explain the optional nature of 'name' and 'color' (they can be null) or provide format details (e.g., color codes), leaving gaps. Baseline is 3 as the description partially compensates for low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update') and the resource ('a tag's name or color'), making the purpose immediately understandable. It distinguishes this tool from sibling tools like 'immich.tags.create' or 'immich.tags.delete' by focusing on modification rather than creation or removal. However, it doesn't specify what 'tag' refers to in the context of the Immich system, which slightly limits specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an existing tag ID), exclusions (e.g., when not to update), or comparisons to sibling tools like 'immich.tags.create' for new tags or 'immich.tags.get' for viewing. This leaves the agent without context for tool selection in a workflow.
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?
Annotations already declare readOnlyHint=true and idempotentHint=true, indicating safe, repeatable read operations. The description adds minimal behavioral context by specifying the breakdown types (images, videos, total), but doesn't disclose further traits like rate limits, authentication needs, or response format. No contradiction with annotations exists.
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 a single, efficient sentence that front-loads the core purpose ('Get asset counts') and adds necessary detail ('broken down by type'). There is no wasted verbiage, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/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 (0 parameters, read-only/idempotent annotations) and lack of an output schema, the description is minimally adequate. It explains what the tool returns (counts by type) but doesn't cover response format or potential errors, leaving some gaps for a statistical 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?
The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately focuses on the tool's function without redundant parameter details, earning a baseline score of 4 for zero-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/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 asset counts broken down by type (images, videos, total).' It specifies the verb 'Get' and the resource 'asset counts' with breakdown details. However, it doesn't explicitly differentiate from sibling tools like 'immich.assets.list' or 'immich.people.statistics', which would require a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There are no mentions of when-not scenarios or explicit alternatives among the many sibling tools (e.g., 'immich.assets.list' for detailed asset lists or 'immich.people.statistics' for people-related counts).
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?
Annotations already declare readOnlyHint=true and idempotentHint=true, indicating this is a safe, repeatable read operation. The description adds value by specifying it discovers 'server features and supported API capabilities,' which provides context about what information is returned. However, it doesn't disclose additional behavioral traits like response format, potential rate limits, or authentication requirements beyond what annotations imply.
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 a single, efficient sentence: 'Discover Immich server features and supported API capabilities.' It's front-loaded with the core purpose, has zero wasted words, and is appropriately sized for a simple, parameterless tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/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, annotations cover safety), the description is adequate but has gaps. It explains what the tool does but lacks output details (no output schema provided) and usage context. For a capabilities discovery tool, more information about what 'features and capabilities' includes would enhance completeness, though annotations help mitigate some risks.
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 tool has 0 parameters, and schema description coverage is 100%. With no parameters to document, the description doesn't need to add parameter semantics. A baseline of 4 is appropriate since the description focuses on the tool's purpose without unnecessary parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/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: 'Discover Immich server features and supported API capabilities.' It uses specific verbs ('Discover') and identifies the resource ('Immich server features and supported API capabilities'). However, it doesn't explicitly distinguish this from sibling tools like 'immich.ping' which might also provide server information, so it doesn't reach the highest score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, timing, or how it differs from other server-related tools like 'immich.ping' or general API exploration methods. This leaves the agent without context for tool selection.
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?
Annotations provide readOnlyHint=true and idempotentHint=true, indicating safe, repeatable operations. The description adds context by specifying the types of data returned (places, people, things), which is useful beyond annotations. However, it doesn't detail behavioral aspects like rate limits, authentication needs, or output format, keeping the score at a baseline level.
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 a single, efficient sentence that front-loads the core purpose ('Get discovery data') and elaborates with specific examples. Every word contributes meaning without waste, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (simple read operation with no parameters), annotations cover safety (readOnly, idempotent), and the description specifies data types. However, the lack of an output schema means the description doesn't explain return values, leaving a gap in completeness for agent invocation.
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 parameters and 100% schema description coverage, the baseline is high. The description doesn't need to explain parameters, and it adds value by clarifying what 'discovery data' includes (places, people, things), which compensates for the lack of parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/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 discovery data: popular places, recognized people, and notable things in your library.' It uses specific verbs ('Get discovery data') and identifies the resource ('your library'), though it doesn't explicitly differentiate from sibling tools like 'immich.search.metadata' or 'immich.search.smart', which prevents a score of 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description mentions 'discovery data' but doesn't specify contexts, exclusions, or compare it to other search tools in the sibling list, leaving the agent without clear usage direction.
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?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the agent knows this is a safe, repeatable read operation. The description adds no behavioral context beyond this (e.g., pagination, sorting, or what 'all' means in practice), but it doesn't contradict the annotations either.
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 a single, efficient sentence that directly states the tool's purpose without any wasted words. It's appropriately sized and front-loaded, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/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, read-only/idempotent annotations), the description is adequate but minimal. Without an output schema, it doesn't explain return values (e.g., format, fields), leaving gaps in understanding what 'list all shared links' actually returns.
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 parameters and 100% schema description coverage, the schema fully documents the absence of inputs. The description doesn't need to add parameter information, so it meets the baseline expectation for a parameterless tool without providing extra value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and resource ('shared links'), making the purpose immediately understandable. However, it doesn't distinguish this from sibling tools like 'immich.shared_links.get' which retrieves a specific shared link, so it's not fully differentiated from alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. With sibling tools like 'immich.shared_links.get' for retrieving a specific link and 'immich.shared_links.create' for creating new links, the agent receives no explicit or implied direction about appropriate contexts or exclusions.
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?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the agent knows this is a safe, repeatable read operation. The description adds no behavioral context beyond what annotations provide, such as pagination, rate limits, or return format. However, it doesn't contradict annotations, so it meets the lower bar with annotations present.
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 a single, clear sentence that states exactly what the tool does with zero wasted words. It's front-loaded and efficiently communicates the core purpose without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/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, read-only/idempotent annotations) and lack of output schema, the description is minimally adequate. However, it doesn't explain what 'tags' are in this context or hint at the return format (e.g., list of tag objects), leaving some gaps for an agent to understand the full context.
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 with 100% description coverage, so no parameter documentation is needed. The description appropriately doesn't discuss parameters, which is correct for a parameterless tool. It gets a baseline 4 because it doesn't need to compensate for any schema gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('all tags in the library'), making the purpose immediately understandable. It distinguishes from siblings like 'immich.tags.get' (which retrieves a specific tag) and 'immich.tags.create' (which creates new tags). However, it doesn't explicitly mention that it lists ALL tags without filtering, which would make it a perfect 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'immich.tags.get' for retrieving specific tags or 'immich.search.metadata' for filtered searches. There's no context about prerequisites, such as whether tags must exist or if authentication is required.
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?
Annotations already indicate readOnlyHint=true and idempotentHint=true, covering safety and idempotency. The description adds valuable context by mentioning 'Supports pagination,' which isn't covered by annotations and is crucial for understanding how to handle large result sets. No contradictions with annotations exist.
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 two sentences that are front-loaded and waste no words. The first sentence states the core purpose, and the second adds critical behavioral context about pagination, making every sentence earn its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with annotations covering safety and idempotency, and no output schema, the description is minimally adequate. It mentions pagination but doesn't detail return format (e.g., structure of people objects) or error conditions. Given the complexity and lack of output schema, it could provide more context about what 'recognized people' entails.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67% (2 out of 3 parameters have descriptions). The description doesn't add any parameter-specific details beyond what the schema provides (e.g., it doesn't explain 'with_hidden' or clarify pagination behavior). With moderate schema coverage, the baseline score of 3 is appropriate as the description doesn't compensate for gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('all recognized people from face recognition'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'immich.people.get' (which retrieves a specific person) or 'immich.people.statistics' (which provides aggregated data), so it doesn't reach the highest score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'immich.people.get' for retrieving specific people or 'immich.search.smart' for broader searches, leaving the agent without context for tool 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?
Annotations provide readOnlyHint=true and idempotentHint=true, indicating a safe, repeatable read operation. The description adds value by specifying the optional filtering capability ('Optionally filter by shared status'), which isn't covered by annotations. However, it doesn't mention other behavioral aspects like pagination, rate limits, or authentication needs, 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 extremely concise—two sentences that directly state the action and optional feature without any fluff. It's front-loaded with the main purpose, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/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 (one optional parameter) and annotations covering safety, the description is somewhat complete but could be improved. It lacks details on output format, pagination, or error handling, and there's no output schema to compensate. For a list tool, this is adequate but has clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the schema doesn't explain the 'shared' parameter. The description adds some meaning by indicating it's for filtering by shared status, but it doesn't detail the parameter's behavior (e.g., true/false/null effects). With one parameter and low schema coverage, the description partially compensates but lacks full semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('all albums'), making the purpose unambiguous. However, it doesn't explicitly distinguish this from sibling tools like 'immich.albums.get' (which likely retrieves a specific album) or 'immich.search.smart' (which might search albums), so it lacks 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing albums with optional filtering by shared status, but it doesn't provide explicit guidance on when to use this tool versus alternatives like 'immich.albums.get' for single albums or 'immich.search.smart' for more complex queries. The context is clear but lacks exclusions or named 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?
Annotations provide idempotentHint=true, indicating safe retries. The description adds valuable context about the dry-run feature for previewing changes without modification, which isn't covered by annotations. However, it doesn't mention permission requirements, rate limits, or what happens when asset_ids are 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 two sentences with zero waste: the first states the core purpose, the second adds the key dry-run feature. It's front-loaded with the main action and efficiently conveys essential information without unnecessary details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a bulk update tool with 5 parameters, 40% schema coverage, no output schema, and only idempotentHint annotation, the description is minimal. It covers the basic purpose and dry-run feature but lacks details on error handling, response format, or constraints like maximum asset_ids count, leaving room for improvement given the complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 40%, with only 'asset_ids' and 'dry_run' having descriptions. The description mentions 'dry_run to preview changes', adding some meaning beyond the schema's 'Preview changes without modifying any assets'. However, it doesn't explain the semantics of is_favorite, is_archived, or rating parameters, leaving gaps in parameter understanding.
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 'update' and resource 'metadata for multiple assets', distinguishing it from siblings like 'immich.assets.update' (singular) and 'immich.assets.delete' (different operation). It specifies bulk operation and mentions dry-run capability, making the purpose specific and differentiated.
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 for bulk metadata updates and mentions dry-run for previewing changes, but doesn't explicitly state when to use this vs. the singular 'immich.assets.update' tool or provide exclusions/alternatives. The context is clear but lacks explicit guidance on tool selection.
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?
Annotations provide readOnlyHint=true, indicating this is a safe read operation. The description adds useful context about the search methodology (CLIP/ML) and the natural language query format, which goes beyond the annotations. However, it doesn't disclose behavioral details like rate limits, authentication needs, or what happens with empty results. No contradiction with annotations exists.
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 perfectly concise: one sentence stating the tool's purpose and methodology, followed by a practical example in parentheses. Every word earns its place, and the information is front-loaded with no wasted text. The structure guides the user immediately to the core functionality.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with good annotations (readOnlyHint) and high schema coverage, the description adequately covers the main use case. However, with no output schema, it doesn't explain what results look like (e.g., format, fields returned). The description could benefit from mentioning result limitations or ordering, but it's minimally complete for basic usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 80%, so the schema already documents most parameters well. The description emphasizes the 'query' parameter's natural language nature with examples, adding value beyond the schema's 'Natural language description' text. It doesn't explain other parameters like 'type', 'is_favorite', or pagination, but with high schema coverage, baseline 3 is appropriate.
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: 'Semantic search using CLIP/ML' with the specific action 'Describe what you're looking for in natural language.' It distinguishes from sibling tools like 'immich.search.metadata' (likely metadata-based search) and 'immich.search.explore' (unclear but different). The examples ('sunset at the beach', 'birthday party') reinforce the natural language query approach.
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 provides clear context for when to use this tool: for semantic search with natural language queries. It doesn't explicitly mention when NOT to use it or name specific alternatives (like 'immich.search.metadata'), but the natural language focus strongly implies this is for content-based rather than metadata-based searches. No prerequisites or exclusions are stated.
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?
Annotations provide 'destructiveHint: true' and 'idempotentHint: true', indicating a destructive and idempotent operation. The description adds valuable context by clarifying that deletion does not affect assets inside the album, which is not covered by annotations. This enhances transparency without contradicting annotations, as 'destructiveHint: true' aligns with 'Delete an album.'
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 and front-loaded, consisting of two short sentences that directly state the action and a critical clarification. Every sentence earns its place by providing essential information without any redundancy or unnecessary elaboration, making it highly efficient and well-structured.
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 (a destructive operation with one parameter), annotations cover safety and idempotency, and the schema fully documents the parameter. The description adds key behavioral context about asset preservation. However, there is no output schema, and the description does not explain return values or error conditions, leaving a minor gap in completeness for a destructive tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with the 'album_id' parameter documented as 'Album UUID.' The description does not add any further details about parameters beyond what the schema provides. According to the rules, with high schema coverage (>80%), the baseline score is 3, as the description does not need to compensate for schema gaps.
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 specific action ('Delete an album') and distinguishes it from potential confusion by explicitly noting 'This does not delete the assets inside it.' This differentiates it from sibling tools like 'immich.assets.delete' which might delete assets directly, making the purpose unambiguous and well-defined.
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 by specifying what the tool does (deleting albums without affecting assets), but it does not provide explicit guidance on when to use this tool versus alternatives (e.g., 'immich.albums.remove_assets' for removing assets from an album without deletion). No exclusions or prerequisites are mentioned, leaving the context somewhat open-ended.
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?
Annotations provide readOnlyHint=true and idempotentHint=true, indicating safe, repeatable operations. The description adds valuable context beyond annotations: it specifies that URLs include API keys for direct browser access and lists the types of links returned (thumbnail, original file, web UI), which helps the agent understand the output format and authentication mechanism.
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 sentences with zero waste: the first states the purpose and return values, the second adds critical behavioral detail about API keys. Every sentence earns its place, and information is front-loaded appropriately.
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 read-only tool with good annotations and full schema coverage, the description is mostly complete. It explains what the tool returns and authentication details. However, without an output schema, it could benefit from more detail on response structure (e.g., JSON format).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with one parameter (asset_id as UUID), so the schema fully documents the parameter. The description doesn't add any semantic details beyond what the schema provides, such as where to find the asset_id or format examples. Baseline 3 is appropriate when schema does the heavy lifting.
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 direct URLs') and resource ('for viewing or downloading an asset'), specifying it returns thumbnail, original file, and web UI links. It distinguishes from siblings like immich.assets.get (likely returns metadata) and immich.assets.list (returns multiple assets).
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 when direct URLs are needed for access, but doesn't explicitly state when to use this tool versus alternatives like immich.assets.get or immich.shared_links.create. No exclusions or prerequisites are mentioned.
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?
Annotations provide 'destructiveHint: true', indicating a potentially irreversible action. The description adds value by specifying that 'the source person will be merged into the target' and 'will be removed', clarifying the destructive nature beyond the annotation. However, it doesn't detail side effects like what happens to associated assets or metadata, or any rate limits.
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 concise sentences with zero waste. It front-loads the core action ('Merge two person clusters into one') and follows with critical behavioral detail ('The source person will be merged into the target'). Every word serves a clear 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?
For a destructive merge operation with two parameters and no output schema, the description is mostly complete. It covers the purpose and basic behavior, but lacks details on error conditions, confirmation requirements, or what the merge entails (e.g., combining faces, metadata). Given the annotations handle safety, it's adequate but could be more thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear parameter descriptions: 'target_person_id' as 'Person UUID to merge into' and 'source_person_id' as 'Person UUID to merge from (will be removed)'. The description adds minimal semantics beyond the schema, only reinforcing the merge direction. Baseline 3 is appropriate given high schema 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?
The description clearly states the specific action ('merge two person clusters into one') and identifies the resource ('person clusters'). It distinguishes from sibling tools like 'immich.people.get' or 'immich.people.update' by specifying a merging operation rather than retrieval or modification of individual person records.
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 for merging person clusters but provides no explicit guidance on when to use this tool versus alternatives like 'immich.people.update' or 'immich.people.delete'. There's no mention of prerequisites, such as verifying person IDs exist, or exclusions, like whether merging is reversible.
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?
Annotations provide destructiveHint=true and idempotentHint=true, indicating this is a destructive but idempotent operation. The description adds value by specifying the behavioral effect ('revoking access to its content'), which goes beyond the annotations by explaining what the removal entails. It does not contradict annotations, as 'remove' aligns with destructive, and idempotency is consistent with removal operations.
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 a single, efficient sentence that directly states the tool's purpose and effect without any unnecessary words. It is front-loaded with the core action ('Remove a shared link') and follows with the consequence, making it highly concise and well-structured.
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 (simple destructive operation), annotations cover key behavioral traits (destructive, idempotent), and the input schema is fully documented, the description is reasonably complete. However, without an output schema, it does not explain return values or potential errors, leaving a minor gap in contextual information for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with the parameter 'shared_link_id' fully documented as 'Shared link UUID'. The description does not add any additional meaning or context about the parameter beyond what the schema provides, such as format details or examples. With high schema coverage, the baseline score of 3 is appropriate.
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 specific action ('Remove a shared link') and the resource affected ('shared link'), with the effect 'revoking access to its content' providing additional context. It distinguishes from siblings like 'immich.shared_links.create', 'immich.shared_links.get', 'immich.shared_links.list', and 'immich.shared_links.update' by focusing on deletion/removal rather than creation, retrieval, listing, or modification.
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 when needing to revoke access to shared content, but it does not explicitly state when to use this tool versus alternatives (e.g., when to remove vs. update a shared link) or provide any exclusions or prerequisites. The context is clear but lacks explicit guidance on alternatives or specific scenarios.
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 adds valuable behavioral context beyond annotations, which only provide a title. It discloses practical requirements like server read access for local files and the server downloading URLs before upload. This helps the agent understand operational constraints, though it could mention rate limits or authentication needs. No contradiction with annotations exists.
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 front-loaded with the core purpose in the first sentence, followed by essential details in the second. Every sentence earns its place by providing critical information without redundancy, making it efficient and easy to parse for an AI agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (upload with multiple parameters) and lack of output schema, the description is somewhat complete but has gaps. It covers source types and server behavior, but does not explain return values, error handling, or the purpose of optional parameters. With no annotations to fill these gaps, the description should do more to be fully helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low at 20%, with only the 'source' parameter described in the schema. The description compensates by explaining the semantics of 'source' (local file path or URL), but does not address other parameters like 'device_asset_id' or 'file_created_at'. This leaves gaps, but the description adds some 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 the specific action ('Upload an asset to Immich') and distinguishes it from sibling tools by specifying the source types ('from a local file path or a URL'). It uses precise verbs and identifies the resource, making it easy to differentiate from other asset-related tools like 'immich.assets.list' or 'immich.assets.update'.
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 provides clear context on when to use this tool by explaining the two source types (local file path or URL) and their requirements (read access for files, server download for URLs). However, it does not explicitly mention when not to use it or name alternative tools for similar functions, such as bulk uploads or other asset management operations.
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?
Annotations only provide a title ('Create Tag'), so the description carries the full burden of behavioral disclosure. It describes the creation action and nested tag syntax, but doesn't mention permissions needed, whether duplicates are allowed, error conditions, or what happens on success. For a creation tool with minimal annotations, this leaves significant behavioral 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 perfectly concise with two sentences that each serve a clear purpose: the first states the core action, the second provides critical usage guidance. No wasted words, and the most important information (the nested tag syntax) is included.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a creation tool with 2 parameters, 50% schema coverage, no output schema, and minimal annotations, the description provides basic purpose and parameter guidance but lacks information about what happens after creation (return values, success indicators), error handling, or system constraints. It's adequate but has clear gaps given the tool's complexity.
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 50% schema description coverage (only the 'name' parameter has a description), the description compensates by explaining the nested tag syntax for the 'name' parameter. However, it doesn't address the 'color' parameter at all, leaving half the parameters without semantic context beyond what the schema minimally provides.
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 specific action ('Create a new tag') and resource ('tag'), distinguishing it from sibling tools like immich.tags.update, immich.tags.delete, immich.tags.get, and immich.tags.list. The mention of nested tags with '/' separator adds specificity beyond just the basic create 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 provides clear context for usage by explaining how to structure nested tags with '/' separator, which helps guide proper parameter input. However, it doesn't explicitly state when to use this tool versus alternatives like immich.tags.update or when not to use it (e.g., for existing tags).
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 annotations provide idempotentHint=true, indicating safe retry behavior. The description adds valuable context beyond this by clarifying that 'The assets themselves are not deleted,' which addresses a potential behavioral concern (asset preservation) not covered by annotations. No contradictions with annotations exist.
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 sentences, front-loaded with the core purpose and followed by a critical clarification. Every word serves a purpose, with no wasted information, making it highly efficient and well-structured.
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 moderate complexity (mutation with idempotency), 100% schema coverage, and no output schema, the description is mostly complete. It covers the purpose, key behavioral trait (non-destructive to assets), and usage context, though it could optionally mention response format or error conditions for full completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear descriptions for both parameters (album UUID and asset UUIDs list). The description does not add any additional semantic meaning beyond what the schema already provides, such as format details or constraints, so it meets the baseline for high schema 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?
The description clearly states the specific action ('Remove one or more assets from an album') and resource ('album'), and explicitly distinguishes it from sibling tools like 'immich.albums.delete' by clarifying that 'The assets themselves are not deleted.' This prevents confusion with asset deletion operations.
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 provides clear context for when to use this tool (to remove assets from an album without deleting them), but does not explicitly mention when not to use it or name specific alternatives. However, the distinction from deletion tools is implied, making the usage context reasonably 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?
Annotations provide readOnlyHint=true and idempotentHint=true, indicating safe, repeatable operations. The description adds value by specifying the return includes 'full metadata needed for deletion decisions' (e.g., file format, size, resolution), which clarifies the output's purpose beyond just listing groups.
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 sentences, front-loaded with the core purpose and followed by specific return details. Every sentence adds essential information without redundancy, making it efficient and well-structured.
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 (listing duplicates with metadata), annotations cover safety, and the description explains the output's utility for deletion decisions. However, without an output schema, it could benefit from more detail on return structure, but it's largely complete for its purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the parameter 'analyze' well-documented in the schema. The description doesn't add any parameter-specific details, so it meets the baseline of 3 by not compensating for gaps but not adding extra value either.
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 'List' and resource 'duplicate asset groups detected by Immich', specifying they contain 'assets with matching content hashes'. It distinguishes from sibling tools like immich.duplicates.delete and immich.duplicates.dismiss by focusing on listing rather than modifying duplicates.
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 usage for 'deletion decisions' by providing metadata, suggesting it's a preparatory step before actions like deletion. However, it doesn't explicitly state when not to use it or name alternatives, such as immich.assets.list for general asset listing.
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?
Annotations already provide readOnlyHint=true and idempotentHint=true, indicating this is a safe, repeatable read operation. The description adds value by specifying the scope ('currently authenticated user') and the types of data returned ('name, email, quota, role'), but does not disclose additional behavioral traits like authentication requirements, rate limits, or error conditions beyond what annotations cover.
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 a single, well-structured sentence that front-loads the purpose ('Get the profile') and efficiently includes all necessary details (scope and data fields). There is no wasted language, and every part of the 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?
Given the tool's simplicity (0 parameters, annotations covering safety, no output schema), the description is nearly complete. It specifies what data is returned, which compensates for the lack of output schema. However, it does not mention the response format (e.g., JSON structure) or potential error cases, leaving a minor gap in completeness.
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 with 100% coverage, so no parameter documentation is needed. The description appropriately does not discuss parameters, earning a baseline score of 4 for not adding unnecessary information. It could be a 5 if it explicitly noted the lack of parameters, but this is not required.
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 specific action ('Get the profile') and resource ('currently authenticated user'), with explicit details about what information is retrieved ('name, email, quota, role'). It distinguishes itself from sibling tools like 'immich.people.get' or 'immich.people.list' by focusing on the authenticated user's own profile rather than other users or general people data.
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 provides clear context by specifying 'currently authenticated user', indicating this tool should be used when the agent needs the profile of the user who is logged in. However, it does not explicitly state when not to use it or name specific alternatives (e.g., for other users' profiles), which prevents a perfect score.
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?
Annotations already indicate destructiveHint=true and idempotentHint=true, covering safety and idempotency. The description adds valuable context beyond this: it explains the trash mechanism (bypassable with force) and recommends a preview mode with dry_run. This enhances understanding of the tool's behavior without contradicting 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 extremely concise (two sentences) and front-loaded with the core purpose. Every sentence adds value: the first states the action, the second provides critical usage guidance. There's no wasted verbiage.
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 destructive tool with good annotations (destructiveHint, idempotentHint) and full schema coverage, the description is reasonably complete. It adds important behavioral context (trash mechanism, preview recommendation). The main gap is lack of output schema, but the description compensates somewhat by explaining the dry_run preview functionality.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are well-documented in the schema. The description adds minimal semantic context: it mentions using dry_run for preview and force for permanent deletion, but this mostly reiterates schema details. Baseline 3 is appropriate as the schema does the heavy lifting.
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 specific action ('Delete one or more assets') and resource ('assets'), distinguishing it from sibling tools like 'immich.assets.get' or 'immich.assets.update'. It's precise about what the tool does without being tautological.
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 explicit guidance on when to use certain parameters: 'Always use dry_run=true first to preview' and 'Set force=true to permanently delete (skip trash)'. This gives clear operational instructions for safe usage, though it doesn't mention alternatives among sibling tools.
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?
Annotations already provide destructiveHint=true and idempotentHint=true, indicating this is a destructive but idempotent operation. The description adds valuable behavioral context beyond annotations: the dry-run recommendation for safety, the force parameter's effect (bypassing trash), and constraints about favorited/album assets. No contradiction with annotations exists.
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 efficiently structured in three sentences: the first states the purpose, the second provides procedural guidance with parameter references, and the third gives critical constraints. Each sentence adds essential information with zero wasted words, making it front-loaded and highly concise.
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 (destructive operation with safety mechanisms) and lack of output schema, the description does well by explaining the dry-run workflow, permanent deletion option, and asset constraints. It could slightly improve by hinting at the response format (e.g., what dry_run returns), but it's largely complete for safe usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters (asset_ids, force, dry_run) thoroughly. The description mentions force and dry_run parameters but doesn't add significant semantic details beyond what's in the schema descriptions. This meets the baseline of 3 for high schema 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?
The description clearly states the specific action ('Delete specific assets from duplicate groups') and distinguishes it from sibling tools like 'immich.duplicates.dismiss' (which likely marks duplicates as dismissed rather than deleting them) and 'immich.assets.delete' (which deletes general assets, not specifically from duplicate groups). The verb+resource combination is precise and differentiated.
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 explicit usage guidance: 'Always run with dry_run=true first to confirm what will be deleted' (when to use initially), 'Set force=true to permanently delete (bypass trash)' (when to use for permanent deletion), and 'Do NOT delete assets that are favorited or belong to albums without explicit user approval' (when NOT to use). This covers both procedural steps and exclusion criteria.
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 adds valuable behavioral context beyond annotations: clarifies that 'asset files are NOT deleted — only the duplicate grouping is removed' and emphasizes the dry-run safety practice. While annotations provide destructiveHint=true and idempotentHint=true, the description adds practical safety guidance and clarifies the nature of the 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tightly focused sentences with zero waste. First sentence states purpose, second clarifies what dismissal means, third provides critical usage guidance. Every sentence adds essential information for correct tool invocation.
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 destructive operation with good annotations but no output schema, the description provides excellent context about what dismissal means, safety practices, and when to use it. The only minor gap is lack of information about return values or confirmation of operation success.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are fully documented in the schema. The description adds context about dry_run usage ('Always run with dry_run=true first') but doesn't provide additional semantic meaning beyond what's in the schema descriptions. This meets the baseline for high schema 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?
The description clearly states the specific action ('dismiss duplicate groups'), resource ('assets'), and distinguishes from sibling tools by contrasting with immich.duplicates.delete. It explains what dismissal means versus deletion, providing clear 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?
Explicitly states when to use ('when assets are intentionally kept as separate copies and should no longer appear in the duplicate list') and provides a clear best practice ('Always run with dry_run=true first'). This gives specific operational guidance beyond basic functionality.
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?
Annotations provide readOnlyHint=true and idempotentHint=true, indicating a safe, repeatable operation. The description adds value by specifying that it returns server version and status, which are behavioral details not covered by annotations. It does not mention rate limits or auth requirements beyond 'authentication', but this is sufficient given the 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 a single, efficient sentence that front-loads the purpose ('Verify connectivity and authentication') and includes the return value. Every word adds value with no waste, making it optimally concise and well-structured.
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 (0 parameters, no output schema, annotations covering safety), the description is nearly complete. It explains what the tool does and what it returns. A slight gap exists in not detailing the exact format of the return (e.g., JSON structure), but this is minor for a ping 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?
There are 0 parameters, and schema description coverage is 100%, so no parameter documentation is needed. The description appropriately does not discuss parameters, earning a high baseline score for not adding unnecessary information.
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 specific action ('Verify connectivity and authentication') and resource ('Immich server'), distinguishing it from all sibling tools which perform data operations like create, delete, list, update, etc. It explicitly mentions what it returns ('server version and status'), making the purpose unambiguous and distinct.
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 usage context by stating it verifies connectivity and authentication, suggesting it should be used to check server availability and auth status. However, it does not explicitly state when not to use it or name specific alternatives, which prevents a perfect score.
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-mcp MCP server](https://glama.ai/mcp/servers/whitehara/immich-mcp/badges/card.svg)](https://glama.ai/mcp/servers/whitehara/immich-mcp)

Score Badge

Copy to your README.md:

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

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/whitehara/immich-mcp'

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