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

readOnlyHint=true already signals a safe read; the description adds that the return value is 'one short message' of questions and that the answers must be forwarded as `goals`, which is genuinely useful behavioral context. It does not describe what happens if the player refuses or partial answers, so not 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?

Two sentences, front-loaded with the deliverable, then the enumeration of question topics, then the routing instruction. The list is long but every item is a distinct intake dimension, so nothing is filler; it is slightly run-on but efficient.

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 no output schema and no parameters, the description must explain what comes back — and it does ('one short message' of questions) plus how to use the result. It is complete for a prompt-template tool, though the exact structure of the returned message is not spelled out.

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?

The tool takes zero parameters, so the schema carries no burden and the baseline is 4. The only parameter mentioned (`goals`) belongs to the downstream tools, not this one, so no additional input semantics are required.

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?

It states a specific deliverable — the set of questions to ask the player before planning — with a scope qualifier ('before planning anything') that no sibling shares. An agent can distinguish this intake/templating tool from evaluate_build, plan_passive_tree and the other planning tools without opening any 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?

It places the tool in the workflow precisely ('before planning anything'), tells the agent to skip already-answered questions, and routes the collected answers downstream to evaluate_build, compare_builds and optimize_build via the `goals` parameter. It lacks an explicit when-not-use clause, keeping it just short of a 5.

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

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

