immich-photo-manager

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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured: a clear action statement, usage context, side effect, then parameter details. Every sentence adds value with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple nature of the tool (add assets to album), the description covers the core functionality. The return summary is helpful even though an output schema exists. However, it omits prerequisites like album existence and potential error handling details.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0% coverage (no descriptions). The description's Args section provides clear semantics: 'Target album UUID' for album_id and 'List of asset UUIDs to add to the album' for asset_ids. This compensates for the schema's lack of descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action: 'Add existing assets to an album.' It provides a specific use case: 'Use this to curate albums from search results or other asset lists.' This distinguishes it from sibling tools like 'create_album' (create new) and 'remove_assets_from_album' (remove).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description says when to use the tool (curate albums from lists) and notes that assets can belong to multiple albums simultaneously, which guides decision-making. It does not explicitly state when not to use it or list alternatives, but the context is clear.

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

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.

Is 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.

Given 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.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (4 sentences) and includes a structured parameter breakdown. However, the parameter list could be integrated more seamlessly into the main description to be more front-loaded. No unnecessary words but slightly fragmented.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple nature of the tool (create album with optional fields and pre-population), the description covers the main use case and return values. It lacks details on error handling or constraints (e.g., name uniqueness) but is sufficient for a basic creation operation. Siblings provide contrast.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description fully compensates. It provides clear semantics for each parameter: name with an example format, description as optional text, asset_ids as optional list of UUIDs. It also explains the return value structure (id, name, asset count), which is not in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool creates a new album, optionally pre-populated with assets, distinguishing it from siblings like add_assets_to_album (adds to existing) or update_album. The verb 'create' and resource 'album' are specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description explicitly notes using the tool to organize photos into collections and mentions optional pre-population. However, it lacks explicit guidance on when not to use it (e.g., for adding assets to an existing album, use add_assets_to_album) or alternatives. Still, the context is clear enough for an AI agent to infer basic usage.

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

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is the description appropriately sized, front-loaded, and free of redundancy?

Concise with front-loaded purpose and parameter list. Could be slightly more structured (e.g., separate sections), but no waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given parameter count, required fields, and output schema, description provides complete context for agent to invoke tool correctly, including side effect and return fields.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but description explains each parameter's purpose (e.g., 'allow_download: Allow visitors to download original files') and return value, adding meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the verb 'Create' and resource 'public shared link for an album', differentiating it from siblings like 'update_shared_link' and 'get_shared_link'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Explicitly says 'Use this to publish a gallery for external viewing', providing a clear use case. Does not mention when not to use or contrast with alternatives, but context is sufficient.

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

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, with only a few sentences. It front-loads the purpose, then provides usage hints, parameter details, and return information. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers purpose, usage hint, parameter semantics, and return value. Given the low complexity (2 params, one required) and the existence of an output schema (return fields mentioned), it provides sufficient context for an agent to use the tool correctly, despite missing annotations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description adds meaning by providing examples for 'name' (e.g., 'Vacation') and 'color' (e.g., '#FF5733'), and states that name must be unique. This compensates for the lack of schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Create a new tag for categorizing assets.' This is a specific verb+resource, and it differentiates itself from sibling tools like delete_tag, update_tag, and list_tags by being the creation operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description advises 'Use list_tags first to avoid duplicates,' providing clear guidance on when to use this tool and a prerequisite action. It does not explicitly mention when not to use it, but the given hint is valuable.

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

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with an Args section and clear separation of modes. It could be slightly more concise but remains efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity and lack of annotations, the description covers essential aspects: behavior, parameters, side effects, and return value. The existing output schema is referenced.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Despite 0% schema coverage, the description adds meaning by explaining asset_ids as UUIDs and force default false, plus its effect on deletion permanence.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool deletes assets with two modes (soft-delete and permanent), and distinguishes it from restoring assets via restore_assets.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

It explains when to use (remove unwanted photos/videos) and provides context for the two modes, but doesn't explicitly state when not to use or alternative tools beyond restore_assets.

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

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.

Is 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.

Given 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.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It 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.

Does 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.

Does 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.

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.

Is the description appropriately sized, front-loaded, and free of redundancy?

Every sentence contributes value: purpose, side effects, parameter description, return value. No redundancy or filler. Efficiently structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple tool (one parameter) and presence of an output schema, the description covers all necessary aspects: action, side effects, parameter, and return. Nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has no descriptions (0% coverage), but the description adds 'The shared link's UUID to delete', explaining the parameter's purpose and format. This compensates well for the missing schema details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (delete/revoke a shared link) and the resource, with specific details like making the public URL immediately inaccessible. It distinguishes from sibling tools like create_shared_link or list_shared_links by its purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description implies when to use the tool (to revoke a link) without explicitly naming alternatives or stating when not to use it. The context of siblings provides differentiation.

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

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It 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.

Does 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.

