Search and organize gallery works

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

The description discloses key behaviors: limited to 10 result pages, merging of official version links and variants, grouping into series, heuristic uniqueWorkCount with confidence levels, and per-page rate-limited search requests. Annotations already mark it as read-only, idempotent, and non-destructive, and the description adds significant operational context beyond those.

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 relatively concise: two main sentences plus an explanatory sentence about counts/confidence. It front-loads the core actions (search, fetch, merge, group). However, the first sentence is a bit dense and could be better structured for quick scanning.

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

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

Given the complexity (13 parameters, output schema exists), the description adequately covers the high-level merging logic and output characteristics. However, it lacks detailed guidance on parameter usage, leaving the agent to rely heavily on the sparse schema or prior knowledge. The existence of an output schema mitigates some completeness gaps for return values, but parameter semantics remain underexplained.

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 only 23% schema description coverage for 13 parameters, the description should compensate by clarifying key parameters. It only mentions maxPages (implicitly through 'up to 10 result pages') and does not explain query syntax, categories, pageFrom/pageTo, filters, or other enums. The description adds minimal parameter-level meaning beyond the sparse schema.

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

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

The description clearly states the tool searches and organizes gallery works, specifying it fetches metadata, merges version links and variants, and groups installments into series. This distinguishes it from sibling tools like eh_search_galleries (raw gallery search) and eh_search_favorites (favorites search) by emphasizing merging and organizing behavior.

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 tool is for getting organized works (merged versions, series grouping) but does not explicitly state when to use it over alternatives like eh_search_galleries or other search tools. No direct guidance on when not to use it or which sibling would be better for specific needs.

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