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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, so safety is covered. The description adds meaningful behavioral context beyond that: the empty-matches-not-error semantics, the combination-product multiplicity behavior, and the RxNorm naming expectation. It does not discuss rate limits or latency, but those are minor.

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

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

Front-loaded with the core purpose, then structured into use-cases, return semantics, and tool-routing. Slightly verbose across four paragraphs for a 1-param tool, but every section carries distinct value and there is no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Although an output schema exists (so return structure needn't be explained), the description still clarifies the most important semantic detail: one entry per ATC code, with combination products yielding multiple. Combined with naming expectations, failure semantics, and sibling routing, 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% and the schema already documents drug_name as brand or generic with an example. The description reinforces the naming convention (English/US as in RxNorm) and adds the fallback attempt behavior on failure, which goes slightly beyond the schema. Baseline 3 would apply without that extra nuance.

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

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

States a precise verb+resource: look up WHO ATC classification(s) for a drug by name, with a concrete example (metformin → A10BA02). It also explicitly distinguishes itself from the sibling tools atc_lookup and atc_members by naming the input type each expects.

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?

Provides an explicit routing rule: start here when you have a drug name, use atc_lookup when you have a class code, and use atc_members to list drugs inside a class. It also handles the failure case (unrecognized name → empty list, try generic name or rxnorm_search), which is exactly the guidance an agent needs.

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 the safe, read-only, idempotent, open-world profile, so the description needn't restate safety. It adds real behavioral context: what is returned (name + hierarchy level) and the endpoint's limitation that substance-level codes are not exposed. It does not cover error behavior or pagination, but those are minor for a single-code lookup.

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?

Opens with the core action, then a scannable bulleted list of use cases, then the code-length explanation and the boundary note. Every sentence earns its place with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has an output schema, so return values needn't be explained, and the single required parameter is fully documented. Combined with the explicit sibling routing and level taxonomy, an agent has everything needed to invoke 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%, so the baseline is 3, but the description goes beyond the schema by mapping each length to a semantic level (A=anatomical, A10=therapeutic, A10B=pharmacological, A10BA=chemical), giving the agent meaning for the allowed pattern rather than just its shape.

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 (look up) and resource (ATC code) and the output (name and hierarchy level). It explicitly distinguishes itself from the sibling atc_classify by scoping to levels 1-4 and routing substance-level codes elsewhere.

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?

Lists three concrete use cases (resolve to class name, confirm existence, identify level) and names the alternative atc_classify along with the exact condition (7-char substance codes) that selects it. 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 safety (readOnly, idempotent, non-destructive, openWorld), so the description earns credit for adding non-obvious context: that each member carries a substance-level source_atc_code for disambiguation, and that RxNorm's catalog is US-centric while ATC names/codes are international. It does not mention result volume or pagination for large classes, which would be the next useful disclosure.

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 one-line purpose, followed by a scannable bullet list and a closing caveat sentence; nearly every line earns its place. Slight redundancy between 'enumerate all members' and 'explore an ATC subtree at any level', which overlap conceptually.

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 an output schema present, the description supplies purpose, usage contexts, parameter levels, an output field note, and a data-provenance caveat - enough to call it correctly. What is missing is only operational detail such as result size for high-level classes.

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 states the level 1-4 vs level-5 return behavior, so the baseline is 3. The description reinforces this with the 'A10BA' example but adds little syntax or format detail the schema does not already carry.

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

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

Specific verb + resource ('List the drugs (substances) that belong to an ATC class') with a concrete example ('A10BA' -> metformin, phenformin). The subtree/level framing implicitly separates it from atc_classify (drug -> class) and atc_lookup (code -> meaning), 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?

The 'Use this tool to:' block gives three clear contexts (enumerate class members, build mechanism-shared drug lists, explore a subtree). It does not name any sibling as the alternative or state when NOT to use it, so routing against atc_lookup/atc_classify 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 usefully adds that all groups return in one response with no pagination and that the 275 groups come from a bundled local dataset. However, 'Answered locally from the bundled CID-10 V2008; no network call' directly conflicts with the openWorldHint=true annotation, which asserts interaction with an open world of external entities — the description describes a closed, offline data source.

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 and scope, then organized into use-case bullets and a routing paragraph. Slightly verbose (the embedded Portuguese example runs long), but every section carries information and nothing is padded.

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 present (so return values need no explanation), the description still covers scope, all 22 chapters/275 groups volume, no-pagination behavior, data source, error behavior, and sibling routing. 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 coverage is 100% (baseline 3), and the description still adds real meaning beyond the schema: the Roman-numeral mapping (chapter I = 1, IX = 9) and the rejection behavior for numbers outside 1-22. These go beyond the bare 'integer 1-22' in the schema.

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

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

States a specific verb+resource ('Get one CID-10 chapter and its constituent groups') and concretely distinguishes itself from siblings by naming cid10_chapters, cid10_lookup, cid10_search and icd11_chapters with the conditions that select each. An agent can route correctly 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?

Explicit when-to-use bullets (drill from chapter into groups, build hierarchical browsers, find which group contains a range) plus explicit alternatives: use cid10_chapters when the chapter number is unknown, cid10_lookup for a single code, cid10_search for Portuguese text, icd11_chapters for ICD-11. When/when-not and alternatives are all present.

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, and non-destructive behavior, so the bar is lower. The description adds genuinely useful context beyond them: the fixed 22-entry result size and the caveat that CID-10 V2008 has not been updated since 2008, which signals a static dataset. No contradiction with annotations.

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

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

Front-loaded with the core purpose, then a scannable bulleted use-case list, then return caveats. The 'Build a navigable table of contents for downstream tooling' bullet is the vaguest line but is short and does not bloat the definition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter list tool with an output schema already defining the return shape, the description supplies everything an agent needs: what it returns, how many entries, the static-version caveat, and the main use cases.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is no parameter semantics to document. Baseline of 4 applies; the description does not need to compensate for anything.

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 (List) and resource (the 22 chapters of CID-10), plus exactly what each entry contains (code ranges and Portuguese titles). The count '22' and the sample entries make the scope unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The 'Use this tool to' block gives three concrete scenarios (structure overview, code-to-chapter mapping, building a table of contents). It does not explicitly name the obvious alternative siblings (cid10_chapter for a single chapter, cid10_lookup/cid10_search for codes), so the differentiation is implied by 'top-level structure' rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so safety is covered. The description adds genuine behavioral context beyond that: both dotted and undotted inputs are accepted, the canonical display form is returned, and gender/cause-of-death flags may be present. Output formatting is partly covered by the output schema, which caps this at a 4.

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 one-line purpose followed by a tight bulleted breakdown and a closing note on input formats. Some content (dotted vs undotted forms) repeats the schema description, which is minor redundancy but not bloat.

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-only lookup with an output schema and full annotation coverage, the description supplies everything needed: what it returns, accepted input forms, and use cases. Nothing an agent needs 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?

With a single parameter at 100% schema description coverage, the schema already documents the code field, its pattern, and its dotted/undotted acceptance. The description largely restates that same dotted/undotted flexibility, adding little new parameter-level meaning, 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 ('Look up a specific CID-10 code') and scopes it to an exact-code resolution with an example ('I21' → 'Infarto agudo do miocárdio'), which implicitly separates it from the search-oriented sibling cid10_search. It never names that sibling explicitly, so differentiation must be inferred.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The 'Use this tool to:' block gives three concrete triggering scenarios (resolve a code, confirm a category/subcategory exists, retrieve restriction flags), which is clear positive guidance. It stops short of stating when NOT to use it or naming cid10_search / cid10_chapter as the alternative for fuzzy or hierarchical lookups.

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), yet the description adds genuinely non-obvious behavior: diacritic-insensitivity, AND-between-words matching, and the vocabulary-normalization layer (câncer→neoplasia maligna, AVC→acidente vascular cerebral) surfaced via vocabulary_notes in the response. It also states the return granularity (3-char categories and/or 4-char subcategories).

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, then bullets for usage, then matching semantics, then the sibling alternative. Every sentence carries information, though the parenthetical expansion of the CID-10 acronym and the example list make it longer than strictly necessary.

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 needn't be explained, annotations carry the safety profile, and all three parameters are documented. The description supplies the domain-specific matching rules that are the real risk of misuse, leaving nothing an agent needs 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 meaning beyond the schema by explaining what 'categories' and 'subcategories' mean in practice (3-char vs 4-char) and elaborating the query normalization behavior. It adds little on max_results, which the schema already bounds.

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 (search) and resource (Brazilian CID-10), including the language constraint (Portuguese text). It explicitly contrasts itself with icd11_search, so an agent can route between them 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?

