Find live PoE2 trade upgrades

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

Annotations already signal read-only/open-world behavior, and the description adds significant non-obvious context: it calls GGG's unofficial trade-site endpoint, may require POE2_TRADE_POESESSID, enforces constraints/ranking, and returns the official trade URL. This goes well beyond the structured annotations and is not contradicted by them.

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 dense sentences with no wasted words: the core search-and-return behavior is front-loaded, followed by the essential endpoint/authentication caveat. Every clause 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 9-parameter tool with no output schema, the description covers the main contract, the external endpoint risk, auth dependency, and the return artifact. It could be more explicit about the exact response shape (ranked candidates vs URL only) and behavior when auth or matches are absent, but the operational essentials are present.

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 56%, and the prose adds meaning by clarifying that priorities are per-stat improvement requirements and that budget/required-level limits constrain the search. But it does not meaningfully clarify slot, resultLimit, or characterName beyond their schema defaults/enums, so the parameter contract remains partially delegated to the 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 states a specific action ('Search live Path of Exile 2 listings'), a clear resource (PoE2 trade items), and the precise success criteria (improves every requested stat over the equipped slot, budget/level limits, ranked candidates, trade URL). This strongly differentiates it from sibling tools such as compare_item or get_defenses.

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 natural use case is implied: find a purchasable upgrade for an equipped slot with budget and level constraints. However, there is no explicit 'use this instead of X' guidance or exclusion of cases where siblings like compare_item would be more appropriate, so the agent must infer the routing boundary.

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