Where to get items

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

Annotations already declare read-only, idempotent, non-destructive, open-world behavior, so safety is covered. The description adds genuine behavior beyond that: results are ranked with a practical recommendation plus its reason, and skill checks are run against the account. It does not explain pagination behavior despite the cursor parameter.

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?

Two sentences, both front-loaded with the trigger condition first and the output behavior second. No redundant restatement of the title, though the source enumeration is fairly dense.

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?

With six optional parameters and no output schema, the description usefully explains what a result looks like (per-item recommendation and reason) and how personalization works. It omits any mention of cursor-driven pagination for long lists and of how items vs. quest inputs differ in output volume, leaving small gaps.

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%, so every parameter (including depth, cursor, and player) is already documented in the schema. The description only adds the ironman/GE exclusion and account-skill-check concept, which map loosely onto the ironman and player fields. Baseline 3 applies when the schema carries the load.

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?

Names a specific verb (find) and resource (item sources) and enumerates the source classes it aggregates: shops, ground spawns, drops, recipes, and GE. This lets an agent distinguish it from the narrower siblings get_shop, get_drops, and find_recipes, which each cover only one of those classes.

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?

Explicitly states the triggering condition: 'Use when the player needs to get items, or every item for a quest,' including the quest-wide planning case. It gives clear context but names no alternative tool or exclusion (e.g., a note to use get_price for market values), so it stops short of full when/when-not routing.

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