The 'Use this tool to:' bullets give concrete usage contexts (SUS/ANVISA, CBCD/USP translation, billing/epidemiology) and name icd11_search as the alternative for the international revision. It does not, however, distinguish itself from cid10_lookup or cid10_chapter, which are equally plausible siblings for code-level or chapter-level lookups.

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/openWorld/idempotent/destructive=false, so the description legitimately adds value by disclosing that unknown ids return an error and that it performs a live GET against the public source (latency/freshness implication). It stops short of describing pagination or caching behavior, so not a full 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-loads the core contract (what is returned) before the routing/companion context, and each sentence carries information. The paragraph on terminology tools is slightly repetitive given the sibling list, but overall it is tight and well ordered.

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?

Output schema exists, so return values need not be explained, yet the description still names the key fields usefully. Combined with annotations covering the safety profile and the description covering provenance, error behavior, and source, nothing an agent needs to invoke 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?

Single parameter with 100% schema description coverage; the schema already says 'Identifier of a document returned by `search`.' The description restates the same provenance constraint rather than adding new semantics such as id format or handling of malformed ids, so it sits at the baseline.

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 full document for an id obtained from `search`,' and enumerates the return shape (id, title, text, url, metadata). It also explicitly distinguishes itself from the terminology siblings, which 'remain the tools for data queries.'

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 precondition ('Only ids returned by `search` are valid') and an explicit exclusion ('The terminology tools ... remain the tools for data queries'). The agent knows both when to call this and which siblings not to call.

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, openWorld, non-destructive), yet the description adds substantial context: limit is a cap not a page, match_score/rank are server-computed, groups clustering is a same-concept signal and its absence is NOT proof of non-equivalence, and searches are English-only.

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, then a bulleted use-case list, then scope/parameter behavior, then language guidance. Dense but every sentence carries actionable information and it is easy to skim.

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 formats needn't be spelled out, yet the description still explains the key output fields (match_score, rank, groups). For a 4-param cross-terminology fan-out tool, 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 coverage is 100%, so the baseline is 3, but the description consolidates the interaction rule ('source is subtracted from targets') and the limit cap semantics in prose, aiding correct invocation. It largely mirrors the schema wording rather than adding syntax beyond it, so it stays below 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?

