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

No annotations are provided, so the description must carry the burden. It only states the search criteria but does not disclose behavior such as that the operation is read-only, that 'query' can be omitted to list everything (though schema says this), or any details about result ordering/pagination. The absence of this context leaves the agent unsure of the tool's side effects and return characteristics.

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?

A single sentence that front-loads the verb and resource, immediately followed by search dimensions. No redundant or extraneous text—every word earns its place.

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

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

For a simple search tool with one optional parameter and no output schema, the description covers the main use case. It specifies what can be searched and the resource under search. It does not describe the return format, but given the simplicity, that omission is acceptable for a minimum viable description.

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 'query' parameter is described). The tool description adds value by clarifying that the query applies to 'name, game, or terrain type,' giving semantic meaning beyond the schema's generic 'Search term.' This enriches parameter understanding sufficiently to guide usage.

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

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

The description uses a specific verb ('search') and clearly identifies the resource ('hex tile sets') with explicit search dimensions ('by name, game, or terrain type'). It distinguishes this from sibling tools like tile_gallery_get (retrieval) and tile_gallery_stats (statistics).

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 usage context: if you need to find tiles based on name/game/terrain, use this search. However, it does not explicitly mention alternatives or exclusions, relying on sibling names to convey differentiation. Still, the intent is clear enough for an agent to select it over get/stats.

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