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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds behavior beyond that: paginated response of {id, name} only, presence of total and hasMore, AND across filters with OR inside an array, and the non-obvious exclusion rule that items lacking a filtered field drop out (rarity+spellLevel matches only rare spells). Those are precisely the semantics an agent cannot infer from 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 purpose and routing, then a short labeled block for the non-obvious data-format traps. Every sentence carries information an agent would otherwise get wrong; nothing is restated from the schema.

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 14-parameter, zero-required filter tool with no output schema, the description covers response shape, pagination signals, combination logic, and exclusion behavior. The remaining gap is result ordering (no sort parameter or documented default order), which affects how an agent interprets offset/limit paging.

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 and the schema already documents each field, including enum casing (veryRare) and spell-only fields. The description earns extra credit for the combination semantics — filters AND together while values inside one array OR — which the schema does not state anywhere. It stops short of discussing interaction between specific filters beyond the rarity/spellLevel note.

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 ("Search the world's Items Directory (game.items)") plus the scoping constraint (dnd5e worlds only), and explicitly names the two tools it is not (item-list for actor inventories, dnd5e-compendium-filter-items for compendiums). An agent can pick it out of the sibling list 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?

Gives explicit routing rules: use world-item-get for full document data, item-list for an actor's inventory, dnd5e-compendium-filter-items for compendiums. The 'NOT ... NOT ...' phrasing supplies genuine exclusions rather than implied usage, which is exactly what the sibling set requires.

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