States a specific verb (find/rank) and resource (equivalent terms across medical terminologies) with explicit scope (ICD-11, LOINC, RxNorm, MeSH). It implicitly separates itself from single-terminology siblings like icd11_search, loinc_search and rxnorm_search, and explicitly routes pt-BR needs to icd11_search/mesh_search/cid10_search.

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?

Provides a 'Use this tool to' list of concrete scenarios (find same concept in other systems, compare representations, support mapping/integration). It also gives explicit exclusions and alternatives: set target_terminologies to narrow, source_terminology to exclude, and use dedicated tools for pt-BR.

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, open-world and non-destructive, but the description adds substantial behavior beyond them: 50-term hard limit with a validation error, dedup of repeated term+domain pairs, per-row error isolation ('one failed lookup does not fail the batch'), needs_review bias, dropped deprecated LOINC codes, and a de-identification requirement before hitting WHO/NLM APIs.

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 a one-line summary, then structured bullets for usage, then behavioral rules. Dense but nearly every sentence carries a rule; minor redundancy in restating the 50-term cap twice and the domain mapping already in 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?

Given the complexity, nested term objects, and presence of an output schema, the description covers everything an agent needs: batch limits, error semantics, match_type scoring rules, why 'glucose' alone fails, and pointer to provenance tools (terminology_versions, per-source provenance blocks). Return values 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 coverage is 100% and the description mostly restates the domain enum mapping that the schema already documents. It does add value on the terms parameter (batching at 50, dedup behavior, English-only search) and on max_candidates (default 3, best-first ordering), but this is elaboration rather than information the schema lacks.

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 (harmonize/map) plus resource (list of free-text clinical terms) plus output shape (ranked candidates with confidence labels). It explicitly positions itself as the batch/building-block counterpart to find_equivalent, so an agent can distinguish it from 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?

Has an explicit 'Use this tool to' list covering the three concrete scenarios (column harmonization, triage, auditable crosswalk), and names when to use alternatives instead: cid10_search for pt-BR diagnoses, validate_codes for existing codes, find_equivalent for one term across all terminologies.

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 annotations: exact result size (28 entries, no pagination), composition (01-26 plus V and X), per-chapter fetch semantics with partial-failure behavior (entry keeps URI and carries an `error`), caching behavior, and official-translation-only guarantee. These are non-obvious operational traits an agent needs.

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

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

Front-loaded with the core action, then bulleted use cases, return shape, and exclusions. Every sentence carries distinct information; nothing is padding.

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 values need not be re-explained, yet the description still covers count, failure modes, and caching. Nothing an agent needs 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% and the schema already documents the language enum, default, and the no-machine-translation rule. The description's `language: "pt"` example and caching note add only marginal value over the schema, 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+resource ('List all ICD-11 chapters (top-level categories) of the pinned WHO release') and immediately scopes it against siblings. An agent can distinguish it from icd11_search, icd11_hierarchy, and cid10_chapters 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 enumerates three use cases (overview, chapter discovery, URI retrieval for drill-down) and a 'When NOT to use' block naming the correct alternatives (icd11_search for diseases, cid10_chapters for CID-10). Routing is fully specified.

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, openWorld). The description adds genuine behavioral context beyond that: blocks return with an empty code and a code_range, and translations return the source's official translation and are never machine-translated. It does not need to explain return shape further since 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-loads the purpose, then a scannable bullet list of uses, then a dense but relevant paragraph on code/uri semantics. Every sentence contributes, though the parameter paragraph is somewhat packed.

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 (no need to describe returns) and annotations carrying the safety profile, the description covers purpose, direction semantics, entity identification, language behavior, and the ICD-10 redirect. Nothing an agent needs 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 description coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema by clarifying that code may be a leaf code or a block range and that blocks arrive as empty-code results with a code_range. The relationship between uri provenance and prior tool calls is also made explicit.

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 ('Navigate the ICD-11 hierarchy to find parent or child entities') and separates itself from siblings like icd11_lookup, icd11_search, and icd11_chapters. An agent can tell immediately this is a traversal tool, not a search or lookup tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The three-bullet 'Use this tool to' list gives explicit contexts (find parents, find children, understand classification structure), and it routes ICD-10 codes away to map_icd10_to_icd11. It stops short of stating when a sibling such as icd11_lookup would be preferable, so it is clear context without explicit exclusions.

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/openWorld/non-destructive, so the description rightly spends its words elsewhere: it discloses that the result is a single entity with no pagination, that an unknown code returns a 'not found' error rather than an empty record, that omitting both code and uri yields a validation error naming both, and that translations are WHO-official and never machine-translated. These are real behavioral facts an agent cannot get from the structured fields.

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

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

