ddb_search_equipment

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

The annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds meaningful behavioral context beyond that: it requires login, covers both mundane and magic items, and offers a filter trick (rarity='common' for mundane equipment). This enriches the agent's understanding without contradicting 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 description is four sentences, each earning its place: the first states the core function, the second lists coverage, the third offers a specific filtering technique, and the fourth notes the login requirement. It is front-loaded with the main purpose and contains zero 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 read-only search tool with three optional parameters and no output schema, the description is quite complete. It covers purpose, scope, a filtering nuance, and an operational prerequisite (login). It does not describe the return format or result limits, but given the simplicity and the annotations, this is not a critical 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 coverage is 100% with each parameter already described ('Partial item name', 'Item type filter', 'Rarity filter'). The description adds extra semantic value by providing concrete examples (Longsword, Plate) and clarifying the rarity filter behavior with the 'common' tip. It doesn't repeat every schema detail, but adds a useful layer of meaning.

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 a clear resource ('D&D Beyond item/equipment compendium'), and explicitly states the dimensions by which one can search (name, rarity, type). It also distinguishes itself from sibling search tools by listing included categories (mundane weapons, armour, gear, magic items) and by contrasting with a likely getter (ddb_get_equipment).

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 clearly implies when to use the tool: to search for items by name, rarity, or type. It also provides a concrete usage tip ('Filter by rarity='common' to see only mundane equipment') and a prerequisite ('Requires login'). However, it does not explicitly mention alternatives (e.g., when to use ddb_get_equipment), so it stops short of full when/when-not guidance.

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