Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true, so the mutation profile is largely covered. The description adds the real-world effect (the caller joins the group), but omits who is permitted to accept, whether the request record is consumed afterward, and what happens if it is expired or already accepted.

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?

Very short and front-loaded: the effect sentence comes before the REST/route metadata. The repeated title as the first line is mildly redundant with the tool name/title, but nothing is padded.

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 mutation with annotations covering safety and no output schema, the essentials are present, but the description leaves out the accept-side prerequisites (caller must be the invited party), post-accept side effects, and failure modes, which an agent would need to call this 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 coverage is 100% for the single required id parameter (uuid format), so the schema carries full documentation. The description adds no semantics about the id beyond what the schema already states, making the baseline 3 appropriate.

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 (accept) and resource (cluster group request), and the second line clarifies the effect: joining the cluster group the request targeted. This distinguishes it from immich_delete_cluster_group_request and immich_create_cluster_group_request without needing the schema, though it never names those siblings explicitly.

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 the prerequisite that a request must already exist, but gives no explicit when-to-use guidance, no exclusions, and no pointer to the alternatives (delete the request instead, or list requests first with immich_get_cluster_group_requests).

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?

Annotations already declare the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the description is not the primary carrier here. It adds the underlying HTTP operation (PUT /albums/{id}/assets), which is mild extra context, but says nothing about auth requirements, partial-failure behavior, or what happens when an asset is already in the album despite the idempotent hint.

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 title is repeated verbatim as the first line and then the same idea is restated as "Add multiple assets to a specific album by its ID," so roughly half the text is redundant. The endpoint/tag metadata is useful but the opening duplication wastes the front-loaded position.

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 mutation with no output schema and full annotation coverage, the description is adequate but thin. It omits the idempotency semantics the annotations imply and any note on whether the whole batch fails if one asset ID is invalid, which matters for a batch-add 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?

Schema coverage is 100% but the schema descriptions are bare ("format: uuid" for both params). The description adds genuine disambiguation by identifying `id` as the album and `ids` as the assets being added, which the schema alone does not make clear. That is meaningful value above the baseline.

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 (add), resource (assets), and target container (a specific album by ID), so the core operation is unambiguous. It does not, however, differentiate itself from the dangerously similar sibling immich_add_assets_to_albums (plural) or from immich_add_users_to_album, leaving the agent to guess which of the near-identical names applies.

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 when-to-use guidance, no prerequisites, and no mention of alternatives. With siblings like immich_add_assets_to_albums, immich_remove_asset_from_album, and immich_add_memory_assets in the list, the absence of routing guidance is a real gap.

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?

Annotations already declare idempotentHint=true, destructiveHint=false, and readOnlyHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral fact beyond annotations: the operation applies a Cartesian product (each asset into each album). It says nothing about permission requirements, handling of invalid/unknown IDs, or partial-failure behavior.

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 and front-loaded: the verb+resource leads, the operative sentence follows immediately, and only the trailing 'Immich operation / tag' line is operational metadata. The first line redundantly restates the tool name/title, which is minor waste but not harmful.

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 bulk mutation with no output schema, the description covers inputs and the cross-product effect but omits return values, error behavior for invalid IDs, and any account/permission context. Adequate for a straightforward put, but thin for a bulk write against an external service (openWorldHint=true).

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 100%, so baseline would be 3; the description earns an extra point by explaining how the two array parameters interact ('add each asset to each album'), which the schema's plain array-of-UUID definitions cannot convey. It still adds no format details (both are UUID arrays) since the schema handles that.

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 and resource ('Add assets to albums') and adds the key semantics that the operation is a cross-product ('add each asset to each album'). However, it never acknowledges the nearly identical sibling immich_add_assets_to_album, so the agent gets no help distinguishing the bulk multi-album variant from the single-album variant.

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 states what inputs to send but gives no when-to-use guidance, no when-not conditions, and no mention of alternatives such as immich_add_assets_to_album or immich_add_users_to_album. With a near-duplicate sibling name in the tool list, the absence of routing guidance is a real gap.

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?

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, which conveys the safety/mutation profile. The description adds nothing beyond the raw PUT endpoint, so it does not enrich behavior (e.g. that re-adding is idempotent, or what happens on duplicate ids) beyond what structured fields 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?

Short and front-loaded, leading with the action. There is mild redundancy between the first line and title and the second line, but no filler and the endpoint reference is compact.

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 two-parameter mutation with full schema coverage and annotations covering the safety profile, the definition gives enough to call it correctly. No output schema is needed. The only gap is the absence of when-to-use routing against the sibling remove/update memory 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?

Schema description coverage is 100%, so the id and ids parameters are already documented with their uuid formats. The description only restates "list of asset IDs" and "specific memory," adding no syntax or constraint detail beyond the schema, which makes the baseline 3 appropriate.

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+resource ("Add assets to a memory") and clarifies it takes a list of asset IDs into one memory. It is distinguishable from siblings like immich_remove_memory_assets and immich_update_memory, though it never names those alternatives explicitly.

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?

No guidance on when to use this versus immich_remove_memory_assets, immich_update_memory, or other asset-attachment tools. The agent must infer applicability purely from the verb. No prerequisites or exclusions are stated.

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

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety/mutation profile is covered. The description adds the useful constraint that only 'individual'-type links are supported, but says nothing about auth requirements or what happens to assets already 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?

Front-loaded and short, but the title is repeated verbatim and then restated as 'Add assets to a specific shared link by its ID', which is redundant. The operation/endpoint metadata line is useful but the definition spends roughly half its words on restatement.

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 mutation tool with annotations covering the safety profile and no output schema, the description is adequate but thin: it omits auth/scope requirements and the effect of re-adding an already-linked asset. The type restriction is the only real addition.

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 100% and both parameters (id, assetIds) are documented in the schema. The description only echoes 'by its ID' and adds no format, ordering, or size-limit detail beyond what the schema provides, so baseline 3 applies.

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 ('Add assets to a shared link') and narrows scope with 'by its ID'. However, it never distinguishes itself from close siblings like immich_remove_shared_link_assets or immich_add_assets_to_album, so the agent gets no 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 line 'only relevant for shared link of type individual' gives a genuine applicability condition, which is more than nothing. But it does not name alternatives or state what to do for other link types, so the guidance is implied rather than explicit.

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?

Annotations already declare idempotentHint=true, destructiveHint=false, readOnlyHint=false and openWorldHint=true, so the safety profile is covered. The description adds only that multiple users are affected and that each carries a role, without noting auth requirements or behavior on duplicate/re-shared users, so it adds modest value over the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The body opens by repeating the title verbatim ('Share album with users'), which wastes the most prominent line, though the remaining sentences and the operation/tag footer are compact and front-loaded enough to be usable.

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 mutation with no output schema and full annotation coverage, the description supplies the action, the scope (multiple users), the role concept, and the underlying endpoint, leaving little that an agent needs 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 100%, so the required id and albumUsers (with the role enum) are already documented in the schema. The description restates that a role is assignable per user but contributes no format, syntax, or constraint detail beyond the schema, making the baseline 3 correct.

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 ('Share an album with multiple users') and adds the REST operation (PUT /albums/{id}/users). It clearly distinguishes itself from the add/remove-asset siblings, though it does not explicitly name the closest counterpart, immich_update_album_user, which changes roles rather than adding users.

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?

Usage is implied by the verb 'share' and the note that users can be given roles, but there is no explicit when-to-use guidance, no prerequisites, and no direction to sibling tools such as immich_update_album_user or immich_remove_user_from_album.

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?

Annotations already declare idempotentHint=true, destructiveHint=false, and readOnlyHint=false, so the mutation/safety profile is largely covered. The description adds the underlying operation (PUT /tags/assets) but does not disclose what happens to existing tags (merge vs replace) or any permission/rate-limit behavior.

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?

Front-loaded and very short: purpose sentence first, endpoint metadata last. The repeated title line plus endpoint reference is slightly redundant but nothing is wasted.

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 two-parameter bulk mutation with no output schema and annotations covering the safety profile, the description is adequate. The only meaningful gap is not clarifying add-vs-replace semantics, which the idempotent hint partially implies.

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 100% with both required parameters documented, so the baseline is 3. The description adds no syntax, cardinality, or format detail beyond what the schema already carries (UUID arrays).

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+resource ('Add multiple tags to multiple assets') and explicitly scopes it to bulk operations ('in a single request'), which separates it from the single-asset sibling immich_tag_assets. It stops short of naming that sibling outright, so differentiation is implied rather than 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?