Front-loaded with the single-sentence purpose, then bulleted capabilities, then parameter rules, then exclusions. Every sentence carries distinct information; there is no filler or repetition of the annotations.

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 described, yet the description still supplies the cardinality ('single entity, no pagination') and the error contract. Combined with full parameter coverage and the sibling routing, an agent has everything needed to call this correctly on the first attempt.

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 a genuine cross-parameter constraint the schema does not express (required is 0): 'at least one is required; calling with neither returns a validation error naming both.' It also clarifies that `uri` may be 'any URI a previous answer returned.' The code example and the official-translation wording largely restate the schema descriptions, 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?

The description opens with a specific verb+resource+cardinality: 'Get detailed information about ONE ICD-11 entity you already have a code or URI for.' That last clause alone distinguishes it from icd11_search and icd11_hierarchy, which the description then 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?

Provides an explicit 'Use this tool to' list (definitions, coding notes, inclusions/exclusions, titles/synonyms) and a dedicated 'When NOT to use' section that routes three distinct cases to icd11_search, icd11_hierarchy, and map_icd10_to_icd11 with the reason why. 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 declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful behavior: an empty axes list is not an error, and it clarifies that value_count is a count rather than the values. It does not add much beyond what the output schema likely shows.

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 definition of the term followed by bulleted use cases and a clear negative clause. Every sentence earns its place and the structure is easy to scan.

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 summarizes the returned fields and the empty-list edge case. Combined with annotations and full schema coverage, an agent has everything needed 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% for the single parameter, so the baseline is 3. The description adds a concrete format example ("BA00") and confirms the parameter is the ICD-11 stem code, which marginally improves on the schema.

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

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

States a specific verb (List) and resource (postcoordination axes) scoped to one ICD-11 stem code in a named linearization/release. It clearly differentiates from siblings by noting it does not build/validate composites or list values, unlike icd11_lookup/icd11_search.

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 use cases (check accepted axes, required vs optional, single/multi-value counts) plus an explicit 'When NOT to use' section naming alternatives (icd11_search for disease name, icd11_lookup when the list is empty). 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 declare readOnly/idempotent/openWorld/non-destructive, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: results come from WHO official translations and are explicitly 'never machine-translated,' plus a note on the return shape (codes, titles, relevance scores).

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, then scannable bullets, then return info – a sensible structure. Minor redundancy in restating the language/translation behavior that the schema already carries, but nothing is bloated.

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 and full annotation coverage, the description need not detail return values or safety. It covers purpose, use cases, language semantics, and a brief return summary; the only real gap is the absence of sibling routing for a namespace dense with search/lookup alternatives.

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 three parameters well. The description's explanation of `language` (official Portuguese labels instead of machine translation) largely repeats the schema's own description, adding only the concrete pt-BR example.

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 ('Search for medical conditions, diseases... in ICD-11') with an expansion of the acronym. It does not, however, differentiate itself from close siblings like icd11_lookup, icd11_hierarchy, or cid10_search, so an agent must infer the distinction from the name alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The 'Use this tool to' bullets sketch intended scenarios (find codes, search by name/keyword, multi-language lookup), which implies usage. But there is no when-not guidance and no explicit routing versus icd11_lookup or the CID-10/Loinc search siblings, leaving selection 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/openWorld, so the safety profile is covered. The description adds genuinely useful behavior beyond that: it discloses that a valid code with no answer list returns an empty list while an unknown code returns a 'not found' error, plus the score semantics for instruments. It does not discuss rate limits or auth, but those are less critical here.

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

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

Front-loaded with the core purpose, then scannable bullets, then edge-case and routing notes. Slightly redundant between the bullet list and the prose, but every sentence carries information and none is 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 one required parameter, full schema coverage, an output schema, and annotations covering safety, the remaining burden is edge-case and routing disclosure — both handled (empty list vs not-found error, sibling alternatives). Nothing an agent needs to invoke 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 the single loinc_num parameter is fully documented in the schema, so the baseline is 3. The description adds a domain constraint (only codes representing questions with defined answer sets), which is meaningful but really usage guidance rather than parameter syntax.

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: 'Get the list of valid answers for a LOINC questionnaire item.' It clearly delineates the scope (question-level answer sets) and names the siblings it is not (loinc_panels, loinc_search), so an agent can select it 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?

Explicit 'Use this tool to' bullets give positive conditions, and the closing sentence gives exclusions plus alternatives: 'Only applicable to LOINC codes that represent questions with defined answer sets. For the questions of a whole questionnaire, use loinc_panels; to find a code by name, use loinc_search.' This is textbook when/when-not 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 readOnlyHint/idempotentHint/destructiveHint, fully covering the safety profile, so the bar is lower. The description adds only return-content context, which the existing output schema also supplies, and says nothing about pagination, auth, or error cases.

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

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

