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

Annotations already declare readOnly/idempotent/openWorld/destructive=false, so safety is covered. The description adds real behavioral context beyond that: one entry per ATC code, single-ingredient vs combination cardinality, the NLM RxClass provenance, and critically that unrecognized names return an empty matches list with a note rather than an error.

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 structured bullets for use cases, return shape, input format, and sibling routing. Slightly long, but each block carries distinct information and nothing is redundant with the schema.

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

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

With an output schema present, the description needn't enumerate return fields, yet it still explains the return shape (one entry per code, empty matches case) and the input contract. For a one-parameter lookup tool it is complete.

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

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

Schema coverage is 100% with a single parameter, so the baseline is 3. The description goes further by specifying that input is a drug NAME, that brand or generic English/US RxNorm naming is accepted, and that the generic name is the better fallback — meaning beyond the schema's 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 (look up) and resource (WHO ATC classification) plus a concrete example mapping ("metformin" → A10BA02). It also explicitly distinguishes itself from the two sibling ATC tools by name, 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?

Provides an explicit 'Use this tool to' list and a dedicated 'Which ATC tool' paragraph naming the alternatives (atc_lookup for class codes, atc_members for drugs in a class) with the condition that selects each. It also handles the failure path by pointing to rxnorm_search.

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, covering the safety profile. The description adds the key behavioral constraint that substance-level codes are not exposed by the endpoint and points to the alternative, which is genuinely useful beyond the annotations, though return-format details are omitted (and covered by the output schema).

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

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

Front-loads the core purpose, then uses a short bulleted list for use cases and code-length guidance. Slightly long and mildly redundant with the schema's substance-code note, but each element is purposeful and skimmable.

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

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

With an output schema present, the description needn't explain return values; it covers purpose, use cases, accepted code formats, and the notable exclusion with the correct alternative. 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?

Schema coverage is 100% and the schema already includes the pattern and the substance-code note, so the baseline is 3. The description still adds value by mapping code lengths to ATC levels (A=anatomical, A10=therapeutic, A10B=pharmacological, A10BA=chemical), which enriches the single parameter's semantics.

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 (look up an ATC code) and its scope (level 1-4) yielding name and hierarchy level. The description makes clear it is distinct from atc_classify, which handles substance codes, so an agent can route without opening sibling schemas.

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

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

Explicitly enumerates three use cases (resolve code, confirm existence, identify level) and names the alternative atc_classify for the excluded 7-char substance-level codes. This is a clear when-to-use and when-to-use-something-else statement.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely new context beyond that: the US-centric RxNorm catalog vs. international ATC names/codes, and the fact that each member carries a 7-char source_atc_code useful for disambiguating level 1-4 queries. Return format details are left to the output schema.

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

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

Purpose is front-loaded in one sentence, followed by scannable bullets and a short caveat paragraph. There is mild redundancy between the opening line and the first bullet, but nothing wasteful enough to hurt usability.

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 values, the description only needs to supply purpose, routing, and domain caveats, which it does. Minor omissions such as result-size or pagination behavior for large subtrees keep it from a 5.

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 explains the atc_code pattern and the level 1-4 vs. level 5 behavior; the description largely restates that ('explore an ATC subtree at any level'). No extra syntax, format, or edge-case guidance is added, 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 gives a precise verb (List) and resource (drugs/substances belonging to an ATC class), and the bullets clarify that this is an enumeration/hierarchy-traversal operation rather than a code lookup or classification, which is what siblings like atc_lookup and atc_classify do. 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?