Beyond the phrase 'in a single request' there is no guidance about when to prefer this over immich_tag_assets or how it relates to immich_untag_assets. No preconditions, no exclusions, and no alternative routing are provided.

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?

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the agent knows this is a non-idempotent mutation. The description adds the current-user scope and the underlying endpoint mapping, but says nothing about side effects—notably what invalidateSessions does to active sessions. Adds modest context beyond structured data.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Front-loaded title and a single well-scoped sentence, plus an operation/tag line useful for routing. No wasted prose, though the endpoint metadata is somewhat redundant with the name.

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 security-sensitive mutation with no output schema, the description omits key operational context: that the current password is required, what invalidateSessions does to other sessions, and whether the change is reversible. Annotations cover the safety profile but not these behavior 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?

Schema description coverage is 100%, so baseline is 3, but the descriptions are tautological ("password (request body)", "invalidateSessions (request body)") and the prose adds no meaning—especially for invalidateSessions, whose behavior is left entirely unexplained by both schema and description.

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 ("Change the password") and narrows scope to the "current user," which distinguishes it from admin tools like immich_update_user_admin that act on other users. It's clear without needing the schema, though it doesn't explicitly name a sibling it replaces.

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?

No guidance on when to use this versus immich_change_pin_code, immich_update_my_user, or the session-management tools. No prerequisites stated, such as needing the existing password or the consequences of the 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?

Annotations already disclose readOnly=false, idempotent=true, destructive=false, so the safety profile is covered. The description adds essentially nothing beyond that: it does not say the operation likely requires the existing pin or account password for verification, nor anything about failure behavior, which matters for a credential-mutating endpoint.

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 content is short and front-loaded, which is good, but the title is restated verbatim in the first line and the 'Immich operation: PUT /auth/pin-code · tag: Authentication' boilerplate is mapping metadata rather than guidance, so little of the text 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 3-parameter credential mutation with no output schema and only weak annotations, the description should clarify the old-credential requirement and the relationship to the setup/reset siblings. As written it is thin, though the annotations and 100% schema coverage keep it from being fully inadequate.

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 100%, so the baseline is 3. The description adds no parameter meaning at all, and the schema's own text ('pinCode (request body)', 'password (request body)') is purely structural, so an agent gets no help on when pinCode vs password must be supplied.

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+resource ('Change the pin code for the current user') and scopes it to the current user, so the action is unambiguous. However, it never distinguishes itself from the very similar siblings immich_setup_pin_code and immich_reset_pin_code, leaving the agent to infer which of the three to pick.

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?

There is no when/when-not guidance and no mention of alternatives. In a sibling set containing setup_pin_code and reset_pin_code, failing to explain that this tool changes an already-existing pin (vs. creating or clearing one) is a real routing gap.

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?

Annotations already declare openWorldHint, idempotentHint and destructiveHint, so the safety profile is largely covered. The description adds that matching is checksum-based and batch-oriented, but says nothing about auth requirements, maximum batch size, or whether the operation is side-effect free despite readOnlyHint=false on a check-style call.

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 and front-loaded: purpose sentence first, then the API operation/tag reference. No filler. The 'Immich operation' line is boilerplate but useful for mapping to the underlying endpoint.

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?

There is no output schema, so the description should explain the response shape (which assets matched and how results map back via id). The id field description in the schema partially covers matching, but the overall return structure is left unstated, leaving a real gap for a check 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?

Schema description coverage is 100%, so the assets array, id echo field, and Base64/hex SHA1 checksum are fully documented in the schema. The description only restates the checksum basis, adding no syntax or format detail beyond structured data; baseline 3 applies.

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+resource+mechanism: determine which assets are already on the server using SHA1 checksums. This is clearly distinguishable from sibling upload/list tools. It stops short of naming an alternative or contrasting with the actual upload tool, but the purpose itself is 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 use case (pre-upload deduplication check) is strongly implied by 'which assets have already been uploaded,' but there is no explicit when-to-use statement, no mention of pairing with immich_upload_asset, and no prerequisites or exclusions. Usage is inferable but not stated.

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?

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the safety profile is covered. The description adds that the re-run is 'forceful' and applies to 'all faces of users in this group', which gives scope and impact context, but it omits side effects, permissions, or whether existing people data is overwritten. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is short and front-loaded, but the first line repeats the title verbatim, which is redundant. The remaining two lines (facial-recognition scope and API operation) are 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?

With annotations covering the safety profile and the schema fully documenting the single parameter, the description is adequate for a simple mutation. However, it lacks any indication of what the operation returns or whether it is asynchronous, which an agent might need given no output schema exists.

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 100% and the single id parameter is documented as uuid format. The description adds no parameter-level detail, so baseline 3 applies when schema does the heavy lifting.

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 (regenerate) and resource (people of users in cluster group), and clarifies the operation as re-running facial recognition for all faces of those users. It does not explicitly differentiate from sibling facial-recognition tools like immich_reassign_faces or immich_get_faces, so a 4 rather than 5.

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?

No explicit when-to-use or when-not-to-use guidance. The description implies the operation but does not name alternatives or conditions that select this tool over siblings such as immich_get_cluster_group_users or immich_reassign_faces.

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?

Annotations already declare readOnly=false, destructive=false, idempotent=true, and openWorld=true, covering the safety profile. The description adds which data categories get copied ('albums, tags, etc.'), but omits key semantics for a copy operation: whether target's existing data is overwritten or merged, and what the response looks like.

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 and front-loaded, with the purpose in the first substantive sentence. The trailing 'Immich operation: PUT /assets/copy · tag: Assets' is metadata padding but compact.

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 mutation tool with annotations covering safety and idempotency and no output schema, the definition is minimally adequate. It leaves unclear what copy actually does to existing target data and whether the boolean flags are opt-in or opt-out, which matters for 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 nominally 100%, so the baseline is 3. However the schema descriptions are pure boilerplate ('albums (request body)') and the description only loosely gestures at 'albums, tags, etc.' without clarifying the boolean flags (stack, sidecar, favorite, sharedLinks) or their defaults, so no value is added.

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 (copy), resource (asset information), and direction (from one asset to another), with examples of what is copied (albums, tags). It is clearly distinguishable from generic update/edit siblings, though it doesn't explicitly name an alternative tool.

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?

There is no guidance on when to use this versus related tools such as immich_edit_asset, immich_update_asset, or immich_add_assets_to_album. No prerequisites, permissions, or exclusions are mentioned.

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?

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=true, so the write/network profile is covered. The description adds only the target domain (album/asset in album) and no extra behavior such as auth requirements or repeat-call effects for a non-idempotent write.

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 and front-loaded, with the meaningful payload description in the second line. Minor waste: the title 'Create an activity' is repeated verbatim as the opening line, and the operation/tag line is boilerplate.

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 4-parameter write tool with annotations and no output schema, the description is minimally sufficient about what it creates, but omits permission/access context and any indication of the returned activity record, leaving some inference to the 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?

Schema description coverage is 100%, so the schema documents all four parameters, and the enum on type is machine-readable. The prose adds conceptual mapping (like/comment on album or asset) but no format or syntax detail beyond what the schema provides, so baseline 3 is appropriate.

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 (create) and resource (activity) and clarifies the two concrete payloads: a like or a comment, targeting an album or an asset within an album. This distinguishes it from the read siblings immich_get_activities/immich_get_activity_statistics, though it does not explicitly name immich_delete_activity as its inverse.

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?

Usage is implied by the description — you use it to post a reaction or comment — but there is no explicit when-to-use, no prerequisites (e.g. album access), and no routing to alternatives such as immich_delete_activity for removal.

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?

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds only the REST endpoint (POST /albums), which is structured metadata rather than new behavioral context; it says nothing about auth needs, duplicate-name behavior, or side effects. Given the annotation coverage, a 3 is appropriate.

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?

