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 declare readOnlyHint=true, so the description must carry the rest; it discloses the return contents (damage, kill times, survival, life/ES, resistances, attribute shortfalls, per-variant verdicts, delta vs first variant, best-for categories) and the platform constraint ('Windows only for now'). No output schema exists, and these disclosures fill that gap well, though depth/limits of each metric are not detailed.

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 constraint, then examples, then return summary, then platform note. Four sentences with little waste, though the examples sentence is dense and slightly long.

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 a very deep nested schema and no output schema, the description covers the essentials: what to pass (2–4 full-build variants with labels), what differing fields typically are, what comes back, and the OS limitation. An agent can call it correctly without opening the schema, though edge behavior (e.g. what if variants share no fields) is unstated.

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 single parameter is a variants array whose structure the description explains: each variant is a full build, carries a label, and variants 'usually share most fields and differ in weapons, items, passives, skills or ascendancy'. It also delegates field detail to evaluate_build, which is a useful pointer given the deep nested 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?

Specific verb (calculate and compare), specific resource (2–4 build variants), and explicit differentiation from the sibling evaluate_build by stating variants use 'the same fields as evaluate_build'. The three concrete examples (two-handed vs one-handed, two ascendancies, with/without a unique) make the tool's identity unmistakable.

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 contexts for use via examples and the 2–4 variant constraint, and implicitly routes agents to evaluate_build for single builds. It stops short of an explicit 'when not to use this' or naming which conditions favor it over siblings like optimize_build or check_build, so not a full 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?

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 full burden and does well: it discloses externally visible side effects (writes a local web page, opens the browser), a conditional behavior ('When the Path of Building engine is available'), and a consent requirement. It stops short of stating overwrite behavior, file location, or error handling.

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 front-loaded sentence stating the action and artifact, followed by an accurate enumeration of contents, then two compact sentences for usage and parameter wiring. Dense but every clause maps to a real feature or schema field; no 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 19-parameter, deeply nested tool with no output schema and no annotations, the description covers the artifact and the critical plan-to-phases relationship but leaves roughly two-thirds of the parameters (class, leagueStart, goals, gearTier conflicts, defence, terms) to a sparse schema. Adequate but visibly incomplete at this complexity.

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 low (37%), but the description compensates for the highest-value parameters: passivePlan is identified as the plan_passive_tree output (id + takeAtLevel), phases are said to split it by level, phase-level passives are only for respecs, and gear slots are tied to stat_priorities names. Many other parameters (name, class, leagueStart, summary, weapons, defence, terms) remain unexplained 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 and artifact ('Write a full build guide as a local web page and open it in the player's browser'), then enumerates the guide's contents precisely (phases, checks, zoomable passive tree, downloadable Build Planner). The artifact is clearly distinct from siblings like export_build 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 explicit timing and a consent gate: 'Use after planning; ask the player first.' That tells the agent this is a terminal step requiring confirmation. It does not, however, name a sibling alternative (e.g. export_build) or state when NOT to use this tool.

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?

The readOnlyHint annotation only declares a safe read, but the description adds rich behavioral context: it's an estimate not a guarantee, Windows-only, Timeless jewels are unsupported, assumed gear is generated when `items` is absent, missing passives are auto-filled, and the default gear tier logic is explained. These caveats and assumptions go well beyond the annotation.

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 one dense paragraph of roughly 300 words. It is front-loaded with the core purpose, but the mass of detail about gear assumptions, optional features, and limitations is packed into long sentences without structural breaks, making it harder to scan than it needs to 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?

There is no output schema, but the description still details the return values (damage, kill times, survivability, resistances, Spirit, verdict band, goalCheck, setupGaps). For a 22-parameter tool with nested objects, it covers assumptions, caveats, and limitations thoroughly enough that an agent knows what to expect.

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 73%, so the schema already documents many parameters, but the description adds relational meaning: how `terms` and `defence` shape assumed gear, how `gearTier` overrides `goals.budget`, how `items` slots replace assumed gear, and what `socketables`/`anoint`/`amuletSkill` do. Some parameters like `avoid` and `ascendancyPassives` receive no prose explanation, keeping it from a 5.

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 specific verb and resource: 'Real numbers from Path of Building's calculation engine for a planned build at a character level.' It distinguishes itself from siblings by naming compare_builds for side-by-side comparison and referencing build_intake for goals, so an agent can tell which tool to pick.

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 explicitly routes comparison work to compare_builds and explains that `goals` come from build_intake, giving clear context for when to use this tool. However, it does not mention when to prefer check_build, optimize_build, or other evaluative siblings, so the guidance is strong but not exhaustive.

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 the write target, the required user confirmation, and the fallback behavior when the folder is missing (contents returned to save manually). It omits any note on the write/overwrite distinction or success response shape, 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?

Front-loaded with the core action before the caveats, and the confirmation rule is stated plainly. The trailing gear-slot enumeration is long but earns its place by defining valid slot values; overall well structured with minor trailing bulk.

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 11-param, no-annotation, no-output-schema mutation tool, the description covers the essential operational context: what gets written, the confirmation gate, and the folder-missing fallback. It is complete enough to invoke correctly, though return-value and overwrite semantics remain 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 only 36%, so the description must compensate, and it does: it enumerates valid gear slot strings (constraining an otherwise free-text slot param) and explains that passives/supports carry level ranges and gear carries stat priorities per slot. It leaves write, overwrite, name, class, and ascendancy meaning 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?

States a specific verb and resource: writes a finished build as a .build file into the game's BuildPlanner folder. Clearly distinguishable from siblings like list_builds, evaluate_build, or create_build_guide, which don't write in-game files.

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?

Implies usage via 'finished build' and the confirmation step ('Ask the player before writing'), which tells the agent this is a terminal export action. However, it names no alternative sibling or a when-not-to-use condition, so routing relies on 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?

With readOnlyHint=true already declaring the safety profile, the description adds genuinely useful behavior: that results expose 'requires' for ascendancy-gated passives, and that returned keys are valid plan_passive_tree targets. It doesn't cover result shape, ordering, or the limit cap.

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 but written as a dense chain of sentence fragments mixing purpose, term vocabulary, three usage modes, and edge cases. Every clause carries information, yet the lack of separation makes it harder to scan than the content warrants.

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, no-output-schema tool the description covers most invocation paths and hints at the returned 'requires' field and key usability. It still leaves the response payload's overall shape and pagination/limit behavior to inference.

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 67%, and the description compensates well for the important ones: terms are 'words from passive text' with a rich example list, kinds ["small"] semantics, listAscendancy meaning, near/within behavior, and the terms-optional-unless rule. It leaves limit, includeJewelSockets, and ascendancy (bare in both places) unexplained.

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 (notables, keystones, ascendancy notables) and what it filters on (text matching build scaling terms), plus distances from class start. It also links forward to the sibling plan_passive_tree as a consumer of its keys, though it never contrasts itself with search_skills or other lookup siblings.

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 conditional usage: supply class (and ascendancy) for distances, set listAscendancy for all 8-point options, and use kinds ["small"] with near/within for small passives. It even restates the required-parameter rule ('no terms needed' / 'terms optional then'). It stops short of naming when-not-to-use or an alternative tool.

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?

Annotations already establish readOnlyHint=true, so the safety profile is covered. The description meaningfully adds behavior beyond that: results are ordered newest first, each entry indicates whether this tool created it, and guide folders returned are only those this tool made — useful provenance semantics an agent would not otherwise know.

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 compact sentence with the ordering/provenance caveats front-loaded, followed by routing guidance. Nothing is wasted, though the leading noun phrase reads as a sentence fragment and could more directly state the listing action.

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, so the description must convey what comes back; it does so by naming the file names, the newest-first ordering, the creator flag, and the guide folders. That is sufficient for a zero-parameter read tool, with only minor gaps (no mention of whether results can be empty or paginated).

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 there is nothing for the description to disambiguate and the baseline of 4 applies. The description correctly implies a no-argument call by never referencing any input.

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 specific resource (.build files in the Path of Exile 2 BuildPlanner folder) and the secondary output (guide folders this tool created), which clearly separates it from siblings like remove_builds or export_build. The sentence is a noun phrase rather than a verb-led statement, so the listing action is inferred from the title rather than stated outright, but the object of the tool 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?

It gives concrete when-to-use guidance: 'Use before remove_builds, or to find the file names of earlier exports.' That explicitly ties it to a sibling workflow and a lookup purpose. It stops short of stating exclusions (e.g., that it does not filter or search), so it is a strong 4 rather than 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 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?

Annotations only declare readOnlyHint=true, so the safety profile is covered and the description is free to add real behavioral context: a 10-40 second runtime, a platform restriction ('Windows only for now'), and an honesty caveat that it is 'a best-effort search, not a guaranteed best build; numbers are estimates.' It also discloses the acceptance thresholds (within 2%, resistances still capped). It does not describe whether changes persist, but nothing suggests mutation, so no contradiction with readOnlyHint.

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, then the change categories, then the return buckets and caveats. Dense but every clause carries information; the enumeration of output keys is slightly list-heavy but warranted given there is no 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 25-parameter tool with nested objects and no output schema, the description compensates well: it explains the return shape (damage, survival, spiritSkills, combined), the constraints applied to each list, the runtime, and the accuracy limits. An agent knows what it will get back and how long it must wait.

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?

With 25 parameters and 76% schema description coverage, the schema already documents most inputs, so the baseline of 3 applies. The description adds no per-parameter detail beyond implicitly mapping the supported change categories (support swaps, notables, Spirit skills, anoint) onto the `kinds` enum.

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 likely changes to a build in Path of Building, one at a time, and keeps what measurably helps') and enumerates the exact change categories it explores. It also distinguishes itself from the sibling evaluate_build by name, 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?

Gives explicit sequencing: 'Use it after the first evaluate_build, and again after applying changes,' naming the sibling that must run first. It does not state what this tool should not be used for, but the context is otherwise unambiguous.

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 supply readOnlyHint, so the description carries the behavioral burden and does so richly: tie-breaking rules for terms/avoid, onTheWay flagging of notables, ascendancy gating requiring the unlocking node to be present and flagged with the trial, and the extra 8 ascendancy points (2 per trial). This is significantly more than the readOnly annotation conveys.

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 core action is front-loaded before the conditional details about tie-breaking and ascendancy gating. It is a dense single paragraph with some nested parentheticals, but every sentence adds actionable rules rather than 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?

With 8 parameters, no output schema, and only a readOnly annotation, the description covers the important behaviors: ordering, tie-breaking, ascendancy gating, and the level annotation it returns. The main remaining gap is the exact shape of the returned route/level data, though it hints at it.

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 88%, so the baseline is 3, and the description adds real meaning on top: it defines the semantics of order, terms, avoid, ascendancyPassives ordering (2 per trial), and the targetLevel budget ('default 90'). It also notes passives can be passed by key, id, or exact name, which the schema does not spell out.

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 specific verb and resource: it connects the class start to chosen passives and reports the character level at which each point can be taken. It is clearly distinguishable from sibling tools like find_passives, which it names as the way to look up small-passive keys.

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 explains the default ordering ('priority order') versus the 'cheapest' alternative, and explicitly tells the agent how to force a route by listing small passives as targets, including the find_passives call needed to get their keys. It stops short of stating when to prefer this tool over optimize_build or check_build among siblings.

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 destructiveHint=true available, the description adds substantial context the annotation cannot: nothing is deleted, files go to Documents/PoE2 Build Planner/removed/<date>, and the move is reversible. It also discloses the important guard that only files this tool created are touched. This exceeds the annotation's safety profile without contradicting it (moving files out of active use is reasonably 'destructive' even though reversible).

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?

Four short sentences, front-loaded with the action and destination, followed by the reversibility guarantee, the required player confirmation, and the input source. No sentence is redundant.

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 two-optional-parameter tool with no output schema, the description covers everything an agent needs: what is affected, where items go, that the action is reversible, and the prerequisite of asking the player and sourcing names from list_builds.

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%, so the baseline is 3, but the description adds genuine meaning by stating that the file and folder names originate from list_builds. It does not add format or validation detail beyond that, so it improves on the schema rather than merely restating it.

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 (move) on a specific resource (.build files and guide folders), and scopes it tightly with '(only ones this tool made)' and the destination path. It clearly distinguishes itself from siblings like create_build_guide by explaining that it relocates rather than deletes or creates.

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 a precondition ('Ask the player first and name exactly what will be moved') and points to the sibling that supplies input ('File and folder names come from list_builds'). It stops short of an explicit when-not-to-use or naming a reverse (restore) tool, so it is strong but not exhaustive.

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.