The 'Use this tool to:' bullets give three concrete scenarios (enumerate class members, find drugs sharing a mechanism, explore a subtree at any level), which is clear positive guidance. It stops short of naming alternatives or stating when not to use it (e.g., vs. atc_lookup for a single code's name), so it lands at 4 rather than 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?

Goes well beyond the annotations: out-of-range input behavior (rejected with a validation error), no pagination and full group return, total dataset size (275 groups), and that results come from a bundled local V2008 snapshot with no network call. The 'no network call' statement sits in mild tension with openWorldHint=true, which is why this is a 4 rather than a 5.

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

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

Somewhat long with bulleted use cases, but it is front-loaded with the core purpose and the 'Which CID-10 tool' routing block carries high value; no sentence is filler, though the routing paragraph could be tightened.

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

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

With an output schema present, return-shape detail is not required, and the description still covers purpose, parameter semantics, failure behavior, data source, and disambiguation against five sibling tools. 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 description coverage is 100%, so the baseline is 3, but the description adds real meaning: the Roman-numeral-to-integer mapping (chapter I = 1, IX = 9) and the validation behavior for values outside 1-22.

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 one CID-10 chapter and its constituent groups') with a concrete example of the returned content. It clearly distinguishes itself from cid10_chapters, cid10_lookup and cid10_search by scope (chapter-level drill-down).

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

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

Explicitly names when to use it (drill into groups, build hierarchical browsers, find the group for a code range) and routes to alternatives: cid10_chapters when the number is unknown, cid10_lookup for a single code, cid10_search for Portuguese text, icd11_chapters for ICD-11.

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 safety is covered structurally. The description adds real behavioral context beyond that: it commits to a fixed result count ('Returns 22 entries') and discloses data staleness ('CID-10 V2008 has not been updated since 2008'), which is exactly the kind of trait annotations cannot express.

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, then a scannable bulleted usage block, then a single closing fact about result size and vintage. Every sentence carries information and nothing is repeated from the schema or 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 shape need not be described, and the description still gives the entry count. Purpose, usage, and the important version caveat are all present; nothing an agent needs to invoke a zero-argument listing tool correctly is missing.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. There is no parameter surface for the description to clarify, and it correctly does not invent any; the content it does provide is about output, not input.

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

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

States a specific verb and resource ('List the 22 chapters of CID-10') plus the scope of what comes back (code ranges, Portuguese titles). The phrase 'top-level structure' and '22 chapters' cleanly separates it from the singular cid10_chapter and from cid10_lookup/search, so an agent can pick it without opening the schema.

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

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

A dedicated 'Use this tool to' block gives three concrete use cases (see top-level structure, map a code to its chapter, build a table of contents), which is clear context for selection. It does not, however, explicitly name the alternative tool (e.g., cid10_chapter) or state when NOT to use this one, 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, non-destructive and openWorld, so the safety profile is covered structurally. The description adds genuine behavioral context — it accepts both dotted and undotted forms and returns the canonical display, plus gender/cause-of-death flags — but does not describe error/not-found behavior or lookup 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?

Front-loaded with the core purpose, then efficiently bulleted and closed with the format note. Slightly redundant at the end, since the dotted/undotted acceptance is already stated in the schema parameter description.

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

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

With an output schema present, the description need not explain return values, and it still covers scope, format flexibility, and the extra flags surfaced. Nothing material for a correct single-parameter lookup 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 'code' parameter is already fully documented with a pattern and format examples. The description's note about dotted/undotted acceptance and the canonical display repeats what the schema says, 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 ('look up'), a precise resource ('a specific CID-10 code'), and the return ('its Portuguese name'). The word 'specific' plus the code-level granularity clearly separates it from sibling search/chapter tools like cid10_search and cid10_chapter without needing to name them.

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

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

The three 'Use this tool to:' bullets give concrete when-to-use scenarios (resolve a code to a Brazilian description, confirm a category/subcategory exists, retrieve restriction flags). There are no explicit exclusions or named alternatives ('use cid10_search if you only have free text'), 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 cover safety (readOnly/idempotent/non-destructive), yet the description adds substantive behavior: diacritic-insensitive matching, AND semantics across words, everyday-Portuguese-to-CID-10 vocabulary resolution (câncer→neoplasia maligna, AVC→acidente vascular cerebral), and the fact that resolution is reported back in vocabulary_notes. That is exactly the kind of non-obvious behavior an agent must know to interpret results.

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

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

Front-loaded with the core purpose, then scannable bullets, then matching semantics, then the sibling hand-off. Every sentence carries information, though the parenthetical glossary expansions 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?

For a 3-parameter search tool with an output schema, everything needed to call it correctly is present: scope (Brazilian CID-10 V2008), matching rules, query style, and the ICD-11 escape hatch. Return-value explanation is unnecessary given 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%, so the baseline is 3; the description goes slightly beyond by illustrating how a query string is normalized (accents ignored, everyday terms rewritten) and showing the response field that reports it. It adds nothing for level or max_results, so it does not fully earn 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?

States a specific verb (search) plus the exact resource (Brazilian CID-10, V2008, Portuguese text) and explicitly separates itself from icd11_search for the international ICD-11. An agent can identify 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?

Three concrete 'use this tool to' bullets name the scenarios (SUS/ANVISA coding, CBCD/USP translation lookup, billing/epidemiology), and the closing sentence names the alternative (icd11_search) with the condition that selects it. The routing decision is explicit rather than implied.

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

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

Annotations already cover read-only, idempotent, open-world and non-destructive traits, so the bar is lower; the description still adds value with the error behavior on unknown ids and the fact that it performs a live GET against the public source. It stops short of describing latency, caching, or failure modes when the source is unavailable.

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 return contract, then placement, then behavior, using bold labels for scannability. Slightly heavy with the parenthetical enumeration of terminology families, but every section still carries information.

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

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

Return fields, validation rule, sourcing behavior, and the boundary against sibling terminology tools are all covered, and an output schema exists so return-value detail need not be expanded further. Nothing essential 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 coverage is 100% with a single `id` parameter, so the baseline is 3. The description adds a real constraint beyond the schema: the id must originate from `search`, and anything else errors — meaningful semantics the schema text does not convey.

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') and enumerates the returned fields, so the agent knows exactly what comes back. It also positions itself against the many sibling terminology tools by declaring itself the companion of `search` in the Deep Research contract.

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 preconditions ('Only ids returned by `search` are valid; an unknown id returns an error') and an explicit exclusion routing data queries to the `icd11_*`, `loinc_*`, `rxnorm_*`, etc. tools. When-to-use and when-not-to-use are both 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 cover safety (readOnly, idempotent, openWorld, non-destructive), and the description adds non-obvious traits: match_score/rank are server-computed because upstreams lack comparable relevance, lexical-title clustering in groups with the caveat that absence of a group is not evidence of non-equivalence, English-only searching, and no stable cursor for paging. This is well beyond structured-field coverage.

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 scannable use-case list and behavioral notes. Well structured, though the source/target subtraction rule is stated twice (body and schema), adding minor redundancy.

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

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

An output schema exists so return values need not be explained, yet the description still clarifies the two computed fields and the grouping semantics that an agent must interpret correctly. Nothing material is missing 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%, so baseline is 3; the description adds real meaning beyond it — limit is a cap not a page (with the reason), and source_terminology combines with target_terminologies by subtraction. The only gap is that some overlap exists between the description and the schema text.

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

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

States a specific verb+resource ('ranked unified search for equivalent terms across multiple medical terminologies') and enumerates the exact terminologies searched. An agent can distinguish it from siblings like harmonize_terms or map_icd10_to_icd11 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?

Three explicit use-case bullets, plus the exclusion mechanism via source_terminology and a clear redirect to dedicated tools for pt-BR content (icd11_search, mesh_search, cid10_search). When-to-use and when-to-use-something-else are both covered.

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

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

Annotations cover the safety profile (read-only, idempotent, open-world, non-destructive), and the description adds genuine behavioral context beyond them: the 50-term hard limit with a validation error, dedup of repeated term+domain pairs, per-row error survival ('one failed lookup does not fail the batch'), candidate-dropping rules, match_type/score definitions, and an explicit de-identification warning since terms go to 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-loads the purpose, then a scannable 'Use this tool to' list, then dense behavior rules. Almost every sentence carries a distinct rule, but the paragraph on match_type/matched_label and LOINC ambiguity is long enough that strong reference content competes with quick-select scanning.

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

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

For a two-parameter batch tool there is an output schema, so return-shape explanation is not needed, and the description still covers limits, error semantics, filtering rules, confidence labeling, and provenance guidance (provenance blocks + terminology_versions). 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 baseline is 3, but the description adds real meaning: the domain routing rules (diagnosis→ICD-11, drug→RxNorm ingredients first plus ATC, lab→LOINC), the batch ceiling, and max_candidates semantics/default. It does not restate the schema's field-level descriptions, which is appropriate.

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

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

States a specific verb (harmonize/map) and resource (a list of free-text clinical terms) with explicit scope: batch mapping to ICD-11/RxNorm+ATC/LOINC with ranked candidates and confidence labels. It distinguishes itself from siblings by naming find_equivalent, cid10_search, validate_codes and icd11_postcoordination as different jobs.

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 (harmonize a column, triage clean vs needs_review, build an auditable crosswalk) plus named alternatives with their selecting conditions: one term across all terminologies → find_equivalent; Brazilian Portuguese → cid10_search; existing codes → validate_codes; postcoordinated clusters → icd11_postcoordination.

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

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

Annotations already cover the read-only, idempotent, non-destructive profile, yet the description adds substantial behavior: exactly 28 entries, no pagination, the composition of chapters (01-26 plus V and X), and crucially the partial-failure semantics where a failed fetch keeps its URI and carries an `error` while the rest succeed. It also discloses official-vs-machine translation and caching, well beyond what annotations convey.

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

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

Front-loaded with the core action, organized into scannable use-case bullets and a use-not clause, and every sentence carries actionable information 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?

An output schema exists, yet the description still usefully previews the entry shape (number, code, title, URI) and error handling, so an agent knows exactly what to expect. Nothing needed 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% with a single enum parameter whose description already explains official translations. The description reinforces this with a concrete example (language: 'pt') and adds that results are cached, modest but real added value over 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 ('List all ICD-11 chapters') and clarifies scope ('top-level categories') and version ('pinned WHO release'). It is clearly distinguishable from icd11_search and cid10_chapters, which are named as alternatives.

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 of scenarios plus an explicit 'When NOT to use' clause routing to icd11_search and cid10_chapters. Both the when and the when-not are spelled out with 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 cover read-only, idempotent, open-world and non-destructive behavior, so the bar is lower. The description still adds non-obvious traits: language returns only the source's OFFICIAL translation and is never machine-translated, and 'parents' can return blocks with an empty code plus a code_range. It does not mention any rate limits or result-size caps, so it falls short of a 5.

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

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

Purpose is front-loaded in the first line, followed by a scannable use-case list and then parameter guidance. Every sentence carries information; the only mild redundancy is that the direction semantics are stated in both prose and schema.

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

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

With an output schema present, return values need not be explained, and the description covers purpose, usage, parameter formats and language behavior. Minor gap: nothing about traversal depth, result volume, or behavior when an entity has no parents/children.

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 genuinely enriches it: it explains the block-range code format, why an entity may arrive as an empty code with a code_range, and the official-translation semantics of language. The uri parameter is only glossed as 'the URI any previous answer returned'.

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 (Navigate) and resource (ICD-11 hierarchy) and immediately scopes it to parent/child traversal, which distinguishes it from icd11_lookup and icd11_search. An agent can tell what this tool returns without opening the schema.

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

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

The 'Use this tool to' block gives three concrete scenarios (broader categories, subtypes, structure) and adds a routing rule: ICD-10 codes must be converted first with map_icd10_to_icd11. That names a sibling and the condition selecting it, so the main misuse path is closed.

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, but the description adds real behavioral context beyond them: single entity with no pagination, unknown codes produce a 'not found' error rather than an empty record, and language returns only official translations and is never machine-translated. These are exactly the failure-mode details 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 purpose, then organized into scannable bullets and a clearly separated exclusion section. Despite its length, every sentence carries distinct routing, constraint, or error information 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?

With an output schema present, return-value documentation is unnecessary, and the description still covers inputs, the at-least-one constraint, error behavior, language semantics, and sibling routing. 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%, so the baseline is 3, but the description adds meaning the schema does not: it clarifies that code and uri are mutually satisfiable alternatives where at least one is required, and that a call with neither yields a validation error naming both. The 'any URI a previous answer returned' hint is also genuinely useful for chaining calls.

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 ONE ICD-11 entity') and immediately scopes it to entities the agent already has a code or URI for. It explicitly names the siblings it is not (icd11_search, icd11_hierarchy, map_icd10_to_icd11), so 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?

Gives an explicit when-to-use list (definitions, coding notes, inclusions/exclusions, titles and synonyms) and an explicit 'When NOT to use' section that routes three distinct cases to the correct alternatives. The precondition ('you already have a code or URI') is stated up front.

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, non-destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond that: it returns one entry per axis with axis_name/required/allow_multiple/value_count, and notably that an unknown or non-postcoordinatable code yields an empty axes list rather than an error, with a suggested recovery step.

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, then grouped usage bullets, return semantics, and an explicit exclusion clause. Slightly longer than strictly necessary but each section carries distinct information and the ordering is logical.

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 full annotations and an output schema, the description covers purpose, usage, exclusions, return shape, and edge-case behavior. An agent has everything needed to call it correctly and interpret an empty result.

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

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

Schema coverage is 100% with a single well-described required parameter, so the baseline is 3. The description adds a concrete format example ('BA00') and clarifies the code is an ICD-11 stem code, giving a small but real improvement over the schema's terse 'ICD-11 code to get postcoordination info for'.

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), a specific resource (postcoordination axes), and the scope (one ICD-11 stem code, MMS linearization/pinned release). The definition of postcoordination that follows makes the resource unambiguous and clearly separates it from sibling lookup/search tools.

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 cover the three selection cases (check accepted axes, required vs optional, single vs multi-value), and a 'When NOT to use' section names icd11_lookup and icd11_search with the conditions that route to them. 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). The description adds genuinely useful behavioral detail beyond them: language returns WHO official translations, never machine-translated, and results include relevance scores. Missing pagination/ranking behavior, but the translation guarantee is real added value.

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

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

