Everloot: WoW Forever data

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, non-open-world), and the description adds substantial behavior beyond them: evidence tiers with confidence rules (three agreeing installs for observed facts), build stamps for unconfirmed game-file facts, lore caveats, and the disclosure that further-reading links are search URLs and nothing is fetched. It also documents a degradation mode ('when Everloot's public player data is not connected, the observed layer is unrecorded, not empty'), which is exactly the kind of context annotations cannot convey. It stops short of describing ordering or truncation behavior when the limit caps results.

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 in the first clause, followed by evidence types, then routing guidance — a sensible order. It is dense but almost every clause carries distinct information; the tier-definition sentence is long and could be split for readability, which keeps it from a 5.

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?

An output schema exists, so return structure needn't be restated, and the description still explains what each returned piece carries (claim, source URL, licence, date). For a citation-oriented retrieval tool, nothing an agent needs to call and interpret it correctly is 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?

Schema description coverage is 100%, and both parameters are documented there (question with length bounds and spelling guidance, limit with default 8 and range 1-25). The description does not add syntax or format meaning for either, aside from implying that the question drives which evidence layers are consulted. Baseline 3 applies since the schema does the work.

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 opening sentence names a specific verb and resource ('returns the evidence behind a question about WoW: Forever') and immediately states the downstream use (so an answer can cite it). It enumerates the evidence types returned, which makes it easy to distinguish from siblings that return entities rather than citations.

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 routing: 'Use it for questions that need citations, such as why, where or how many', then names two alternatives — search_knowledge for finding a record by name and item_page/npc_page/quest_page for one entity's agreed facts. This gives both positive and negative selection 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?

Annotations already declare this a safe, idempotent read, so the bar is low; the description still adds real behavior: data comes from player-uploaded auction scans, a day only becomes public after 3 installs scanned that item on that realm, copper values are medians, and missing data is reported explicitly rather than silently. That provenance, privacy-threshold and aggregation context is exactly what annotations cannot convey.

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 what is returned, then the aggregation rule, then sibling routing, then data source and error behavior. Dense but nearly every clause carries information; the realm/itemId sentence is the one place it repeats structured data.

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?

An output schema exists so return shape needn't be described. Given that, the description covers provenance, the publication threshold, units, sibling alternatives, and explicit error reporting — nothing an agent needs before calling is 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?

Schema coverage is 100%, so both parameters are already documented, and the description's 'Realm is the realm's name; the item id is the game's' largely restates the schema text. It adds only a light cross-reference ('as item_page takes it'), so baseline 3 is right.

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: 'Returns the day-by-day price history of one item on one WoW: Forever realm.' It immediately bounds scope (one item, one realm) and distinguishes itself from the closest siblings by naming them.

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: 'Use it for how a price moved over time; use market_value for today's market value, minimum buyout and units listed, item_page for the item itself, and vendor_page for vendor prices.' Both the when-to-use and the alternatives with their selecting conditions are given.

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, idempotentHint, non-destructive, and non-open-world, so the safety profile is covered. The description adds genuinely new behavioral context: the data's provenance and reliability caveat ('found in game files, unconfirmed, with the build'), which an agent should surface when answering. It also pre-empts a follow-up by noting trait effects live on the linked class page, though the parenthetical is slightly garbled by the repeated 'from the game files'.

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 tool's output scope, then usage routing, then the provenance caveat, so the most decision-relevant content comes first. It is slightly over-stuffed — 'from the game files (found in game files, unconfirmed, with the build)' repeats itself and could be tightened to one clause.

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?

Annotations cover safety, an output schema covers return shape, and the description still supplies what structured fields cannot: the data's unconfirmed provenance and where trait effects are documented. Nothing an agent needs in order to call this correctly or interpret the answer is 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?

Schema description coverage is 100% and the schema already documents both parameters, including the faction default ('Without it, both.'). The description's 'Narrow to one faction' merely restates that, and it adds no syntax or format detail for the required class argument beyond what the schema provides. Baseline 3 applies when the schema carries the parameter burden.

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 ('Lists which races can be one class in WoW: Forever, on which faction') and enumerates what is returned (race's racial traits, name, active or passive). The bidirectional framing ('whether a race can be a class, or which races a class is open to') makes the tool's purpose unambiguous 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?

Explicitly routes the agent: 'use talent_tree for the class's talents, and population for how many play it', naming two sibling tools and the condition that selects each. It also states the narrowing behavior ('Narrow to one faction') so the agent knows how to constrain results.

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 cover read-only, idempotent, closed-world safety. The description adds valuable provenance behavior: data becomes public after 3 installs agree, 'owned is unknown, not empty' when no upload exists, and missing data is reported explicitly. These are behavioral traits beyond what annotations capture.

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 front-loaded and each sentence earns its place: purpose, data provenance, disambiguation from other tools, usage guidance, edge case, data source, and error handling. There is no redundant wording or 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 an output schema present, the description need not explain return values. It covers the tool's behavior, data-source caveats, and edge-case failure modes, which is complete for a two-parameter collection comparison.

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 schema already documents both parameters with clear descriptions. The description reinforces that 'owned' refers to what the ownerInstallId uploaded, but adds no new syntax, format, or constraint beyond what the schema provides. Baseline 3 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?

The description opens with a precise verb and resource: 'Returns what one install still misses in one collection, against what that install uploaded as owned, grouped by source.' It explicitly distinguishes itself from sibling completion_progress and disclaims being a Blizzard profile or copied catalog, so an agent can identify its purpose 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 explicitly says 'Use it for which items of a collection a player is missing; use completion_progress for achievements, reputations and titles,' giving both a positive use case and a named alternative. No inference is left to the agent.

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?

Goes well past the readOnly/idempotent annotations by disclosing the trust model (an entry is public after 3 installs on different addresses report it identically), the privacy gate (requires the collection sharing choice plus a verified grant), and the degraded answer when that gate fails. It also names the upstream source (Everloot public player data) and states that missing data is reported explicitly rather than silently omitted.

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 output content before the trust, privacy, and exclusion sentences, and each sentence carries distinct information. It is on the dense side with several long clauses, but little is genuinely 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?

With an output schema present, the description need not explain return shape, and it covers the remaining gaps an agent would need: privacy precondition, degraded-state behavior, data source availability, and error reporting. Nothing essential for a correct call is left implicit.

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% and both parameters are documented there, so the schema carries the parameter burden. The description adds only an implied scoping statement ('one install's characters'); it never mentions ownerInstallId or the optional per-character key and its fallback behavior.

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 a concrete set of resources: achievements with the most criteria met, reputations nearest the next standing, titles known, and quests finished in a chain, all scoped to one install's characters. It explicitly negates two confusable readings ('Not a Blizzard profile read and not a copied catalog'), so an agent can place it 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?

Gives a positive routing rule ('Use it for what a player is closest to finishing') plus two named alternatives with their distinct conditions: collection_gap for missing collection items and guild_board for a guild's kills. Those are the two siblings an agent would most plausibly pick instead.

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 read-only, idempotent and non-destructive behavior, so the safety profile is covered. The description goes well beyond them by defining settled vs confirmed, the denominator rule, the three-install reporting threshold, the dating of scoped totals, and the [?] convention for unknown values. What it does not disclose is anything about result volume or how large a response can be for all-zones queries.

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 purpose is front-loaded, but the middle section is dense with compressed jargon ('settled over expected, with confirmed over expected beside it', 'come separately dated and measured') that takes effort to parse. Several clauses about output formatting could be tightened for a tool with only two optional parameters.

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 burden of explaining return semantics, and it does so for the metric definitions, unknown handling, and data dating. It is still unclear what the overall response shape looks like (whether zone/type breakdowns are nested or flat), which leaves a gap for a reporting tool.

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%: both parameters carry descriptions and the type enum is fully enumerated, so the schema already does the explanatory work. The description adds no syntax or semantics beyond the schema for 'zone' or 'type' (the 'per field' dimension has no corresponding parameter). Baseline 3 applies when the schema carries the load.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Counts how much of WoW: Forever's database is settled or confirmed') plus the exact dimensions of aggregation (per zone, per type, per field). It also explicitly separates itself from the entity/page tools at the end, so an agent can tell it is a metrics tool rather than a fact lookup.

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 it for how complete the database is for a zone or type; use the page tools for the facts themselves' gives a clear when-to-use and a contrasting alternative. The alternative is named as a category ('page tools') rather than a specific sibling, so routing is slightly less precise than it could be.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description adds substantive data semantics: the five ranking boards, the install-counting rule (counted from 3 installs; missing means not counted, not zero), the "projects are ranked, never people" caveat, and GitHub fact freshness timestamps. These are non-obvious behaviors an agent could not recover from 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?

Purpose and board list are front-loaded, then details, then sibling routing, then the limit note — a sensible order. It is dense but every clause carries information; only the closing "limit caps the projects listed" is slightly redundant with the 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?

With an output schema present, the description needn't explain return shape, and annotations cover safety; the remaining burden is scope, ranking semantics, and data caveats, all of which are covered. Nothing an agent needs to select or call this tool correctly is 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?

Schema coverage is 100%, so the baseline is 3, but the description expands the enum values with plain-language meaning ("most installed, rising, most active, freshest release or best maintained") and restates limit's capping role plus the .toc interface-number condition behind forever_ready_only. It adds genuine interpretation beyond the bare enum labels.

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?

Opens with a specific verb and resource ("Lists the Forever addons and tools in the community registry") plus the ranking dimension, and immediately distinguishes itself from everloot_plan and recent_changes by name. An agent can tell what this returns 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?

Explicitly states the use case ("which Forever addons exist and how maintained they are") and routes the agent to two named siblings with the conditions that select them: everloot_plan for Everloot's own features, recent_changes for Blizzard's posts. Nothing 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real provenance context beyond them: player-observed relations require 3 agreeing installs and carry install count and last-seen, while game-file relations are unconfirmed and tied to a specific build. It does not discuss result volume beyond what the limit parameter implies, 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?

Opening sentence is front-loaded with the core action and output shape; subsequent sentences add provenance, id convention, and sibling routing in a logical order with no filler or repetition.

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 an output schema present the description needn't explain return values, and it covers purpose, provenance, id conventions, and alternatives. Minor gap: it doesn't hint at how relation groups are ordered or what happens when no relations meet the 3-install threshold.

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 kind, id, rel, limit and direction are all documented in the schema including the from/to semantics. The description only adds that ids are the game's own as returned by page tools or world_map_near, which is a small but useful clarification — baseline 3 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?

Opens with a specific verb and resource plus scope: 'Lists every typed relation of one entity, in both directions, grouped by relation.' It immediately makes clear it is a relation graph lookup, not an entity fact lookup, which separates it from item_page/npc_page without needing 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?

States the triggering question ('where something comes from or what something drops, sells or rewards'), then names the excluded alternatives and when to prefer them: page tools for one entity's own facts, world_map_near for proximity. Explicit when-to-use and when-not-to-use routing.

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 readOnly, idempotent, closed-world, non-destructive behavior, so the safety profile is covered. The description adds genuinely new context: it is the authoritative tracker that ships with the site, holds no game data, and requires no account. It does not describe result shape, but an output schema exists to carry that.

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 the tool returns, then scope, then alternatives, then invocation constraints — a logical order with no filler. The clause "as the tracker that ships with the site holds it" is slightly awkward phrasing, a minor deduction.

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, read-only lookup with an output schema, the definition covers purpose, content categories, scope exclusions, sibling routing, and invocation requirements. Nothing an agent needs in order to call it correctly is 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?

Zero parameters, so the baseline is 4. The description's "Takes no arguments and needs no account" merely restates the empty schema but usefully assures the agent that no auth or input assembly is 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?

States a specific verb and resource ("Returns the Everloot feature catalogue") and enumerates the categories returned: live, next, waiting, and page-shape-only reference sites. It is immediately distinguishable from siblings like search_knowledge and ecosystem_projects.

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 bounds scope ("Use it only for questions about Everloot itself, such as whether a feature exists") and names the correct alternatives for out-of-scope questions: search_knowledge or answer_sources for game facts, ecosystem_projects for community addons. Both when-to-use and when-not-to-use are 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description productively adds behavior beyond them: long arrays are truncated at 48 rows, arrays are returned in pages with a nextOffset cursor, and the field pointer changes the shape of the returned text. The remaining gap is error/not-found behavior and what happens when the id is malformed or exceeds maxLength.

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?

It is a single dense paragraph with the core purpose front-loaded and no filler sentences. However, the pagination rule is stated twice ("pages of up to 48 rows with nextOffset" and "A long array in a whole record is cut at 48 rows"), and the final sentence "The text block is the same JSON as a string" is terse enough to be ambiguous on first read.

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 rich annotations and an output schema, the description need not explain return structure, and it correctly focuses on the id-source contract, field projection, and pagination. Minor gaps remain around failure modes and how the field projection interacts with limit/offset for non-array values, but nothing essential for a correct call is 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?

Schema description coverage is 100%, so the schema already documents all four parameters, which sets the baseline at 3. The description adds some meaning beyond it, notably that a field pointer returns the value as JSON in text and that arrays paginate via nextOffset, but it does not clarify limit/offset interaction in more depth than the schema's own descriptions.

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 plus resource and scope: "Returns one knowledge record in full, by the string id a search result gave," then enumerates the returned parts (title, full text, URL, metadata). It explicitly distinguishes itself from get_entity ("which gives only an excerpt") and ties its input to search results, so an agent can tell it apart from siblings 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 concrete invocation guidance: "Use it after search, or with a search_knowledge id as a string," naming the two upstream tools that produce valid ids. It also names the excerpt-only alternative get_entity. It stops short of stating when not to use it (e.g. versus the page-specific siblings like quest_page or npc_page), so it is clear but not fully exclusionary.

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 readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds genuinely new behavioral facts beyond them: matching is case-insensitive, matches are exact-full-name only, multiple records can share a name across kinds, and empty hits are a definitive negative rather than an error. It does not mention result caps or ordering, which is the remaining gap.

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 behavior and the case-insensitive exactness are front-loaded, followed by usage routing, then the collision caveat and the empty-result meaning. Every clause carries distinct information with no repetition of the 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?

An output schema exists, so return-shape explanation is unnecessary, and the description instead covers the interpretive edges an agent actually needs: cross-kind duplicates and empty results. For a two-parameter lookup with full schema coverage, nothing material is 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?

Schema coverage is 100% and the enum description already explains each kind's provenance, so the baseline is 3. The description goes slightly beyond the schema by explaining why the kind parameter matters (names collide across kinds, so check each hit's kind) and by reinforcing case-insensitive matching semantics for name.

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 ("returns the records whose full name matches exactly, case-insensitively") and immediately bounds the scope with the optional kind narrowing. It also names the sibling it is not (search_knowledge), so an agent can distinguish it without opening either 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 states the selecting condition explicitly ("use it to disambiguate when you know the exact name and want the id without a ranked search") and routes the alternative cases to a named sibling (partial names, keywords, questions -> search_knowledge). Both the when and the when-not are covered.

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?

Beyond the readOnly/idempotent/non-destructive annotations it discloses real behavior: null-hit instead of an error on unknown ids, array results paged at up to 48 rows with nextOffset as the continuation token, and bad JSON pointers answering with the keys that would have worked rather than failing. It also notes that game-file records carry build info and when player uploads confirm them.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and return shape, then alternatives, then the field/paging variant - a sensible order. It is dense but not padded; the only mild redundancy is explaining the field pointer both as a value-reader and again in the trailing error sentence.

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?

An output schema exists, so return values need not be spelled out, yet the description still covers paging, continuation, and both error-softening behaviors an agent must plan around. Nothing needed to call this correctly is 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?

Schema coverage is 100%, so the baseline is 3, but the description adds the relationship the fields have to each other: field reads one value instead of the excerpt, an array result is paged with nextOffset pointing at the next offset. The example pointer (/questIds) and the lenient bad-pointer behavior are meaningfully beyond the schema text.

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?

Opens with a concrete verb+resource: 'Returns one knowledge record's summary, by the numeric id'. It enumerates what comes back (title, excerpt, URL, source, licence, date) and explicitly contrasts with fetch ('for the whole text, call fetch with the same id as a string'), so it is distinguishable from its nearest sibling without opening either 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 when-to-use ('Use it to read one hit again by its id'), names the alternative and the condition that selects it (fetch for the full text), and covers the field-pointer variant with its own trigger. It also sets expectations for the miss case ('an id no record has returns a null hit, not an error').

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?

Beyond the read-only and idempotent annotations, it explains important behavioral constraints: each install's ledger is kept apart, missing categories read as unrecorded rather than zero, other gameplay gold is unrecorded, and the income-to-peak gap is never characterized as bought gold or a ban. It also discloses the Everloot public-data dependency and explicit missing-data reporting.

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 dense but front-loaded with the return value, then proceeds through data caveats, usage boundaries, alternatives, and source limitations. Every sentence carries useful information for interpreting or invoking the tool.

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 lookup with two fully described parameters, rich annotations, and an output schema, the description supplies the remaining semantic context an agent needs. Its account of unrecorded data, per-install separation, and unavailable characters is complete for this tool's 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?

The schema has 100% description coverage for both required parameters, so character and realm are already documented. The description reinforces that only one character is queried and that ledger data is kept per install, but it adds no syntax or formatting detail 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?

The description states a specific return: peak and current gold plus recorded income and spending events for one character. It clearly distinguishes the tool from guild_board and market_value, so an agent can identify its purpose 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 explicitly says to use this for one uploaded character's own gold history, states that it cannot look up a character that never uploaded, and names the sibling alternatives for guild loot and prices. This covers both when to use it and when to use something else.

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 readOnly/idempotent/non-destructive, yet the description adds substantial context beyond them: a figure is public only after 2 verified officers agree, characters may opt out, hidden guilds produce no response, and missing data is reported explicitly rather than silently omitted. The one residual gap is that pagination or response size for large rosters is never mentioned, which is a moderate concern for a roster-returning tool.

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?

It is front-loaded with the payload and earns most of its length on caveats, but 'kills per instance and its rank' is introduced in sentence one and then re-explained at length in sentence three, and the officer-board definition is restated twice. Dense multi-clause sentences could be tightened without losing meaning.

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 an output schema present, return shape needn't be explained, and the description still covers provenance, privacy opt-outs, empty/hidden guild outcomes, and the caveat that average item level reports how many members were measured with no combined score. An agent has everything needed to call this correctly and interpret the result.

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% and both parameters already document 'as guild_search gives it', so the description adds no syntax, format, or casing guidance beyond the schema. Baseline 3 applies since the schema does the heavy lifting.

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 first sentence names the resource (one guild's board) and enumerates the specific payload: roster, bosses killed, loot awarded, raid attendance, average item level, kills per instance and rank. It is immediately distinguishable from guild_search (name lookup) and guild_rankings (cross-guild comparison), which are named explicitly.

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 routing is given: 'Use it for one guild's own board; use guild_search to find a guild's exact name and realm, and guild_rankings to compare guilds in one instance.' It also states when-not conditions — hidden guilds return no answer, unpublished guilds return an empty officer board plus the public part.

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 cover the safety profile (readOnly, idempotent, non-destructive, not open world), and the description adds substantial unannotated behavior: the tie-breaking chain (bosses killed, then earliest latest kill, then name), what counts as a kill (2 matching installs, timed at earliest report, or an officer board post which carries no time), how the boss list is derived, and explicit reporting of missing data. This is far beyond what the annotations convey.

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 ranking rule, then the kill definition, then the excluded interpretations, then routing to alternatives — a sensible order. It is dense but nearly every sentence carries a rule; the parenthetical qualification about officer-published kills having no time is slightly heavy for the space it takes.

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 ranked listing with a full input schema, output schema, and complete annotations, the description supplies the ranking logic, kill derivation, tie handling and data source. Nothing needed to call it correctly or interpret the ordering is 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?

Schema description coverage is 100%, including the exact semantics of instanceMapId (map id from a search_knowledge hit of kind instance, omit for newest raid with a kill), realm and faction scoping, and limit bounds. The description adds only indirect meaning, explaining that the boss list is scoped to the given instance, but does not clarify parameters beyond the schema, so the 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 verb (ranks) and resource (every guild with an agreed kill in one instance) plus the exact ordering criteria. It immediately separates itself from siblings by naming guild_board and guild_search as different tools, so an agent can pick this one without reading the other schemas.

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 says 'Use it to compare guilds' progress in one raid or dungeon' and then routes the agent elsewhere: guild_board for one guild's own board, guild_search to find a guild. It also rules out a plausible wrong expectation ('no score, no rating and no total across instances'), which is a when-not-to-use signal.

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 cover the safety profile (read-only, idempotent, non-destructive, closed domain), and the description goes well beyond them: it discloses the three separate inclusion triggers (two member installs agreeing on a boss, an officer-published board, or a character sighting), hidden-guild suppression, and the crucial 'unrecorded, not zero' semantics when player pages are disconnected. That last point materially changes how an agent should interpret results and is not inferable from annotations or 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?

Content is front-loaded: purpose and return fields come first, then inclusion rules, then the routing instruction. It is dense but nearly every clause carries operational meaning; the sentence about reading Everloot's public data and explicit missing-data reporting is somewhat repetitive with the adjacent 'unrecorded, not zero' sentence.

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?

An output schema exists, so return values need not be formally specified, yet the description still orients the agent to the notable fields and their caveats. For a two-parameter, read-only lookup it covers matching semantics, coverage conditions, exclusions, and result interpretation, leaving nothing an agent would need before calling 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 100%, so both parameters are already documented, yet the description adds the constraint that the query matches guild names only and never member names, which prevents a common misuse. The 'starts with what you typed' phrasing reinforces prefix rather than substring matching, though it does not add limits or defaults 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?

The opening sentence names a specific verb (finds) and resource (guilds) with precise matching semantics: prefix match on guild name. It also enumerates what comes back (realm, faction, observed character count, agreed boss-kill count and date), which no sibling tool does. An agent can distinguish it from guild_board and guild_rankings without opening either 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 an explicit routing rule: use this to resolve a guild's exact name and realm before calling guild_board, and use guild_rankings for a ladder. It also states a hard exclusion (hidden guilds are omitted), which is the kind of when-not guidance most definitions omit.

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 readOnly, idempotent and non-destructive, so safety is covered. The description adds genuine context not in the annotations: data is derived from game files and is 'unconfirmed, with the build,' and results are ids only because names come from player uploads. It does not note the default/limit behavior when a class query returns many ids, which the schema covers but the description could have surfaced.

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 mode descriptions and sibling routing are front-loaded and every clause carries information. Minor friction from the parenthetical 'found in game files, unconfirmed, with the build,' which reads awkwardly and slightly duplicates the opening phrase.

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?

An output schema exists, so return shapes need not be spelled out. The description covers all three call patterns, the id-only limitation, the data provenance caveat, and the two sibling alternatives — sufficient for an agent to invoke it correctly on the first try.

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; the description earns above it by explaining the conditional semantics the schema cannot express — no arguments yields the whole tree with counts, `item` yields that item's category path, and `class` with optional subclass/slot/quality yields item ids. Only `limit` is left unexplained, and the schema handles 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?

States a specific verb and resource ('Lists item categories from the game files') and immediately enumerates the dimensions covered: class, subclass, slot and quality. It clearly separates itself from item_page (names and stats) and entity_relations (provenance), so an agent can discriminate 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?

Explicit routing is present: 'Use it to place an item in its category or to list a category; use item_page for an item's name and stats, and entity_relations for where it comes from.' The three invocation modes (no args, item, class+optional filters) tell the agent exactly which call shape maps to which question.

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 cover the read-only, idempotent, closed-world safety profile, but the description adds substantial behavior the annotations cannot convey: the 3-agreeing-installs consensus rule, withholding of contested values, per-number provenance (installs, build, last seen, corpus date, method), [?] markers with reasons, and exclusion of baseline rows and player names. It also notes it reads Everloot public player data when connected, which is real operational 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?

Front-loaded with the purpose before the data-quality rules and sibling routing, and every sentence carries distinct information. Some phrasing is dense and hard to parse on first read ('the newest build that 3 installs reported'), which trims a point but not for 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?

An output schema exists, so return values need not be spelled out, yet the description still covers what an agent must know to interpret results: consensus rules, contested-value withholding, provenance fields, and missing-data markers. For a one-parameter read tool this is complete.

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% and the single itemId parameter is fully documented in the schema, including where to source it (drop row, entity_relations, search_knowledge extId). The description only restates 'by item id' and adds no format, range, or resolution guidance beyond the schema, so the 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 verb and resource (returns one Forever item's page by item id) and then enumerates the payload: agreed name, drop frequency, map pins, and player-reported armor/block/DPS/stats/resistances. That specificity makes it immediately distinguishable from siblings like entity_relations or item_categories.

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 says 'Use it when you have an item id' and then routes three adjacent needs to named alternatives: market_value for price, entity_relations for drop/sale relationships, item_categories for class and slot. Both the trigger condition and the alternative set are stated, not inferred.

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 a safe read-only, idempotent operation, but the description earns credit for adding provenance ('full auction scans players started and uploaded'), a data-eligibility threshold (3 distinct reporter addresses), the aggregation method (median of reporters, weighted mean over 14 days, thin-day and outlier exclusion), a 60-day historical window, an auth/connection note ('Reads Everloot's public player data when connected'), and an explicit missing-data contract.

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 what is returned, then the methodology, then the sibling routing; every sentence carries information. The middle methodological sentences are dense and long, which costs a point on immediate scannability, but none of the content is filler given how non-obvious the aggregation rules are.

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?

An output schema exists, so return-value shape need not be explained, and the description still covers data provenance, eligibility thresholds, aggregation rules, the time window, the connected-data dependency, and a failure contract. Nothing an agent needs in order to call this correctly or interpret its output is 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?

Schema coverage is 100% and both parameters are fully described in the schema (realm as the game-shown name, itemId as item_page takes it), so the schema already carries the burden. The description only reinforces the 'one realm, one item' cardinality, which is a marginal addition over structured data — 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?

The opening sentence names a specific verb (Returns) and enumerates the exact returned quantities — market value, minimum buyout, historical value, units listed — scoped to 'one item on one WoW: Forever realm'. This is unmistakable against siblings like auction_history or vendor_page, which are named explicitly.

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 an explicit routing rule: 'use it for what an item is worth now; use auction_history for the price over time, and vendor_page for vendor prices.' Both alternatives and the condition that selects them are stated, so no inference is required from the agent.

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 readOnly/idempotent/non-destructive, yet the description still adds real behavioral context: data-agreement thresholds (three installs must agree), the rule that a pin does not require a drop, that no copied spawn list is included, the Everloot public-data provenance, and that missing data is reported explicitly rather than silently omitted.

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 return content, then usage, then alternatives, then caveats — a sound ordering with no filler sentences. It is dense, packing several rules into semicolon-linked clauses, which is efficient but slightly harder to scan than discrete sentences.

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?

An output schema exists, so return shape needn't be spelled out, yet the description still tells the agent what categories of data come back and how trustworthy they are. For a single-parameter read tool, nothing an agent needs in order to call it correctly is 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?

Schema coverage is 100% for the single npcId parameter, so the schema already carries validation and sourcing detail. The description only restates "by NPC id" and adds a loosely matching note about where ids come from, so the 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 verb and resource ("Returns one Forever NPC's page by NPC id") and then enumerates what the page contains: agreed name, agreed map pins, and loot windows not yet in drop rates. It is clearly distinguishable from siblings like vendor_page and item_page, which the description names explicitly.

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 trigger ("Use it to name or place an NPC when you have its id") plus where the id comes from (a search_knowledge hit, a drop row, or entity_relations). It then routes four alternatives to their proper tools: vendor_page for sales, item_page for a single drop rate, entity_relations for typed links, world_map_near for surroundings.

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 read-only, idempotent, closed-world safety, but the description adds substantive behavior the annotations cannot convey: the 3-install-report publication threshold, that an empty public object reads as a measured zero, that names appear only after 3 agreeing installs, the data source (Everloot public player data), and explicit reporting of missing/unavailable data.

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 return contract, then thresholds, then routing — a sensible order with no filler. The opening sentence is dense and carries several clauses, which slightly reduces scannability 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?

The tool returns a rich composite payload, and an output schema exists so return shape needn't be restated. The description still supplies the interpretive rules (thresholds, measured-zero semantics, name agreement) plus data provenance and missing-data behavior, leaving no material gap 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 100% and the single parameter is fully documented in the schema, including a concrete path example (/database/objects/1731). The description only echoes 'entry id', adding no format or sourcing detail beyond the schema, so the 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 verb and resource — 'Returns one game object's page ... by its entry id' — and enumerates the concrete object types (chest, herb, ore vein, fishing pool) so an agent knows the domain without opening the schema. It also names the two siblings it is not (npc_page, item_page).

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 routing: 'Use it for gathering nodes and containers; use npc_page for creatures, and item_page for every source of one item.' That covers both when-to-use and when-to-use-a-different-tool, which is rare and valuable.

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 readOnly/idempotent/non-destructive, but the description goes well beyond them: it discloses suppression thresholds (10 characters, 3 installs, 3 addresses), rounding to the nearest 5, complementary suppression, and that no character names are ever returned. It also states that when census data is unavailable the answer says so rather than returning zero, which is exactly the kind of quirk an agent must know to interpret results.

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 counting verb, then disclosure rules, then window semantics, then the sibling routing. Dense but no sentence is filler; even the privacy clauses carry decision-relevant information for interpreting suppressed counts.

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?

An output schema exists, so return-value structure need not be explained. With suppression, rounding, window labelling, missing-data behavior, the no-argument default, and the sibling split all covered, an agent has everything needed to call this correctly and to read its output honestly.

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 schema already documents race, class, window, and faction. The description adds meaning on top: it frames the parameters as grouping/scope selectors (each character counts once), clarifies the default overview behaviour with no arguments, and states that every answer reports its window (last 7 days vs. since launch).

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?

"Counts how many characters play each race, class, race and class, faction and level band" states a specific verb plus the exact grouping dimensions, and narrows the domain (WoW: Forever, Everloot addon census). The final line routes the agent to the sibling tool class_races, so it is distinguishable from siblings 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?

"Use it for how many play a race or class; use class_races for which races can be a class" gives an explicit when-to-use and a named alternative with the condition that selects it. "With no arguments, the overview, most played class first" further tells the agent the zero-arg case is valid and what it returns.

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 cover read-only, idempotent, non-destructive, but the description adds real behavioral context the annotations cannot: the 3-install/3-price agreement threshold, the fallback rule for starting rank, that uncovered ranges are left as gaps rather than invented, and that Everloot public player data is read when connected. This is well beyond structured fields, though it does not mention pagination or result size.

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 and every sentence carries information, but the middle section is a dense run-on chain of agreement rules that takes effort to parse. Slightly tighter phrasing of the consensus rules would improve scannability without losing content.

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?

An output schema exists, so return shape need not be explained, yet the description still summarizes the three outputs and explains the provenance and gap behavior. For a read-only analytical tool with three simple parameters, nothing an agent needs to call it correctly is 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?

Schema description coverage is 100% and each parameter already carries range and default documentation, so the schema does the heavy lifting. The description only restates the two-skill-level framing and adds no format or edge-case detail (e.g. what happens when fromSkill equals toSkill).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Names a specific verb and resource ('Returns a leveling path for one Forever profession between two skill levels') and states the payload: steps, summed reagents, and cost. It also explicitly distinguishes itself from recipe_thresholds and market_value, so an agent can route 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?

Gives a direct when-to-use ('how to level a profession from one skill to another') plus two named alternatives with the exact condition that selects each. Nothing about tool selection 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?

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so safety is covered. The description still adds genuine context the annotations cannot: the 3-install agreement rule for facts, the 'no copied quest text' constraint, the Everloot player-data dependency when connected, and explicit reporting of missing data. It stops short of describing paging or partial-result shape, but that is largely covered by the 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?

Purpose is front-loaded and almost every clause earns its place (provenance rule, licensing constraint, alternatives, missing-data behavior). It is one dense block rather than broken into scannable pieces, and the alternative-routing sentence packs two tools together, which slightly slows parsing.

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-parameter read tool with rich annotations and an output schema, the description covers everything an agent needs: what it returns, where the id comes from, what data sources are involved, and how gaps are surfaced. Return-value details are correctly left to the output schema.

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 questId parameter is already documented with its source (entity_relations or the extId of a search_knowledge hit of kind quest). The description restates that provenance rather than adding format or range detail beyond the schema, so the 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?

The description opens with a specific verb and resource: 'Returns one Forever quest's page by quest id', and enumerates the payload (title, level, giver, turn-in, rewards). It is immediately distinguishable from siblings like npc_page, item_page, and entity_relations.

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 states the entry condition ('Use it when you have a quest id, from a search_knowledge hit or entity_relations') and explicitly routes two adjacent needs elsewhere: answer_sources for story/chain questions and entity_relations for rewards. Both the when and the when-not are named.

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 a safe, idempotent read, so the description focuses on genuinely additive behavior: results are truncated excerpts with source links, and a build's timestamp is Everloot's first-seen time rather than Blizzard's release time. That timestamp caveat is the kind of subtlety an agent would otherwise misinterpret.

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 return contents and ordering, then caveats, then usage routing — a sensible priority order with no filler. The closing sentence about filter and limit is somewhat redundant with a fully documented schema, costing a bit of tightness.

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 annotations and an output schema present, the description still covers what an agent needs: content types, ordering, the excerpt-only constraint, the build-time caveat, and sibling routing. Nothing material is left to inference for a three-parameter read tool.

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 two of three parameters are enums the schema fully documents, so the baseline is 3. The description's 'filter picks one kind; limit caps the entries' restates the schema rather than adding format or interaction detail, and the game parameter is not mentioned at all.

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 ('Returns the newest official changes for WoW: Forever') and enumerates the three content types returned: blue posts, hotfix posts, and new game builds. That enumeration makes it distinguishable from lore/knowledge siblings 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 states the use case ('what Blizzard changed or posted lately') and names two alternatives with the conditions that select them: answer_sources for lore and game facts, ecosystem_projects for community addons. Both when-to-use and when-not-to-use are covered.

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 annotations already declare a read-only, idempotent, non-destructive, closed-world operation. The description adds meaningful provenance: ranges are inferred from observed trade-skill window colours rather than guessed exact numbers, a recipe appears only after three installs agree, and costs appear only when every reagent has an agreed price.

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 behaviour is front-loaded in the first sentence, followed by provenance, usage, filtering and scope. Every sentence contributes, though the provenance sentence is dense and could be split for readability.

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?

It covers scope, data provenance, the three-install agreement threshold, optional filtering and the sibling alternative. An output schema exists, so return-value detail is not required. Minor gaps remain around behaviour for unknown professions or coverage limits across professions, but the definition is complete enough to call 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 100%, so both parameters are already documented in the input schema. The description reinforces that recipe is a partial-name filter and that profession is singular, but adds no syntax or format detail beyond the schema, so the baseline of 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?

The description gives a specific verb and resource: it returns where one profession's recipes turn yellow, green and grey as skill ranges. It explicitly distinguishes itself from the sibling profession_path, which gives a step-by-step route between skill levels, so an agent can choose without opening schemas.

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 states the use case directly: how long a recipe keeps giving skill points. Then it names the alternative, profession_path, and the condition that favours it. It also explains that the list can be narrowed with part of a recipe name.

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 read-only, idempotent, closed-world, non-destructive, so the safety profile is covered. The description adds result-shape behavior the annotations cannot: a cap of 10 results, per-result id/title/URL for citation, and that the text block duplicates the JSON as a string. It does not discuss ranking or empty-result 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 the tool is and what it returns, then the routing rule. Slight redundancy between "It is the same search as search_knowledge" and the follow-up instruction about which clients should use search_knowledge, but both reinforce routing rather than repeating verbatim.

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?

Covers the three things an agent needs here: what it does, when to pick it over search_knowledge, and what the response contains (count cap, per-result shape, duplicated text block). Output schema existence means return values need no deeper explanation.

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?

There is a single parameter with 100% schema description coverage, so the schema already explains the query string, including that question words are ignored. The description adds nothing about the query param, so the baseline of 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 verb and resource ("Searches the knowledge base") plus the contract it implements, and explicitly distinguishes itself from search_knowledge. An agent can route between this and search_knowledge without opening either 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 an explicit selection rule: use only when the client expects the search/fetch pair, otherwise call search_knowledge. Both the positive condition and the exclusion are stated, and the fetch sibling in the list is implicitly the pair partner.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context: exact-name matches rank first, every hit carries id/kind/source/licence/date, and game-file hits flag whether player uploads confirm them. It stops short of describing pagination or how to page past `limit`, which keeps it off 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 scope, then the ranking rule, then the chaining/alternative guidance — a sensible priority order with no filler sentences. The closing remark about 'search' being the same search in the ChatGPT connector shape is useful but slightly awkwardly appended.

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 4-parameter search with an output schema, the description covers scope, ranking, result metadata, the id-to-get_entity follow-up and all relevant sibling alternatives. The only soft spot is the phrase 'or to fetch as a string for the whole text', which names the sibling but leaves the fetch mechanics to that tool's own definition.

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 enum groupings for `kind`, the version values and the limit bounds are already fully documented in the schema. The description restates that searching happens by 'names, keywords or a question' and that question words are ignored, but adds no syntax or formatting guidance beyond it. Baseline 3 is appropriate when the schema carries the parameter burden.

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 ('Searches WoW lore, Forever reference data and the game-file catalogs...') and enumerates the covered record families. It explicitly separates itself from get_by_name, answer_sources, get_entity and the connector-shaped 'search' sibling, so an agent can route without opening schemas.

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 workflow ('find a record from a name or a topic, then pass the hit's id to get_entity') plus two named alternatives with their selecting conditions: get_by_name for known exact full names, answer_sources when cited evidence is wanted instead of records. Exclusions are stated, not implied.

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 cover read-only, idempotent, non-destructive, closed-world, so the description correctly spends its words elsewhere: it discloses that output includes per-tree point counts, minimum holding level, and every problem in plain words, and that 'Nothing is dropped silently' — implying partial-result reporting rather than hard failure. It also flags data provenance ('found in game files, unconfirmed'), a caveat no structured field carries. Slightly short of 5 because it doesn't say what distinguishes a fatal invalid-code path from the reported problems.

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 verb and resource, then the trigger and alternative. The first sentence is a long accumulation of parentheticals and clauses that takes effort to parse, but each clause (input forms, output contents, error reporting) carries information the agent needs.

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 decode-and-validate tool with an output schema already covering return shape, the description supplies everything else an agent needs: accepted input forms, what the result contains, that problems are reported rather than thrown, the sibling alternative, and a data-confidence caveat.

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 one fully described parameter, the baseline is 3, and the description earns above it by explaining the internal structure of the code string (class, spec, build, payload segments) and that a calculator link with #plan= is accepted — meaning the schema's generic 'share code, or a link that carries one' does not provide. No other parameters exist to document.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Names a specific verb ('Decodes') and resource ('an Everloot talent share code'), spells out the accepted input formats (EL1-<class>-<spec>-<build>-<payload> or a link with #plan=), and explicitly contrasts itself with the sibling talent_tree. An agent can distinguish it from every other sibling 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 an explicit trigger ('Use it when given a share code or a calculator link') and an explicit alternative with its condition ('use talent_tree to read the trees themselves'). This is the when/when-not/alternative structure at full strength.

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 cover the safety profile (readOnly, idempotent, non-destructive, not open-world), so the description spends its space on genuinely new behavior: data provenance and an explicit reliability caveat ('found in game files, unconfirmed, with the build'), the id-namespace guarantee that node ids match share-code ids, and the side effect of builds=true adding the Everloot team's starter builds explicitly labelled as the team's and not observed. That is meaningful context an agent could not infer from 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?

It is a single front-loaded paragraph where scope and routing come first, and every clause carries information. The parenthetical '(found in game files, unconfirmed, with the build)' is awkwardly redundant with 'from the game files', and the builds labelling is stated twice (description and schema), costing a point.

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?

An output schema exists, yet the description still characterizes the return shape enough to plan around it (node fields, level thresholds, linked calculator, optional builds section). Combined with explicit sibling routing and the unconfirmed-data caveat, an agent has everything needed to call this 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 100%, so the baseline is 3; the description still adds value by explaining what builds actually returns beyond the boolean (share code and page, and the team-not-observed caveat) and by clarifying the tree narrowing behavior. The class parameter is only restated, which keeps 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: it 'Returns the WoW: Forever talent trees of one class from the game files', and it enumerates the payload (nodes, talents, ranks, grid position, prerequisites, row gate, level thresholds). It also names the sibling tools it is not (talent_plan, class_races), so an agent can route 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 gives explicit when-to-use guidance ('read or explain a class's trees') and explicit alternatives for adjacent tasks: talent_plan for decoding a share code, class_races for race eligibility. It also states the scoping decision for the optional tree parameter ('Narrow to one tree by name; without it the answer holds every node of every 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 cover the read-only, idempotent, closed-world safety profile, yet the description still adds real substance: the 3-install corroboration rule, the fact that two agreed prices both stay listed, 'No copied catalog', the Everloot public-data source, and explicit reporting of missing data. The only shortfall is that return shape and error surface are gestured at rather than specified, though an output schema exists.

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 definition and the agreement rule, then routed to alternatives in one compact sentence. Slightly wasteful that the trailing id sentence restates what the schema already declares.

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-parameter lookup with an output schema, the description covers what is returned, when rows appear, data provenance, and data-gap behavior. An agent needs nothing else 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?

Schema coverage is 100% and the schema's own description already says the id is the NPC id used by npc_page and sourced from world_map_near or entity_relations. The description's line 'The id is the same NPC id npc_page takes' largely repeats that, adding only mild cross-tool reassurance, 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 verb and resource ('Returns the goods one Forever vendor sells') plus the keying parameter and what each row carries ('copper price players saw'). The sibling distinction against npc_page, entity_relations and market_value makes the boundary 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?

Explicitly says what to use it for ('what a vendor sells and at what price') and names three alternatives with the condition that selects each: npc_page for location, entity_relations sold_by for item-to-seller, market_value for auction prices. Nothing 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?

Goes well beyond the annotations (which already cover read-only, idempotent, non-destructive). It discloses data provenance and thresholds: entrances from game files with a 3-install confirmation, player-observed NPCs/vendors/treasures requiring 3-install agreement, suppression of possibly-unreleased zones, and that public player data is read when connected. These are behavioral facts an agent could not infer from 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?

Front-loaded with the core capability and tight throughout, but slightly redundant at the close, where 'Use it for what is near a spot' restates the title's premise before naming alternatives. Every other sentence carries new information.

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 an output schema present, return-shape explanation is unnecessary, and the description covers the remaining gaps: anchor modes, coordinate convention, provenance and reliability thresholds, and sibling routing. Nothing needed to invoke it correctly is 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?

Schema coverage is 100%, so baseline is 3. The description adds the additive semantics the schema only hints at: zone+x+y and npcId are alternative anchors ('instead of'), and the 0-100 coordinate convention is reinforced. It does not explain the interaction between radius/limit and each list, so it stops short of 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?

Names a specific verb and resource ('Lists the entrances, NPCs, vendors and treasures near a spot'), states ordering ('nearest first') and units ('straight-line distances in yards'). An agent can distinguish this from npc_page or vendor_page without opening either 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 both positive and negative guidance plus named alternatives: 'Use it for what is near a spot; use npc_page, vendor_page or entity_relations for one entity's own facts.' It also spells out the two valid input modes (zone+x+y or npcId), which is exactly the decision an agent must make before calling.

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