immich-photo-manager
Server Quality Checklist
Latest release: v2.0.2
- Disambiguation5/5
Each tool targets a distinct operation (albums, assets, tags, people, shared links, duplicates, trash, server info) with clear descriptions. Overlaps are minimal and well-differentiated (e.g., single vs batch thumbnails, specific vs bulk trash restore), so selection ambiguity is very low.
Naming Consistency5/5Virtually all tools follow a consistent verb_noun pattern (e.g., create_album, list_tags, update_person). There are no mixed conventions like camelCase or inconsistent verb styles. The few exceptions (ping, rotate_assets) are still predictable and don't break the overall pattern.
Tool Count4/5With 50 tools, the server covers a broad feature set (albums, assets, people, tags, sharing, duplicates, trash, metadata editing). While somewhat high, each tool is justified by Immich's capabilities. A few tools could be merged (e.g., restore_assets and restore_trash are distinct but related), but the count is reasonable for the scope.
Completeness4/5The surface covers core CRUD operations, search (metadata and visual), duplicate resolution, sharing, and trash management. Minor gaps exist: no direct 'list all assets without filters' (list_assets requires at least one filter), and no batch move between albums (requires add/remove steps). These are workable but leave room for improvement.
Average 4.6/5 across 50 of 50 tools scored. Lowest: 3.8/5.
See the Tool Scores section below for per-tool breakdowns.
- 3 of 3 community issues answered or closed in the last 6 months
- 92 commits in the last 12 weeks
- Last stable release on
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
This repository includes a glama.json configuration file.
This server has been verified by its author.
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
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does a good job: it discloses the side effect ('deletes the notes on the server'), the narrow scope ('Only the plugin's own key is removed'), and the success semantics ('Success is true only when nothing failed'). It does not cover permissions or irreversibility explicitly, but the key behavioral traits are transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured: the main purpose is front-loaded, follow-up sentences add scope and side-effect detail, and the Args/Returns block is clearly labeled. There is no filler or redundant prose; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter destructive operation, the description covers the purpose, scope, side effect, and return value semantics, including a failed-array explanation. An output schema exists per context, so the explicit Returns block is a bonus. Minor omissions like handling of invalid or missing asset IDs do not significantly hamper correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. However, it only says 'asset_ids: The assets to clear,' which barely adds meaning beyond the schema's title 'Asset Ids' and array-of-strings type. No format, edge-case behavior, or array semantics are explained, leaving the parameter mostly self-explanatory by name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Forget the plugin's notes on assets (reviews and actions).' It further scopes the operation by noting 'Only the plugin's own key is removed; metadata other apps stored stays,' which clearly distinguishes it from generic note-related tools in the sibling list such as get_asset_notes and review_assets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit when-to-use guidance, prerequisites, or exclusions. It does not mention alternatives or caution against using it when preserving plugin notes is desired. The intended usage is only implied by the verb 'Forget,' so an agent has to infer when this tool should be selected over related siblings.
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?
No annotations are provided, so the description carries the full burden. It mentions 'Side effect: creates a new tag in Immich' and describes the return format, but it lacks details on authorization needs, rate limits, or other behavioral traits. The description is minimal for a creation tool without annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with only a few sentences. It front-loads the purpose, then provides usage hints, parameter details, and return information. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, usage hint, parameter semantics, and return value. Given the low complexity (2 params, one required) and the existence of an output schema (return fields mentioned), it provides sufficient context for an agent to use the tool correctly, despite missing annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description adds meaning by providing examples for 'name' (e.g., 'Vacation') and 'color' (e.g., '#FF5733'), and states that name must be unique. This compensates for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new tag for categorizing assets.' This is a specific verb+resource, and it differentiates itself from sibling tools like delete_tag, update_tag, and list_tags by being the creation operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises 'Use list_tags first to avoid duplicates,' providing clear guidance on when to use this tool and a prerequisite action. It does not explicitly mention when not to use it, but the given hint is valuable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden and clearly declares the operation is read-only. It also describes the return JSON shape, which helps an agent know what to expect. It omits details like limits or ordering, but these are not required for a simple read-only listing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-organized, with separate lines for action/usage, arguments, and return value. Every sentence contributes value, and the main use cases are front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one optional parameter and no required arguments, the description covers the action, use cases, parameter filter, and return shape. An output schema exists, so the return description is a nice addition. The only minor gap is not explicitly stating what happens when the filter is omitted, but that is easily inferred.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description compensates by explaining the one parameter: 'Only the stack fronted by this asset.' This adds real meaning beyond the schema's type and default. It is concise but lacks an example, so a 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('List every stack') and the resource (stacks in the library). It also gives practical use cases, which helps an agent understand when to call it. However, it does not explicitly distinguish itself from the sibling get_stack, so it stops short of full differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states when to use the tool: to see existing groupings before creating new stacks and to find a stack's id. It does not mention when not to use it or alternative tools, so it gets a 4 rather than a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry full behavioral burden. It mentions the side effect of creating an album in Immich but does not disclose potential errors (e.g., duplicate names), permissions required, or whether the operation is reversible. For a creation tool, this is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (4 sentences) and includes a structured parameter breakdown. However, the parameter list could be integrated more seamlessly into the main description to be more front-loaded. No unnecessary words but slightly fragmented.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature of the tool (create album with optional fields and pre-population), the description covers the main use case and return values. It lacks details on error handling or constraints (e.g., name uniqueness) but is sufficient for a basic creation operation. Siblings provide contrast.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates. It provides clear semantics for each parameter: name with an example format, description as optional text, asset_ids as optional list of UUIDs. It also explains the return value structure (id, name, asset count), which is not in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a new album, optionally pre-populated with assets, distinguishing it from siblings like add_assets_to_album (adds to existing) or update_album. The verb 'create' and resource 'album' are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly notes using the tool to organize photos into collections and mentions optional pre-population. However, it lacks explicit guidance on when not to use it (e.g., for adding assets to an existing album, use add_assets_to_album) or alternatives. Still, the context is clear enough for an AI agent to infer basic usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure, and it does so well. It clearly states the non-destructive nature ('assets are NOT deleted'), the immediate user-visible effect ('show as individual items again'), and the server-side side effect ('removes the grouping on the server'). It also mentions the return type. Minor omissions like reversibility or permission requirements prevent a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and every sentence earns its place. The first sentence states the core action, the second clarifies the most important non-destructive caveat, the third describes the side effect, and the Args/Returns lines are minimal and useful. No redundant wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with an output schema, the description covers the purpose, the key behavioral nuance, the parameter role, and the return value. It does not discuss error cases or authorization, but these are not essential for this low-complexity operation. The main gap is the lack of explicit guidance about when to choose this over similar stack or deletion tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only provides the parameter name and type with no description, so the schema description coverage is 0%. The description compensates with 'stack_id: The stack to dissolve,' clarifying the role of the single parameter. It does not add details like ID format or lookup behavior, but for a single simple parameter this is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Dissolve a stack.' It also resolves the ambiguity of the tool name by explicitly stating that assets are NOT deleted, which distinguishes it from deleting assets or deleting other entities. This clearly differentiates delete_stack from siblings like delete_assets and delete_album.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the operation's effect obvious but does not explicitly state when to use this tool versus alternatives. It implies usage by context (for dissolving a stack) but does not name related stack operations or exclude cases like deleting a whole stack's assets, which a cautious agent might confuse.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Declares 'Read-only' and describes return shape. No annotations exist, so description carries burden. Lacks details on permissions or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Short, front-loaded purpose, uses clear sections for Args and Returns. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Describes return format despite no output schema. Lacks error handling or permission details but adequate for a simple read operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides no description for asset_id. The description adds 'The asset's UUID,' clarifying the parameter. This adds value beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it retrieves detected faces with person assignments. Differentiates from siblings like reassign_face (modifies) and get_person (single person).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly guides to use for seeing who is in a photo or finding face IDs for reassign_face. Lacks 'when not to use' but positive context is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description clearly states the side effect (only removes association, not the tag) and the return structure (tag_id, count, per-asset results). It also notes the constraint that asset_ids must not be empty. With no annotations, it carries the full burden but omits permissions or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short paragraphs with clear separation for Args and Returns. Every sentence provides necessary information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and the description covers the core function, side effect, parameter constraints, and output shape. Given the output schema exists, the description is complete enough, though it could mention potential errors or rate limits for a higher score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description adds meaning: it specifies that tag_id is a UUID, asset_ids are UUIDs, and asset_ids must not be empty. This is more informative than the schema's type/title alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the action 'Remove a tag from multiple assets', names the key resources (tag and assets), and distinguishes from sibling tools like 'delete_tag' (which deletes the tag itself) and 'tag_assets' (which adds the association).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (untagging many assets) but does not explicitly say when to choose this over alternatives, such as if a single asset needs untagging or if the tag should be deleted instead. No 'when-not' guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It mentions a side effect ('changes person metadata in Immich') and states that only provided fields are modified. However, it does not discuss permissions, rate limits, or reversibility of actions like hiding a person.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a brief overview paragraph followed by an Args list. It is front-loaded with purpose and every sentence is useful. However, the Args section could be slightly more concise, but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 7 parameters and lack of annotations, the description covers all parameters with context and explains the side effect. The return type is mentioned as 'JSON with the updated person object,' which is sufficient given the presence of an output schema (context signals indicate one exists). The description is fairly complete for a moderate-complexity tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, but the description provides detailed semantics for each of the 7 parameters in the Args section, including examples (e.g., '1990-05-15' for birth_date) and specific guidance (e.g., set name to name unnamed face clusters). This adds significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update a person's profile details' and lists specific use cases like naming unnamed faces, setting birth dates, hiding clutter faces, and changing the thumbnail. This distinguishes it from sibling tools such as get_person or search_people.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use this to name unnamed faces, set birth dates, hide clutter faces, or change the representative thumbnail.' This provides clear context for when to use the tool, though it does not mention when not to use it or suggest alternatives explicitly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It explicitly discloses the mutation with 'Side effect: creates a memory on the server' and warns that an empty asset list yields an empty memory. However, it omits permission requirements, conflict/duplicate behavior, and reversibility, leaving gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Efficiently structured with a one-line purpose, a usage workflow sentence, a clean Args list, and a Returns specification. No filler, and the core verb/resource is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage context, all three parameters, side effects, and the return shape in a compact definition. It omits error handling, permissions, and potential conflicts, but for a creation tool with no annotations it is still notably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, but the Args section compensates fully: memory_at is explained as the ISO date shown on, year as the required past year, and asset_ids with the empty-list caveat. This gives the agent everything needed to build correct parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Create an "on this day" memory from chosen assets.' It clearly differentiates from sibling memory tools (list_memories, update_memory, delete_memory) by describing the creation action and the Immich memories feed effect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear workflow context: 'Use this after curating a set of photos from the same past date (e.g. via search_metadata with a date range).' This tells the agent when to invoke the tool, but it doesn't explicitly state alternatives or when not to use it, so it's not a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses side effect of creating a publicly accessible URL, but lacks details on permissions, reversibility, or rate limits. Adequate but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Concise with front-loaded purpose and parameter list. Could be slightly more structured (e.g., separate sections), but no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given parameter count, required fields, and output schema, description provides complete context for agent to invoke tool correctly, including side effect and return fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but description explains each parameter's purpose (e.g., 'allow_download: Allow visitors to download original files') and return value, adding meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'Create' and resource 'public shared link for an album', differentiating it from siblings like 'update_shared_link' and 'get_shared_link'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this to publish a gallery for external viewing', providing a clear use case. Does not mention when not to use or contrast with alternatives, but context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses side effect: 'Side effect: deletes all edit records for the assets.' No annotations provided, so description carries the full burden. This is sufficient for a revert operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is moderately concise, but includes a separate 'Args:' section that largely repeats parameter info from the schema description (which is absent). Could be tightened, but structure is logical: purpose, usage, args, returns.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description provides return format ('JSON with reverted/failed counts'). Mentions side effect and mutual exclusivity. No annotations, but behavioral side effect is covered. Lacks error handling info, but acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but description adds full meaning: asset_ids (list of UUIDs, mutually exclusive with album_id) and album_id (revert all in album). Also clarifies the mutual exclusivity and provides argument context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'remove' and resource 'non-destructive edits (rotation, crop, mirror) from assets', clearly distinguishing from siblings like rotate_assets. It explicitly states the restoration of original appearance.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage context: 'Use this to undo rotate_assets or any other display transforms.' Also explains mutual exclusivity of asset_ids and album_id. Lacks explicit when-not-to-use, but the non-destructive scope is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Mentions 'Side effect: adds tag association to assets' which is good, but lacks details on idempotency, error handling, or prerequisites. With no annotations, more behavioral context would be beneficial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences plus structured Args and Returns sections. No redundant information, every part is useful and front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, side effects, parameter details, and return format. Lacks error handling or limits, but for a straightforward bulk-operation tool, it is largely complete given the output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but description includes a detailed Args section explaining each parameter's origin (tag_id from list_tags/create_tag) and constraints (asset_ids must not be empty), adding significant value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Apply a tag to multiple assets at once' with a specific verb and resource. It distinguishes from siblings like untag_assets and create_tag by noting bulk application.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a clear use case (bulk-categorize vacation photos) and lists required args. However, it does not explicitly discuss exclusions or when to use alternatives, though the context differentiates it from untag_assets.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden and it explicitly flags 'Side effect: modifies the memory on the server' and states the return payload. It stops short of discussing reversibility, permissions, or failure behavior, so it is not a 5, but the side-effect disclosure is meaningful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the core operation, and every section—summary, side effect, args, returns—earns its place. There is no filler or redundant restatement of the schema types.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 4-parameter update with an output schema, the description covers what the tool does, side effects, all argument meanings, and the response shape. It does not explicitly explain that only supplied optional fields are updated or how the operations combine in one call, but these are minor gaps given the schema's optional defaults.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, every parameter gets a plain-language semantic explanation: is_saved gets true/false behavior, memory_at is described as the new ISO date to display, and seen_at is tied to the user viewing action. This is exactly the meaning the raw schema, with only types and defaults, cannot convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific operation on a specific resource and then enumerates three concrete behaviors: saving the memory, moving its date, and marking it seen. This clearly distinguishes it from sibling memory tools such as create_memory, list_memories, and delete_memory.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The use case is implied by 'Update a memory' and the listed operations, but the description does not explicitly say when to use this tool instead of create_memory or delete_memory. An agent must infer that modifying an existing memory is this tool's job.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses a side effect: 'modifies album membership.' This adds behavioral context beyond the schema. However, it does not mention authentication needs, rate limits, or other potential consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a clear action statement, usage context, side effect, then parameter details. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature of the tool (add assets to album), the description covers the core functionality. The return summary is helpful even though an output schema exists. However, it omits prerequisites like album existence and potential error handling details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% coverage (no descriptions). The description's Args section provides clear semantics: 'Target album UUID' for album_id and 'List of asset UUIDs to add to the album' for asset_ids. This compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Add existing assets to an album.' It provides a specific use case: 'Use this to curate albums from search results or other asset lists.' This distinguishes it from sibling tools like 'create_album' (create new) and 'remove_assets_from_album' (remove).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says when to use the tool (curate albums from lists) and notes that assets can belong to multiple albums simultaneously, which guides decision-making. It does not explicitly state when not to use it or list alternatives, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states the important side effect that the activity appears for everyone the album is shared with, and also notes the return value. It does not cover permissions or reversibility, but the main behavioral traits are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded: a one-sentence purpose, a clear side-effect note, a compact parameter list, and a return line. Every sentence adds useful information, with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple creation tool, the description covers the purpose, target selection, all parameters, a key side effect, and the return format. The lack of annotations is compensated by the explicit behavior disclosure and complete argument semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description's Args section fully documents all four parameters: album_id, comment, asset_id, and like. It adds meaningful relationships, such as 'Leave empty when sending a like' and 'attach to asset instead of the album', which go well beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Post a comment (or a like)') and a clear resource ('on a shared album or on one asset in it'). It distinguishes itself from related siblings like list_activities and delete_activity by describing exactly what kind of activity is created.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool by explaining its purpose and target scope, and clarifies the album vs. asset distinction. However, it does not explicitly state when not to use it or name alternative tools for related actions.
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?
There are no annotations, so the description carries the behavioral transparency burden. It explicitly discloses the key side effect: 'grants the user read access to the whole library,' which is crucial for a mutating, security-relevant operation. It could go further by mentioning behavior on duplicate partners or reversibility, but the most important side effect is clearly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the main action, followed by the side effect, parameter, and return value. The 'Returns' line is slightly redundant given an output schema exists, but the overall structure is tight and every remaining sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool, the description covers the action, the side effect, how to find the required ID, and the return value. It does not mention how this compares to shared links or what happens if a partner already exists, but the essential information needed to call the tool correctly is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the JSON schema provides only the title 'User Id' and no description, the tool description compensates fully with 'Args: user_id: The user to share with.' It also tells the agent how to obtain a valid value ('Find the id with list_users'), giving the single parameter both meaning and provenance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Share'), a concrete resource ('this account's library'), and a clear recipient ('another user on the server'). It distinguishes itself from sibling tools by explaining the result: 'The other user will see these photos next to their own.' This makes the tool's role unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use the tool—sharing with another server user—and provides a concrete prerequisite: 'Find the id with list_users.' It does not explicitly name alternatives like create_shared_link or remove_partner, but the phrasing 'another user on the server' helps disambiguate from link-based sharing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the behavioral burden and explains that the memory is removed from the server while photos remain in the library. This discloses the destructive scope and the non-destructive side effect, which is valuable for an agent deciding whether to invoke a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core action, followed by the key side effect, parameter documentation, and return clarification. Each sentence serves a distinct purpose, and there is no unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter destructive tool, the description provides enough context: what is deleted, what is preserved, where the deletion happens, and what the response is. It does not discuss irreversibility or error cases, but the 'goes away' language sufficiently implies permanence.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It documents memory_id as 'The memory to delete,' which, while minimal, is sufficient for a single required parameter and confirms its role beyond the bare schema property name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies a specific action ('Delete a memory') and clearly separates 'memory entry' from photos, so the tool is not confused with photo/asset deletion. It also differentiates from sibling memory tools like create_memory and update_memory by stating the resource and effect precisely.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly communicates that this tool removes a memory while preserving photos, which tells the agent when to use it and explicitly what it does not do. It does not name alternative tools, but the exclusion of photo deletion provides clear contextual guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral disclosure burden. It explicitly states 'Read-only,' which is a key behavioral trait, and describes the return payload (id, primary_asset_id, asset list), giving the agent a clear expectation of side-effect-free behavior and output shape. It could add more detail about errors or not-found cases, but the core transparency is 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: a one-sentence purpose, a one-sentence usage context, a read-only flag, and a clear returns section. It is front-loaded with the most important information and contains no filler or redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity tool with one parameter, no annotations, and an output schema, the description covers the essential aspects: what it does, when to use it, and what it returns. It is complete enough for an agent to invoke get_stack correctly, though a more explicit note on where to obtain stack_id (e.g., from list_stacks output) would make it fully self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only a type and title for stack_id with 0% description coverage, so the description must compensate. The Args line 'stack_id: The stack to fetch' is essentially a restatement, but the body's instruction to use the tool 'after list_stacks' implies that stack_id originates from list_stacks output, adding contextual meaning beyond the schema. Still, the parameter description is minimal and could explicitly state the source or format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches a single stack and its assets, using a specific verb ('get') and resource ('stack'). It explicitly distinguishes itself from list_stacks by noting it returns a single stack's full asset list, and positions it relative to create_stack, so an agent can select it correctly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides concrete when-to-use guidance: 'Use this after list_stacks to see everything a group holds before changing its cover or dissolving it, or to check what create_stack actually grouped.' This establishes the correct workflow and ties to sibling tools without needing further inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Declares 'Read-only' and describes the return format (JSON with total count and tags array). With no annotations provided, this sufficiently discloses the tool's non-destructive nature and output structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences: purpose, usage guidance, return format. No extraneous words, well-structured, and front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers what, when, and return format. For a zero-parameter tool with an output schema, this is sufficient. Missing details on error handling or edge cases, but acceptable for a simple list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters, so baseline is 4. The description adds no parameter details, but none are needed. It appropriately implies no inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all tags in the library' with a specific verb and resource. It further explains usage context ('discover existing tags before creating new ones or to find a tag ID'), effectively distinguishing it from sibling tools like create_tag or get_tag.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises using it to discover existing tags before creating new ones or to find tag IDs. While alternatives are not named, the context implies when to use this tool vs. others (e.g., get_tag for a single known tag).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses side effect: 'permanently changes face-to-person mapping' and return type. Lacks details on permissions or reversibility but acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences with clear structure: purpose, usage, args, returns. No wasted words; front-loaded with main action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple mutation tool with 2 required params and output schema present, description covers purpose, usage, side effect, and parameter semantics. Could mention error conditions or idempotency, but adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% (only titles), so description compensates well. Explains face_id as 'from get_asset_faces results' and person_id as 'correct person UUID', adding meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'reassign' and the resource 'face to person', with explicit use case for correcting recognition mistakes. Distinguishes from sibling tools like 'merge_people' or 'update_person' which operate on different entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Specifies when to use: 'correct face recognition mistakes' and provides prerequisite: 'Get face_id from get_asset_faces first'. Lacks explicit when-not-to-use or alternatives, but context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description mentions a side effect ('changes public link behavior immediately') but no annotations exist. It lacks disclosure on authorization needs or other behavioral traits, leaving some gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with a clear purpose, side effect note, and formatted Args/Returns sections. No unnecessary sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, description doesn't need to detail returns. It covers all 6 parameters, required field, and behavior, making it fully complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by explaining each parameter, including edge cases like empty string clearing values and removing expiry, adding significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it updates a shared link's permissions or expiry, using specific verb and resource. It distinguishes from related tools like create_shared_link and delete_shared_link.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool ('to tighten/loosen access or set an expiration date') but does not explicitly state when not to use it or provide alternatives, though context from sibling tools implies those.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly warns of the destructive side effect ('deletes it for everyone') and states the return format (JSON confirming the deletion), covering the most important behavioral aspects for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core action and side effect, followed by concise args and returns sections. Every sentence earns its place and there is no redundant elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has one required parameter, no enums, and an output schema, so the description only needs to cover purpose, parameter source, and side effects—all of which are present. Nothing an agent needs to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must clarify the parameter. It adds crucial context by specifying that activity_id is 'The activity to remove (from list_activities)', grounding the opaque string ID. For a single-parameter tool, this is sufficient compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Remove') and a clearly scoped resource ('one comment or like', i.e., an activity). This distinguishes it from sibling deletion tools like delete_assets, delete_album, and delete_tag, and it further grounds the resource by referencing list_activities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly establishes when to use the tool: to remove a single comment or like, with the activity_id sourced from list_activities. While it does not explicitly name alternatives or exclusions, the resource scoping makes the intended use unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavioral traits: default soft-delete, permanent deletion with force=true, side effect of moving/deleting, and return format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with an Args section and clear separation of modes. It could be slightly more concise but remains efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and lack of annotations, the description covers essential aspects: behavior, parameters, side effects, and return value. The existing output schema is referenced.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema coverage, the description adds meaning by explaining asset_ids as UUIDs and force default false, plus its effect on deletion permanence.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes assets with two modes (soft-delete and permanent), and distinguishes it from restoring assets via restore_assets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains when to use (remove unwanted photos/videos) and provides context for the two modes, but doesn't explicitly state when not to use or alternative tools beyond restore_assets.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses side effects (permanently removes the link), scope (album and photos unaffected), and immediate impact (URL inaccessible). It lacks info on error handling for invalid link_id but is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence contributes value: purpose, side effects, parameter description, return value. No redundancy or filler. Efficiently structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool (one parameter) and presence of an output schema, the description covers all necessary aspects: action, side effects, parameter, and return. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no descriptions (0% coverage), but the description adds 'The shared link's UUID to delete', explaining the parameter's purpose and format. This compensates well for the missing schema details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (delete/revoke a shared link) and the resource, with specific details like making the public URL immediately inaccessible. It distinguishes from sibling tools like create_shared_link or list_shared_links by its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (to revoke a link) without explicitly naming alternatives or stating when not to use it. The context of siblings provides differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description effectively discloses read-only nature and the intentional masking of the API key. It also mentions thumbnails use base64 data URIs, adding useful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Five sentences, each serving a distinct purpose: main function, use case, security reason, read-only note, and return format. No waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and presence of output schema, the description fully explains what the tool returns and why, making it complete for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so the description does not need to add parameter info. It correctly focuses on the return values and usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns the Immich base URL and a masked API key, with a specific use case of populating gallery template placeholders. It is distinct from all sibling tools, which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says when to use it (populate template placeholders) and explains the key masking for security. Could be more precise about when not to use, but the use case is well-defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description declares 'Read-only' and specifies return format (JSON with 'data' and 'type'). Adequate disclosure for a simple read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two paragraphs plus parameter description, each sentence adds value. No fluff, well structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Simple operation with one parameter; description covers purpose, usage context, parameter, and output format completely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but description adds 'The person's UUID' to the parameter, clarifying its purpose beyond type/title.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb+resource: 'Get a base64-encoded face crop thumbnail for a person.' Clear distinction from siblings like get_person or merge_people.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use: 'Use this to visually identify a person before merging or renaming.' Lacks explicit when-not-to or alternatives, but context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It explicitly states 'Read-only' and describes the return format (major, minor, patch). This is adequate disclosure for a nondestructive, safe operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences with no wasted words. It front-loads the purpose and includes important details (read-only, return format) efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with an output schema, the description is complete. It explains the tool's purpose, behavior, and return structure, leaving no gaps for an AI agent to misunderstand.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters and schema coverage is 100%, so the baseline is 4. The description does not need to add any parameter information, and it appropriately avoids redundancy.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get') and resource ('Immich server version'), and provides specific use cases (check compatibility, report version), distinguishing it well from sibling tools like 'ping' or others.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly mentions when to use the tool ('to check compatibility or report the running server version'). It does not provide when-not-to-use or alternatives, but the context is sufficiently clear for a simple read-only operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description declares read-only and describes return format (photo count, video count, storage usage). Adequate disclosure for a simple statistics tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, front-loaded with purpose, then usage, then return format. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and presence of output schema, the description covers purpose, usage context, and return structure fully. No missing information for a read-only statistics tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters in schema, so baseline 4 applies. Description does not need to add parameter info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb-resource (Get library statistics) and distinguishes from siblings by noting it's for a quick overview without listing individual assets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (quick overview) and implies when not (if you need individual assets, use list_assets). No explicit exclusions, but sufficient for context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the tool is 'Read-only,' a key behavioral trait. It also outlines the return structure, though it could mention that tag_id is required and must be valid.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with three lines covering purpose, usage, and return value. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, output schema present), the description fully covers what the tool does, how to use the parameter, and what is returned.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by explaining that tag_id is 'The tag's UUID (from list_tags),' guiding the agent on how to obtain the ID.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get details for a specific tag,' specifying the precise verb and resource. This distinguishes it from sibling tools like list_tags (list all tags) and create_tag.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises 'Use this to inspect a tag's properties. Read-only,' clearly indicating the tool's context. It does not explicitly exclude other tools, but the purpose is clear enough for appropriate selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the behavioral disclosure burden. It explicitly marks the tool as 'Read-only' and describes the return format (JSON with an assets array and listed fields), which provides useful behavioral transparency. It doesn't mention pagination limits or error behavior, but that's not a major gap for a read-only bucket fetch.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the tool's purpose and usage context, then cleanly lists arguments and return shape. Every sentence adds information and there is no fluff or repetition of schema defaults. It is appropriately sized for a tool with five parameters and no schema descriptions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core invocation contract: exact bucket key, optional filters, read-only behavior, and return fields. Given the output schema exists, it doesn't need to over-explain return values. A minor gap is that it doesn't state how multiple filters combine (e.g., AND vs OR), but the tool is otherwise complete enough to be called correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully explain the parameters. It does: time_bucket must be the exact key from get_timeline_buckets (with example), and each optional ID/filter parameter is explained with its meaning. This goes well beyond the bare schema property names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies what the tool returns—the assets for one month bucket—and explicitly ties it to get_timeline_buckets, distinguishing this retrieval tool from its sibling. The phrase 'Use the two tools together to walk a library month by month' clarifies the tool's specific role in the workflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear usage context: pair with get_timeline_buckets to navigate a library month by month and avoid expensive searches. It does not explicitly state when not to use it or compare against alternative search tools, but the intended workflow is evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the operation is read-only, explains the partner-sharing model ('each side keeps its own library but can see the other's'), and describes the returned structure. This is solid transparency for a simple no-parameter listing 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded, opening with the core question the tool answers. The partner-sharing explanation and return-format note each add distinct value, with no redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters and an output schema, the description is complete. It clarifies the domain concept, confirms read-only behavior, and summarizes the response shape, so an agent has enough to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so no parameter documentation is needed. The description instead adds useful semantic detail about what the result represents, which is appropriate for a parameterless tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly defines the tool as querying partner-sharing relationships: 'Who shares their library with this account, and who this account shares with.' It also distinguishes this from other listing tools by explicitly describing the partner-sharing concept, so an agent can tell it apart from list_people, list_users, and list_shared_links.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when this tool is relevant: it is the family/partner-sharing listing operation, and 'Read-only' signals it is a query rather than a mutation like create_partner or update_partner. It does not explicitly name alternatives or state when not to use it, but the context is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses 'Read-only' nature, which is a key behavioral trait. Also describes return format (JSON with total count and links array with fields). Lacks details on authentication, rate limits, etc., but for a simple list operation, this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: two sentences plus a return description. Every sentence adds value. No fluff, front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and a simple list operation, the description fully covers purpose, behavior (read-only), and output format. Context signals indicate output schema exists, but description already details return fields. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has no parameters, so baseline is 4. Description does not add parameter info because none are needed. Schema coverage is 100%, so no gaps to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'List' and resource 'shared links (public gallery URLs)'. Specifies use cases: see what's shared or find link ID for updates/deletion. Distinguishes sufficiently from siblings like get_shared_link, create_shared_link.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use it: to see currently shared links or find link ID for updates/deletion. Does not explicitly mention when not to use or alternatives, but the context of list vs get is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states the operation is read-only and clarifies the scope of results to users visible on the server. It also describes the response shape, which is useful behavioral context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: it states the resource, the use case, the read-only nature, and the response format in a few short sentences. Every sentence adds value without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter list operation, the description is complete: it explains what is returned, why an agent might want to call it, and that it is safe and read-only. No critical information needed for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the parameter semantics dimension is trivially satisfied. The description correctly omits parameter details because none exist, and the return structure is summarized to compensate for the empty input schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states what the tool does: it lists the users visible on the Immich server. It goes beyond the tool name by explaining the intended use case and scoping the results to visible users, which distinguishes it from potentially similar 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives concrete guidance on when to use it: to find the id needed by create_partner or to see who could be shared with. It does not explicitly name alternatives or when not to use it, but the use cases are clear enough for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It clearly states side effects: 'modifies album membership' and confirms no deletion. It also describes the return value structure. This adequately discloses behavior for a non-destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is relatively short (three sentences plus Args and Returns sections). Every sentence adds value: purpose, side effect, parameter details, output. Could be slightly more compact, but no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no provided output schema, the description covers all necessary aspects: what the tool does, parameter roles, side effects, and return value. It is self-contained and sufficient for correct selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% coverage (no descriptions). The description fully explains both parameters: album_id as 'Album UUID' and asset_ids as 'List of asset UUIDs'. It also describes the output, adding significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Remove assets from an album without deleting them.' It specifies the resource (album), verb (remove), and key constraint (assets remain in library and other albums). This distinguishes it from siblings like delete_assets and add_assets_to_album.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides a clear use case: 'Use this to un-curate mistakenly added assets.' While it doesn't explicitly list when not to use or alternative tools, the use case is specific and implies context. Sibling differentiation is not explicit but is evident from the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of disclosing side effects. It explicitly notes that the user's own photos are not touched and that the side effect is revoking their access. This is valuable transparency for a mutating operation and goes beyond merely restating the tool's name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the main action. Every sentence earns its place: the action, the non-destructive clarification, the side effect, the argument explanation, and the return value. There is no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool, the description covers the action, the effect on the target user, the argument semantics, and the return type. Nothing critical is missing for an agent to invoke it successfully.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates by explaining 'user_id: The user to unshare with.' This adds role semantics beyond the bare schema property. For a single required parameter, this is sufficient guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Stop sharing this account's library with a user.' This is a specific verb-resource pairing that distinguishes it from sibling tools like create_partner, update_partner, and list_partners. It also reassures that the user's own photos are untouched, which sharpens the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: when the account should no longer share its library with a given user. It does not explicitly name alternatives or exclusions, but the action is unambiguous enough that an agent can select it appropriately among the partner-related siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the sole burden of behavioral disclosure. It compensates well by explicitly stating the operation is read-only, uses offline geodata, and contacts no external service, which are key behavioral traits for an agent deciding whether to call it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: a one-line purpose, a usage context, an explicit read-only note, and clearly separated Args and Returns sections. Every sentence adds information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter read-only lookup, the description is complete: it explains what the tool does, when to use it, what the inputs mean, and what the response shape is. No critical information for invoking it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must define the parameters itself. It does so by stating lat and lon are in decimal degrees, adding meaningful semantic detail beyond the schema's bare 'number' type. It could add ranges or validation expectations, but the core meaning is clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb-resource pair: 'Resolve GPS coordinates to a place name using Immich's own offline geodata.' It clearly distinguishes itself from sibling search tools by noting the offline nature and by tying its use to get_map_markers or asset EXIF coordinates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance on when to use the tool: to name the location of a marker from get_map_markers or an asset's EXIF coordinates. It does not mention explicit alternatives or exclusions, so it stops short of a 5, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure, and it does well by stating 'Read-only' explicitly. It also discloses the return shape and sort order, so the agent knows the call has no side effects and what to expect in the response.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded, with the core purpose and use case in the first sentence. The args and returns sections are efficiently formatted. Minor redundancy exists ('largest first' appears in both intro and returns), but it does not bloat the description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only search tool with no annotations, the description covers the purpose, when to use it, all parameters, defaults, allowed values, sorting, and return payload structure. Nothing needed to call the tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates by explaining all three parameters: min_size_mb meaning and zero behavior, size range and default, and asset_type allowed values ('IMAGE'/'VIDEO') plus omission behavior. This is complete and unambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'The biggest files in the library, largest first,' which clearly identifies the verb, resource, and ordering. It distinguishes itself from the many other search_* siblings by focusing on file size and storage cleanup, so an agent can select it without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use this tool: 'Use this to find what is eating storage before a cleanup.' This is clear contextual guidance. It does not name alternatives or exclusions, but the use case is specific enough that an agent knows this is for size-based triage rather than general metadata search.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the burden; it discloses read-only behavior, the absence of asset involvement, and a JSON places array return. This is adequate for a simple lookup, though it does not describe edge cases such as no-match or multiple ambiguous matches.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Tight and well-structured with Args and Returns sections; every sentence adds information and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, usage, parameter meaning, and return shape, and an output schema exists. Minor details like partial-match behavior or empty-result handling are missing, but this is acceptable for a one-parameter gazetteer lookup.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides no description for 'name' (0% coverage). The description compensates fully with a clear explanation and an example: 'name: Place name to look for (e.g. 'Lisbon')'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Look a place name up in Immich's built-in gazetteer (no assets involved)'. The 'no assets involved' clause distinguishes it from sibling asset-focused searches like search_smart or search_metadata.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit use case: 'Use this to resolve a spelling or get coordinates for a place before a geographic search.' This clarifies when to call, though it does not name alternative tools to prefer instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions a side effect ('modifies album metadata in Immich') and describes parameter behavior ('Leave empty to keep current name/description'). It could disclose more about authorization or reversibility, but the provided context is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (4 lines plus Args and Returns sections) and front-loaded with the purpose. Every sentence adds value, and the structure is clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (3 params, 1 required) and the presence of an output schema, the description covers the essential behavior and parameter details. It could mention error scenarios or additional effects, but it is complete enough for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates fully by explaining each parameter: album_id as 'The album's UUID,' name and description with 'Leave empty to keep current.' This adds critical meaning absent from the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update an album's name or description' and 'Use this to rename or re-describe an existing album,' providing a specific verb and resource. It distinguishes itself from sibling tools like create_album and delete_album.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use this to rename or re-describe an existing album,' providing clear when-to-use guidance. It lacks explicit when-not-to-use or alternative tool mentions, but the context is sufficient for this straightforward tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the disclosure burden and does a solid job: it notes the photos remain reachable either way, the operation only applies to shared-with-me partners, and the setting is persisted server-side. It stops short of discussing permissions or error behavior, but the key behavioural traits are covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: purpose in the first sentence, precondition in the second, side-effect note, then a clean Args list. No filler; every line adds information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has only two required parameters and no nested objects, and an output schema exists. The description covers the return value ('JSON with the updated partner entry'), the precondition, and the parameter semantics, so an agent has enough to call it correctly; only error/edge-case behavior is absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description is the only documentation for both parameters. It fully explains user_id ('the partner whose setting changes') and in_timeline ('True to mix their photos into the timeline, false to keep them separate'), adding meaning the schema lacks.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action — toggling whether a partner's photos appear in the main timeline — and clarifies that the photos remain accessible. It clearly differentiates this from partner management siblings like create_partner/remove_partner by focusing on the timeline visibility flag.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear precondition: 'Only works on a partner who shares their library with this account (someone in shared_with_me).' It implies the tool is for adjusting visibility rather than membership, but it does not name alternative tools or explicitly say when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It explicitly states the side effect ('updates the stack on the server') and the input constraint on primary_asset_id, which goes beyond the raw schema. It does not cover error behavior or permissions, but for a simple non-destructive update the disclosure is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short, front-loaded with the core purpose, and uses a compact Args block followed by a Returns line. Every sentence contributes necessary information without redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with an output schema, the description covers purpose, side effects, parameter meanings, a key validation constraint, and the return type. It lacks explicit notes on error handling or authorization, but that is a minor gap given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must provide all parameter meaning. It does this fully: stack_id is 'The stack to update' and primary_asset_id is 'The asset that should become the cover' with the important precondition that it already belongs to the stack.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Change which asset fronts a stack', and clarifies the domain effect with '(the one the library shows)'. This clearly distinguishes the tool from sibling stack operations like create_stack, list_stacks, get_stack, and delete_stack.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does 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: when updating which asset serves as the stack cover. It also gives a precondition ('It must already belong to the stack'), but it does not explicitly name alternatives or when-not-to-use conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden; it is unusually transparent, disclosing a server-side side effect, the primary-asset rule ('The first id becomes the primary'), a minimum of two assets, and that assets are kept rather than deleted. It does not address reversibility or conflict behavior, but the core state-changing traits are clearly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The text is compact, front-loaded with the core behavior, and organized with Args/Returns sections. Each sentence adds information—purpose, effect, parameter constraint, return shape—with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter create operation, the description covers what, when, why, how parameters behave, side effects, and the return shape. The output schema exists and the description also spells out the returned fields, leaving little for an agent to guess.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the schema only declares asset_ids as a string array. The description compensates fully: it imposes the 'at least two' constraint, explains that order matters, and defines the first element as the cover/primary—making the single parameter fully meaningful.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
States the specific action 'Group near-identical assets into one stack' and differentiates it from a hard delete by describing it as 'a gentler cleanup than deleting.' The 'Side effect: creates the stack on the server' confirms a create operation distinct from stack list/get/update/delete siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: use when you have near-identical assets (burst, retries) and want to reduce clutter while keeping all shots. It contrasts with deleting, implying this is the non-destructive alternative, though it does not explicitly name sibling alternatives or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility. It discloses that the tool is read-only, describes the degradation behavior when the API key lacks feature-flag access ('features is empty and a note says so; the version and the quirks still come back'), and explains the format of quirks. This is significant behavioral context beyond any schema or annotation, giving the agent realistic expectations of output under permission limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well organized with a front-loaded summary, a usage directive, and a detailed 'Returns:' section. It is slightly longer than the absolute minimum but every sentence carries useful information—none is wasted. The colon-separated list of feature flags is dense but readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose, usage timing, return fields, quirks format, permission degradation, and read-only nature. Given the empty input schema and existing output schema, nothing essential is missing. An agent can invoke it and interpret its output confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline of 4 applies. The description does not need to explain parameters because there are none. It focuses on return semantics, which is appropriate given the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the resource (server capabilities) and the specific aspects returned: version, feature flags, and known quirks. It goes beyond a simple verb+noun by enumerating the exact features ('OCR, smartSearch, facialRecognition, map, trash') and explicitly separates this tool from get_server_version and ping through scope. An agent can understand what this tool does and what it uniquely provides.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit timing and purpose: 'Use this once at the start of a session to learn whether OCR, smart search or facial recognition are available before offering them.' It also explains when version-specific behavior matters. It does not name alternatives or explicitly say when not to use it, but the context is clear enough for an agent to select it appropriately.
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?
There are no annotations, but the description explicitly states the operation is read-only and that the zip is not actually built. It also describes the return content. It does not mention potential errors or authentication requirements, but the core behavioral profile is clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: purpose first, then usage guidance, then parameter explanations, then return summary. Every sentence contributes useful information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose, parameters, read-only behavior, and return shape, while the output schema handles exact return details. The only notable gap is that it does not explicitly state that at least one of album_id or asset_ids should be provided, which matters given the schema marks both as optional.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no descriptions, so the description carries the full burden. It explains that album_id sizes the whole album and asset_ids sizes specific assets, which adds real meaning beyond the bare schema. However, it does not explicitly clarify whether exactly one of the two is required or what happens if both are provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states what the tool does: estimate the size of a zip before building it, for either an album or a selection of assets. It also distinguishes itself from the sibling tool download_archive by framing this as a pre-flight sizing step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly tells the agent when to use this tool: warn the user about size before deciding whether to call download_archive. It also names the alternative tool and the decision context, which is strong usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does well: it states 'Read-only' (safety), 'Returns up to 500 markers' (limit), and includes a Returns section describing the output structure. It could additionally mention pagination or authentication requirements, but for a simple read operation, these are sufficient. The description provides key behavioral traits beyond what annotations might have covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a main sentence, use case, sibling reference, read-only and limit statements, followed by an Args/Returns section. It is concise but not sparse. The pseudo-docstring format adds clarity though some information (like read-only) is repeated. Overall, it uses space efficiently and is easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (3 optional parameters, no required, no enums, output schema exists), the description covers all essential aspects: purpose, usage context, parameters, return structure, and limits. The output schema exists, so detailed return description isn't needed, but the description still outlines the output. The sibling differentiation also adds contextual completeness. There are no gaps that would hinder an AI agent from using the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It lists all three parameters with explanations: file_created_after and file_created_before get ISO date examples, and is_favorite is described as 'If true, only return favorites.' This adds meaningful context beyond the schema, which only provides types and defaults. The descriptions are clear but could be slightly more detailed (e.g., date inclusivity), hence a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get GPS map markers for all geotagged assets.' It includes specific use cases (discover photo locations, build travel maps) and explicitly distinguishes from the sibling tool 'search_metadata' by noting that the sibling is for city/country searches. This provides a clear, specific verb+resource combination with sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance: 'Use this to discover where photos were taken or to build travel maps. For searching by city/country name, use search_metadata instead.' This clearly states when to use the tool and when not to, with an alternative tool named, fulfilling the usage guidelines dimension fully.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states the tool is read-only, which discloses a key behavioral trait. It also describes the return content (JSON with details, permissions, expiry, assets). Since annotations are absent, this carries the full burden, and the description is sufficient for a simple retrieval operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of three efficient sentences plus an 'Args' and 'Returns' section. It is front-loaded with the purpose and reads naturally without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, read-only, with an output schema), the description is complete. It explains the return content and parameter source, and no additional information (error handling, pagination) is expected for such a straightforward operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides explicit meaning for the single parameter, 'The shared link's UUID (from list_shared_links),' which adds value beyond the schema (only indicates type string). With 0% schema description coverage, the description fully compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves full details of a shared link, including specific properties like permissions, expiry, and linked assets. It distinguishes from siblings like create_shared_link, update_shared_link, and list_shared_links by emphasizing inspection of a specific link.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says 'Use this to inspect a specific link's configuration,' providing clear context for when to use it. It also mentions the link_id comes from list_shared_links, guiding the workflow. However, it does not explicitly state when not to use it or list alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden, and it does well by explicitly stating 'Read-only' and describing the JSON return shape including total and an activities array with fields. It does not mention pagination, error cases, or auth requirements, but for a simple list operation the disclosed behavior is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: a plain-language summary first, then a clear Args section, then a Returns section. Every sentence adds information, and the read-only note is placed early where it matters most.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fully covers the three parameters, the purpose, the read-only nature, and the return format. Given that the tool has only one required parameter and the output schema is already available, nothing essential is missing for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it does thoroughly. Each parameter is explained: album_id identifies the album, asset_id restricts to a specific asset, and activity_type accepts 'comment' or 'like' with omission meaning both. This adds meaningful semantics beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool reads comments and likes on a shared album or a specific photo within it. The phrase 'Use this to read what the people an album is shared with have said' is a specific verb-plus-resource statement that separates it from create/delete activity siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear guidance on when to use the tool: to read activity on an album or one of its photos. It does not explicitly name alternatives or state when not to use it, but the read-only framing and the focus on social activity make the intended context unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states 'Read-only' and describes the return shape in detail. It also clarifies that each memory includes a trimmed assets list, which is useful behavioral context. It does not cover error behavior or authentication, but for a simple read-only list tool the disclosure is solid.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear purpose statement, a usage hint, a compact Args section, and a Returns section. Every sentence adds information; there is no redundancy or fluff. 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.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with three optional parameters and an output schema, the description covers all the essential information: what the tool does, when to use it, the meaning of each parameter, and what fields the response contains. Nothing critical is missing for an agent to call it correctly. Minor omissions like null filter behavior or error handling are not substantial given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description fully compensates: every parameter is explained with its semantics. for_date is described as an ISO date with behavior and an example, is_saved is defined for true/false, and size is given a default and meaning. This far exceeds what the bare schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ('List memories') and clarifies what memories are in Immich's domain: 'on this day' collections of photos from past years. This clearly distinguishes the tool from sibling tools like list_assets, create_memory, update_memory, and delete_memory by defining the unique concept it operates on.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a concrete use case: 'Use this to build a tal día como hoy story, album or PDF.' It clearly implies when to call this tool, but it does not explicitly mention when not to use it or name alternatives like list_assets for raw asset listing. This is clear context without exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses a key side effect: moving rejected duplicates to trash. It also notes recoverability via restore_assets. This provides essential behavioral insight beyond basic mutation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences plus a structured Args block. Every sentence adds value, and the purpose is front-loaded. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the single parameter and presence of an output schema, the description covers all necessary aspects: purpose, when to use, parameter structure, side effects, and return format. It references sibling tools appropriately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero description coverage (only 'type: object, additionalProperties: true'). The description fully compensates by detailing the exact fields required: duplicateId, assetIds, trashIds, with data types and source references. This is indispensable for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool resolves duplicate groups by choosing which assets to keep and trash, explicitly referencing the parent tool get_duplicates, which distinguishes it from sibling tools like merge_people or delete_assets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context to use this after reviewing results from get_duplicates, and mentions that trashed assets can be recovered via restore_assets. While it doesn't explicitly state when not to use, the guidance is sufficient for typical workflows.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and meets it: it explicitly declares 'Read-only,' so the agent knows this is a safe read. It also discloses a non-obvious edge case — cities only appear once they hold at least 5 assets, so small libraries can come back empty — and explains the 'one representative asset per city/concept' selection behavior. This goes well beyond what structured fields could have conveyed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, followed by usage guidance, then edge-case and safety notes, each earning its place. The only redundancy is the 'Returns:' section, which partially overlaps with the existing output schema — though it does add a concrete example field name ('exifInfo.city') and the asset_id pairing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only tool with an output schema, nothing an agent needs to invoke it correctly is missing: semantics, usage timing, edge-case empty returns, and safety are all covered. The missing annotations are fully compensated by the explicit 'Read-only' statement and the small-library warning. The output schema handles the detailed return structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters and the schema's properties object is empty, so the 0-param baseline of 4 applies and there is no parameter gap to compensate for. The description instead uses the space to clarify what the response represents, which is appropriate. No parameter-level meaning is missing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource — 'Overview of what the library contains, grouped by explore field' — and grounds it in Immich's Explore page. It answers 'what is in here?' in one call, clearly distinguishing this library-wide overview from the targeted search_* siblings such as search_metadata and search_cities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
'Use this to get oriented in an unknown library before searching for anything specific' is an explicit, actionable when-to-use instruction. It implies a temporal when-not — once you want something specific, move on to targeted search tools — but it never names an alternative sibling, leaving the agent to infer which search_* tool to use next. Clear context with an implied exclusion, but no explicit alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and clearly discloses 'Read-only' along with the JSON return format. It also flags the OCR dependency ('needs OCR on the server') and that results are random, which are non-obvious 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized: purpose and usage up front, then an Args block, then Returns. Each sentence contributes necessary information, and nothing is redundant or wasteful given the 7-parameter surface.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only random-search tool with no annotations and 7 optional parameters, the description covers purpose, use cases, parameter semantics, safety (read-only), and return shape. The output schema provides the formal structure, so the description fully equips an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully compensate, and it does. Every parameter (size, city, country, make, model, is_favorite, ocr) gets a plain-language meaning, with size's default/max and the OCR server dependency highlighted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description opens with 'Random assets from the library, optionally filtered' – a specific verb, resource, and mode that sets it apart from all other search_* siblings. The sampling use cases ('quick feel', 'surprise pick', 'spot checks') further clarify its unique role without confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use the tool with concrete use cases like sampling and spot checks. It does not name alternative tools or give exclusion criteria, but the context is clear enough that an agent can decide this is the random/sampling choice among the many search 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?
With no annotations provided, the description carries full behavioral weight. It discloses that the tool is read-only, returns distinct values, and provides a JSON response with total and suggestions. It does not cover every edge case, but the essential behavioral traits are transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tightly written, front-loads the core behavior and usage example, and organizes the argument documentation clearly. Every sentence adds value, and the length is appropriate for the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 5 parameters, missing schema descriptions, no annotations, and existing output schema, the description covers all essential context: purpose, when to use, all parameter meanings, and the return shape. Nothing critical is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully document parameters. It does: suggestion_type is listed with all six allowed values, and country, state, make, and model each get a clear narrowing explanation. This adds substantial meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific purpose: returning distinct values for one field, with the exact spellings search_metadata expects. This clearly distinguishes it from the many search-related sibling tools and explains what the tool accomplishes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly advises using this tool before filtering by city or camera to avoid guessing, which gives clear contextual guidance. It does not explicitly name alternative tools or state when not to use it, but the usage context is strong enough for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosing side effects, and it does: it states the change 'permanently changes the metadata of every listed asset' and notes that only provided fields change. It also flags rating limitations (cannot be cleared, 0 rejected). This is strong behavioral disclosure for a mutating tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and efficiently front-loaded: it opens with the core batch purpose, gives relatable examples, then lists parameters in a scannable Args block. Every sentence adds value, including the side-effect warning and return type.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 7 parameters, no annotations, and a meaningful sibling distinction, the description covers purpose, usage, parameter semantics, side effects, and return value. Nothing critical is missing for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates by explaining each parameter's meaning: ISO 8601 for date_time_original, decimal degrees for GPS, favorite status semantics, and the special -1/0/1-5 rating rules. This adds meaning well beyond the raw schema field names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Update'), a clear resource ('metadata fields on many assets'), and the batch nature in 'ONE call'. It explicitly differentiates itself from the singular sibling update_asset_metadata by emphasizing multi-asset operation, so an agent can distinguish the tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives concrete usage scenarios (scanned album roll, trip photos, selection favorites) and references update_asset_metadata as the same-fields counterpart. It implies the singular tool is for single assets, though it does not explicitly state 'use update_asset_metadata for one asset', so some inference remains.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does it well: it discloses the side effect of writing a file on the server machine, streaming to disk for large albums, and the no-overwrite guarantee. It also states the return shape. These are meaningful behavioral details beyond what the schema provides.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear first-sentence purpose, a useful usage hint, behavioral facts, then a labeled Args and Returns section. Every sentence adds value and nothing feels redundant or padded. It is appropriately sized for the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no schema descriptions, the description covers all essential aspects an agent needs: purpose, parameter selection, side effects, safety, and return format. The existence of an output schema covers detailed return structure. It even names the related get_download_info tool for size checks. No critical decision-making information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains each parameter: output_path (where to write, existing file refused), album_id (whole album), asset_ids (just those assets). It adds the mutual exclusivity via 'or' and the refusal behavior. It lacks explicit detail on what happens if both or neither are provided, but the core semantics are clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Download an album or a selection as one zip of the original files') and the destination ('written to a local path'). It distinguishes from siblings by specifying the zip of original files and local-path output, which separates it from get_download_info, export_pdf, and thumbnail/image tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly directs the agent to call get_download_info first when size matters, which is a clear alternative and condition. It also presents the album_id vs asset_ids choice with 'or'. However, it does not explicitly state when not to use this tool (e.g., for previews or PDF exports), so it falls slightly short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states 'Read-only' and explains the exact return shape: 'JSON with album metadata, a flat list of all asset_ids, and an assets array.' It also notes that the returned recognized people data can answer questions about who appears in an album without further calls, which is a useful behavioral promise. It does not cover error conditions or authentication requirements, but for a read-only single-resource fetch this is a minor gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: the purpose is front-loaded in the first sentence, followed by usage guidance, parameter explanation, and return details. Every section earns its place, and there is no redundant padding. The 'Args' and 'Returns' sections are clearly labeled, making it easy for an agent to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read-only fetch with an output schema, the description is complete: it states purpose, when to use it, what album_id should be, and what the response contains. It also contextualizes the return data with the 'who appears in this album / who repeats' use case. No critical information for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the parameter's meaning. It does: 'album_id: The album's UUID (from list_albums or create_album).' This adds format guidance and tells the agent where to obtain valid values, which is genuinely helpful beyond the bare schema. The one parameter is fully addressed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Get full details for a specific album including all its asset IDs.' It clearly distinguishes itself from list_albums by stating, 'For listing all albums, use list_albums instead.' This makes the tool's purpose unambiguous and differentiates it from its closest sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use this tool: 'to inspect album contents or retrieve asset IDs for further operations (thumbnails, metadata, rotation).' It also gives an explicit exclusion: 'For listing all albums, use list_albums instead.' This provides clear routing for an agent choosing between 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?
With no annotations present, the description carries the behavioral disclosure burden. It clearly states 'Read-only', discloses that with_notes incurs 'One extra request', and describes what the returned notes object contains. It does not discuss auth requirements or failure behavior, but for a simple metadata retrieval tool this is reasonably transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, followed by clear usage guidance, parameter explanations, and return-value summary. Every sentence earns its place, and the format with Args and Returns sections makes it easy for an agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter, single-asset metadata lookup, this description covers the key context: when to use it, how to obtain asset_id, the optional with_notes behavior, cost implications, and the shape of the response. The presence of an output schema means the return-value summary in the description is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains both parameters: asset_id is 'The asset's UUID (from search results, album listings, or list_assets)' and with_notes is described as including notes at the cost of one extra request. This adds meaningful guidance beyond the schema's bare type definitions, though it does not enumerate the exact notes structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Get full metadata for a single asset.' It distinguishes the tool from its siblings by explicitly naming the metadata types (EXIF, GPS, camera info, file properties) and contrasting with search_metadata and search_smart, which are for finding assets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool ('Use this when you need EXIF details, GPS coordinates, camera info, or file properties for a known asset ID') and provides clear alternatives ('For finding assets, use search_metadata or search_smart instead'). It also signals the read-only nature, helping the agent avoid unsafe or irrelevant choices.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility for behavioral disclosure. It explicitly states the operation is read-only, notes the ordering ('newest last'), and defines the empty-list behavior when the asset was never annotated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The key purpose and behavior are front-loaded in the first sentence, followed by compact Args and Returns sections. Every sentence earns its place with no redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read-only tool, the description covers the input, the full return shape, ordering, and edge case behavior. Nothing essential is missing for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema gives no description for asset_id, so the description must compensate. It explains that asset_id identifies 'the asset to read,' which is sufficient for a simple string parameter, though it adds no further constraints or format details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('get'), a specific resource ('notes on one asset'), and the content of those notes (review verdicts and recorded actions). This distinguishes it from the plural sibling get_assets_notes and other note-related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly scopes the tool to a single asset ('one asset') and labels it read-only, so an agent can infer when to use it. It does not explicitly name alternatives or say when not to use it, but the singular scope is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations at all, the description carries the full burden and delivers thoroughly: it explicitly declares 'Read-only', explains the per-asset server query batching, discloses the cost profile (no tokens on assets without notes), and defines partial-failure semantics (failed array of {asset_id, error}; 'Success is true only when nothing failed'). This is rich behavioral context far beyond the bare schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is front-loaded in the first sentence and the text is cleanly organized into Args and Returns sections. It runs a bit long (~150 words) and the Returns paragraph overlaps with the existing output schema, but given 0% parameter schema coverage and absent annotations, the length is largely justified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a batch read tool with variable-length input, partial-failure handling, and no annotations, the description is complete: purpose, use case, cost/safety behavior, parameter semantics, return shape, and a precise success criterion. Nothing an agent needs to invoke the tool or interpret its result is left to guesswork.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% — asset_ids has only a title and array-of-string type. The description compensates fully by defining it as 'the candidates to check' with concrete examples ('an album's assets, a search result'), which tells an agent exactly what to pass and where that list comes from.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
States a specific, actionable purpose: it returns which of a batch of candidate assets already carry notes and their last verdict. The plural framing ('these assets', 'an album's assets') and the candidates-to-check semantics distinguish it from the singular sibling get_asset_notes, and no other sibling reads notes in batch, so an agent can select it confidently.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a concrete when-to-use scenario — a cleanup pass that wants to skip assets an earlier session already reviewed — and explains the cost rationale (the server is queried once per asset, no tokens spent on unannotated ones). It does not explicitly state when not to use it or name an alternative, so it stops one step short of full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It declares the operation as read-only, which is key. It also describes the return format. However, it does not mention potential pagination limits if 'all' is large, but given the context, this is minor.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with a clear purpose and Args/Returns sections. However, the Args section slightly duplicates information already in the description, but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (1 optional param) and the presence of an output schema, the description covers all essential aspects: purpose, usage guidance, parameter behavior, and return format. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant meaning for the single parameter 'shared': true for shared, false for non-shared, omit for all. This is much more informative than the schema's type (boolean or null) and covers all possible values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all albums with summary info. It distinguishes from siblings by specifying it's for discovery and finding album IDs, which contrasts with other tools like get_album for details or create_album for adding.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: to discover existing albums before creating new ones or to find an album ID. Also declares it's read-only, implicitly guiding away from mutation tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It clearly states the operation is read-only and describes the return format ('server' status with 'pong' if healthy). This fully informs the agent about behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with no wasted words. It front-loads the purpose and provides necessary details in just three lines.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters, straightforward output), the description covers all needed aspects: purpose, usage timing, read-only nature, and return format. It is fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is empty (no parameters). The description adds no parameter details but compensates by explaining the return value, which is relevant since the agent must understand what the tool outputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'check' and the resource 'Immich server connectivity'. It distinguishes itself from sibling tools by indicating it's a readiness check, not a data manipulation operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use this to verify reachability before other operations, providing clear context. It does not mention alternatives, but due to the tool's simplicity, this is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses the side effect of moving assets out of trash. However, no annotations are present, so the description carries the full transparency burden. Could mention error handling or permissions, but the side effect is a key behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences plus structured Args/Returns. Front-loaded with main purpose, no wasted words. The important guidance about selective recovery is placed early.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the essential information: what it does, when to use, side effect, parameter, and return value. Could be improved by mentioning validation or whether the operation is idempotent, but it's sufficient for safe usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains that 'asset_ids' is a list of asset UUIDs currently in trash, which adds context beyond the schema's type definition (array of strings). With 0% schema description coverage, the tool description effectively documents the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'restore', resource 'assets from trash', and destination 'active library'. Distinguishes from sibling 'restore_trash' by specifying selective recovery vs mass restore.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use this tool (selective recovery) and when not to use it (use restore_trash for everything at once), directly naming the alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description discloses side effect (moves all trashed assets back to active library) and return format (JSON success confirmation). Could mention if operation is reversible or requires permissions, but adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences with no wasted words. First sentence states purpose, second provides usage guidance, third adds behavioral detail and return info.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless tool with an output schema, the description covers purpose, use case, side effect, and return format. No obvious gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has no parameters; description clarifies that it acts on all trashed assets globally, implying no user choice. No param info needed, baseline high.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Restore ALL trashed assets back to the library' with specific verb and resource, and distinguishes from sibling tool 'restore_assets' which restores specific assets only.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use (undo accidental bulk deletion) and provides alternative (restore_assets for specific assets).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden and exceeds it: it discloses the write side effect ('writes the plugin's metadata key on each asset; other apps' keys are untouched') and the partial-failure semantics ('Success is true only when nothing failed'). This is precisely the behavioral context an agent needs beyond bare schema fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average but front-loads purpose and usage before side effects, args, and returns, and every section earns its place. The Args/Returns layout is scannable; a slight tightening of the example prose would make it a 5, but there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter, 2-required write tool with zero schema descriptions and no annotations, the description is fully self-sufficient: purpose, when-to-use, side effect, all parameter semantics, and return shape with failure handling are covered. Nothing an agent needs to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must supply all parameter meaning — and it does critically, by enumerating the valid verdict values ('keep', 'delete_candidate', 'duplicate_of', 'needs_check') that the schema omits as an enum. It also adds format guidance for reason with a concrete example and a 'short and concrete beats long' rule.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific purpose — persisting a review verdict with its reason so later sessions skip re-analysis — with a clear resource ('assets') and a precise outcome ('the why survives'). It also differentiates from siblings by noting tags are Immich-visible while these notes are not, which distinguishes it from tag_assets and record_action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
'Use this after deciding what to do with a photo in a cleanup or duplicate pass' gives explicit when-to-use context, and the tag comment provides a real selection condition (user must see the state in Immich). It does not explicitly name sibling tools such as tag_assets or resolve_duplicates as alternatives, so exclusion guidance is implied rather than exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description fully discloses behavioral traits: non-destructive, no file modification, display transform only, edits are written to Immich and accumulate, side effect of persisting rotation. With no annotations provided, the description carries the full burden and meets it exceptionally.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear purpose statement, usage guidance, and an Args section. It is front-loaded with key information. However, a few extra words ('Provide EITHER...') could be trimmed without losing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, three parameters with mutual exclusivity, and an output schema (implied), the description covers purpose, behavior, parameter usage, return value, and side effects. It is complete and leaves no significant gaps for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description compensates fully by explaining each parameter: angle (multiples of 90, default 90), asset_ids (list of UUIDs, mutually exclusive with album_id), album_id (string, mutually exclusive with asset_ids). It adds constraints and defaults not present in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (non-destructive clockwise rotation), the target (one or more assets), and the purpose (fix orientation issues). It distinguishes from related tools like revert_asset_edits and delete_assets, making its role unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool ('fix orientation issues') and mentions revert_asset_edits as an alternative for undoing. It also clarifies mutual exclusivity of asset_ids and album_id. However, it does not explicitly state when not to use it or compare to other rotation-like tools (none exist among siblings).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description bears the full burden — and meets it. 'permanently deletes the album (cannot be undone)' discloses irreversibility, and the NOT-deleted photos caveat prevents a destructiv misunderstanding. These are exactley the safety-relevant facts an agent needs before invoking a destructiv tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Roughly 60 words, front-loaded with the core action, followed by the key caveat, use case, side-effect warning, parameter, and return type. Every sentence earns its place and no filler exists.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter destructive tool with zero annotation coverage, all gaps are closed: action, side effect, permenance, parameter format, and return shape. Nothing needed to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% — the schema only says album_id is a string. The description fully compensates with 'The album's UUID to delete,' adding both the required format (UUID) and the parameter's role. For a single-parameter tool this is complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Delete') + resource ('album container') and immediately distinguishes itself from siblings by clarifying 'The photos inside are NOT deleted — they remain in the library.' This sets it apart from delete_assets and remove_assets_from_album without needing to open those tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
'Use this to remove unwanted album groupings' gives a clear intended scenario. The photos-remain caveat implicitly routes away from photo-deletion tools, but alternatives are not explicitly named, so it stops short of the explicit when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden and does it well. It explicitly discloses the permanent, irreversible nature of the deletion and states that assets are not affected. This is exactly the kind of side-effect transparency needed for a 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short, front-loaded with the primary action, and uses clear sections for side effects, arguments, and return value. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter destructive tool with an output schema, the description covers the action, the irreversible side effect, the parameter meaning, and the return value. Nothing essential is missing for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only provides 'type: string' and 'title: Tag Id', so the description fully compensates by specifying that tag_id is 'The tag's UUID to delete'. This adds both type detail (UUID) and purpose, which is sufficient for the single required parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Delete') and resource ('a tag'), then clarifies the key differentiator: the tag is removed from all assets but the assets themselves are unaffected. This clearly distinguishes it from asset deletion and other tag-related 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use it: when a tag should be permanently deleted and removed from all assets. It doesn't explicitly name an alternative like untag_assets, but the behavior is clear enough that an agent can infer when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the safety burden; it states 'Read-only' and describes return type and size/limit behavior. It doesn't document error handling or output structure details, so while transparent, it isn't exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose, usage-routing, read-only safety, args, and return are all covered in a compact, front-loaded layout. No filler sentences; the Args list is scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete enough to invoke correctly without opening sibling definitions or schemas: it identifies the album resource, optional parameters with defaults, output type, and the key alternative. The absence of an output schema is mitigated by the Returns line.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but description documents all three parameters: album_id as UUID, size values with pixel dimensions and default, and limit range 1-50 with default. This fully compensates for the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Get'), a clear resource ('an album'), and a concrete output type ('image blocks for inline visual display'). It also names the sibling alternative get_album_thumbnails, making the distinction explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this to visually browse an album in clients that render images' and directs to get_album_thumbnails for HTML gallery generation with base64 data URIs. This gives an agent a clear decision rule rather than relying on tool names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description reveals the read-only nature and the return format (JSON with 'data' and 'type'). It does not mention potential error scenarios but adequately discloses core behavior beyond what annotations would provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: purpose sentence, usage guidance, parameter details, return format. Every sentence adds value with no extraneous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for this simple tool, covering purpose, when to use, parameters, returns, and behavioral read-only trait. Even with an output schema existing, the description provides necessary context for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description adds full meaning: asset_id is a UUID, size has two options with pixel dimensions and a default. This compensates entirely for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a base64-encoded thumbnail for a single asset, using a specific verb and resource. It distinguishes itself from siblings by naming alternative tools for batch or album thumbnails.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use ('visually inspect one photo') and when not to (multiple photos: use get_thumbnails_batch or get_album_thumbnails). It also marks the operation as read-only, providing clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does well: it discloses that the operation is read-only, that it depends on the ML service, and that results are duplicate groups with similarity scores. It does not mention failure modes or authorization, but the key behavioral traits are covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with a front-loaded purpose, an explicit note, an Args section, and a Returns section. Every sentence contributes meaningful information, and the format makes it easy for an agent to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given only one optional parameter and an output schema, the description fully covers the tool's behavior, input semantics, return shape, and dependency. An agent has enough context to decide whether and how to invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it does for the only parameter. It explains album_id is optional, restricts to groups touching the album, and changes the returned group metadata to include inside/outside asset status.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ('Get ML-detected duplicate asset groups') and clarifies the meaning as 'same image stored more than once.' It also explicitly distinguishes itself from related tools like get_album and get_asset_faces, so an agent can immediately tell what this tool is for.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly states when to use the tool ('review potential duplicates before resolving them with resolve_duplicates'), when not to use it ('not the same person'), and names alternative tools for the other case. It also flags the dependency on the Immich ML service.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It explicitly says 'Read-only', describes the returned options with defaults, and gives the return shape including error format. This is strong behavioral disclosure for a read-only preview tool. It could add what happens if both album_id and asset_ids are supplied, but the 'Pass exactly one' instruction covers the main contract.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized into clear sections: purpose, usage guidance, args, and return format. Each sentence adds value; the options-explanation is directly actionable and the parameter list is compact. Length is appropriate for the tool's complexity without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema, but the description still covers the practical decision flow, parameter semantics, return values, and error case. It even explains how to use the returned options to decide between preview-guided asking and direct export. Nothing an agent needs to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description fully compensates by explaining each parameter: album_id as Album UUID, asset_ids as explicit asset UUIDs, and limit as max assets with range and default. It also adds the critical exclusivity rule that the schema alone does not convey. Every parameter is given meaningful context beyond its title.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('List'), a specific resource ('what export_pdf would include'), and the included fields (id, type, filename, date, place, people, video duration). It clearly positions this as a preview tool and distinguishes it from its sibling export_pdf. The read-only note and the exclusivity requirement further sharpen the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: call it before looking at images and writing captions to know which assets exist. It also explains what to do with the returned options: when the user gave no PDF preferences, show the choices and ask; when they gave specs or want defaults, export directly. This effectively routes the agent between this tool and export_pdf.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full transparency burden, and it explicitly marks the operation as 'Read-only.' It also discloses the limit truncation behavior ('Only the first N IDs are fetched') and the return shape, which is useful behavioral context beyond the bare schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with purpose and usage, followed by a structured Args block. Every sentence adds information: usage context, alternative routing, read-only status, parameter details, and return type. There is no filler or tautology.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only tool with three parameters and no output schema, the description is complete: all inputs are documented with defaults and behaviors, the return type is stated, and the main sibling alternative is explicitly distinguished. No critical information needed to invoke the tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it does: asset_ids are defined as asset UUIDs, size is explained with concrete pixel values ('thumbnail' 250px/'preview' 1440px), and limit is given a range (1-50), default (20), and selection behavior. Every parameter receives meaningful semantics not present in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Get thumbnails for arbitrary asset IDs') and the exact output type ('image blocks for inline visual display'). It further distinguishes itself from the sibling get_thumbnails_batch by naming the alternative and the scenario where that tool should be used instead.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says when to use this tool ('visually show search results in clients that render images') and names the alternative tool for HTML gallery generation with base64 data URIs. This gives an agent clear routing guidance between two similarly named batch thumbnail 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?
Declares 'Read-only' which is key behavioral disclosure. With no annotations, the description carries full burden; it also lists return fields. However, it does not mention potential errors or authorization, but for a simple read operation it is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no fluff: purpose, usage context, args/returns. Front-loaded with key information, every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a simple single-parameter tool with an output schema, the description adds necessary context about the person_id source and the fields included in the response, making it fully self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Even though schema description coverage is 0%, the description adds crucial meaning: 'The person's UUID (from list_people or search_people)' explains the expected format and source, fully compensating for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and resource 'full details for a specific person including name, birth date, and photo count'. It distinguishes from siblings like list_people and search_people by focusing on a single person's detailed retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Use this after finding a person via list_people or search_people', providing clear context for when to use and sourcing for the required person_id parameter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Mentions read-only nature and return format. No annotations provided, so description carries burden. Could add details on authentication or rate limits, but covers key behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, well-structured with Args and Returns sections. Every sentence adds value; no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a batch thumbnail tool with output schema. Explains return structure and parameter constraints. No missing context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters are explained with details not in schema: asset_ids as UUIDs, size with pixel dimensions, limit with range and behavior. Compensates for 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it retrieves base64-encoded thumbnails for arbitrary asset IDs without needing an album. Distinguishes from siblings like get_album_thumbnails and get_asset_thumbnail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly describes when to use (visual display of search results or ad-hoc sets) and when not to (use album-based for albums, single for single photos). Names alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full disclosure burden and meets it: it declares 'Read-only,' characterizes the call as cheap ('one cheap call'), and discloses ordering defaults ('newest month first unless order="asc"') plus per-filter counting semantics for every argument. This gives an agent a reliable safety, cost, and behavior picture that the empty schema and absent annotations do not 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a memorable summary, followed by a single purpose-driven usage sentence, then compact Args/Returns blocks. Given that the schema provides zero descriptions, every section earns its place, and the structured line layout keeps it scannable without bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no annotations and an empty schema, an agent can select and invoke this tool correctly: all parameters are optional and documented, defaults are explicit, and the return shape (total_buckets plus buckets array of {timeBucket, count}) is stated even though an output schema exists. The only minor omission, the concrete type of timeBucket, is covered by the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the tool description must carry all parameter meaning, and it does: a documented Args block explains all five parameters (album_id, person_id, tag_id, is_favorite, order), including what each filter counts and the order value/default. This fully compensates for the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific resource and behavior: 'Month-by-month map of the library: one bucket per month with its asset count,' which clearly defines an aggregation tool over time buckets. It implicitly distinguishes itself from the sibling get_timeline_bucket (singular) by describing a full month-by-month map, and frames its role as a pre-fetch navigation aid rather than a per-item lookup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
'Use this before fetching assets' gives an explicit point-in-workflow trigger, and the description names concrete use cases: 'finding gaps, busy periods, or navigating a large library without paging through everything.' It does not name specific alternative tools or state when not to use it, so it stops just short of full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and handles it well: it states read-only behavior, the confirmation gate above 12 frames, the 120-frame cap, parameter interactions (interval overrides count), and the exact return shapes including confirmation and error objects. This is unusually thorough behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a one-sentence summary, then organized into Args and Returns sections. Every line carries needed information: parameter semantics, defaults, constraints, and output structure. It is dense but not bloated, and the structure makes it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given seven parameters, zero schema descriptions, and no annotations, the description covers all necessary invocation details, including the confirmation flow and return shapes. The presence of an output schema reduces the need to document return values, yet the description still provides an accurate summary, making the tool fully self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates by documenting every parameter with type, default, meaning, and constraints. It adds valuable semantics like '600px preview is ~6.4k tokens per frame' and 'interval is mutually exclusive with count', which the bare schema cannot convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns video frames as base64 JPEGs with timestamps, which is specific and distinguishes it from the sibling get_video_frames. It also names the intended use cases (HTML galleries and skills) and explicitly references the sibling to clarify the relationship.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context for when this tool is appropriate by mentioning HTML galleries and skills, and by framing it as a read-only JSON-returning variant of get_video_frames. It does not explicitly state 'use this instead of get_video_frames when...', but the intended use is clear enough without exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it delivers: it declares 'Read-only', documents the tri-state behavior of favorite/archived flags, and exposes the Immich-specific quirk that trashed items and active library items are never mixed. This goes well beyond a bare action statement, though it could add more detail on filter interactions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is stated first, followed by a compact Args block that earns its place. Every sentence conveys operational value, and there is no repetition of schema defaults that are already visible.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the operation, filters, pagination, and a summary of return fields. An agent has enough to invoke list_assets correctly and interpret the result, especially given the output schema is also provided. No critical guidance is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate fully, and it does. Every one of the six parameters is explained with accepted values, defaults, and omission behavior. This makes the tool callable without needing to infer anything from ambiguous schema titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'List assets with simple filters', and clarifies it is for browsing, not search. It also explicitly distinguishes itself from search_metadata and search_smart, so an agent can tell siblings apart at a glance.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It states exactly when to use this tool ('browse the library by status or type') and names the alternatives for finding specific content ('search_metadata (structured) or search_smart (visual AI)'). This is explicit when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states the tool is 'Read-only' and describes the return format, but does not disclose potential rate limits, authentication requirements, or any side effects beyond the listed behavior. However, for a simple read operation, the level of disclosure is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise yet comprehensive, with a clear structure: purpose, usage note, parameter block, and return note. Every sentence adds value, and the length is appropriate for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity and the presence of an output description (though no formal output schema), the description covers all contextual needs: what the tool does, when to use it, parameters, and return format. It is fully self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaningful descriptions for each parameter (page, size, with_hidden) beyond the schema's basic type/default definitions. The schema had 0% coverage, but the description fully compensates by explaining the semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('list'), the resource ('all recognized people'), and the context (face clusters in the library). It also distinguishes the tool from its sibling `search_people`, avoiding ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use this tool ('browse who appears... or find a person's ID') and when not to ('For searching by name, use search_people instead'). This provides clear usage context and alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and delivers: it discloses the side effect ('writes the plugin's metadata key on each asset'), scopes it ('other apps' keys are untouched'), and explains partial-failure semantics ('Success is true only when nothing failed', with a failed array of {asset_id, error}). This is exactly the behavioral context an agent needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose is front-loaded in the first sentence, the side effect follows immediately, then a tight Args/Returns structure. Every sentence earns its place — the examples in Args serve as operational guidance, not padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter tool with no annotations and no schema descriptions, the description is complete: purpose, side effects, parameter semantics, return format, and success criteria are all covered. The only minor gap is whether the metadata key is overwritten or appended on re-record, which is negligible against the overall coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate — and it does. The Args section gives all three parameters real meaning: asset_ids ('the assets the action touched'), action with example labels ('added_to_album', 'date_fixed', 'rotated'), and detail with concrete content guidance ('album name, previous value, the user's request'). Fully compensates for the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Remember something the plugin did to assets') and names the purpose ('for audit or undo'), with concrete examples of what gets recorded. This clearly positions it as a logging/audit tool distinct from the many sibling mutation tools (rotate_assets, tag_assets, delete_assets) and undo tools (restore_assets, revert_asset_edits).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context for when to use it: after the plugin changes assets, to preserve prior state and rationale for audit or undo. The examples (which album, previous date, why rotated) make the trigger scenario concrete. It doesn't explicitly name exclusions or alternative tools, but no sibling fills this recording role, so the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It explicitly declares 'Read-only,' discloses a server-side prerequisite for the ocr parameter ('Needs OCR enabled on the server — check with get_capabilities'), and notes case-sensitivity for city. It also describes the return shape. Missing are filter-combination semantics (AND vs OR across fields) and sorting behavior, but the key behavioral traits are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is cleanly organized: a purpose-and-routing paragraph, a complete Args list covering all 15 parameters, and a one-line Returns note. Every sentence earns its place, and the length is fully justified given that the schema provides zero descriptions for the parameters. Information is front-loaded with purpose before detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a high-complexity tool (15 optional parameters, no annotations, 0% schema coverage), the description covers everything needed to call it correctly: purpose, routing, all parameter semantics, return format, and the OCR prerequisite. An output schema exists, so return values need no further elaboration. The only implicit detail is cross-filter AND combination, which is minor given the 'only' qualifiers on each filter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully compensate — and it does. Every one of the 15 parameters gets meaning, format hints, and often concrete examples ('Barcelona', 'iPhone 14 Pro', 'EOS R5'). It clarifies case-sensitivity, ISO date semantics, the ALL-matching rule for person_ids, omit-for-both behavior for asset_type, and the 1-200 range for size. This is exemplary compensation for a zero-coverage schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Search assets by EXIF metadata fields' — a specific verb, resource, and mechanism. It further distinguishes itself from siblings by name: search_smart for natural language visual queries and list_assets for browsing without criteria. An agent can pick this tool correctly without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use this when you know specific criteria like city, camera model, or date range' and then gives named alternatives with conditions: 'For natural language visual queries... use search_smart instead. For browsing without criteria, use list_assets.' This is textbook when/when-not/alternatives guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Declares 'Read-only' and describes return fields. No annotations provided, so description carries full burden. Missing details on potential errors or pagination, but sufficient for a simple search tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Five well-structured sentences, including an Args section. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage, parameters, return format, and sibling differentiation. Output schema exists but description already mentions return fields. Complete for a simple tool with 2 parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but description adds meaning for both parameters: name is case-insensitive partial match, with_hidden includes hidden people and default false. This goes beyond schema titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Search for people by name (partial match)' with a specific verb and resource. It distinguishes from sibling 'list_people' by noting that list_people is for browsing all.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this when you know the person's name. For browsing all people, use list_people instead.' Provides clear when-to-use and alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full disclosure burden and delivers: 'permanently changes asset metadata in Immich' warns of the irreversible side effect, 'Only provided fields are modified' clarifies partial-update semantics, and the rating caveat ('cannot be cleared from here, 0 is not a rating Immich 3.x accepts') flags version-specific behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose, use cases, and side effect are front-loaded in three tight sentences; the Args list maps 1:1 to schema parameters in a scannable format; the single Returns line closes the contract. Every sentence earns its place given 7 parameters need documentation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-parameter mutation tool with no annotations and no schema-level descriptions, the description covers purpose, when to use it, side effects, every parameter's format and range, and the return shape (backed by the output schema). Nothing an agent needs to construct a correct call is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description fully compensates by documenting all 7 parameters with real semantics: UUID for asset_id, an ISO 8601 example for date_time_original, decimal-degree ranges for latitude/longitude, and the -1/1-5 rating scale with rejection semantics that the bare schema could never convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Update metadata fields on a specific asset.' The singular framing distinguishes it from the sibling update_assets_metadata, and the concrete use cases (fix dates, correct GPS, add descriptions, change favorite/rating) make the tool's scope unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use context via 'Use this to fix dates, correct GPS, add descriptions, or change favorite/rating status.' However, it does not name the batch alternative update_assets_metadata or state when not to use this tool, so it stops short of full when/when-not routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses side effects: persists to disk, hot-swaps live connection, and validates credentials. Also mentions return structure (success status, counts, persistence path). No annotations provided, so description fully covers behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Concise with no wasted words. Structured in clear paragraphs: purpose, when to use, side effects, args, returns. Front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all necessary aspects: purpose, usage, behavior, parameters, and return. Output schema exists, so return details are sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, but the description adds detailed explanations for both parameters, including expected format and example for base_url, and origin for api_key.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly specifies the verb 'Update' and the resource 'Immich connection credentials'. Distinct from sibling tools like get_connection_info (read-only).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: when API key is rotated or server URL changed. Does not mention when not to use, but the use case is specific enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and delivers thoroughly. It explains side effects (creates new asset), security restrictions (symlinks rejected), and that the original file is untouched. The return format is also described.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized, starting with a clear purpose, followed by constraints in a bullet-like format, and parameter details. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, the description covers all necessary aspects: purpose, usage context, behavioral details, parameter semantics, and return value. No gaps are evident.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite the input schema having no parameter descriptions (0% coverage), the description adds rich meaning: file_path is an absolute path that must exist, and album_id is an optional UUID for immediate album assignment. This fully compensates for the schema's lack of detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Upload' and the resource 'local photo or video file to Immich', and specifies its use for ingesting new media. It distinguishes itself from sibling tools which perform other operations like album management or search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit constraints (max 25MB, allowed types, symlinks rejected) and context for when to use the tool. However, it does not explicitly mention when not to use it or suggest alternatives, though the context of siblings makes it clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Labels as 'DESTRUCTIVE and IRREVERSIBLE' and describes side effects (permanently destroys trashed assets, frees storage). No annotations were provided, so description fully covers behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences plus a return line, all essential. Front-loaded with purpose and warning. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters and an output schema exists (return value described), the description is fully sufficient. Covers purpose, usage, side effects, and result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters in input schema, so description need not explain them. It adds return value description ('Returns: JSON with success confirmation'). Baseline for 0 params is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'permanently delete' and the resource 'ALL assets currently in trash'. It distinguishes from siblings like 'delete_assets' and 'restore_trash'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises to use only after user confirmation and provides an alternative tool ('delete_assets') for deleting specific items.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden, and it does so thoroughly: it discloses destructiveness, irreversibility, permanent deletion of merged persons, the transfer of faces, the preview behavior when confirm is false, and the side effects with confirm=true. The description is explicit that without confirm=true nothing happens, which is essential for an agent to avoid accidental data loss.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but organized: a clear purpose sentence, a behavioral warning, a workflow explanation, then a compact Args list and Returns line. Every sentence earns its place. Slightly long, but the destructive complexity justifies the length; the Args section could arguably be tightened, but it remains highly scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there are no annotations and no schema descriptions for parameters, this description provides everything an agent needs: purpose, when to use, destructive consequences, the confirm gate, parameter semantics, and return shape. The output schema exists and the description even names the preview keys, making the return behavior clear without redundantly restating the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain all three parameters, and it does: person_id is the target UUID that keeps faces, merge_ids are the persons absorbed and permanently deleted, and confirm is the boolean switch between preview and execution. It also mentions the default behavior (nothing happens without confirm=true) and the return structure, which adds meaning far beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource ('Merge multiple person clusters into one') and adds the crucial scoping detail that it is for the case where the same real person has been split into multiple face clusters. It is clearly distinguished from siblings like update_person, reassign_face, or delete_assets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use it ('when the same real person has been split into multiple face clusters') and explains the confirm=true vs confirm=false workflow, telling the agent to pass true only after the user has seen the preview and agreed. It also warns about irreversibility, which serves as a clear exclusion criterion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the full behavioral burden. It explicitly states the operation is read-only, describes the one-representative-asset behavior, and specifies the return shape. This goes beyond the tool name and gives an agent reliable behavioral expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured, with the core purpose first, a useful sibling comparison second, and return format last. Every sentence adds value and there is no redundant or vague wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only search operation with an output schema, the description is complete. It covers what is returned, how cities are selected, the comparison to a sibling tool, and the read-only nature, leaving no meaningful gap for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema coverage is 100%, so there is no parameter documentation burden. Per the baseline for zero-parameter tools, a 4 is appropriate since nothing more is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns every city in the library, with one representative asset per city. It also differentiates itself from search_explore by noting the lack of a minimum-asset threshold, making its purpose specific and distinct among sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly identifies when to use this tool: to answer 'which places are in this library?'. It also contrasts with search_explore, giving a concrete alternative and explaining the key difference, which is strong usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does: PDFs are written to disk, existing files are never overwritten, the PDF never enters the conversation unless return_base64=True, video frames cost no tokens, the map uses a third-party OSM tile server, and undeciable formats fall back to preview. Side effects, costs, and failure/fallback behavior are all disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Though long, the structure is efficient: purpose first, then key behavioral notes, then usage guidance, then a well-grouped argument list. Every sentence adds information an agent needs; nothing is redundant with the schema since the schema has no descriptions. The length is justified by the tool's 24-parameter complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the two mutually exclusive selectors, all defaults, the return JSON shape, edge cases (HEIC fallback, video frame cap, 2 MB base64 limit, third-party map call), language options, and the one-story-per-PDF rule. Combined with the schema defaults and the described output object, an agent has everything needed to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully explain the 24 parameters, and it does in detail. It clarifies defaults, mutual exclusivity (album_id vs asset_ids), parameter interactions (frame_times wins over frames_per_video/frame_interval; frame_captions only matter in photobook layout), numeric bounds (0-120, 1-500), and the meaning of each enum-like string (layout, order, footer, etc.).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence states exactly what the tool does: 'Build a PDF (cover, index, places, one section per asset) from an album or a list of assets' with the location ('on the machine running this server'). It also names the sibling get_export_preview and explicitly says to call it first when the user hasn't specified choices, so the agent can distinguish this tool from that one.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance: call get_export_preview first if the user asked for a PDF without specifying how; keep one story per PDF; offer one PDF per story rather than mixing unrelated assets; and when confirm is required (explicit assets mixing videos more than 90 days apart), only pass True if the user explicitly asked. This is direct, actionable usage guidance with clear alternatives and exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description states the tool is read-only, describes the return format (JSON with album info and thumbnails array including asset_id, base64 data, filename, date), and clarifies parameter behavior (size options with pixel dimensions, limit range). This full context compensates for the lack of annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise yet comprehensive: a clear purpose sentence, usage guidelines, read-only note, and structured parameter list with return details. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool having 53 siblings, the description sufficiently differentiates it and covers all needed context: input, output, behavior, and use case. The output schema exists, but the description still clarifies return structure, which is helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, but the description fully explains all three parameters: album_id (UUID), size (two options with default and pixel dimensions), and limit (range 1-50, default 20). This adds complete semantic meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get base64-encoded thumbnails for photos in an album.' It explicitly distinguishes from the sibling tool get_thumbnails_batch, ensuring proper differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: 'Use this to generate visual HTML galleries from an existing album. For thumbnails from search results (no album), use get_thumbnails_batch instead.' This tells both when and when not to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden, and it delivers. It explicitly states 'Read-only', describes the exact return type ('MCP ImageContent'), and explains the behavioral consequences of the size parameter (250px/fast vs 1440px/higher quality). This is sufficient behavioral disclosure for a simple retrieval tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tightly structured: purpose, usage context, parameter docs, and return type are each given in compact, front-loaded statements. There is no filler or redundancy; every sentence contributes distinctive information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter, single-asset image retrieval tool with no output schema, the description covers everything an agent needs: intended client environments, alternative for a different use case, full parameter semantics, return format, and read-only status. No critical information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully compensate, and it does. It documents asset_id as 'The asset's UUID' and size with its two values, dimensions, quality implications, and default. This adds far more meaning than the bare schema fields, which only list type and default.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Get a single asset's thumbnail as an image block for inline visual display.' It also explicitly distinguishes itself from the sibling get_asset_thumbnail, naming the exact alternative and its different return type, so an agent can immediately tell them apart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage context: 'Use this in clients that render images (Open WebUI, Claude Desktop).' It then states the exclusion condition and alternative: 'For HTML gallery generation with base64 data URIs (Cowork/skills), use get_asset_thumbnail instead — it returns JSON.' This is precisely the when-to-use vs when-not-to-use guidance an agent needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure, and it succeeds thoroughly. It declares read-only status, explains Immich 3.x vs 2.x behavior, documents request costs, describes defaults for omitted bounds, and clarifies that days missing from the series mean zero activity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average but every sentence earns its place: purpose, use cases, version caveats, parameter details, and return shape. It is front-loaded with the core purpose and progresses logically through args and returns, making the length justified by the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers everything an agent needs to select and invoke this tool correctly: use cases, version-specific behavior, performance implications, parameter semantics, defaults, and the return structure. Even though an output schema exists, the description's own return description adds useful interpretation, such as oldest-first ordering and how missing days are represented.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully explain the parameters, and it does. It documents ISO date format with an example, server defaults on each version, the meaning of omitted bounds, and defines heatmap_type values 'Taken' and 'Upload' including version restrictions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a concrete one-sentence definition: 'How many photos per day, over a date range — the data behind a calendar heatmap.' It clearly identifies the queried resource, the aggregation unit, and the date-range scope, and it distinguishes itself from asset-listing tools by framing its use as a health/gap check without listing assets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use this tool: to find gaps, busy periods, or check library health 'without listing assets.' It also gives strong behavioral guidance for version differences, warns about cost on Immich 2.x, and advises passing the narrowest range that answers the question. No ambiguity remains about when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for behavioral disclosure. It does so thoroughly: it is read-only, it downloads the video and cuts frames locally, it depends on PyAV 1.7.1+ or ffmpeg, every frame becomes one model image, and frames above 12 trigger a confirmation plan rather than images. It also exposes the hard cap and token estimates, giving the agent a strong model of cost and side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every sentence earns its place: it front-loads the core purpose, then explains the workflow, limits, alternative format, and each argument in a scannable Args block. Technical details like the PyAV dependency and token estimates are not padding; they affect invocation decisions. The structure mirrors how an agent actually needs to reason about the call.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 parameters, no output schema, and no annotations, this description is remarkably complete. It covers what the tool returns (JPEG image blocks in time order, or JSON), when confirmation is required, the hard cap, the sheet alternative, and the sibling tool for timestamped base64 JSON. An agent has everything needed to select this tool and invoke it correctly in the tricky >12-frames case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate entirely — and it does. Every parameter gets an explanation beyond its schema title: asset_id is the video asset's UUID, count is evenly spaced frames, size includes pixel dimensions and approximate token cost, start/end are seconds, interval means one frame every N seconds, confirm is required past 12 frames, and sheet packs frames into contact sheets with timestamps. This is exemplary compensation for a schema with no parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: "Get frames of a video as image blocks, to 'watch' a clip." It clearly distinguishes itself from the sibling by explicitly naming get_video_frames_json as the alternative for base64 JSON with timestamps. This is far more than a tautology and fully differentiates the tool's scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides an explicit workflow: try 6 frames first, narrow with start/end, or use interval down to 1 second. It also gives a decision rule for >12 frames (show the JSON plan, call again with confirm=true only if the user agrees), states the hard cap of 120, and names the alternative tool for a different return format. This is complete, actionable usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and meets it: it declares 'Read-only,' discloses the server-side dependency, and flags that the ocr parameter requires OCR enabled, pointing to get_capabilities as a check. It also reveals non-obvious behavior — results are 'ranked by visual similarity to the query.'
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence earns its place: purpose, usage condition, alternative, prerequisite, and safety are front-loaded before the structured Args block. The per-line parameter format is compact and consistent, with examples and constraints inline, and the Returns line closes with the essential output shape.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 12-parameter tool with no annotations and zero schema descriptions, the description covers what the tool does, when to use it, the alternative, prerequisites, every parameter's semantics, and the return shape. Since an output schema exists for detailed return structure, the brief Returns line is sufficient; nothing needed to select or invoke the tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the Args block must compensate — and it fully does. Every one of the 12 parameters gains meaning beyond the schema titles: the ALL constraint on person_ids, ISO date semantics for taken_after/taken_before, source hints like 'ids from list_people' and 'ids from list_tags,' and the 1-200 range for size.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb and resource — 'AI-powered visual search using CLIP embeddings' — and clarifies the input modality with concrete natural-language examples. It explicitly differentiates itself from sibling search_metadata ('For structured criteria (city, camera, date), use search_metadata instead'), so an agent can select it without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit when-to-use rule ('Use this when describing what a photo looks like in natural language') and names the exact alternative for structured criteria. It also states the prerequisite ('Requires Immich ML service with Smart Search enabled'), which tells the agent when the tool is available.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states 'Read-only,' 'WITHOUT fetching them,' and highlights the efficiency benefit of returning one integer instead of pages of assets. It also notes the OCR server prerequisite, which is useful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The main purpose and usage guidance are front-loaded in the first sentence, followed by a compact and necessary Args list. Every sentence earns its place, and the examples clarify usage without adding fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 11 parameters, no annotations, and no visible output schema details, the description covers everything needed: purpose, alternative tool, parameter semantics, return shape ({total}), and behavior. There are no significant gaps for an agent to invoke and interpret this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully document parameters. It provides a meaningful one-line explanation for all 11 parameters, including critical distinctions such as created_after (upload date when it reached Immich) vs taken_after (capture date when the photo was taken). This goes well beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Count how many assets match a filter WITHOUT fetching them.' It also explicitly differentiates from search_metadata, making it clear this tool returns a count rather than asset pages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says to use this instead of search_metadata whenever only the number matters, with concrete natural-language examples like 'how many photos from Spain?' This provides a clear when-to-use condition and names the alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states the side effect on all assets using the tag, the API limitation about renaming, the error behavior for `name`, and the return value. This goes well beyond the input schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but well-structured: purpose, side effect, limitation, workaround, and per-argument semantics are all covered in a compact format. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update operation, the description covers the action, side effects, unsupported parameters, workaround, and return format. The presence of an output schema further reduces the need to describe the response object in more detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully documents all three parameters: `tag_id` as the UUID, `name` as unsupported with a concrete consequence, and `color` with a hex format example and 'omit to keep current'. This compensates completely for the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence states a specific verb and resource ('Update a tag's color'), immediately distinguishing it from create_tag, delete_tag, and tag_assets. It also clarifies the tool's scope boundary by explicitly noting that renaming is not supported.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly routes rename workflows to create_tag, tag_assets, and delete_tag, and warns that passing `name` returns an error explaining the workaround. This gives clear when-to-use and when-not-to-use guidance relative to sibling tools.
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:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/drolosoft/immich-photo-manager'
If you have feedback or need assistance with the MCP directory API, please join our Discord server