Front-loaded with the core purpose, then bulleted use cases and a return summary. Well structured and mostly waste-free, though the use-case bullets overlap noticeably with the opening sentence.

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

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

With an output schema present and annotations covering the safety profile, the description supplies the remaining critical context — the official-translation guarantee for language and the shape of returned fields. Minor gaps in ranking/ordering behavior keep it short of a 5.

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 including the language enum and official-translation note. The description largely echoes the schema's language semantics rather than adding new meaning, 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 (search) and resource (medical conditions/diseases in ICD-11) with clear scope. It implicitly distinguishes from code-lookup siblings (icd11_lookup, icd11_chapters) by framing itself as name/keyword search, but never names a sibling to make the boundary 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:' bullets give clear context (find codes, search by name/keyword, multi-language lookup), but they restate the purpose rather than saying when to choose this over icd11_lookup or cid10_search. No when-not guidance or alternatives are offered.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds real behavioral context: the shape of each returned answer (LA code, text, display order, score, null score when absent), the empty-list case for valid codes without an answer set, and the 'not found' error for unknown codes.

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 scannable bullets, a return-shape sentence, and a usage/alternative sentence. Every line carries distinct information with no 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 read tool with an output schema and full annotation coverage, the description covers purpose, return values, edge cases (empty list, not-found), applicability constraints, and sibling routing. 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?