Front-loaded with the core action and short overall. The leading line repeats the title verbatim and the trailing 'Immich operation / tag' line is boilerplate, which is minor waste but doesn't obscure the main point.

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 four parameters are fully documented in the schema, so no param explanation is needed, and there is no output schema to describe. However, for a create mutation with no output schema the description omits what is returned (the created album identifier) and any failure/duplicate nuances, leaving a modest gap.

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 100%, so the baseline is 3. The description adds interpretive context by noting the album can carry initial users and assets, loosely mapping to albumUsers and assetIds, but it gives no format, constraint, or role details 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?

States a specific verb and resource ('Create a new album') and adds that the album can be created with initial users and assets, which clarifies the tool's scope. It does not explicitly distinguish itself from siblings such as immich_update_album_info or immich_add_assets_to_album, but the create-vs-modify distinction is fairly evident from the name and verb.

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?

No explicit when-to-use or when-not-to-use guidance. The sentence 'The album can also be created with initial users and assets' hints at an option but does not tell the agent when to prefer this over immich_create_album-plus-add calls or other album siblings. Usage is only implied.

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?

Annotations already declare readOnly=false, idempotent=false, destructive=false, and openWorld=true, so the agent knows this is a non-idempotent write. The description usefully adds that the resulting key is limited to the supplied permissions, but omits key behavioral facts such as whether the secret is returned only once, permission escalation limits, or what happens on failure.

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 'Create an API key' heading and 'Creates a new API key' sentence duplicate each other and the tool name, wasting the front-loaded position. The trailing 'Immich operation: POST /api-keys · tag: API keys' line is metadata rather than agent-facing guidance.

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?

With no output schema, the description carries the burden of explaining what the creation returns, yet it never says the API key secret is produced and must be captured. It covers the permission-scoping behavior but leaves the return value and auth requirements undocumented.

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 100%, so the schema already names and constrains both parameters (including the full permission enum), making the baseline 3 appropriate. The description repeats the permissions constraint without adding format, defaults, or guidance on the 'name' 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 title 'Create an API key' and the body's first line 'Creates a new API key' are near-tautological given the tool name immich_create_api_key. It does add that the key is scoped to specified permissions, but it never distinguishes itself from siblings like immich_rotate_api_key, immich_update_api_key, or immich_get_api_key.

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?

There is no when-to-use guidance, no mention of prerequisites (e.g. that the caller must already be authenticated or hold apiKey.create), and no routing against the rotate/update/get siblings. The agent is left to infer everything about when this is the right 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?

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the useful behavioral fact that this is a request/notification sent to another user rather than a direct membership change, but says nothing about approval flow, permissions, or failure modes.

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 lines, purpose front-loaded, with the operation/tag metadata trailing as boilerplate. Nothing is padded, though the metadata line adds little for an agent.

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?

A simple two-parameter mutation with full schema coverage and annotations covering the safety profile; the description supplies the missing 'what this actually does' semantics. Remaining gaps (permission requirements, response shape) are minor given no output schema exists.

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 100%, so the baseline is 3. The schema's own descriptions are thin ('format: uuid', 'userId (request body)'), and the prose only weakly implies that 'id' is the cluster group and 'userId' is the invited user, so no real clarification is added beyond structured data.

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 line names the verb+resource and the follow-up sentence 'Ask another user to join the cluster group of the current user' makes the actual semantics concrete, distinguishing it from accept/delete siblings conceptually. However, it never names those siblings explicitly, so differentiation relies on inference.

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 second sentence implies the usage context (inviting another user), which is more than nothing, but there is no explicit when-to-use, no prerequisite (e.g., must the requester own the group?), and no pointer to immich_accept_cluster_group_request or immich_delete_cluster_group_request as the follow-up 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?

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=true, so the write/safety profile is covered. The description usefully clarifies that the bounding box content is treated as a face, but it says nothing about auth requirements, whether an existing personId must reference a real person, or whether duplicate faces are rejected.

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 and front-loaded: verb+resource first, qualifying detail second, endpoint metadata last. The leading 'Create a face' line duplicates the title and the second sentence opens with the same phrase, which is minor redundancy rather than 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?

For a mutation tool with 8 required parameters and no output schema, the description covers intent and the bounding-box concept but omits key context an agent needs: required permissions, constraints on personId/assetId, and what the call returns. Annotations carry part of the load, so it is adequate but clearly incomplete.

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 100%, so the baseline is 3, but the schema 'descriptions' are placeholders like 'x (request body)' that convey almost nothing. The description adds only a partial hint that x/y/width/height form a bounding box; it does not explain personId, assetId, or how imageWidth/imageHeight relate to the box coordinates.

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 + resource ('Create a face') and adds a meaningful qualifier: the face must not already have been discovered by facial recognition, which separates it from auto-detected faces. It does not name or contrast with any sibling tool (e.g., immich_create_person, immich_get_faces, immich_reassign_faces), so it falls short of the 5 bar.

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?

Usage is only implied by the clause 'that has not been discovered by facial recognition' – an agent can infer this is for manually registering undetected faces, but there is no explicit when-to-use/when-not guidance, no mention of the alternative immich_create_person, and no prerequisites such as the asset or person needing to exist.

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?

Annotations already declare non-readOnly, openWorld, non-idempotent behavior, so the safety profile is covered. The description adds the kind of jobs available (cleanup tasks, database backup) but says nothing about async execution, auth requirements, or side effects, so it only modestly extends the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Front-loaded with the operation and followed by one useful clarifying sentence; the trailing 'Immich operation: POST /jobs · tag: Jobs' metadata is low-value but brief. Overall tight and well-ordered.

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 tool with no output schema, the description is minimally sufficient, covering what the tool does and roughly when. It omits whether the job runs asynchronously or returns a job handle, which an agent would benefit from knowing.

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 100% and the single 'name' parameter is backed by a self-describing enum, so the baseline is 3. The description does not explain any of the job names, adds no meaning beyond the schema's enum 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 gives a specific verb+resource ('Create a manual job', 'Run a specific job') and clarifies the operation is for manually triggering a subset of jobs. It doesn't differentiate from close siblings like immich_run_asset_jobs or immich_run_queue_command_legacy, so it stops short of a 5.

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 signals context ('Most jobs are queued automatically... allows for manual creation') which implies when to use it, but names no alternative tool and gives no explicit when-not conditions. Usage is implied rather than spelled out against 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?

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=true, so the safety/mutation profile is covered structurally. The description adds only the fact that the library is 'external' (implying filesystem import paths) and the underlying POST endpoint; it says nothing about permissions, what the created library contains, or 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?

It is short and front-loaded with the action, but the title is restated verbatim as the first line before the actual sentence, and the 'Immich operation: POST /libraries · tag: Libraries' trailer is generator metadata rather than agent-useful 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 4-parameter write tool with no output schema, the annotations plus the schema cover most needs. However, the description never notes that ownerId is required, that the library is external/scan-backed, or how it relates to immich_scan_library, leaving gaps an agent would want filled.

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 100%, so all four parameters (name, ownerId, importPaths, exclusionPatterns) are already documented in the schema. The description adds no format, default, or constraint detail beyond what the schema provides, so the baseline 3 applies.

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 ('Create a new external library'), and the 'external' qualifier distinguishes it from generic library concepts. It is clear enough to separate from the many other create_* siblings, though it never names update_library/delete_library to draw the boundary explicitly.

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?

There is no when-to-use guidance, no prerequisites (e.g., that a user/owner must exist), and no mention of the sibling tools that operate on the same resource (immich_update_library, immich_delete_library, immich_scan_library). The agent must infer usage purely from the name.

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?

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true, so the safety/behavioral profile is covered by structured data. The description adds nothing beyond the endpoint line: no auth requirements, no side effects, no note on what the memory becomes visible as or whether it can be undone.

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 and front-loaded, with the create verb leading and the endpoint/tag line trailing. The opening sentence merely restates the title, a small redundancy, but there is no padding beyond that.

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 an 8-parameter mutation with a nested object (data.year), a const enum-ish type, and several optional timestamps, plus no output schema, the description is far too thin. It never explains the on_this_day memory concept, the meaning of memoryAt/showAt/hideAt/seenAt, or defaults, leaving the agent guessing on the core 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 nominally 100%, but the schema descriptions are boilerplate ('(request body)'), so the schema carries little real meaning. Worse, the description names 'name' and 'description' fields that do not exist in the schema and omits the actual required fields (data.year, memoryAt, type const 'on_this_day'), which is actively misleading rather than merely unhelpful.

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 ('Create a new memory') and the POST /memories operation line anchors it precisely, so the agent knows this is the creation counterpart to update/delete/get memory. However, it does not distinguish itself from siblings like immich_add_memory_assets or immich_update_memory, and the fields it names (name, description) do not match the actual schema, muddying the picture.

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?