Front-loaded with the core purpose in the first sentence and overall tight. The three-bullet list of returned fields partly duplicates what the output schema already declares, which is mild redundancy rather than padding.

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, fully-annotated read tool with an output schema, the description is complete enough to call correctly. The only gap is routing guidance against the many sibling lookup tools, which is small given how simple invocation is.

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 lone parameter already carries its own description and a regex pattern. The description restates the same format ('XXXXX-X') and example, adding no semantics beyond the schema, 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+resource ('Get detailed information about a specific LOINC code') and enumerates the returned fields, which distinguishes it from the search/list family. It never names the sibling it complements (e.g. loinc_search, loinc_answers), so sibling differentiation is implied rather than explicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The 'Use this tool to:' block describes what you get, not when to choose it over loinc_search or the other LOINC tools. There is no when-not guidance or named alternative, so usage is only implied by the word 'specific'.

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, openWorld), so the bar is lower. The description adds the return type (list of LOINC codes) but doesn't disclose behavior for unknown/invalid loinc_num or error handling. Adequate, not rich.

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

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

Front-loaded with the core purpose, then a compact bulleted list of use cases, then the return value. Efficient and well-structured; the bullet list is slightly redundant with the opening line but earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter read tool with an output schema, annotations, and full schema coverage, the description provides enough to call it correctly. Missing only edge-case behavior and explicit sibling routing, which are minor given the rich structured context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single parameter includes a pattern and example, so the schema fully documents it. The description doesn't add format or constraint details beyond what the schema provides. 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?

Clear verb+resource: retrieves the structure of a LOINC panel/form and returns its constituent codes. It is distinguishable from siblings like loinc_details and loinc_search, though it doesn't explicitly name a competing sibling. Solid but lacks explicit sibling differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The 'Use this tool to' list gives concrete contexts: viewing tests in a panel (CBC, metabolic panel), getting form structure, and finding grouped observations. Clear usage context, but no explicit exclusions or named alternatives.

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, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description's only added behavioral note is the shape of the return ('names, components, and properties'), which duplicates information better served by the output schema. Adds little beyond 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 a one-sentence definition, then scannable bullets, then the return summary. Sized appropriately, with only minor redundancy between the intro sentence's enumeration and the bullet list.

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 covering safety and an output schema covering the return shape, the description needs only to establish purpose and context, which it does. The remaining gap is disambiguation from sibling LOINC tools, which matters given this tool set's density.

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 (query, max_results) are fully documented in the schema with types, bounds, and defaults. The description adds no syntax, format, or matching-rule detail (e.g., partial vs exact matching), 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 (Search) and resource (LOINC lab tests/clinical observations/measurements), which is unambiguous on its own. However, it never differentiates itself from the many LOINC siblings (loinc_details, loinc_answers, loinc_panels, map_loinc_to_snomed), so an agent must infer which LOINC tool fits.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The 'Use this tool to:' bullets give clear positive contexts (finding codes for lab tests, vital signs, diagnostic observations). There are no exclusions or named alternatives despite several overlapping LOINC siblings, so it stops short of the when-not guidance a 5 requires.

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 safe read-only, idempotent, open-world profile; the description adds substantial behavior beyond that: bundled WHO release version, primary 1:1 vs alternative mappings, returned fields, 11,243-category coverage, excluded chapter/block codes, accepted dotted and undotted formats, and the honest 'no mapping' failure mode. No contradiction with annotations.

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 does, then explains return behavior, usage, coverage limits, input formats, and failure behavior. Each sentence adds distinct operational value with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Even with an output schema and safety annotations, the description supplies complete invocation context: scope, data source, coverage boundaries, accepted input formats, and what happens when no mapping exists. 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%, so the parameter is already documented with examples. The description adds useful semantic detail beyond the schema: both dotted and undotted code forms are accepted, and examples carry clinical labels such as 'E11' for Type 2 diabetes and 'A07.8' having four alternatives.

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: mapping ICD-10 codes to ICD-11 using authoritative WHO transition tables. It explicitly contrasts itself with fuzzy text-search candidates and defines coverage boundaries, so an agent can distinguish it from search/lookup siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear use cases (clinical coding, billing migration, retrospective analysis) and the key alternative class: authoritative mapping rather than text-search candidates. It does not explicitly name a specific sibling tool or spell out when-not conditions, so it falls just short of a 5.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds a genuinely useful behavior: translations are NLM's official ones and content is never machine-translated, which 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 purpose followed by a compact bullet list; the bullets overlap somewhat with what the schema already conveys, but overall it is short and scannable.

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 covering safety and an output schema covering return shape, the description supplies the remaining essentials: the required ID pattern, the language option, and the translation guarantee. Adequate for a two-parameter lookup 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% and both parameters are documented there, so baseline 3 applies. The description echoes the mesh_id example and language code example without adding syntax or constraints beyond the schema.

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

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

States a specific verb and resource ('Get detailed information about a MeSH descriptor by ID'), which distinguishes it from the search-oriented siblings. It does not explicitly contrast itself with mesh_search or mesh_tree, so an agent must infer that this is the by-ID detail 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?