Annotations only declare readOnlyHint=true, so the description usefully adds behavior the schema doesn't: missing connecting passives are auto-filled and counted, Giant's Blood tripling is applied to weapon requirements, and the check mirrors export_build's enforcement rules. It stops short of describing what the pass/fail result looks like or how violations are surfaced, which matters since there is no output schema.

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-loads the purpose, then uses the remaining sentences for actionable instructions (leveling-phase cadence, sibling routing). It is dense with enumerated check categories but nearly every clause maps to a distinct behavior, so little is wasted.

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 nested tool with no output schema, the description covers the check domains, a behavioral gotcha (auto-filled passives), and where to go for other needs. The main gap is that it never describes the shape or nature of the check results, which is the one thing an agent must guess.

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 56%, so the description has to compensate, and it does for several params: it tells the agent to supply `weapons` and why (attribute requirements with Giant's Blood tripling), and clarifies how passives interact with '+5 to any Attribute' allocation. It leaves ascendancy/ascendancyPassives and gearAttributes largely to the schema, but adds real value beyond the structured fields.

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 ('rule-based checks') and resource ('a planned build at a given character level') and then enumerates the actual check categories (skill usability, gem/weapon attribute requirements, Spirit, passive budget, skill/support rules). This clearly separates it from evaluate_build, which is named as the different tool.

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 invocation guidance ('Run it for each leveling phase (e.g. levels 12, 28, 45, 65, 90)') and routes the agent to the alternative for a different need ('For damage and survival numbers use evaluate_build'). It also ties scope to a sibling by noting these are 'the same rules export_build enforces'.

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

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

Annotations only cover the safety profile (readOnlyHint=true), but the description goes well beyond: it enumerates the per-variant output (damage, kill times, survival, life/ES, resistances, attribute shortfalls, verdicts), the delta against the first variant, best-for-clearing/bossing/survival verdicts, the 2-4 variant bound, and a platform limitation (Windows only for now). That is substantive context an agent cannot get from the structured fields.

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?

A single front-loaded paragraph that leads with the verb and scope; the e.g. list of comparison scenarios is slightly long but each example adds discriminative value. The return-value and platform notes are compact and earn their 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 tool with a very large nested schema and no output schema, the description supplies the missing return-value picture (per-variant metrics, deltas, best-for verdicts) as well as the variant count bound and platform constraint. Nothing an agent needs to invoke it correctly appears to be missing.

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?

Top-level schema coverage for the single 'variants' parameter is reported as 0%, so the description must carry the load; it does so by explaining that each variant is a full build with the same fields as evaluate_build plus a label, and that variants usually differ only in a few areas. It stops short of explaining the 'label' semantics used in the per-variant output comparison, but the nested field descriptions fill most remaining gaps.

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 (calculate variants and compare) plus the resource (builds), and explicitly anchors the variant format to evaluate_build, so an agent can distinguish it from the single-build sibling without opening either schema. The named use cases (two-handed vs one-handed, two ascendancies, with/without a key unique) make the purpose unambiguous.

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 concrete conditions for use (comparing 2-4 variants that share most fields and differ in weapons/items/passives/skills/ascendancy) and implies the alternative by referencing evaluate_build's fields. It does not explicitly state when NOT to use it (e.g. use evaluate_build for a single build), so it falls just short of full routing guidance.

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

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

With only readOnlyHint in annotations, the description adds meaningful behavior: results are ranked by the game's own recommendations first then tag matches, each result explains its rationale, and lineage supports are flagged as rare/expensive drops. That's real value beyond the annotation, though it doesn't describe output shape or result limits.

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?

Three short sentences, front-loaded with the core function followed by ranking behavior and one caveat. No filler or repetition of the name.

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?

No output schema exists, and the description notes each result 'explains why,' partially compensating. For a read-only lookup with a 4-param schema, an agent has enough to call it correctly; only return-format detail is thin.

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 75% and documents gemId, prefer, and includeLineage individually. The description adds interpretation the schema lacks: the 'game's recommendations first, then tag matches' ordering clarifies what 'prefer' actually does, and the lineage cost note explains why includeLineage matters.

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 resource (support gems) and its relation to the input (gems that can support a given skill), plus the ranking logic. This is clearly distinguishable from siblings like search_skills and gem_details, which operate on skills/gems rather than supports.

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 implies you use it after identifying a skill to find its supports, but it never states when to prefer this over siblings (e.g. suggest_extras) or any prerequisites. Usage is inferable from context rather than explicit.

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

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

With no annotations, the description carries the burden and does well: it discloses browser opening, downloadable Build Planner files per phase, conditional behavior when the Path of Building engine is available, and a human-confirmation requirement. It omits where files are written and any permission/file-overwrite implications.

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 the outcome, then the artifact list, then parameter guidance. It is dense and long but almost every clause maps to a real output section or schema relationship, so little is wasted.

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 an 18-param, deeply nested tool with no output schema and no annotations, the description conveys what gets produced and how the key nested inputs relate. Gaps remain around the simpler required scalars, but an agent has enough to build a valid call.

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 only 33% with 18 params, so the description must compensate, and it does: it explains passivePlan's provenance (plan_passive_tree, id + takeAtLevel), that phases split it by level, that phases.passives is only for respecs, and that gear slots use stat_priorities names. Many top-level required params (name, class, summary, leagueStart) still go unexplained, but the high-risk nested ones are covered.

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 artifact ('Write a full build guide as a local web page and open it in the player's browser') and enumerates the page's contents, making it unmistakable versus siblings like evaluate_build or plan_passive_tree. An agent can distinguish the generator role immediately.

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?

'Use after planning; ask the player first' gives clear sequencing and a consent gate. It doesn't name which sibling produces its inputs by name (plan_passive_tree is only referenced indirectly via passivePlan), but the context is otherwise explicit.

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

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

readOnlyHint=true already declares this is a non-destructive read, so the safety profile is covered by annotations. The description adds the useful behavioral detail that results include cache location and per-file load/check state, which mild-compensates for the absent output schema, but it says nothing about the shape of the result, whether files are listed exhaustively, or what 'whether it loaded' looks like on failure.

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?

A single tight sentence with no filler, and the most useful content (cache location) is front-loaded. Slightly under-specified rather than over-long, but nothing in it is waste.

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 zero-parameter read-only diagnostic with no output schema, describing the three things returned (location, last-checked time, load status) supplies most of what an agent needs to interpret the result. It could note what constitutes a stale/failed state, but the 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?

The tool takes no parameters, which is the baseline-4 case; there is nothing for the description to disambiguate. The description correctly implies the call is unconditional and takes no arguments.

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 names the resource (game data cache/status) and enumerates the specific content reported: cache location, per-file last-checked timestamps, and load success. It is clear enough to distinguish from every sibling (which are build/analysis tools), but it is written as a noun phrase describing return content rather than stating the operation, so the 'what it does' verb is implicit (report/inspect status) rather than explicit.

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?

There is no when-to-use guidance, no mention of what a stale or failed load implies, and no routing to or away from any sibling tool. The agent must infer that this is a diagnostic call to check data freshness before running build operations.

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

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

readOnlyHint=true already covers the safety profile, yet the description adds substantial behavioral context beyond it: default budget-gear assumptions, resistance capping at level 65+, connector passives being auto-filled, "Numbers are estimates: assumed gear and heuristic bands, not guarantees", the Timeless-jewel limitation, and the Windows-only constraint. This is exactly the extra context the annotations cannot carry.

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?

Every sentence carries real information (no filler), and the output content is front-loaded. But it is a single dense ~350-word paragraph with no grouping, which makes it hard to scan for a 22-parameter tool where the setup/extras options could have been structured. Information-dense yet structurally taxing.

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 very complex 22-param tool with no output schema, the description effectively describes the return payload (damage vs normal/boss, seconds to kill, hits survived, life/ES/resistances, verdict band, goalCheck, setupGaps, damage-type breakdown). Combined with the tiered level 65+ rules and estimate caveat, an agent has enough to call it correctly.

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?

At 73% schema coverage the schema documents most params, but the description still enriches several: it explains what `terms`/`defence` do to the assumed rares, that `gear: "none"` disables gear, that `items` slot-by-slot replace assumed gear ("jewels too"), and what `gearTier`, `anoint`, `helmetInstill`, `socketables`, `amuletSkill`, `flasks`/`flasksActive` and `weaponSwap` do. It leaves `avoid`, `ascendancy*` and `mainSkill` unaddressed, so it is above baseline but not exhaustive.

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 opens with a precise verb+resource: it returns "real numbers from Path of Building's calculation engine for a planned build at a character level", and then enumerates exactly what is computed (damage, time-to-kill, survivability, resistances, verdict band). It also routes the agent away to a specific sibling ("To compare options side by side, use compare_builds"). An agent can tell what this does 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?

It gives clear context for use, naming the alternative (compare_builds) and tying inputs to build_intake ("With `goals` (from build_intake)"). However it never states when NOT to use it versus evocative siblings like check_build, optimize_build or suggest_extras, so the guidance stops short of full exclusion criteria.

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

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

With no annotations, the description carries the full burden and does well: it discloses that a file is written to a specific game folder, that confirmation is required first, and that a failure mode returns contents for manual saving. It omits overwrite/reversibility semantics and any permission requirements, so not quite 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 main action is front-loaded, followed by the confirmation rule and fallback, which is good ordering. The trailing enumeration of twelve gear slots is verbose and would be better expressed as a schema enum, costing a point on conciseness.

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 mutation/export tool with no annotations and low schema coverage, the description covers the critical behaviors an agent needs: where it writes, that it asks first, and the manual-save fallback. It lacks overwrite explanation, but is largely complete for correct invocation.

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 only 30%, so the description must compensate. It usefully enumerates the twelve legal gear slots (the schema's 'slot' has no description) and explains level ranges for skills/supports and take-at-level for passives, but leaves name, class, ascendancy, description, and overwrite unaddressed.

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?

Specific verb+resource: 'Write the finished build as a .build file into Path of Exile 2's BuildPlanner folder.' It clearly names the artifact, destination, and in-game pickup point, which distinguishes it from siblings like create_build_guide or evaluate_build.

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 clear operational context and a key precondition ('Ask the player before writing') plus a well-defined fallback ('If the game folder isn't found, the file contents are returned to save manually'). It doesn't explicitly name an alternative tool or state when-not to use it, so it falls short of a 5.

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

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

readOnlyHint=true is already declared, so the safety profile is covered, yet the description still adds real behavioral context: results include distances from the class start and that ascendancy's nodes, and listAscendancy returns every node with stats. It omits any statement about result limits or pagination behavior.

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-loads what is returned, then the class/ascendancy distance behavior, then terms with examples, then the listAscendancy escape hatch. The long term-example list is dense but earns its place by demonstrating acceptable term granularity.

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 6-param tool with no output schema and half its parameters undocumented, the description covers the important query paths but leaves limit and includeJewelSockets unexplained and says nothing about response size or ordering.

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 only 50%, and the description usefully explains class, ascendancy, terms (with concrete examples) and listAscendancy semantics, including the terms-required-unless-listAscendancy rule. However, limit and includeJewelSockets remain undocumented in both schema and description.

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?

Specific verb (find) plus a precise resource scope: notables, keystones and ascendancy notables whose text matches the build's scaling stats. It reads as a keyword-driven passive search, distinguishable in spirit from plan_passive_tree, though no sibling is named outright.

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?

States two clear modes and their conditions: supply terms to match passive text, or set listAscendancy to enumerate an ascendancy's nodes with no terms needed, and explains why (to see all 8-point options). It lacks explicit guidance on when to prefer this over siblings like plan_passive_tree.

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

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

readOnlyHint=true already covers the safety profile, and the description adds real value beyond that: it discloses returned fields (full current mods, level requirement, drop locations), explains the bossDrop field's cost implication, and clarifies it returns no prices. It stops short of any pagination or result-count behavior, so not 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?

Purpose, guidance, and the alternative-tool rule are front-loaded in the first sentences. The trailing slot enumeration is bulky but functional as an enum substitute; it earns its place, though the list does lengthen the entry notably.

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 no output schema, the description carries the return-shape burden and does so by naming the fields returned and stating the absence of prices. The main gap is unaddressed 'avoid'/'limit' parameters, but the core contract for calling this tool correctly is 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 coverage is only 40% (terms and maxRequiredLevel documented), so the description must compensate. It does enrich slots by enumerating valid slot values (schema has no enums) and clarifies terms semantics, but 'avoid' and 'limit' are left entirely undocumented in both places.

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 (find) and resource (unique items) and scopes it to 'mods match what the build scales', which is far more than restating the name. It also explicitly separates itself from the pricing siblings ('No prices here'), so an agent can tell it apart from item_prices and trade_links.

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 an explicit routing rule ('For a price, use trade_links') plus a decision heuristic for budget builds (prefer common uniques, treat bossDrop: true as expensive). It names the alternative tool and the condition that selects it, leaving little to inference.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. With no output schema, the description carries the return-value burden and does so well by enumerating the returned dimensions (tags, skill types, level 1/20 behavior, Spirit cost, attribute weighting, weapon requirements, support family, recommended supports), which is real added context.

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?

One dense enumerating sentence plus a short imperative. Front-loaded with the resource, no filler, and every listed field is load-bearing given the absence of an output 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 single-param read-only lookup with no output schema, the description supplies the missing return contract and the exact-identifier requirement. It could be more complete by clarifying behavior when the name is ambiguous (e.g., name collides across gem types) or not found.

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% and the single parameter already documents 'Exact gem name, e.g. "Herald of Ash", or gemId'. The description's 'Pass the exact name or gemId' restates the schema rather than adding format resolution rules, so baseline 3 applies.

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 resource (one skill/spirit/support gem) and enumerates exactly what is returned, which lets an agent distinguish it from a search or list tool. It stops short of naming search_skills or compatible_supports as alternatives, so the boundary against the overlapping 'recommended supports' sibling is left implicit.

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 closing line ('Pass the exact name or gemId') gives invocation guidance, but there is no statement of when to reach for this tool versus search_skills (broad discovery) or compatible_supports (support matching). Usage is implied by the verbosity of the field list rather than stated.

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

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

Annotations already declare readOnlyHint and openWorldHint, and the description adds real context beyond them: the source (official Currency Exchange), freshness (last full hour), denominations (Exalted Orbs, Divine Orbs for expensive items), and that prices are trade-derived estimates. It omits any rate-limit or pagination/return-shape detail, keeping it short of 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?

Three sentences, each earning its place: scope of items, unit/estimation semantics, and the explicit exclusion pointing to the alternative. The most decision-relevant routing cue is front-loaded alongside the resource.

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 two-parameter query with no output schema, the description supplies item scope, price units, and the key sibling exclusion. Return shape (list vs. map, per-item fields) is left implicit, but that is the only meaningful gap for a tool this simple.

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 the schema already documents both names and league. The description adds item-name examples but no syntax, limits (50 max), or league-default detail beyond what the schema states, making the baseline 3 appropriate.

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+resource (current prices for stackable items) and enumerates the covered categories (currency orbs, runes, soul cores, essences, etc.). It also names the sibling it is not (trade_links for uniques/rares), so an agent can distinguish it without opening another 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?

Explicitly routes the agent: this tool is for exchange-traded stackables, while uniques and rares must use trade_links. It also scopes the data source and time window (official Currency Exchange, last full hour), leaving little to inference.

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

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

readOnlyHint=true already establishes this as a safe read, and the description adds useful context beyond that: it is static reference data whose 'Level ranges come from quest area levels', i.e. a derived lookup table rather than live character state. No auth, mutation, or rate-limit concerns are implied, consistent with the annotation, though pagination/ordering behavior is not mentioned (not relevant for a 0-param static table).

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?

A single dense sentence, front-loaded with the resource name and followed by the enumerated payload. Every clause carries information needed by the agent given there is no output schema, though the long comma-heavy list is slightly harder to scan than a short bulleted structure would be.

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 no output schema and no parameters, the description carries the full burden of describing what comes back, and it does so thoroughly (phases, ranges, checkpoint, passives, Spirit, gem level, quest rewards). It is complete enough to call correctly; only the concrete return shape/field names are left unspecified, which is a minor gap for a static reference table.

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?

The tool takes zero parameters, so per the rubric the baseline is 4. The description correctly implies a parameterless reference lookup with no input filtering.

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 names a specific resource (leveling phases for a league-start character) and enumerates its exact contents — phases, level ranges, checkpoint level, passive points, Spirit, gem level, quest rewards. It also ties itself to the sibling check_build via the 'checkpoint level to run check_build at', which helps an agent place it among the build tools. It stops short of a stated verb ('returns/reference lookup'), but the scope is unambiguous.

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?

There is no explicit when-to-use, when-not-to-use, or alternatives guidance. Only the phrase 'for a league-start character' implies context, and the check_build mention implies a downstream workflow step, but nothing tells the agent whether to prefer this over create_build_guide, evaluate_build, or plan_passive_tree.

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

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

readOnlyHint=true already tells the agent this is a safe read with no side effects, so the safety burden is covered by annotations. The description contributes only the shape of the payload (ascendancies plus starting attributes); it says nothing about filtering, ordering, or size of the result set.

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?

A single compact phrase with no padding, and the key content ('playable classes') leads. It is a fragment rather than a sentence, but nothing is wasted.

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 no-argument reference-list tool whose annotations cover the safety profile and which has no output schema, the description gives an adequate sketch of what comes back. Only the return format (structure, whether ascendancy data is nested) is left unspecified.

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?

The tool accepts zero parameters, so there are no semantics to explain and the schema fully describes the input. Baseline for a parameterless tool.

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 names a specific resource (playable classes) and enumerates the scope of what is returned (released ascendancies, starting attributes), which is clearer than a bare 'List classes'. It does not differentiate itself from any sibling, but none of the siblings overlap meaningfully with class/ascendancy reference data.

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?

There is no statement of when to reach for this tool versus siblings like evaluate_build, build_intake, or stat_priorities. Usage is only inferable from the name and the fact that it takes no parameters.

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

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

Adds substantive behavioral context that annotations do not carry: runtime of 10-40 seconds, that it is a best-effort search with estimated numbers rather than a guaranteed optimum, the acceptance constraint (no loss of EHP/max hit within 2%, resistances still capped), and a platform limitation (Windows only). readOnlyHint already covers the safety profile, so this is genuine added value.

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 the core action and the change categories, then the return shape, then timing/caveats. Three dense sentences with no filler, though the enumeration of change types and result keys runs long enough that a reader must parse carefully; a bulleted split would read faster.

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?

Given 25 parameters, nested objects and no output schema, the description compensates by naming the return keys (damage, survival, spiritSkills, combined) and explaining what each contains, plus cost, variance and platform limits. An agent can decide whether to call it and interpret the result without further sources.

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 76%, so the schema does most of the work, but the description adds real meaning: it maps the change categories to the `kinds` enum values (support swaps, notables, Spirit, anoint), ties `objective` to boss DPS vs clear DPS vs both, and explains that passive picks report point cost and fit against free points. Parameters like `avoid`, `maxEvaluations` and `terms` get no description-level elaboration.

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 (tries candidate changes to a Path of Building build and keeps what measurably helps) and enumerates the exact change categories it searches: support swaps, notables, Spirit skills, anoint. This makes it clearly distinct from evaluate_build (measure) and suggest_extras without opening any 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?

Explicitly names the sequencing: 'Use it after the first evaluate_build, and again after applying changes,' which routes the agent relative to the sibling that measures the build. It stops short of saying when NOT to use it (e.g. before a baseline evaluation exists, or when the caller wants a quick single check), so it isn't a full when/when-not/alternatives statement.

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

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

Annotations only declare readOnlyHint=true, so the description usefully adds behavioral detail beyond safety: the result minimizes point count, orders points sensibly, reports the character level for each point, and includes ascendancy pathing limited to 8 points. It still does not describe the response shape or how infeasible/blocked paths are handled.

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?

Dense but front-loaded: the core operation comes first, followed by the ascendancy add-on and the input-format note. The phrase 'Also paths the ascendancy nodes (8 points)' is slightly clipped, but no sentence is wasted.

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 no output schema, the description correctly carries the burden of describing what comes back (an ordered, level-annotated path). Five parameters with only two required leave ascendancy and targetLevel under-explained, but the essential contract for calling the tool is 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 coverage is 60%, and the description compensates by explaining that passives may be supplied by key, id, or exact name, which is not in the schema. It also clarifies the ascendancy pathing intent for the ascendancy parameters, though it never mentions the targetLevel budget or its default of 90.

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 gives a specific verb and resource: build a minimal-point path from the class start to chosen passives, ordered sensibly, annotated with the level each point becomes available, plus an ascendancy path. That is far more than a restatement of the name. It does not explicitly contrast with siblings like find_passives or optimize_build, so it falls just short of 5.

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?

There is no statement of when to call this versus alternatives such as find_passives (search) or optimize_build (tuning). The implied workflow of first finding passives then planning them is left for the agent to infer. Only the input-format note ('by key, id or exact name') hints at a prerequisite.

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

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

readOnlyHint=true already covers the safety profile, so the bar is lower. The description adds real behavioral value by enumerating the fields each result contains (gemId, tags, skill types, description, weapon requirements, earliest level, uncut-gem/item origin) and by spelling out how each filter class behaves.

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?

Purpose is front-loaded, followed by filter semantics and routing. The long 'useful terms' enumeration is dense but functional as a value hint; otherwise every sentence earns its place with no redundancy.

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 no output schema, the description compensates by describing the result fields, and it covers filter behavior and sibling routing. Only minor gaps remain (e.g. limit/pagination behavior), but the definition is complete enough to invoke correctly.

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 high (86%), setting a baseline of 3, but the description meaningfully refines the key filters: it clarifies that require terms must all match tags/types/name, text words must all appear in the description, and prefer only affects ranking. The 'useful terms' list additionally helps the agent choose valid filter values.

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 verb and resource ('Find active and spirit skill gems') and scopes it by the four search axes (gem tags, skill types, name words, description text). It explicitly distinguishes itself from sibling tools gem_details and compatible_supports, so an agent can route without opening a 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?

It clearly explains the three filter modes (require vs text vs prefer) and routes to alternatives: 'Use gem_details for one gem's full details and compatible_supports for its supports.' It gives strong context for use but stops short of explicit when-not-to-use conditions.

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

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

readOnlyHint=true already covers the safety profile, and the description adds genuinely new behavior: itemLevel causes each mod to show the best tier rollable at that level plus the end-game tier, and a defence baseline is always included with resistances always present. It does not mention pagination or output shape limits, but for a read-only lookup the added behavioral detail is solid.

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 the core behavior, then progressively adds parameter guidance. It is dense rather than padded. The long slot enumeration is tedious but earns its place by supplying the valid string values that the schema does not enumerate.

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 no output schema and only 50% schema coverage, the description carries the burden well: it describes the return structure (ranked mods per slot, defence baseline), and the effect of the key optional parameters. The only notable gap is `perSlot`, whose purpose and default are never explained.

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 50%, so the description meaningfully compensates: it explains what `terms` mean (words from mod text, with many examples), what `avoid` does, what `defence` produces, the itemLevel tier behavior, and enumerates the valid slot names. Only `perSlot` (the result count, max 20) is left undocumented in both places.

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 specifically what is returned: for each gear slot and jewels, ranked random modifiers that the build scales, plus a defence baseline. The verb+resource is implicit (it computes/lists stat priorities) but the output is described concretely enough that an agent knows what it gets. It does not explicitly differentiate itself from siblings like evaluate_build, but the subject matter (per-slot mod priorities) is distinct.

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 usage guidance for parameters ('Use `avoid` to rule out mods, e.g. ["attack"] for a caster', 'Give `itemLevel` for leveling advice'), which implies when the tool is useful. However, there is no statement of when to choose this tool over siblings such as evaluate_build or optimize_build — selection guidance is left to inference.

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

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.

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

Annotations only declare readOnlyHint=true, so the description carries most of the burden and delivers: it never contacts the trade site, mods are searched at 80% of value by default, cheapest first, unrecognised mods surface in 'leftOut', and the player must open the links themselves. It doesn't describe link lifetime or format, but the added context is substantial for a link-generator.

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 the core purpose and scoping constraint, then efficiently branches rares vs uniques. Dense with parentheticals but nearly every clause carries unique information; only the 80%-default explanation and 'share the links' advice overlap slightly in intent.

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 3-param tool with no output schema and sparse annotations, the description covers purpose, both usage modes, the side-effect constraint, and the leftOut return behavior. Minor gaps remain around link expiry and whether both 'rares' and 'uniques' can be combined in one call, but nothing blocks correct invocation.

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 33%, so the description must compensate. It explains strictness's default behavior (80% of mod value) which the schema leaves bare (only 0.1-1 bounds), and clarifies that 'slot' accepts a slot, item class, or base type. league default is already in the schema and is not repeated, which is appropriate.

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 precise verb+resource: it produces links to pre-filled trade-site searches. Crucially it disambiguates from data-fetching siblings by saying it 'never contacts the trade site', so an agent knows it returns URLs, not prices. This distinguishes it from item_prices and find_uniques.

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?

Explicit branching guidance: use 'rares' with slot/item class plus mods for rare searches, use 'uniques' with names for unique searches. It even points to sibling tools (evaluate_build, stat_priorities) as sources for the mods to supply, which is exactly the routing an agent needs.

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