Schema coverage is 100%, so the schema documents the single parameter, but the description adds a meaningful constraint — only LOINC codes representing questions with defined answer sets are applicable, with the numeric-lab example (2339-0) showing a code that yields an empty list. This adds value beyond the schema's pattern/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 — 'Get the list of valid answers for a LOINC questionnaire item' — and the bullet list pins down exactly what is retrieved (answer codes, scores). It clearly differentiates from siblings loinc_panels and loinc_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?

Explicitly names when to use it (survey response options, data-entry validation, scored instrument items) and names the alternatives: loinc_panels for whole-questionnaire questions and loinc_search to find a code by name. 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 readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, so the safety profile is clear. The description adds no further behavioral context such as rate limits, permissions, or response format. With annotations covering safety, this is adequate but minimal.

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 concise and front-loaded: a clear purpose sentence followed by a bullet list of retrievable details and a precise input format note. Every sentence earns its place without 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?

Given the tool has an output schema, the description need not explain return values. It covers the purpose, input format, and what fields are included. However, it could mention that this tool is for exact LOINC code lookup versus broader searches, which would improve completeness for routing among siblings.

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 is well-documented with a pattern and example. The description repeats the format and example but adds no new semantic meaning beyond the schema. Baseline 3 applies when schema fully covers parameters.

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 clearly states a specific verb and resource: 'Get detailed information about a specific LOINC code.' It distinguishes itself from siblings like loinc_search by emphasizing retrieval by identifier, though it does not explicitly name alternatives. The purpose is immediately understandable.

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

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