The bullet list describes what the tool returns (scope note, tree numbers, related concepts) rather than when to choose it over mesh_search/mesh_tree/mesh_qualifiers. The ID format example is helpful context but is not conditional guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds only the domain nuance that qualifiers refine descriptors, plus the 'Descriptor/qualifier' notation example; it says nothing about behavior on an invalid or non-existent mesh_id. With annotations carrying the behavioral burden, 3 is appropriate.

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?

Well front-loaded: the core purpose is the first sentence, followed by scannable bullets and a concrete example. It is slightly redundant, since 'Find which qualifiers can be combined with a descriptor' restates the opening sentence, which keeps it off 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 values need not be described. For a single-parameter read-only lookup, the description covers purpose, use cases, and the notation semantics; nothing essential is missing, though an explicit pointer to mesh_descriptor for the descriptor itself would complete the routing story.

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 mesh_id parameter is fully documented in the schema with a pattern and examples. The description adds no syntax, format, or validation detail beyond that, 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 opening sentence states a specific verb and resource: 'Get allowed qualifiers (subheadings) for a MeSH descriptor.' That is unambiguous and distinguishes it from the descriptor/lookup siblings. It stops short of naming an alternative (e.g., mesh_descriptor) to route the agent, so it lands at 4 rather than 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The 'Use this tool to:' bullets give concrete contexts (combining qualifiers with a descriptor, building precise queries, enumerating specifiable aspects), which is clear when-to-use guidance. There are no exclusions or named alternatives for cases like 'I just want the descriptor itself', so it is not a full 5.

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

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

Annotations already cover read-only/idempotent/open-world, so the bar is lower; the description adds a real behavioral fact beyond them – that language returns NLM's official translations and content is never machine-translated. It also states the return shape (descriptors with MeSH IDs and labels).

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 purpose sentence followed by a compact bullet list and a single sentence on language behavior and return values. Efficient overall, with only minor overlap between the prose language note and the identical schema text.

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 search tool whose annotations cover the safety profile and whose output schema exists, the definition supplies purpose, use cases, the non-obvious translation caveat, and the return shape. Nothing critical to correct invocation 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 match enum, language enum, and max_results bounds, so the baseline is 3. The description's language explanation with a 'pt' example largely restates what the schema already documents, adding little beyond 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+resource ("Search for MeSH descriptors") and enumerates concrete use cases (indexing, PubMed subject headings, controlled vocabulary), which clearly separate it from lookup siblings like mesh_descriptor. It never names a sibling explicitly, so differentiation is functional rather than direct.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The "Use this tool to" list gives clear retrieval contexts (indexing terms, PubMed subject headings, controlled vocabulary), so when-to-use is well established. It stops short of exclusions or naming alternatives such as mesh_descriptor or mesh_tree for ID/tree navigation.

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, openWorldHint and non-destructive behavior, so the safety profile is covered. The description adds genuinely useful return context by showing the tree-number format (e.g., C14.280.647 for Myocardial Infarction), which is not derivable from the annotations.

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

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

Front-loaded with the core purpose, then scannable bullets, then a concrete example. Slight redundancy between the opening line and the first bullet ('where a term fits in the MeSH hierarchy'), 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?

An output schema exists, so return-value documentation is not required, and the safety profile is carried by annotations. The description covers purpose, use cases, and tree-number format, leaving only trivial gaps for a simple one-parameter lookup.

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% with a single documented mesh_id parameter including its pattern and an example. The description adds nothing beyond the schema about the parameter, 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 ('Get the tree hierarchy location(s) for a MeSH descriptor') and the bullet list narrows the scope to hierarchy/branch relationships. This is clearly distinguishable from siblings like mesh_descriptor, mesh_search, and mesh_qualifiers.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The 'Use this tool to' bullets give concrete context: seeing hierarchical fit, understanding broader/narrower relationships, finding related terms in the same branch. There is no explicit when-not-to-use or named alternative, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds the return shape (class IDs, names, classification sources), which is mildly useful, but an output schema already exists and no auth or rate-limit context is given.

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

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

Front-loaded with the core action, then a short scannable bullet list, then the return summary. There is some redundancy between the header sentence and the bullets, but nothing is bloated.

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 simple one-parameter read tool with full annotations and an output schema, the definition covers what the tool does and what it returns. It lacks only sibling routing guidance, a minor gap given the crowded RxNorm toolset.

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?

Single parameter rxcui has 100% schema description coverage, so the schema carries the semantics. The description adds nothing about the identifier's source or format beyond what the schema documents, matching the baseline for high coverage.

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 ('Get therapeutic and pharmacologic classes for a drug') with concrete examples (Beta-blockers, NSAIDs). It does not differentiate itself from siblings like rxnorm_concept or rxnorm_ingredients, which also serve the RxNorm space.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The bulleted 'Use this tool to' list implies when to use it, but the items largely restate the purpose rather than giving conditions or naming alternatives. No when-not guidance or prerequisite (e.g., needing a resolved RxCUI) is provided.

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, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds modest value by noting what data types are returned (status values such as active/remapped, related concepts), but says nothing about the data source, caching, or field completeness.

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 opening sentence and the bullet list is scannable without redundancy. It is slightly longer than strictly needed given the schema carries the parameter detail, 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?