There is no when-to-use guidance, no prerequisites, and no routing to alternatives. The agent must infer on its own that adding assets to an existing memory belongs to immich_add_memory_assets rather than this 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?

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=true, so the mutation profile is covered. The description's only added behavioral context is the admin-tagged endpoint, which implies elevated authorization needs; it says nothing about what side effects a notification has or whether recipients can see it immediately.

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?

It is short and front-loads the operation and scope. There is minor redundancy between the title line and the first description sentence, plus a metadata line, but nothing wasteful.

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 7-parameter tool with a nested free-form "data" object, two enums, and no output schema, the description is minimal. It never explains the notification types/levels or what the data payload should carry, leaving the agent to guess at the substantive part of the call.

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 100%, so the baseline is 3, and the schema entries are largely placeholders ("title (request body)") so there is little to build on. The description only hints at the userId requirement via "for a specific user" and never explains the meaning of the data object, type, or level enums.

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 ("Create a new notification") and adds scope ("for a specific user"), plus the underlying endpoint POST /admin/notifications. It does not differentiate from adjacent siblings like immich_update_notification or immich_delete_notification, but the core purpose is 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?

There is no statement of when to use this tool versus alternatives such as immich_update_notification, immich_delete_notification, or immich_get_notifications, and no prerequisites. Usage is only implied by the name and admin tag.

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?

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds no behavioral context beyond that: it does not say the sharing is bidirectional/all-assets, whether duplicate partners error (non-idempotent), or what permissions are required.

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 and front-loaded, but the first line merely repeats the title verbatim before the slightly redundant sentence, and the trailing "Immich operation: POST /partners · tag: Partners" is machine metadata. Little waste, but little earned value either.

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 creation tool with annotations covering safety and no output schema, the essentials are present, and the POST endpoint reference is a small plus. It still omits the sharing semantics and the sharedWithId format, which an agent would need to call it authoritatively.

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 reported at 100%, so the single sharedWithId parameter is documented in the schema, though only as "sharedWithId (request body)". The description adds nothing about the parameter's format (user id vs email) or referent, so baseline 3 applies.

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 a partner") and adds domain meaning with "to share assets with," so an agent understands what a partner represents. It does not differentiate from the sibling immich_create_partner_deprecated or explain how it relates to immich_get_partners/immich_remove_partner.

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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as the deprecated create variant or the remove/update counterparts in the sibling list. The agent must infer usage entirely from the name.

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?

Annotations already declare the mutation/safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=true). The description adds the deprecation warning, which is real behavioral value, but omits auth requirements and what 'sharing' actually grants.

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 and front-loaded, with the deprecation warning placed at the end where it is visible. Minor redundancy in restating the title verbatim and including a boilerplate 'Immich operation' line.

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 create tool with annotations covering safety, the description is roughly adequate. Its key gap is that a deprecated tool should name the replacement operation, and it does not.

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?

Only one parameter, and schema description coverage is 100% ('format: uuid'), so the schema carries the load. The phrase 'share assets with' hints that the id refers to a user to partner with, but this is not stated explicitly.

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 a new partner') plus intent ('to share assets with'), which is clear. It does not distinguish itself from the near-identical sibling immich_create_partner beyond the name's '_deprecated' suffix, so it stops short of full 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 'DEPRECATED — prefer the replacement operation if one exists' line nudges the agent away from this tool, which is useful context. However it never names the actual replacement (immich_create_partner) and 'if one exists' is vague, leaving the agent to infer the alternative from the sibling list.

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?

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered structurally. The description adds only the domain detail that faces can be attached; it says nothing about duplicate-name handling, permissions required, or what the call returns, which is a real gap for a non-idempotent create.

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?

Front-loaded with the verb+resource, followed by one useful sentence and a terse API reference. Slight redundancy between the title line and the 'Create a new person' sentence, but overall tight with no wasted prose.

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 five-parameter, zero-required, non-idempotent mutation with no output schema, the description leaves open what is created and returned and how duplicates are treated. Annotations cover the safety side and the schema covers the inputs, so the definition is minimally viable but not fully self-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 100%, so the schema already documents all five body fields, and the baseline for high coverage is 3. The description contributes no additional parameter meaning (formats, defaults, constraints like birthDate format or color syntax).

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 (Create) and resource (person) and adds the domain fact that a person can have multiple faces assigned, which helps distinguish it from immich_create_face and immich_get_person. It does not explicitly name which sibling to prefer over it, but the create semantics are 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?

No when-to-use guidance, prerequisites, or alternatives are given. The clause about faces implies a modeling role but does not tell the agent when to create a person versus using immich_merge_people, immich_search_person, or immich_update_person. The agent must infer usage entirely.

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?

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, and openWorldHint=true, so the mutation/safety profile is covered. The description adds that the image is set for the current user, but does not state whether a previous image is replaced or removed, which is the key behavioral question for this endpoint.

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?

Front-loaded one-line summary followed by a clarifying sentence and an operational pointer (POST /users/profile-image). Nothing is padded; the only minor redundancy is the title repeating the first line.

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 mutation with no output schema, the definition is close to adequate, but it omits practical details an agent needs: the upload encoding of the required 'file' parameter and the effect on any existing profile image.

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 100%, so baseline is 3, but the schema's only description is the tautological 'file (request body)'. The description adds 'Upload' implying a file upload, yet gives no format guidance (binary/multipart, accepted image types, size limits) for what is a non-trivial upload 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?

States a specific verb (create/set) and resource (profile image) with clear scope ('for the current user'), which distinguishes it from the sibling get_profile_image and delete_profile_image. It does not explicitly name siblings, but the action is 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 phrase 'for the current user' implies the usage context, and 'set a new profile image' implies replacing the existing one, but there is no explicit when-to-use vs alternatives guidance (e.g., contrast with upload_asset or update_my_user).

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?

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, and openWorldHint=true, so the safety/mutation profile is covered. The description usefully adds that the created session is a child of the current session and is for casting. It still omits session lifetime, auth/permission requirements, and what the response contains, so it adds moderate value beyond 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 opening line redundantly repeats the title ('Create a session') before restating it in the next sentence, which is wasted space. The core useful content (child session, casting) is front-loaded, and the operation/tag footer is compact, but the duplication keeps it at adequate rather than tight.

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 3-parameter, optional-param creation tool with annotations covering the safety profile and no output schema, the description covers the essential purpose and casting use case. Gaps remain around session lifetime, required permissions, and return behavior, making it minimally adequate rather than 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?

Schema description coverage is 100%, so the parameters (deviceOS, duration, deviceType) are considered documented, though their schema descriptions are trivial ('... (request body)'). The description adds no parameter-level meaning (e.g., duration units, valid deviceType values). Baseline 3 applies when the schema carries the load.

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 gives a specific verb+resource ('Create a session') plus meaningful scope detail: 'as a child to the current session' and 'used for casting.' This distinguishes it from the many other session tools. It stops short of explicitly naming siblings like update_session or end_session, keeping it from a 5.

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 casting context ('This endpoint is used for casting') implies when the agent should reach for this tool versus other session operations. However, there is no explicit when-not guidance and no named alternative (e.g., get_sessions, update_session, end_session). Usage is implied rather than stated.

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?

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true, so the mutation profile is covered externally. The description adds nothing beyond that — no auth/permission requirements, no note on what happens to an existing link with the same slug, and no mention that the created link's visibility is governed by password/expiresAt/showMetadata.

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?