The description implies usage through bullet points of what can be obtained and the input format, but it lacks explicit guidance on when to use this tool versus alternatives like loinc_search (for keyword search) or loinc_panels (for panel information). It provides context but no exclusions or alternative 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=true, idempotentHint=true, destructiveHint=false, so the safety profile is fully covered by structured data. The description's only added behavioral claim is that it returns the list of LOINC codes forming the panel, which is redundant with the output schema and says nothing about non-panel inputs or errors.

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 three-bullet usage list and a one-line return statement; no filler. Slightly list-heavy for a single-parameter tool, but every line carries information.

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

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

For a simple one-parameter read tool with full annotations and an output schema, the description covers purpose, use cases, and return content adequately. The only gap is behavior when the supplied code is not a panel, which an agent might reasonably want to know.

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 is documented in-schema with an example and pattern, so the baseline is 3. The description adds no meaning about loinc_num beyond the schema, such as whether it must be a panel-type code rather than any LOINC code.

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 structure of a LOINC panel or form') and enumerates concrete things the caller will see (tests in a CBC, form structure, related observations). It is clearly distinct from generic siblings like loinc_search or loinc_details, though it never names those siblings to draw the contrast 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' bullets give clear situational context: enumerating panel members, reading form structure, and finding grouped observations. There is no guidance on when NOT to use it (e.g., for a standalone test code, use loinc_details instead), so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds only the return shape ('codes with names, components, and properties'), which is already carried by the output schema, and discloses nothing about pagination, ranking, or match semantics.

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 the bullets scan quickly. Slightly redundant since the bullet list and the first sentence overlap in meaning, but no sentence is wasted.

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

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

With an output schema present and annotations covering the safety/read profile, the description is nearly complete for a search tool. The only real omission is sibling differentiation against the other LOINC tools, which an agent would need in this crowded namespace.

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 query and max_results are fully documented in the schema itself (including the 1-100 range and default 25). The description adds no syntax, format, or search-behavior detail beyond that, so the baseline of 3 applies.

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

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

States a specific verb (Search) and resource (LOINC lab tests/observations/measurements) with concrete examples like glucose and hemoglobin. However, it never distinguishes itself from the LOINC siblings loinc_details, loinc_answers, and loinc_panels, so an agent cannot tell from the description alone which LOINC entry point to pick.

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

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

The bulleted 'Use this tool to' list gives implied use cases (find codes, search measurements, look up observations) but they largely restate the purpose. There is no explicit when-not guidance and no routing to the sibling tools that also operate on LOINC (loinc_answers, loinc_details, loinc_panels), which is the key decision an agent faces.

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/non-destructive, yet the description adds substantial behavioral context: the return shape (primary 1:1 plus alternative candidates), the included fields (code, title, chapter, Foundation/Linearization URI), 11,243-category coverage, and the honest 'no mapping' behavior instead of a fuzzy fallback.

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: source, return shape, then usage and edge cases. Slightly longer than strictly necessary (multiple example codes, coverage count), but every sentence carries useful information.

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

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

Although an output schema exists, the description still gives enough about return contents and edge-case behavior ('no mapping') to call the tool confidently. Nothing an agent needs is missing.

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

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

Schema coverage is 100% for the single parameter, so baseline is 3; the description goes beyond the schema by noting that both dotted ('A07.8') and undotted ('A078') forms are accepted and giving example codes, which the schema does not state.

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 (ICD-10 → ICD-11 mapping) and the authoritative source (WHO transition tables, release 2025-01). It also implicitly separates itself from the text-search siblings ('authoritative mapping rather than text-search candidates'), so an agent can route correctly without opening schemas.

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

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

Gives concrete use cases (clinical coding, billing migration, retrospective analysis) and the condition that selects it over fuzzy search ('rather than text-search candidates'), plus an explicit exclusion for chapters/blocks. It stops short of naming the alternative tool (e.g., icd11_search) directly, but the routing signal is clear.

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, open-world). The description adds genuine behavioral context beyond them: translations are NLM's official ones where they exist and content is never machine-translated, which sets correct expectations about partial and authoritative data.

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

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

Front-loaded purpose sentence followed by a tight bulleted capability list and one parameter hint; no filler. Slightly redundant with the schema on the language parameter, but well within budget for a two-parameter tool.

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

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

For a simple lookup with an output schema present, the description covers purpose, the ID format, and language behavior adequately; return-value shape is left to the output schema. Nothing essential is missing, though it never mentions what happens for an unknown ID.

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 are already documented in the schema, including the enum and the official-translation caveat. The description's ID example (D015242) and language example duplicate schema content almost verbatim, adding only the 'NLM' attribution.

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 is clearly distinct from mesh_search (search) and mesh_tree (hierarchy browsing). It does not name siblings explicitly, but the resource is unambiguous enough to distinguish them.

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

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

