immich-mcp

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.

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.

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.

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.

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.

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.