It is short and front-loaded, but three of its four lines are redundant: the name, the first line, and the second line all say 'create a shared link.' The only novel content is the Immich operation/tag footer, so efficiency is undermined by restatement.

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 10-parameter creation tool with no output schema, the description leaves critical gaps: that 'type' is required, that ALBUM needs albumId while INDIVIDUAL needs assetIds, and what the created link returns. Annotations cover safety but not the structural constraints an agent needs to call this 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 100%, so the baseline of 3 applies even though the description itself says nothing about parameters. The description adds no meaning for the ten fields, and notably does not explain the ALBUM vs INDIVIDUAL enum or how it relates to albumId and assetIds.

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 does give a clear verb+resource pair ('Create a new shared link') and names the underlying endpoint POST /shared-links, so the agent knows this is a creation tool. However, it is essentially a restatement of the tool name and title with no differentiation from siblings like immich_update_shared_link, immich_get_all_shared_links, or immich_add_shared_link_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?

There is no when-to-use guidance, no mention of prerequisites, and no routing to alternatives. The description repeats 'Create a shared link / Create a new shared link' rather than explaining when this tool is the right choice over the shared-link 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?

Beyond the annotations (destructiveHint=false, openWorldHint=true, idempotentHint=false), the description discloses a non-obvious side effect: if an asset is a primary asset of an existing stack, that existing stack is absorbed into the new one. This is valuable behavioral context an agent could not infer from the schema. There is a mild tension with destructiveHint=false, since an existing stack effectively disappears, but the description does surface the effect rather than hide it.

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 merge caveat is front-loaded in the second sentence and the text is short. However the leading "Create a stack" line merely repeats the title, and the trailing "Immich operation: POST /stacks · tag: Stacks" duplicates routing metadata that already lives in structured fields.

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 mutation with annotations present and no output schema, the merge semantics are the most important thing to document and they are covered. The completeness is undercut by the fabricated "name" field and by no mention of permission/auth requirements or what the created stack response looks like.

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 100% schema coverage the baseline is 3, but the description actively introduces a mismatch: it says to provide "a name and a list of asset IDs," while the schema accepts only assetIds and sets additionalProperties=false. An agent following the prose would attempt an invalid parameter, so this is worse than schema-only documentation.

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+resource ("Create a new stack") plus the inputs that define it, so an agent understands this groups asset IDs into a stack. It does not differentiate from nearby siblings such as immich_create_album or immich_create_tag, which also create containers from 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?

Usage is implied by "Create a new stack by providing a name and a list of asset IDs" and the merge note hints at overlap handling, but there is no explicit when-to-use vs. when-not, and no pointer to alternatives like immich_update_stack or immich_remove_asset_from_stack.

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?

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=true, covering the safety profile. The description adds the underlying endpoint (POST /tags) and confirms color is optional, but says nothing about behavior on duplicate names, auth requirements, or tag hierarchy 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?

Short and front-loaded: purpose first, then the input contract. The repeated 'Create a tag'/'Create a new tag' phrasing is slightly redundant but not harmful.

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?

Adequate for a simple three-parameter create tool with no output schema. It nonetheless omits duplicate-name behavior and the parentId hierarchy concept, both of which an agent would need to call it correctly alongside immich_upsert_tags.

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 nominally 100%, so the baseline is 3. The description echoes the name/color fields but omits parentId entirely, even though that parameter enables nested tag creation — a meaningful capability the schema's bare 'parentId (request body)' label does not explain.

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+resource ('Create a tag') and clarifies the required input (name) plus optional color. It does not, however, distinguish itself from the closely related sibling immich_upsert_tags, which also creates tags.

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?

No guidance on when to use this versus immich_upsert_tags, immich_update_tag, or immich_tag_assets. The agent is left to infer that this is a single-tag creation call with no deduplication/upsert semantics.

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?

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=true, so the safety profile is covered. Beyond that the description adds only the REST verb/path and tag — nothing about admin authorization requirements, what the optional flags (notify, shouldChangePassword) actually trigger, or side effects like welcome emails.

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?

It is short and front-loaded, but two of the three lines say the same thing ('Create a user' / 'Create a new user'), which is pure redundancy. Only the endpoint/tag line 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 10-parameter admin mutation with no output schema, the description omits anything an agent needs beyond the bare verb: admin permission requirement, whether the created account is local vs OAuth, and the effect of optional fields like notify and quotaSizeInBytes. Annotations cover safety but not these operational facts.

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 100%, so the schema itself carries the 10 parameters (including required email/name/password and the avatarColor enum). The description adds no parameter meaning at all, which is the baseline 3 when the schema does the heavy lifting.

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 clear verb+resource ('Create a user' / 'Create a new user') and adds the concrete endpoint POST /admin/users with tag Users (admin), which signals this is an administrative creation path rather than self-signup. It does not explicitly contrast with siblings such as immich_sign_up_admin, so it falls short of a 5.

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?

There is no when-to-use guidance, no stated prerequisite that the caller must be an admin, and no reference to any alternative tool. The agent gets no help deciding between this and immich_sign_up_admin or immich_create_session.

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?

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds that creation is possible with empty filters/actions, a modest behavioral detail, plus the underlying POST /workflows endpoint. It does not disclose auth needs, side effects on existing workflows, or what the response contains.

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 opening line duplicates the title verbatim, and the 'Immich operation: POST /workflows · tag: Workflows' trailer is boilerplate. The substantive sentence is useful but the whole block is padded with redundant framing.

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 six-parameter mutation tool with no output schema and no annotations covering behavior, the description is thin. It never mentions that 'trigger' is required, does not list the trigger enum values, and does not explain what a workflow or its steps do, leaving the agent to infer everything from the 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 100%, so the schema already documents all six parameters, and the description adds no syntax or format detail. Its mention of 'filters and actions' does not map to any actual schema property (steps/trigger/name/enabled/logging/description), so it neither clarifies nor 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?

States a specific verb and resource (create a workflow), which is clearly distinct from the update/delete/get/search workflow siblings. However, it does not explicitly name or differentiate against those siblings, and the first line merely restates the title.

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?

No when-to-use guidance, no prerequisites, and no alternatives named. The only usage-adjacent note is that the workflow may be created with empty filters and actions, which is a constraint rather than routing 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?

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful domain context (the target is a like or comment, scoped to an album or asset) and the underlying HTTP operation, but says nothing about authorization requirements or whether the removal is permanent.

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?

Front-loaded with the action and immediately followed by the clarifying sentence; the trailing 'Immich operation: DELETE /activities/{id} · tag: Activities' line is mostly boilerplate that duplicates the endpoint already implied by the name. Overall tight, with only minor redundancy against the title.

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, no-output-schema mutation whose safety semantics are carried by annotations, the description supplies the essential missing piece — what an activity is. Only the authorization/ownership requirement and the effect on activity counts remain unstated, which are minor gaps at this complexity.

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?

Only one parameter (id) and schema description coverage is 100%, so the schema already documents it. The description adds no syntax, format or sourcing guidance for the id beyond what the schema's 'format: uuid' provides — baseline 3 is appropriate.

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 (delete an activity) and, crucially, defines what an 'activity' actually is — a like or comment on an album or asset — which is the non-obvious part an agent needs. It does not explicitly name the inverse sibling immich_create_activity, but the mapping is 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?

No when-to-use or when-not-to-use guidance is given. The description never states prerequisites (e.g. must the caller own the activity?), nor routes to any alternative such as removing a like via another endpoint. Usage is only implied by the verb.

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?

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds genuinely new context: the album is first trashed, then scheduled for deletion, and a background job must complete the process. That deferred/non-immediate completion is exactly the kind of trait an agent cannot infer from the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Short and front-loaded: purpose first, then the behavioral caveat, then the operation/tag reference. The title is repeated as the opening line, which is mildly redundant, but nothing else is wasted.

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 no output schema, the description covers the operation and its asynchronous completion path. Missing only the authorization/ownership expectation, which would make it fully self-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 100% for the single 'id' parameter, so the schema already carries the meaning. 'By its ID' restates the schema rather than adding format, permission, or lookup guidance, so the baseline 3 applies.

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 ('Delete a specific album by its ID'), which is unambiguous against siblings like delete_library or delete_tag. It does not, however, explicitly contrast itself with any sibling tool, so it stops short of the top band.

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 what deletion does but never states when to reach for this tool versus alternatives, nor any prerequisites (ownership, permissions). The deferred-deletion note is behavioral, not 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?

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely new behavioral context by clarifying that the current session survives, which annotations do not convey.

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 and front-loaded, with the key constraint stated immediately after the purpose. The opening line restates the title verbatim, which is mild redundancy but costs little.

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, no-output-schema operation whose annotations already carry the destructive/idempotent profile, the description supplies the one behavioral detail an agent needs (current session preserved). Nothing critical 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 tool takes zero parameters, so there is nothing for the description to disambiguate. This is the expected baseline for a no-argument operation.

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 with clear scope: 'Delete all sessions for the user.' The word 'all' distinguishes it from the singular immich_delete_session sibling, though the description never names that alternative explicitly.

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 contextual guidance via 'This will not delete the current session,' which tells the agent a boundary of the operation. However, it does not state when to prefer this bulk delete over immich_delete_session or immich_end_session, leaving the routing decision implicit.

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?

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds genuine context beyond that: the ownership authorization requirement, which the agent cannot infer from the annotations. It stops short of noting irreversibility or token invalidation side effects, so not 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?