The 'Use this tool to:' bullets describe what content is returned (scope note, tree numbers, synonyms) rather than conditions for choosing this tool over mesh_search or mesh_tree. Usage is implied by the required-ID input, but no alternatives or exclusions are stated.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description adds domain context by defining qualifiers as subheadings and illustrating refinement syntax ('Diabetes Mellitus/drug therapy'), which is genuine value beyond the structured fields. It does not discuss output shape, but 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?

The core purpose is front-loaded in the first sentence, followed by a scannable bullet list of use cases and one clarifying example. Every element earns its place, though the bullets add minor length for a one-parameter tool.

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

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

For a simple single-parameter read tool with full annotations and an output schema, the description supplies the conceptual background needed to interpret qualifiers. Nothing critical for 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% and the single mesh_id parameter is fully documented with a pattern and examples, so the schema carries the load. The description's example concerns qualifier syntax, not the mesh_id argument, adding no parameter detail. 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 (Get) and resource (allowed qualifiers/subheadings for a MeSH descriptor), which is unambiguous. It distinguishes itself from mesh_descriptor, mesh_search, and mesh_tree by naming the distinct concept of qualifiers/subheadings.

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 three concrete scenarios: finding combinable qualifiers, building precise MeSH queries, and understanding specifiable aspects. It does not explicitly name which sibling to use instead (e.g., mesh_descriptor for descriptor metadata), so it stops short of full alternative 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 cover read-only, idempotent, open-world, non-destructive behavior. The description adds real value beyond them: the language parameter returns NLM's official translations where they exist and content is never machine-translated, which is a meaningful data-quality disclosure for an agent judging result trustworthiness.

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

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

Purpose is front-loaded in the first sentence, followed by a scannable bullet list and a return-value line. Slight redundancy in repeating the language translation caveat that the schema already states.

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 little explanation, and the description still names the shape (descriptors with MeSH IDs and labels). Safety profile is carried by annotations. Complete for a search tool of this complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates the language behavior already documented in the schema and adds nothing about match modes or max_results semantics.

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 MeSH descriptors') and expands the acronym, so the agent knows exactly which vocabulary is being queried versus the ICD-10/LOINC/RxNorm search siblings. It does not explicitly distinguish itself from mesh_descriptor or mesh_tree, but the resource is unambiguous.

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

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

Three concrete use cases (indexing medical literature, PubMed subject headings, controlled vocabulary lookup) give clear context for when this tool applies. It stops short of naming alternatives or exclusions, e.g. that mesh_descriptor should be used once an ID is known.

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 the safety profile is covered structurally. The description usefully adds the output shape of tree numbers (e.g., C14.280.647) but says nothing about error handling for non-descriptor IDs or qualifier IDs. With annotations carrying the behavioral load, a 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?

The purpose sentence is front-loaded and the supporting bullets are short and scannable. The bullets partly restate the opening sentence's idea (hierarchy location vs. broader/narrower relationships), so there is mild redundancy, but 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?

With an output schema present, annotations covering the safety profile, and a fully documented single parameter, the description only needs to frame intent — which it does. The tree-number format example helps an agent interpret the response, though it doesn't note what happens for qualifiers or invalid IDs.

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

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

There is a single parameter with 100% schema description coverage, including a regex pattern and examples (D015242, D003920), so the schema does the heavy lifting. The description adds no additional meaning about mesh_id beyond what the schema states, which is the expected baseline of 3.

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+resource ('Get the tree hierarchy location(s) for a MeSH descriptor') and clarifies that output is hierarchical tree-number paths, which distinguishes it from a plain descriptor lookup. It does not explicitly name mesh_descriptor or mesh_search as the alternatives, so differentiation from those siblings is left implicit.

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

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

The 'Use this tool to' block supplies three concrete scenarios (locating a term in the hierarchy, reading broader/narrower relationships, finding branch siblings), which is clear positive context. However, it offers no exclusions or prerequisites — e.g., that a descriptor ID must be obtained from mesh_search first — 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 declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered elsewhere. The description adds only that results include class IDs, names and classification sources, and says nothing about behavior for an invalid or non-existent RxCUI. Some added value, but modest.

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 short scannable bullets and a returns line. Slightly redundant because the bullets and the returns line partially restate the purpose and duplicate the output schema.

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

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

With a rich annotation set, a documented single parameter and an output schema in place, the description covers what an agent needs to select and call the tool. Only minor gaps remain, such as behavior on an unknown RxCUI or how multiple classification sources are ordered.

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

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

There is a single parameter (rxcui) with 100% schema description coverage, so the schema already carries the semantics. The description adds no format, range, or resolution guidance beyond what the schema states, which is the expected baseline when schema coverage is complete.

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: fetching therapeutic and pharmacologic drug classes for a given drug. It is clearly distinct from siblings like rxnorm_ingredients or rxnorm_ndc, but it never names or contrasts those siblings, so the differentiation is left to inference.

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 use-case context (drug class lookup, therapeutic categories, mechanism of action), but they largely restate the opening sentence rather than adding new guidance. No when-not-to-use condition and no named alternative (e.g., rxnorm_concept) is offered.

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 adds value by disclosing what content comes back (name, synonyms, status, related concepts), but says nothing about error behavior for an unknown RxCUI, remapping behavior, or rate/auth context.

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

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

