Suggest Spirit skills, jewels, flasks, anoints, runes and more

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

readOnlyHint already declares a safe read, and the description adds substantive behavior beyond that: costs are Exalted Orbs sourced from the official Currency Exchange for 'the last full hour...when it can be reached' (a data-freshness caveat), and it discloses the freeWithAmulet mechanic and the Raven-Touched Shard second-notable rule. Return format is not described, keeping it below a 5.

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 entire body is a single sprawling sentence stacked with parentheticals and 'and' clauses, which is dense and hard to parse. It is front-loaded with the scope, and most clauses carry information, but the structure works against quick comprehension.

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 11 parameters, no output schema, and only a readOnly annotation, the description carries the disclosure burden and does so thoroughly across all six categories plus the pricing caveat. The remaining gap is the shape of the returned results, which nothing else documents.

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 already 82%, so the baseline is 3, but the description adds real meaning the schema lacks: gearSpirit is defined as quests plus user-supplied gear Spirit, mainSkill is scoped to jewel-type selection, and the amuletSkills section explains the amulet-granted free skills. It does not fully clarify 'allocated' or 'avoid' beyond 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?

States a specific verb (suggest) and enumerates the exact resources covered (Spirit skills, jewels, flasks, anoints, runes/soul cores/idols), scoped 'beyond the main skill at a character level'. This is specific enough to separate it from siblings like find_uniques or optimize_build 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?

Frames the tool as a follow-up layer ('beyond the main skill') and routes the agent to evaluate_build for applying the results (anoint, helmetInstill, socketables, amuletSkill, flasks). It gives clear context but no explicit when-not or a full comparison against sibling suggestion tools.

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