Front-loaded and short, with the ownership constraint stated early and the API operation mapping appended. The title is repeated almost verbatim in the first sentence ('Delete an API key' / 'Deletes an API key'), a minor redundancy that keeps it from a 5.

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 delete with destructive/idempotent annotations already covering the safety profile and no output schema, the description supplies what is needed: what it does, the ownership precondition, and the underlying endpoint. 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?

Only one parameter with 100% schema description coverage, so the schema already documents the UUID id. The description's 'identified by its ID' adds no format or syntax detail beyond the schema, making the baseline 3 appropriate.

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) and resource (API key) and identifies the selector (by ID). An agent can distinguish it from immich_create_api_key, immich_update_api_key, and immich_rotate_api_key without opening any schema.

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

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

Provides a real prerequisite ('The current user must own this API key'), which is useful for deciding whether the call will succeed. However, it gives no explicit when-to-use guidance or alternative routing (e.g., use rotate_api_key to regenerate rather than delete), leaving usage implied.

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?

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds one useful extra fact — the record is removed from the database, not just the file — but says nothing about permissions required, whether the underlying object storage file is also purged, or recoverability.

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?

Very short and front-loaded, with the core action stated first. The opening line duplicates the title and 'Delete a file' repeats the first sentence, a small amount of redundancy but nothing that obscures the message.

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 delete with annotations covering the safety profile and no output schema, the description is minimally sufficient. It could still clarify the asset-file vs asset boundary and what happens to the backing binary, which are the questions an agent would have here.

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?

There is a single required id parameter with 100% schema coverage, so the schema already documents the input. The description adds no semantics about what the id identifies (asset file id vs asset id), leaving the baseline 3 appropriate.

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 (delete an asset file) and adds that the file is removed from the database. It is clear on its own, but does not differentiate itself from nearby siblings like immich_delete_assets, immich_delete_asset_metadata, or immich_get_asset_file — the 'asset file' vs 'asset' distinction is left implicit.

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?

No when-to-use guidance, no prerequisites, and no mention of alternatives in a sibling set containing several other delete/asset-file tools. The agent must infer the routing decision entirely from the name.

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?

Annotations already declare destructiveHint=true, idempotentHint=true, readOnlyHint=false, and openWorldHint=true, so the safety profile is covered without the description's help. The description is consistent with those hints and adds the underlying DELETE endpoint, but says nothing about behavior when the key is absent (error vs. silent no-op) or any permission requirement.

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 and front-loaded: purpose first, endpoint last. The opening line duplicates the title verbatim and the second sentence largely restates it, so there is mild redundancy, but nothing is bloated.

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 trivial two-parameter, fully-annotated delete with no output schema, the description covers what the operation does and where it maps in the API. The only meaningful gap is what happens on a missing key, which is minor for a delete-by-key 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?

Schema description coverage is 100% ('Asset ID', 'Metadata key'), so both parameters are already documented in the schema. The description adds no format, casing, or key-namespace detail beyond what the schema provides, making the baseline 3 appropriate.

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) and resource (a single asset metadata key-value pair on a given asset), which an agent can distinguish from immich_get_asset_metadata_by_key and immich_update_asset_metadata. It never explicitly names the bulk sibling immich_delete_bulk_asset_metadata, so the single-vs-bulk distinction is left to inference from 'specific'.

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?

No when-to-use or when-not-to-use guidance is given, and no alternative is named even though immich_delete_bulk_asset_metadata and immich_update_asset_metadata are obvious adjacent choices. The agent must infer routing purely from the tool name.

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?

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is covered structurally. The description adds nothing beyond that: it never says whether deleted assets go to trash or are permanently removed, whether the `force` flag changes that, or what authorization is required — meaningful context for a destructive bulk 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?

Very short and front-loaded, but the first line merely repeats the title verbatim before the sentence that adds information, which is mild redundancy rather than a functional flaw.

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 destructive, multi-asset delete with no output schema, the description should at minimum clarify trash-vs-permanent semantics and the effect of `force`. Given the complexity of the operation and its irreversibility, the current text leaves the agent under-informed.

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 100%, so both `ids` and `force` are documented in the schema, establishing the baseline of 3. The description contributes no additional meaning, notably nothing about what `force` actually does.

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 ('Delete assets', 'Deletes multiple assets at the same time') and the underlying operation (DELETE /assets), so the agent knows exactly what it does. It does not, however, distinguish itself from the many other delete_* siblings in the namespace.

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?

No guidance on when to use this versus alternatives such as immich_delete_asset_file, immich_delete_duplicate(s), or immich_restore_assets. There is no mention of prerequisites, permissions, or the recovery path after deletion.

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?

Annotations already declare destructiveHint=true, idempotentHint=true, readOnlyHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the underlying operation and clarifies that key-value pairs are removed, but does not add further behavioral context such as auth requirements or irreversibility details.

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 and front-loads the action and scope. The first line duplicates the title, which is slightly redundant, but the remaining two lines are useful and earn their 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?

With annotations covering safety semantics and the schema covering the single parameter completely, the description provides enough context for an agent to understand what the tool does and when it applies. No output schema exists, so return-value explanation is not required.

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 100% and the single 'items' parameter is fully documented in the schema, including nested assetId and key descriptions. The description adds no parameter syntax or format details beyond what the schema already provides, so the baseline of 3 applies.

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 ('asset metadata'), and scope ('for multiple assets'). This clearly distinguishes it from the singular sibling immich_delete_asset_metadata and from update operations on bulk metadata.

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 phrase 'for multiple assets' implies the bulk use case and distinguishes it from single-asset deletion, but it does not explicitly name alternatives or state when not to use it. Usage context is implied rather than instructed.

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?

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds only the 'pending' state qualifier and the underlying endpoint, with no detail on permissions, effects on the requester, or reversibility – modest added value against a lower bar.

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?

Very short, but the title sentence is repeated verbatim in the description body and the following line restates the same action, so a third of the text is redundant. The API-operation trailer is useful metadata but not front-loaded 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 single-parameter delete whose annotations already disclose the destructive/idempotent profile and whose schema is fully documented, the description says enough to invoke correctly. Minor gaps remain (no mention of required permissions or the resulting state of the declined request).

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?

There is a single 'id' parameter at 100% schema coverage (documented as uuid format), so the schema carries all meaning. The description adds nothing about which id is expected beyond what the schema already provides, making the baseline 3 appropriate.

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 (Decline/Delete) and resource (a pending request to join a cluster group), which an agent can distinguish from the many unrelated delete_* siblings. It does not explicitly name its opposite sibling immich_accept_cluster_group_request, so it stops short of full 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 no when-to-use or when-not-to-use guidance and never mentions the obvious alternative, immich_accept_cluster_group_request. The only usage signal is the word 'pending', which implies the request must still be pending but is not stated as a condition.

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?

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the agent knows this is an irreversible-style write. The description adds the concrete endpoint (DELETE /admin/database-backups) and that the target is identified by filename, but says nothing about whether the file is permanently removed from disk or whether the action can be undone.

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 lines, front-loaded with the action and followed by the identifying detail, with no filler prose. The only waste is mild repetition between the title line and the 'Delete a backup by its filename' line.

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 admin tool whose annotations already cover the safety profile, the description is close to sufficient but leaves two gaps: it never says the parameter is a list of multiple filenames (the schema takes an array), and it does not state whether deletion is permanent or recoverable via the restore flow.

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 reported at 100%, but the schema's only text is the placeholder 'backups (request body)', so the schema itself conveys little. The description's 'by its filename' adds real meaning by telling the agent the array elements are backup filenames, which is the baseline expectation when the schema does the naming.

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 ('Delete database backup') and adds the key discriminating detail 'by its filename', which separates it from sibling list/download/upload backup tools. It stops short of naming those siblings explicitly, so an agent must infer the boundary from the verb alone.

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?