Front-loaded with the core purpose, then a compact bullet list, then parameter guidance. The closing sentence on RxCUI formatting largely repeats the schema, which is a small redundancy, but overall the structure is tight 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 an output schema present, return-value structure need not be described, and the annotations carry the safety profile, so the remaining burden is light. The description covers purpose, use cases, and both parameters adequately; only the routing against rxnorm_search is left implicit.

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

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

Schema description coverage is 100%: both rxcui and include_related are documented in the schema, including the string-or-integer duality and the default for include_related. The description's restatement of the RxCUI format and the '161' example duplicate the schema rather than extending it, 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 detailed information about a specific RxNorm concept') and scopes it to an identifier lookup ('by RxCUI'), which inherently separates it from name-based siblings like rxnorm_search. An agent can identify this as the ID-based detail lookup without opening the schema.

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

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

The bulleted use cases ('get full name and synonyms', 'check concept status', 'view related concepts') give clear context for when this tool applies. However, it never names an alternative or an exclusion — it doesn't tell the agent to prefer rxnorm_search when it only has a drug name, which is the most likely confusion among these 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 readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety and determinism profile is covered. The description adds the return shape ('ingredient RxCUIs and names') but says nothing about behavior for invalid RxCUIs, missing ingredients, or multi-ingredient products beyond a use-case mention. Useful but modest added value over 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?

Short and front-loaded: the core operation is stated first, followed by a compact bullet list and a one-line return note. The first bullet largely restates the opening sentence, a minor redundancy, 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, the description need not document return values, and annotations cover the safety profile. The remaining minor gaps are failure/edge-case behavior (invalid or unknown RxCUI, products with no ingredient data), which an agent could reasonably want to know.

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% for the single 'rxcui' parameter, so the schema already carries the semantic load. The description only echoes the parameter ('by RxCUI') without adding format expectations, accepted value sources, or error behavior. Baseline 3 is appropriate when the schema does the work.

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

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

The opening sentence gives a specific verb and resource ('Get active ingredients for a drug by RxCUI'), which is functionally distinct from siblings like rxnorm_concept, rxnorm_classes, rxnorm_ndc, and rxnorm_search. An agent can tell immediately that this tool returns ingredient-level data rather than a full concept record or a code 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 bulleted use cases ('find active ingredients', 'check for single vs. multiple ingredient products', 'identify generic components of brand drugs') give clear context for when to reach for this tool. There is no guidance on when NOT to use it or which sibling to prefer for a related question (e.g., rxnorm_concept for full concept details), which keeps it out of the top band.

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 the safety profile is fully covered. The description adds the dual-mode behavior (input field determines direction of the mapping), which is useful, but says nothing about return shape, rate limits, or ambiguity handling.

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

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

Front-loads the core mapping statement, then uses a compact bulleted list for use cases and closes with the input rule. The bullet 'Cross-reference between coding systems' slightly restates the opening line, a minor redundancy.

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

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

With an output schema present the description needn't explain return values, and annotations cover safety. Coverage of when each input mode applies is adequate; the only gap is not stating NDC format expectations or what happens if neither parameter is supplied.

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 parameter descriptions already state the alternative relationship ('alternative to rxcui'). The description's either/or sentence largely restates that, so baseline 3 applies; format details for NDC (10/11-digit) are absent.

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 (map) and resource (RxNorm concepts ↔ NDC codes) and makes the bidirectionality explicit. An agent can distinguish it from rxnorm_concept, rxnorm_search, and the ATC/LOINC 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?

Three concrete use cases are enumerated and the input convention ('provide either an RxCUI ... or an NDC') is stated, so the agent knows how to invoke it. No exclusions or alternative-tool routing (e.g. when to prefer rxnorm_concept) are given, keeping it 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, openWorldHint and destructiveHint=false, so the safety profile is covered without the description's help. The description adds that results carry RxCUI identifiers, names, and term types, but that return-value detail is already available through the output schema, so the added value is modest.

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 short bulleted use-case list and a return-value sentence; nothing is wasted. The bullet framing is slightly padded but still efficient and skimmable.

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 complete input schema, and an output schema that carries the return structure, the description supplies everything needed to call the tool correctly. Only the sibling-routing question is left open, which is a minor gap for a search entry point.

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% – both 'query' (brand or generic) and 'max_results' (1-100, default 25) are fully documented in the schema. The description adds no syntax, matching behavior, or format hints beyond that, 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?

States a specific verb+resource ('Search for drugs in RxNorm') and even expands the acronym as 'Normalized names for clinical drugs'. It does not, however, distinguish itself from siblings like rxnorm_concept, rxnorm_classes, or rxnorm_ingredients, so the agent must infer which RxNorm entry point 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?

Three explicit use cases are given (find by brand/generic name, look up medications for prescribing, search formulations), which cleanly tells the agent when this tool applies. There are no exclusions or named alternatives, so the agent gets context but no routing guidance against sibling tools.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description still adds real context beyond them: result count cap (10), relevance ordering, empty-list semantics, and that the catalog is fetched from a public source and cached in memory. It stops short of describing pagination or latency, but that is minor 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 purpose and return shape, then usage routing, then query semantics and behavior. Some redundancy (the accent/case note repeats the schema, and the catalog framing appears twice), but every block 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?