An output schema exists, so return values need not be explained, and annotations cover the safety/idempotency profile. For a two-parameter read-only lookup the description is largely sufficient; the only gap is the absence of sibling routing.

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 both parameters (rxcui and include_related) are already fully documented in the schema, including the string-or-integer format and the boolean/string acceptance. The description only repeats the RxCUI example, adding no meaning beyond the structured fields, 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?

The description gives a specific verb (Get) plus resource (detailed information about a specific RxNorm concept) and the key (by RxCUI), with concrete examples of what you retrieve (name/synonyms, status, related concepts). It clearly reads as an ID-based lookup, implicitly distinguishing it from sibling rxnorm_search, but never names a sibling 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?

The 'Use this tool to' list gives positive use cases but no when-not guidance or named alternatives. It overlaps with siblings like rxnorm_ingredients (for 'ingredients') and rxnorm_search without clarifying which to pick, leaving the routing decision 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety and side-effect profile. The description adds that it returns ingredient RxCUIs and names, which is useful output context, though it doesn't describe error behavior or rate limits.

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

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

The description is short and front-loaded with the core action, followed by a bulleted list of use cases. There is no wasted text, though the bullet points could be slightly more compact.

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 one required parameter, 100% schema coverage, and a declared output schema, the description provides enough context to invoke the tool correctly. It could mention sibling alternatives for broader use-case routing, but it is largely 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 description coverage is 100%, so the schema fully documents the single 'rxcui' parameter with its type and pattern. The description does not add any syntax or format details beyond what the schema provides, so 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 states a specific verb and resource: 'Get active ingredients for a drug by RxCUI.' It distinguishes the tool from sibling rxnorm_concept and rxnorm_search by focusing on ingredient-level lookup, and the bullet list clarifies the exact use cases.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The 'Use this tool to' bullet list provides clear context for when to call it: finding active ingredients, checking single vs. multiple ingredients, and identifying generic components of brand drugs. It does not explicitly name when not to use it or mention the alternative tools in the rxnorm family.

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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description still adds value by spelling out the either/or input mode (RxCUI -> NDCs or NDC -> RxCUI), which is a behavioral constraint beyond the annotations.

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 one-line purpose followed by a short bulleted usage list; well sized. The usage bullets partially restate the opening line, but the redundancy is minor and it stays easy to scan.

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 explained, and annotations carry the safety profile. The description covers the input modes adequately; only minor details (e.g., behavior if both parameters are omitted or supplied) are unaddressed.

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 two parameters are already documented as alternatives. The description restates the either/or relationship but adds no format, validation, or edge-case 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 states a specific verb (map) and both resources (RxNorm concepts / RxCUI and NDC codes), and makes the bidirectional nature explicit. An agent can distinguish this lookup/mapping tool from sibling search or concept tools 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 clear, enumerated usage cases: get NDCs for a drug by RxCUI, find the RxCUI for an NDC, or cross-reference systems. However, it names no alternatives or exclusions relative to siblings like rxnorm_concept or rxnorm_search, so a small inference gap remains.

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, openWorldHint, and destructiveHint=false, so the safety and idempotency profile is fully covered. The description adds only that results include RxCUI identifiers, names, and term types, which is largely redundant given the output schema exists. No auth needs, rate limits, or partial-match behavior are disclosed.

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 sentence is front-loaded and the bullet list is scannable and free of filler. Slightly more text than necessary for a two-parameter search tool, but nothing is wasted or duplicated.

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, a fully described schema, and an output schema covering return values, the description needs only to convey purpose and scope, which it does. It falls short of 5 only because it leaves the boundary with sibling RxNorm tools (concept, ingredients, NDC) unstated.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with both query and max_results fully documented (including range and default), so the baseline is 3. The description adds no extra meaning such as accepted query syntax, partial matching, or how brand vs generic matching behaves.

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

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

States a specific verb+resource: search for drugs in RxNorm, with the acronym expansion clarifying what RxNorm is. It also enumerates concrete use cases (brand/generic names, prescribing, formulations). It does not, however, distinguish itself from siblings like rxnorm_concept, rxnorm_ingredients, or rxnorm_ndc, so an agent must infer the boundary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The bulleted use cases imply when the tool applies (finding concepts, prescribing lookups, formulation search), which is more than nothing. But there is no explicit when-not guidance and no named alternative (e.g. use rxnorm_concept once you have an RxCUI), so the agent must decide on its own among a dense set of RxNorm siblings.

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

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

Annotations already declare readOnly, idempotent, openWorld and destructive=false, and the description reinforces this ('read-only and idempotent') while adding traits annotations cannot express: a 10-document result cap, relevance ordering, empty-list-means-no-match semantics, in-memory caching from the public source, and query language tolerance (Portuguese/English, accents and case ignored). These are exactly the operational details an agent needs and cannot infer.

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

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