There is no explicit when-to-use or when-not-to-use guidance; the admin tag hints at required privilege but the description never states that an admin context is mandatory. Nothing routes the agent between this tool and immich_list_database_backups, immich_download_database_backup, or immich_upload_database_backup.

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?

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description earns credit by resolving the tension the annotations create: it explains that this 'delete' does not destroy assets but only unlinks them. It omits auth/rate-limit context, so not 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?

Short and front-loaded, with the key behavioral nuance in the second sentence. The first line simply repeats the title, which is minor redundancy, and the trailing 'Immich operation' metadata is useful provenance rather than padding.

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 mutation tool whose annotations already cover safety, the definition is nearly complete: it explains what the mutation actually does and which endpoint it maps to. The only meaningful omission is how it relates to the plural delete/resolve duplicate siblings.

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 100% for the single id parameter, so the schema carries the documentation burden. The description only adds that the ID refers to the duplicate group, which is a marginal clarification over the schema's uuid type. Baseline 3 is appropriate.

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 ('dismiss a duplicate group by its ID') and clarifies the actual effect: assets are unlinked, not deleted. This is genuinely helpful given the 'delete' name. However, it never distinguishes itself from close siblings like immich_delete_duplicates (plural) or immich_resolve_duplicates, which an agent could easily confuse with it.

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?

No when-to-use, when-not, or alternative guidance. With siblings immich_delete_duplicates and immich_resolve_duplicates operating in the same duplicate-handling space, the absence of routing guidance is a real gap.

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?

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered structurally. The description adds only the underlying endpoint (DELETE /duplicates) and tag, plus the fact that deletion is by ID list; it says nothing about irreversibility, permissions, or what happens to the removed assets.

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?

Front-loaded with the verb phrase and kept to one operative sentence plus endpoint metadata. The repeated title as the first line is slightly redundant but not wasteful.

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 full annotations and no output schema, the description is minimally sufficient to invoke. It falls short only on sibling disambiguation, which matters here because immich_delete_duplicate exists and could easily be chosen instead.

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 100% for the single ids parameter, so the schema already documents the UUID array. The phrase 'specified by their IDs' mirrors that without adding format or constraint detail, so the baseline 3 applies.

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) and resource (multiple duplicate assets specified by their IDs), and the 'multiple' wording hints at batch scope. However, it never distinguishes itself from the near-identical sibling immich_delete_duplicate (singular) or immich_resolve_duplicates, which is the main ambiguity an agent would face.

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?

There is no when-to-use guidance, no prerequisites, and no mention of the alternative immich_delete_duplicate or immich_resolve_duplicates. Given three sibling tools all dealing with duplicate removal, the absence of any routing guidance is a real gap.

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?

Annotations already declare destructiveHint=true, idempotentHint=true, readOnlyHint=false, and openWorldHint=true. The description adds the raw HTTP operation and mentions force deletion, but does not explain what force does, whether deletion is permanent, what permissions are required, or what side effects occur.

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 and front-loaded, but it redundantly repeats 'Delete a face' after the title and before the main sentence. Otherwise it is appropriately sized for a simple delete operation.

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 is a simple delete endpoint with annotations covering its safety profile and a schema covering both parameters. However, the description omits what force actually does and misleadingly calls it optional when it is required, leaving a meaningful gap for 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 100%, so the baseline is 3. The description adds that the id identifies the face and that force can be used, but it says force is optional while the schema marks it as required, which is a misleading nuance rather than a helpful clarification.

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: delete a face identified by id. It clearly distinguishes from generic delete tools by naming the resource, though it does not explicitly differentiate itself from siblings like immich_delete_person or immich_delete_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?

No guidance is provided on when to use this tool versus alternatives such as immich_delete_person. The phrase 'Optionally can be force deleted' hints at a mode but does not explain when or why to use force deletion.

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?

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true. The description adds genuine value beyond those flags by disclosing the cascading side effect ('perform corresponding deletion, e.g. trash asset, delete file'), which tells the agent that deleting a report item alters underlying asset/file state. It stops short of permission or reversibility detail.

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?

Compact and front-loaded, leading with the action and following with the side-effect clarification and the raw operation. Slight redundancy between the title line and the 'Delete a given report item' sentence, but no wasted 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 destructive admin delete with no output schema, the description covers the action, its cascading effect, and the endpoint/method. Nothing critical is missing for correct invocation, though it could note admin permission requirements.

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 100% with a single 'id' (uuid) parameter, so the schema fully documents the input. The description adds no format or sourcing guidance for the id beyond what the schema already provides. Baseline 3 is appropriate.

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 ('Delete integrity report item') and clarifies that the deletion cascades to downstream actions (trash asset, delete file). It does not, however, differentiate itself from the many sibling delete tools beyond naming the integrity-report resource. Clear verb+resource with useful scope detail.

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?

No statement of when to use this tool versus alternatives, no prerequisites, and no mention that it targets an admin/maintenance context (the '(admin)' label is buried in the operation string). The agent must infer usage from the resource name alone.

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?

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds the API endpoint and clarifies that it targets an external library by ID, but it does not disclose cascading effects, permission requirements, or what happens to associated assets.

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 definition is short and front-loads the action. The first line repeats the title, and the API-operation line is metadata rather than explanation, but there is no unnecessary 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 simple one-parameter delete operation with annotations covering destructiveness and idempotency, the description is minimally sufficient. However, it omits usage context and any caution about the impact of deleting an external library, which would help an agent decide when this tool is appropriate.

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 100% for the single required id parameter, and the schema specifies the UUID format. The description only repeats 'by its ID' and adds no further 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?

States a specific verb and resource: 'Delete an external library by its ID.' It also includes the exact API operation, so an agent can distinguish this from deletion tools for albums, assets, users, and other resources without opening the schema.

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 explains what the tool does but gives no guidance on when to use it versus alternatives such as immich_update_library, immich_scan_library, or immich_get_library. There are no prerequisites, warnings, or 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?

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is covered. The description adds the concrete HTTP operation 'DELETE /memories/{id}', which is useful context, but does not add details like permission requirements or what happens to associated memory assets beyond the annotation-level destructive hint.

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 and front-loaded with the operation. However, the first line simply repeats the title 'Delete a memory', which is redundant, while the second and third lines add useful specificity and API context.

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 delete tool with rich annotations and no output schema, the description is largely complete. It identifies the exact operation and parameter role, though it omits permission or downstream-effect details that could matter for a destructive memory 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?

There is only one parameter, and the schema has 100% description coverage with 'format: uuid'. The description says 'by its ID' but adds no syntax or format detail beyond what the schema already provides, so the baseline 3 is appropriate.

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 ('Delete a memory') and then narrows it to 'a specific memory by its ID.' This clearly distinguishes it from sibling tools like immich_update_memory, immich_remove_memory_assets, and immich_search_memories.

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 guidance on when to use this tool versus alternatives. It does not mention prerequisites, when not to use it, or how it differs from related memory operations such as immich_remove_memory_assets or immich_update_memory.

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?

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is fully covered by structured data. The description adds only the REST mapping (DELETE /notifications/{id}) and repeats the title, contributing no behavioral context such as whether deletion is permanent or what permissions are required.

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 content is padded: the title 'Delete a notification' is repeated verbatim as the first line, followed by a near-identical second sentence, plus a metadata line. Only the REST endpoint reference is non-redundant, so most of the text does not earn 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 delete with full annotation coverage and no output schema, the definition is minimally sufficient. However, it omits the irreversibility/alternative-tool context that would make an agent confident it is choosing the right delete variant.

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 100%, and the single id parameter is documented (format: uuid), so the schema carries the weight. The description adds nothing beyond the endpoint template echoing {id}, which fits the baseline 3 for high schema 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?