An output schema exists so return values need not be spelled out, yet the description still names the {id, title, url} shape and the empty-result case. Combined with the explicit sibling routing for a large tool set, 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?

Only one parameter and schema description coverage is 100%, so the schema already documents `query` fully. The description's note on natural language vs keywords, Portuguese/English, and accent/case insensitivity largely restates the schema. Baseline 3 applies since the schema carries the load.

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

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

States a specific verb (searches) and resource (the medical terminologies catalog), names the domains covered (CID-10, ICD-11, LOINC, RxNorm, MeSH, version records), and explicitly distinguishes itself from the sibling terminology tools by calling itself 'a catalog index, not a data query'.

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

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

Gives explicit when-to-use (the OpenAI Deep Research contract requiring exactly `search` and `fetch`), the follow-up action (pass an id to `fetch`), and a clear when-not-to-use with named alternatives (prefer `icd11_*`, `cid10_*`, `loinc_*`, etc. for actual data). 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, and the description layers on substantial behavioral context beyond them: the server doesn't ship historical snapshots, bundled_versions lists what's on hand, and the ICD-10 case returns concrete fields (1:1 vs split counts, average alternatives). It even sets expectations about the tool being a metadata layer rather than a diff engine.

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

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

It is front-loaded with the core distinction and uses a clean bulleted input list, but it is fairly long and the closing paragraph restates the 'metadata + guidance layer, not a diff engine' framing already implied by the opening. Slight redundancy, though every block is informative.

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 metadata/guidance tool with an output schema already present and annotations covering safety, the description supplies everything an agent needs: which terminologies get real data, the special ICD-10 invocation, param defaults, and a fallback source. No material gap remains.

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

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

Schema coverage is 100%, so the schema already documents all three params, but the description adds real semantic value: it explains the default behavior when from_version or to_version are omitted (report against bundled version / publisher's latest), and that the terminology value changes the entire behavior model. This goes beyond the terse schema descriptions.

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

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

The description states a specific verb+resource ('report what diff data is available between two versions of a terminology') and immediately disambiguates it from being an actual diff engine. It also delineates itself from siblings like terminology_versions and map_icd10_to_icd11 by naming exactly which terminology surfaces real cross-revision data.

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

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

It gives explicit when-to-use guidance: guidance-only for most terminologies, real cross-revision summary for ICD-10 vs ICD-11, and it names the exact call pattern ('terminology: "icd10"' with no to_version). It further routes the agent to the publisher's official changelog as the authoritative source for fast-moving 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?

Annotations already declare readOnly/idempotent/openWorld/non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: the ICD-10 → ICD-11 entry is read live from the bundled dataset while all others are release-maintained metadata, and the full set is 7 entries. It stops short of stating whether the live read can differ between calls.

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, followed by a compact bulleted list of use cases and a filtering note. Every sentence carries information, though the three bullets are slightly verbose for what amounts to a single 'check versions before running' idea.

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 only one optional enum parameter, an output schema present, and rich annotations, the description covers everything an agent needs: what is listed, default vs filtered behavior, the live-vs-static distinction, and the motivating use cases. No material gap remains.

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 values are already documented, so the baseline is 3. The description adds value by stating the default behavior ('omit to return all 7') and the cardinality of the unfiltered result, which the schema alone does not convey.

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 enumerates exactly what is returned (version, release date, publisher, source URL, update cadence) for every terminology the server queries against. This is clearly distinct from the many lookup/search siblings, which operate on codes rather than server metadata.

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

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

Gives concrete when-to-use contexts: confirm releases before a batch run, verify bundled/frozen table versions, cite versions in research. It does not explicitly name an alternative (e.g. terminology_diff) or state when-not to use it, so it falls short of a 5.

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

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

Goes well beyond the annotations (which only declare readOnly/idempotent/openWorld/non-destructive) by disclosing the error-vs-not-found contract, that `active` is null for most terminologies and boolean only for LOINC, that `replaced_by` is populated only for ICD-10 with WHO transition tables, the 50-code hard cap, and worst-case ~10 s latency from parallel upstream clients and 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?

Front-loads the purpose and use case, then structures return semantics as a scannable list. It is on the long side and the return-field block partially overlaps the output schema, but the null/error nuances are non-obvious and earn their space.

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 batch validation tool with an output schema, an open-world upstream dependency, and a hard cap, the description supplies everything an agent needs: input shape, terminology requirement, failure semantics, and latency expectations. Nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it enumerates the accepted terminology values and justifies why terminology is required per code (category codes like "A00" are ambiguous between ICD-10 and CID-10), plus the per-call cap rationale. This is value beyond the schema's field descriptions.

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

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

States a specific verb (validate) and resource (a mixed batch of medical codes against their source terminologies), and the batch framing distinguishes it from the per-code lookup siblings like icd10_lookup and icd11_lookup. An agent can identify the tool's role without opening the schema.

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

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

Gives clear context for use — retrospective analysis of legacy databases, flagging dead codes, surfacing ICD-10 → ICD-11 replacements. However, it never explicitly names an alternative or states when NOT to use it (e.g. for single-code validation where a lookup sibling would suffice), so routing is inferred rather than spelled out.

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