Search asset statistics

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

The description states this is a 'Retrieve' operation returning counts, i.e. a pure read, while the annotations declare readOnlyHint=false. That is a direct inconsistency an agent could act on (e.g. treating a harmless statistics query as a mutating call). Aside from the contradiction it adds no auth, rate-limit, or scope context.

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

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

The body sentence is efficient, but the first line merely repeats the tool title verbatim and the trailing 'Immich operation: POST /search/statistics · tag: Search' is metadata padding. Roughly half the text earns its place, and the useful content is not front-loaded.

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

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

For a 29-parameter filter tool with no output schema, the description should at least outline what statistics come back; it mentions only 'total matching count'. Combined with the missing sibling differentiation and the annotation mismatch, the definition is not sufficient for confident 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%, but the descriptions are placeholders like 'city (request body)', so the schema does not really explain the 29 fields. The description says nothing about parameters beyond 'search criteria', so it neither compensates nor misleads. Baseline 3 for high coverage 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 ('Retrieve statistical data about assets') and clarifies the output is a count ('total matching count'). However, it never differentiates itself from near-identical siblings such as immich_get_asset_statistics, immich_get_album_statistics, or immich_search_assets, so an agent cannot tell which statistics tool to pick without opening schemas.

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

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

The phrase 'based on search criteria' hints that this tool is the filterable variant, but there is no explicit when-to-use, when-not-to-use, or named alternative. With so many statistics and search siblings, 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.