The description states a specific verb (Delete) and resource (a notification), and 'a specific notification' implies single-item scope versus the bulk sibling. It does not explicitly name immich_delete_notifications, so the agent must infer single-vs-bulk from the wording alone.

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?

There is no when-to-use guidance, no exclusion, and no mention of the obvious alternative immich_delete_notifications for bulk deletion. The agent gets a purpose statement but nothing that routes it between the singular and plural 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?

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, covering the safety profile. The description adds only the raw endpoint and tag metadata, saying nothing about permanence, whether IDs that don't exist cause errors, or any auth requirements — no value beyond the structured fields.

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?

It is short and front-loaded, but the first line simply repeats the tool title verbatim, and the 'Immich operation: DELETE /notifications · tag: Notifications' line is generator metadata that carries little decision value. Roughly half the text is redundant.

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 bulk delete with full schema coverage and annotations that declare the destructive/idempotent profile, the description is adequate — an agent can call it correctly. Only minor gaps remain, such as behavior on non-existent IDs.

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 100% (a single required 'ids' array with uuid items), so the schema fully documents the parameter. The description adds no format, limit, or batch-size guidance beyond what the schema provides, which is the baseline 3 case.

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 ('Delete notifications') and clarifies the bulk scope with 'Delete a list of notifications at once,' which implicitly separates it from the singular sibling immich_delete_notification. It stops short of explicitly naming that sibling, so differentiation requires a small inference.

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 phrase 'at once' hints at the bulk use case, but there is no explicit when-to-use guidance, no mention of the single-notification alternative, and no prerequisites or permission notes. An agent must infer the routing decision entirely.

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?

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds the bulk-multiplicity context but says nothing about consequences (e.g., what happens to associated faces/assets) or auth needs, so the added behavioral value is modest.

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 body is short and front-loaded, but the opening line 'Delete people' duplicates the tool title verbatim and the closing 'Immich operation/tag' line is template boilerplate. Small redundancy keeps it from being tight.

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 essentials exist, and annotations carry the safety profile. However, the description omits what deleting a person actually removes or affects, leaving room for an agent to underestimate impact; it is adequate but not 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?

Schema description coverage is 100% for the single 'ids' parameter, so the schema already documents the UUID-array body. The description's 'list of people' loosely reinforces that ids is plural but adds no format or constraint detail; baseline 3 is appropriate.

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+resource ('Delete people') and clarifies the bulk scope ('Bulk delete a list of people at once'), which distinguishes it from the single-target sibling immich_delete_person. It falls short of naming that sibling explicitly, so an agent must infer the distinction from 'bulk' and 'list'.

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 phrase 'Bulk delete a list of people at once' implies usage (multiple people to remove in one call), but there is no explicit when-to-use guidance, no named alternative, and no preconditions such as required permissions or confirmation. Usage is only implied.

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?

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered structurally. The description adds nothing beyond the raw endpoint: it does not say what collateral data is removed (faces, thumbnails, asset associations), whether the action is reversible, or what permissions are required.

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 and front-loaded, but 'Delete person' is restated as 'Delete an individual person' with no new information, so one of the three lines is redundant padding.

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 delete, the schema and annotations cover input and safety. The remaining gap is the blast radius of the deletion, which a destructiveHint alone does not convey, so the definition is adequate but not 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?

Schema coverage is 100% with a single uuid id parameter, so the schema fully documents the input and the description adds no syntax or format detail. Baseline 3 applies when the schema does all the work.

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?

Clear verb+resource ('Delete an individual person') and the word 'individual' gestures at single-item scope versus the plural sibling immich_delete_people. It stops short of naming that sibling, so the differentiation is implied rather than 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?

No when-to-use guidance and no alternatives are mentioned. With immich_delete_people (bulk) and immich_delete_face sitting right beside it, the definition never tells the agent which one applies to a given request.

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?

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds the 'current user' target scope and the underlying DELETE /users/profile-image operation, which is useful context. It does not say what happens when no profile image exists or whether the default avatar is substituted, which for a destructive tool is a residual 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?

Three short lines, front-loaded with the action. The opening line merely restates the title before the substantive 'current user' detail, which is minor redundancy but not costly at this length.

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, no-output-schema mutation whose annotations already carry the destructive/idempotent profile, the description supplies everything needed to invoke it safely. Only the post-deletion state is left unaddressed.

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 takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies for a correctly parameterless definition.

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 ('Delete the profile image') and scopes it to the current user, which distinguishes it from admin-level image operations and from immich_get_profile_image / immich_create_profile_image. It does not name those siblings, but the resource and scope are 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?

There is no when-to-use or when-not-to-use guidance and no alternative tool is mentioned. The 'current user' phrasing implies self-service usage, but an agent must infer that rather than read 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?

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, so the agent knows the safety profile. The description adds only 'currently set', implying it acts on whatever key exists with no input; it does not say what happens if no key is configured or what authorization is required, which is modest added value over the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Two short sentences plus an endpoint reference line; the action and its target are front-loaded with no filler or repetition beyond the title restatement.

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, destructive administrative action with rich annotations and no output schema, the description is adequate. Only error behavior (e.g., no license present) is unstated, a minor gap.

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 takes zero parameters, so the baseline is 4. The description correctly implies no input is needed by scoping the action to the 'currently set' key, but there is no parameter detail to add.

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 ('Delete server product key') and clarifies scope with 'currently set', which distinguishes it from set_server_license and get_server_license in the sibling list. It does not name those siblings explicitly, so it falls short of a 5.

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?

There is no when-to-use guidance, no mention of the paired immich_get_server_license or immich_set_server_license tools, and no statement of prerequisites or consequences. Usage is only inferable from the name itself.

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?

Annotations already declare destructiveHint=true, idempotentHint=true, readOnlyHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the concrete DELETE /sessions/{id} operation and Sessions tag, but does not describe auth requirements, side effects, or whether the current session can be targeted.

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 and front-loaded, with the operation line giving useful API context. The first line repeats the title 'Delete a session' exactly, which is slightly redundant, but overall it is 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?

For a simple one-parameter delete operation with full schema coverage and annotations covering destructiveness and idempotency, the description plus structured fields are largely complete. It does not explain potential effects on the caller's own session or authentication requirements, leaving minor context 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?

Schema description coverage is 100%: the single id parameter is fully documented in the schema with its uuid format. The description only says 'by id', adding no syntax or format meaning beyond the structured schema, so baseline 3 is appropriate.

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 ('Delete a session', 'Delete a specific session by id') and includes the underlying API operation. However, it does not explicitly distinguish this tool from close siblings such as immich_delete_all_sessions or immich_end_session, so it falls short of full 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 phrase 'by id' implies the tool is used when a specific session id is available, but there is no explicit guidance about when to choose this over immich_delete_all_sessions or immich_end_session. Usage is left to 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?

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds only the raw API endpoint (DELETE /stacks/{id}); it does not say whether the underlying assets are deleted or merely unstacked, which is the key behavioral question for a destructive 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?

Front-loaded and brief, with the core action stated first. There is minor redundancy between the title, the repeated 'Delete a stack', and the boilerplate API-operation line, but nothing is bloated.

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 operation with annotations carrying the safety hints, the definition is minimally adequate. It omits the consequence for stack members and any prerequisite/permission notes, which an agent would benefit from before invoking.

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 100% and the single id parameter is documented as a uuid in the schema, so the schema does the heavy lifting. The description's 'by its ID' adds only marginal confirmation beyond that.

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 ('Delete a stack') and adds the identifier scope ('by its ID'), which distinguishes it from a bulk delete. However, it never names or contrasts with the close sibling immich_delete_stacks, so the differentiation is only implied.

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 phrase 'a specific stack by its ID' implies single-stack usage versus bulk deletion, but there is no explicit when-to-use/when-not guidance or routing to alternatives such as immich_delete_stacks or immich_remove_asset_from_stack.

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?

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered structurally. The description confirms the batch/list nature but says nothing about what actually gets destroyed (e.g., whether member assets are deleted or merely unstaked), which would be valuable extra context for a destructive op.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.