Front-loaded with the core purpose, return shape and result cap, followed by clearly separated routing, query and behavior notes. It is longer than strictly necessary — the OpenAI contract paragraph could be tighter — and the accents/case detail is restated in the schema, but every section carries routing or behavioral value.

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 one-parameter search tool with an output schema and full annotations, nothing needed to call it correctly is missing: source coverage, result cap, ordering, query language handling, the search→fetch handoff, and the reason to prefer sibling data tools are all present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With a single parameter at 100% schema coverage, the baseline is 3, but the description adds real meaning beyond the schema: the query accepts natural language or keywords and works in Portuguese or English. It does not add syntax or escaping rules, so it sits just above baseline rather than at the top.

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

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

The description states a specific verb and resource ('Searches the medical terminologies ... catalog'), names the sources (CID-10, ICD-11, LOINC, RxNorm, MeSH, version records), and specifies the return shape and cap ({ id, title, url }, up to 10, relevance-ordered). It explicitly contrasts itself with the data-returning siblings, so an agent can distinguish it 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 unambiguous when-to-use (the OpenAI Deep Research contract requires exactly `search` and `fetch`, then pass the id to `fetch`) and an explicit when-not-to-use, listing the concrete alternatives (`icd11_*`, `cid10_*`, `loinc_*`, `rxnorm_*`, `mesh_*`, `atc_*`, `map_*`, `find_equivalent`, `validate_codes`) for direct questions and actual data. Routing is fully resolved in the description.

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 cover the safety profile (readOnly, idempotent, openWorld, non-destructive), and the description adds substantial non-obvious context beyond them: the server lacks historical snapshots, `bundled_versions` reflects what is actually on hand, and frequent-change terminologies defer to the publisher's changelog. This is exactly the behavioral disclosure annotations cannot provide.

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 first sentence and clear Inputs section, sized appropriately for a genuinely nuanced tool. Slightly redundant, repeating 'guidance only' and the publisher's-changelog point, which costs it the top score.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given an output schema exists, return values need not be explained, and the description covers the branching behavior (guidance vs real ICD-10/ICD-11 summary), the bundled-version concept, and the authority hierarchy. 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 the baseline is 3, but the description adds real semantics the schema lacks: omitting `from_version` reports against the bundled version, omitting `to_version` reports against the publisher's latest known release, and the icd10+no-to_version combination triggers the cross-revision summary. It does not, however, explain the enum members themselves.

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 (report) and resource (diff data between versions of a terminology) and immediately carves out what it is not: 'a metadata + guidance layer, not a diff engine.' This distinguishes it from siblings like map_icd10_to_icd11 (real mapping) and terminology_versions (version listing).

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 when-to-use guidance: for most terminologies it is guidance only and the publisher's changelog is authoritative, while for ICD-10 vs ICD-11 it surfaces a real summary. It even names the exact invocation (`terminology: "icd10"` with no `to_version`), leaving nothing 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/openWorld, and the description adds provenance detail: the full set of 7 is returned by default, the ICD-10 → ICD-11 version reads live from the bundled dataset while everything else is release-maintained metadata. This live-vs-static distinction is useful behavioral context beyond the annotations.

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 returned fields, then a scannable bullet list of use cases, then the parameter behavior. The bullets are slightly verbose but each carries real information; 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?

An output schema exists, so return values need not be explained, yet the description even enumerates the returned fields. It covers filtering, default behavior, data provenance, and the one-parameter surface, leaving no 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 enum already documents the filter values and the omit-to-return-all behavior. The description restates the same filtering semantics, adding little meaning beyond the schema, so the 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?

States a specific verb (List) and resource (version, release date, publisher, source URL, update cadence of every terminology) with a clear scope. This is instantly distinguishable from every sibling, which are all code-lookup/search tools, so an agent can tell it apart 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?

Provides concrete when-to-use scenarios (confirm release before a batch run, verify bundled tables, cite data version in research). It gives clear positive guidance but does not explicitly name alternatives or exclusions, though the meta purpose has no meaningful sibling overlap.

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

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

Adds rich behavioral context beyond annotations: the 50-code hard cap, parallel validation with wall-time scaling, the null semantics of 'active' per terminology, and the precise valid/error truth table for distinguishing 'not found' from 'couldn't validate'.

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 purpose, then a clean bulleted return-value contract, then constraints. Dense but every sentence carries load; no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite an output schema existing, the description fills the remaining gaps an agent needs: v / error semantics, per-terminology 'active' behavior, replacement-mapping coverage, and throughput/latency limits.

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, but the description adds meaning beyond the schema: explains why terminology is required (A00 ambiguity), enumerates the accepted values, and documents the batch cap and latency implications.

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 (validate) and a specific resource (mixed batch of medical codes against their source terminologies), and clarifies the scope as batch/multi-terminology, distinguishing it from all the per-terminology lookup/search siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear usage context ('retrospective analysis of legacy databases', flag dead codes, surface ICD-10 → ICD-11 replacements) and implicitly differentiates from single-code lookup siblings, but does not explicitly name an alternative tool or state exclusions.

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