Does 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.

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.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences plus a return line, all essential. Front-loaded with purpose and warning. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no parameters and an output schema exists (return value described), the description is fully sufficient. Covers purpose, usage, side effects, and result.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters in input schema, so description need not explain them. It adds return value description ('Returns: JSON with success confirmation'). Baseline for 0 params is 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'permanently delete' and the resource 'ALL assets currently in trash'. It distinguishes from siblings like 'delete_assets' and 'restore_trash'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Explicitly advises to use only after user confirmation and provides an alternative tool ('delete_assets') for deleting specific items.

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

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate 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.

Does 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.

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

The description explicitly says when to use this tool: '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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise yet comprehensive: a clear purpose sentence, usage guidelines, read-only note, and structured parameter list with return details. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite the tool having 53 siblings, the description sufficiently differentiates it and covers all needed context: input, output, behavior, and use case. The output schema exists, but the description still clarifies return structure, which is helpful.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0% description coverage, but the description fully explains all three parameters: album_id (UUID), size (two options with default and pixel dimensions), and limit (range 1-50, default 20). This adds complete semantic meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Get base64-encoded thumbnails for photos in an album.' It explicitly distinguishes from the sibling tool get_thumbnails_batch, ensuring proper differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Provides explicit guidance: 'Use this to generate visual HTML galleries from an existing album. For thumbnails from search results (no album), use get_thumbnails_batch instead.' This tells both when and when not to use the tool.

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

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.

Is the description appropriately sized, front-loaded, and free of redundancy?

Short, front-loaded purpose, uses clear sections for Args and Returns. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Describes return format despite no output schema. Lacks error handling or permission details but adequate for a simple read operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema provides no description for asset_id. The description adds 'The asset's UUID,' clarifying the parameter. This adds value beyond the raw schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it retrieves detected faces with person assignments. Differentiates from siblings like reassign_face (modifies) and get_person (single person).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Explicitly guides to use for seeing who is in a photo or finding face IDs for reassign_face. Lacks 'when not to use' but positive context is strong.

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

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured: purpose sentence, usage guidance, parameter details, return format. Every sentence adds value with no extraneous text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is complete for this simple tool, covering purpose, when to use, parameters, returns, and behavioral read-only trait. Even with an output schema existing, the description provides necessary context for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Despite 0% schema description coverage, the description adds full meaning: asset_id is a UUID, size has two options with pixel dimensions and a default. This compensates entirely for the schema's lack of descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves a base64-encoded thumbnail for a single asset, using a specific verb and resource. It distinguishes itself from siblings by naming alternative tools for batch or album thumbnails.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description explicitly says when to use ('visually inspect one photo') and when not to (multiple photos: use get_thumbnails_batch or get_album_thumbnails). It also marks the operation as read-only, providing clear context.

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

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.

Is 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.

Given 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.

Does 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.

Does 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.

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

The description explicitly says when to use this tool: 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is the description appropriately sized, front-loaded, and free of redundancy?

Five sentences, each serving a distinct purpose: main function, use case, security reason, read-only note, and return format. No waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no parameters and presence of output schema, the description fully explains what the tool returns and why, making it complete for an agent to use correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist, so the description does not need to add parameter info. It correctly focuses on the return values and usage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it returns the Immich base URL and a masked API key, with a specific use case of populating gallery template placeholders. It is distinct from all sibling tools, which serve different purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

It explicitly says when to use it (populate template placeholders) and explains the key masking for security. Could be more precise about when not to use, but the use case is well-defined.

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

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, 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.

Does 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.

Does 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.

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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured: a main sentence, use case, sibling reference, read-only and limit statements, followed by an Args/Returns section. It is concise but not sparse. The pseudo-docstring format adds clarity though some information (like read-only) is repeated. Overall, it uses space efficiently and is easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (3 optional parameters, no required, no enums, output schema exists), the description covers all essential aspects: purpose, usage context, parameters, return structure, and limits. The output schema exists, so detailed return description isn't needed, but the description still outlines the output. The sibling differentiation also adds contextual completeness. There are no gaps that would hinder an AI agent from using the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It lists all three parameters with explanations: file_created_after and file_created_before get ISO date examples, and is_favorite is described as 'If true, only return favorites.' This adds meaningful context beyond the schema, which only provides types and defaults. The descriptions are clear but could be slightly more detailed (e.g., date inclusivity), hence a 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Get GPS map markers for all geotagged assets.' It includes specific use cases (discover photo locations, build travel maps) and explicitly distinguishes from the sibling tool 'search_metadata' by noting that the sibling is for city/country searches. This provides a clear, specific verb+resource combination with sibling differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description gives explicit guidance: 'Use this to discover where photos were taken or to build travel maps. For searching by city/country name, use search_metadata instead.' This clearly states when to use the tool and when not to, with an alternative tool named, fulfilling the usage guidelines dimension fully.

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

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.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences with no fluff: purpose, usage context, args/returns. Front-loaded with key information, every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given a simple single-parameter tool with an output schema, the description adds necessary context about the person_id source and the fields included in the response, making it fully self-contained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Even though schema description coverage is 0%, the description adds crucial meaning: 'The person's UUID (from list_people or search_people)' explains the expected format and source, fully compensating for the schema gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get' and resource 'full details for a specific person including name, birth date, and photo count'. It distinguishes from siblings like list_people and search_people by focusing on a single person's detailed retrieval.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Explicitly states 'Use this after finding a person via list_people or search_people', providing clear context for when to use and sourcing for the required person_id parameter.

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

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.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two paragraphs plus parameter description, each sentence adds value. No fluff, well structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Simple operation with one parameter; description covers purpose, usage context, parameter, and output format completely.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but description adds 'The person's UUID' to the parameter, clarifying its purpose beyond type/title.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb+resource: 'Get a base64-encoded face crop thumbnail for a person.' Clear distinction from siblings like get_person or merge_people.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Explicit when-to-use: 'Use this to visually identify a person before merging or renaming.' Lacks explicit when-not-to or alternatives, but context is sufficient.

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

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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise: two sentences with no wasted words. It front-loads the purpose and includes important details (read-only, return format) efficiently.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter tool with an output schema, the description is complete. It explains the tool's purpose, behavior, and return structure, leaving no gaps for an AI agent to misunderstand.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has no parameters and schema coverage is 100%, so the baseline is 4. The description does not need to add any parameter information, and it appropriately avoids redundancy.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Get') and resource ('Immich server version'), and provides specific use cases (check compatibility, report version), distinguishing it well from sibling tools like 'ping' or others.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description explicitly mentions when to use the tool ('to check compatibility or report the running server version'). It does not provide when-not-to-use or alternatives, but the context is sufficiently clear for a simple read-only operation.

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

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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, consisting of three efficient sentences plus an 'Args' and 'Returns' section. It is front-loaded with the purpose and reads naturally without unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one parameter, read-only, with an output schema), the description is complete. It explains the return content and parameter source, and no additional information (error handling, pagination) is expected for such a straightforward operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description provides explicit meaning for the single parameter, 'The shared link's UUID (from list_shared_links),' which adds value beyond the schema (only indicates type string). With 0% schema description coverage, the description fully compensates.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves full details of a shared link, including specific properties like permissions, expiry, and linked assets. It distinguishes from siblings like create_shared_link, update_shared_link, and list_shared_links by emphasizing inspection of a specific link.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description says 'Use this to inspect a specific link's configuration,' providing clear context for when to use it. It also mentions the link_id comes from list_shared_links, guiding the workflow. However, it does not explicitly state when not to use it or list alternatives.

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

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three concise sentences, front-loaded with purpose, then usage, then return format. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity and presence of output schema, the description covers purpose, usage context, and return structure fully. No missing information for a read-only statistics tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters in schema, so baseline 4 applies. Description does not need to add parameter info.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb-resource (Get library statistics) and distinguishes from siblings by noting it's for a quick overview without listing individual assets.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Explicitly states when to use (quick overview) and implies when not (if you need individual assets, use list_assets). No explicit exclusions, but sufficient for context.

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

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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with three lines covering purpose, usage, and return value. Every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one parameter, output schema present), the description fully covers what the tool does, how to use the parameter, and what is returned.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description compensates by explaining that tag_id is 'The tag's UUID (from list_tags),' guiding the agent on how to obtain the ID.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Get details for a specific tag,' specifying the precise verb and resource. This distinguishes it from sibling tools like list_tags (list all tags) and create_tag.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description advises 'Use this to inspect a tag's properties. Read-only,' clearly indicating the tool's context. It does not explicitly exclude other tools, but the purpose is clear enough for appropriate selection.

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

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.

Is the description appropriately sized, front-loaded, and free of redundancy?

Concise, well-structured with Args and Returns sections. Every sentence adds value; no fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Complete for a batch thumbnail tool with output schema. Explains return structure and parameter constraints. No missing context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

All three parameters are explained with details not in schema: asset_ids as UUIDs, size with pixel dimensions, limit with range and behavior. Compensates for 0% schema description coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it retrieves base64-encoded thumbnails for arbitrary asset IDs without needing an album. Distinguishes from siblings like get_album_thumbnails and get_asset_thumbnail.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Explicitly describes when to use (visual display of search results or ad-hoc sets) and when not to (use album-based for albums, single for single photos). Names alternatives.

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

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description fully compensates 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, 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.

Does 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.

Does 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.

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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured with a clear purpose and Args/Returns sections. However, the Args section slightly duplicates information already in the description, but overall efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the low complexity (1 optional param) and the presence of an output schema, the description covers all essential aspects: purpose, usage guidance, parameter behavior, and return format. No gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds significant meaning for the single parameter 'shared': true for shared, false for non-shared, omit for all. This is much more informative than the schema's type (boolean or null) and covers all possible values.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists all albums with summary info. It distinguishes from siblings by specifying it's for discovery and finding album IDs, which contrasts with other tools like get_album for details or create_album for adding.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Explicitly states when to use: to discover existing albums before creating new ones or to find an album ID. Also declares it's read-only, implicitly guiding away from mutation tasks.

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

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.

Is 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.

Given 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.

Does 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.

Does 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.