Medical Terminologies MCP

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

Annotations already declare read-only, idempotent, open-world, non-destructive behavior, so the safety profile is covered. The description adds genuinely useful context beyond them: return cardinality (one entry per ATC code; single-ingredient vs. combination products) and provenance (WHO ATC codes retrieved via NLM RxClass).

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 in the first sentence and organized with a scannable bullet list. There is mild redundancy between the 'find the ATC code' and 'cross-reference drugs with their international ATC codes' bullets, but nothing is seriously padded.

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

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

For a one-parameter lookup with a full output schema and rich annotations, the description covers the essentials and even explains return cardinality. It omits error behavior for unrecognized drug names and, more importantly, sibling differentiation against atc_lookup/atc_members.

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

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

Schema coverage is 100% and the single parameter is already documented as accepting brand or generic names with an example, so the structured data does the heavy lifting. The description's example ('metformin' → A10BA02) adds a little value but no syntax or matching-rule detail beyond the schema.

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

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

States a specific verb and resource ('look up the WHO ATC classification(s) for a drug by name') and gives a concrete output example (metformin → A10BA02), so the purpose is unambiguous. However, it never distinguishes itself from the sibling tools atc_lookup and atc_members, which is exactly the ambiguity an agent faces in this tool set.

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 usage context (find a code, get the class hierarchy, cross-reference medicines), but they elaborate the purpose rather than giving when-to-use conditions or exclusions. With atc_lookup and atc_members present, the description provides no basis for choosing between the three ATC 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 the safe, read-only, idempotent, open-world profile, so the description needn't restate safety. It adds real behavioral context: what is returned (name + hierarchy level) and the endpoint's limitation that substance-level codes are not exposed. It does not cover error behavior or pagination, but those are minor for a single-code lookup.

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

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

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

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

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

The tool has an output schema, so return values needn't be explained, and the single required parameter is fully documented. Combined with the explicit sibling routing and level taxonomy, an agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes beyond the schema by mapping each length to a semantic level (A=anatomical, A10=therapeutic, A10B=pharmacological, A10BA=chemical), giving the agent meaning for the allowed pattern rather than just its shape.

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

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

States a specific verb (look up) and resource (ATC code) and the output (name and hierarchy level). It explicitly distinguishes itself from the sibling atc_classify by scoping to levels 1-4 and routing substance-level codes elsewhere.

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

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

Lists three concrete use cases (resolve to class name, confirm existence, identify level) and names the alternative atc_classify along with the exact condition (7-char substance codes) that selects it. Nothing is left to inference.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, openWorld), so the description earns credit for adding non-obvious context: that each member carries a substance-level source_atc_code for disambiguation, and that RxNorm's catalog is US-centric while ATC names/codes are international. It does not mention result volume or pagination for large classes, which would be the next useful disclosure.

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

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

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

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

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

For a single-parameter read tool with an output schema present, the description supplies purpose, usage contexts, parameter levels, an output field note, and a data-provenance caveat - enough to call it correctly. What is missing is only operational detail such as result size for high-level classes.

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

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

Schema description coverage is 100% and the schema already states the level 1-4 vs level-5 return behavior, so the baseline is 3. The description reinforces this with the 'A10BA' example but adds little syntax or format detail the schema does not already carry.

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

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

Specific verb + resource ('List the drugs (substances) that belong to an ATC class') with a concrete example ('A10BA' -> metformin, phenformin). The subtree/level framing implicitly separates it from atc_classify (drug -> class) and atc_lookup (code -> meaning), so an agent can route without opening schemas.

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

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

The 'Use this tool to:' block gives three clear contexts (enumerate class members, build mechanism-shared drug lists, explore a subtree). It does not name any sibling as the alternative or state when NOT to use it, so routing against atc_lookup/atc_classify is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description adds only the shape of the result (chapter → groups with code ranges), which is modest additional context and not rich behavioral disclosure.

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

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

Front-loaded purpose, followed by a compact usage list and the parameter hint. The parenthetical example is a bit long but earns its place by showing the group format. No wasted filler.

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

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

With an output schema present, the description need not explain return values; purpose, usage contexts and the required parameter are all covered. It is nearly complete, though a one-line note distinguishing it from cid10_chapters would close the remaining gap.

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 param is fully documented in the schema (range 1-22, 'CID-10 V2008 has 22 chapters'). The description merely repeats 'Provide a chapter number (1-22)', adding no meaning beyond the schema, so the baseline 3 applies.

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

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

The first sentence states a specific verb and resource ('Get one CID-10 chapter and its constituent groups') and the example makes the return shape concrete. The singular 'chapter' plus 'its constituent groups' naturally distinguishes it from the plural sibling cid10_chapters, though no sibling is named explicitly.

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

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

The bullet list gives clear usage contexts: drilling into groups, building hierarchical browsers, and locating which group contains a code range. It supplies no exclusions or explicit alternative (e.g., when to use cid10_lookup or cid10_chapters instead), 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 read-only, idempotent, and non-destructive behavior, so the bar is lower. The description adds genuinely useful context beyond them: the fixed 22-entry result size and the caveat that CID-10 V2008 has not been updated since 2008, which signals a static dataset. No contradiction with annotations.

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

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

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

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

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

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

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

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

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

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

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

States a specific verb (List) and resource (the 22 chapters of CID-10), plus exactly what each entry contains (code ranges and Portuguese titles). The count '22' and the sample entries make the scope unambiguous.

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

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

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

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

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

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

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

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

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

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

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

For a single-parameter, read-only lookup with an output schema and full annotation coverage, the description supplies everything needed: what it returns, accepted input forms, and use cases. Nothing an agent needs to invoke it correctly is missing.

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

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

With a single parameter at 100% schema description coverage, the schema already documents the code field, its pattern, and its dotted/undotted acceptance. The description largely restates that same dotted/undotted flexibility, adding little new parameter-level meaning, so the baseline 3 applies.

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

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

States a specific verb and resource ('Look up a specific CID-10 code') and scopes it to an exact-code resolution with an example ('I21' → 'Infarto agudo do miocárdio'), which implicitly separates it from the search-oriented sibling cid10_search. It never names that sibling explicitly, so differentiation must be inferred.

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

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

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

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds genuinely non-obvious behavior: diacritic-insensitivity, AND-between-words matching, and the vocabulary-normalization layer (câncer→neoplasia maligna, AVC→acidente vascular cerebral) surfaced via vocabulary_notes in the response. It also states the return granularity (3-char categories and/or 4-char subcategories).

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

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

Front-loads what the tool is, then bullets for usage, then matching semantics, then the sibling alternative. Every sentence carries information, though the parenthetical expansion of the CID-10 acronym and the example list make it longer than strictly necessary.

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

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

An output schema exists so return values needn't be explained, annotations carry the safety profile, and all three parameters are documented. The description supplies the domain-specific matching rules that are the real risk of misuse, leaving nothing an agent needs missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by explaining what 'categories' and 'subcategories' mean in practice (3-char vs 4-char) and elaborating the query normalization behavior. It adds little on max_results, which the schema already bounds.

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

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

States a specific verb (search) and resource (Brazilian CID-10), including the language constraint (Portuguese text). It explicitly contrasts itself with icd11_search, so an agent can route between them without opening either schema.

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

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

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

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

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

Annotations already declare readOnly/idempotent/non-destructive/open-world, so the safety profile is covered. The description still adds real context beyond them: an unknown id returns an error, and the fetch is a live GET against the public source rather than a cache hit. That error and live-fetch disclosure is valuable, though it does not cover rate limits or pagination.

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

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

Front-loads what it returns before explaining context, and each block (return shape, contract/catalog scope, id validity, sibling routing, behavior) earns its place. Slightly long with three paragraphs for a one-parameter tool, but 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 values are already structured, yet the description still summarizes the payload and adds error behavior, catalog scope, and routing to sibling tools. An agent has everything needed to call this correctly in the Deep Research contract.

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 describes the single `id` parameter as coming from `search`, so baseline is 3. The description adds the consequential constraint that only ids from `search` are valid and that an unknown id produces an error, which meaningfully augments the 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 and resource ('Returns the full document for an id obtained from `search`') and specifies the exact return shape ('{ id, title, text, url, metadata }'). It names its sibling `search` as the source of the id, so an agent can instantly distinguish fetch (retrieve full doc) from search (find ids).

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

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

Explicitly states the prerequisite that only ids returned by `search` are valid and that unknown ids error, and it names the alternative set — the `*_*` terminology tools plus `find_equivalent`/`validate_codes` — as the tools for actual data queries. This is clear when-to-use and when-not-to-use 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 readOnly/idempotent/non-destructive/openWorld, and the description still adds real behavioral context: match_score and rank are server-computed because upstreams expose no comparable relevance scores, results are clustered into groups, absence of a group is explicitly NOT evidence of non-equivalence, and the search corpus is English-only. These are interpretive details an agent needs and cannot get from 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?

Purpose is front-loaded, then bulleted use cases, then parameter mechanics, then the clustering caveat and language limitation. Generally dense and every sentence carries weight, though slightly long and mildly repetitive in restating the terminology coverage.

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 handles everything else: search scope, fan-out behavior, ranking provenance, grouping semantics with an important caveat, English-only limitation, and routing to pt-BR alternatives. An agent has all it needs to select and call this tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description earns above baseline by explaining how the two terminology parameters combine ('source is subtracted from targets') and restating the limit default/max, though much of this duplicates the 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?

States a specific verb+resource ('Ranked unified search for equivalent terms') and immediately bounds the scope with the exact terminologies searched (ICD-11, SNOMED CT, LOINC, RxNorm, MeSH). This clearly separates it from siblings like terminology_diff, map_icd10_to_icd11, and the single-terminology *_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?

Provides explicit use cases (find the same concept across coding systems, compare representations, support mapping/integration) and names concrete alternatives with their trigger condition — for pt-BR content use icd11_search/mesh_search with language "pt" or cid10_search. It also tells the agent how to select between source_terminology and target_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, non-destructive, and open-world, so the safety profile is fully covered. The description adds only the fact that there are 28 chapters; it says nothing about whether the list is cached, how translations behave, or pagination, though the translation behavior is handled in the 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-loaded with the core action, then a short scannable list, then a useful structural fact. No filler, though the three bullets are partly output-oriented rather than guidance.

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 safety, the description need not explain return values. It is sufficient for a no-required-parameter list tool, missing only explicit routing to sibling navigation/search tools.

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 language parameter is documented in detail there, including the official-translation caveat. The description adds nothing beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('List all ICD-11 chapters') and immediately clarifies the granularity ('top-level categories'), which distinguishes it from icd11_hierarchy, icd11_lookup, and icd11_search. An agent can tell what it 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' list gives real context (overview, locating the chapter for a body system, navigating onward), which implies when it fits. However, it never names alternatives such as icd11_search for conditions or icd11_hierarchy for drilling down, and the bullet 'Navigate to specific disease categories' describes an outcome rather than this tool's scope.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld). The description adds genuine behavioral context beyond that: blocks return with an empty code and a code_range, and translations return the source's official translation and are never machine-translated. It does not need to explain return shape further since an output schema exists.

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

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

Front-loads the purpose, then a scannable bullet list of uses, then a dense but relevant paragraph on code/uri semantics. Every sentence contributes, though the parameter paragraph is somewhat packed.

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

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

With an output schema present (no need to describe returns) and annotations carrying the safety profile, the description covers purpose, direction semantics, entity identification, language behavior, and the ICD-10 redirect. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema by clarifying that code may be a leaf code or a block range and that blocks arrive as empty-code results with a code_range. The relationship between uri provenance and prior tool calls is also made explicit.

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

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

States a specific verb and resource ('Navigate the ICD-11 hierarchy to find parent or child entities') and separates itself from siblings like icd11_lookup, icd11_search, and icd11_chapters. An agent can tell immediately this is a traversal tool, not a search or lookup tool.

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

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

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

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds behavioral context beyond that: language returns WHO's official translation and content is never machine-translated, which tells the agent what to expect from output. It does not clarify what happens when neither code nor URI is supplied (required params = 0), a minor gap.

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

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

Front-loaded with a clear one-line purpose, then a tight bullet list and an input-mechanics sentence. Every element is relevant, though the bullets weigh toward restating outputs rather than new information.

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

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

With an output schema present, return values need not be explained, and the definition covers both input modes (code or URI) plus the language behavior. Remaining gaps are the ambiguity when neither identifier is given and the lack of routing against sibling tools; both are minor given the rich structured metadata.

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 largely repeats what the schema already documents: the code example ('BA00') matches the schema example, and the official-translation note duplicates the schema text for `language`. It adds little semantic value beyond the structured fields, including no guidance on code-vs-URI precedence.

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 with scope ('detailed information about a specific ICD-11 entity by code or URI') and the bullet list enumerates what is returned (definition, notes, exclusions, title, synonyms). It implies the lookup-vs-search distinction by emphasizing a specific entity, but never names sibling tools like icd11_search or icd11_chapters, so an agent still has to infer the boundary.

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

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

The 'Use this tool to' bullets describe usage contexts, but they mostly restate return values rather than give routing guidance. There is no exclusion such as 'if you only have a text term, use icd11_search instead,' which is the key decision against the many icd11_* siblings. Usage is implied rather than explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered by structured data. The description's remaining value is conceptual — it explains that postcoordination adds severity/laterality/anatomy — which aids interpretation but adds no operational behavior (no failure modes, auth, or limits) beyond the annotations.

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

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

Front-loaded with the core verb+resource sentence, then a compact bulleted clarification of what the tool returns. No filler sentences, though the bullets restate the purpose somewhat rather than adding new information.

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

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

With an output schema present, return values need not be described, and the single required parameter is schema-documented. The description supplies enough domain context (what postcoordination means) for an agent to call it correctly; only routing relative to sibling ICD-11 tools is unaddressed.

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

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

Only one parameter with 100% schema description coverage, so the schema already documents 'code' fully. The description adds no syntax, format, or versioning detail about the code beyond what the schema says; 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 postcoordination information for an ICD-11 code') and the bullet list clarifies what 'postcoordination information' concretely means (axes, required/optional, extensions). It implicitly distinguishes itself from lookups like icd11_lookup or icd11_hierarchy, though it never names a sibling to route against.

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 use cases (build composite codes, check required vs optional, explore extensions), which is solid context for when to reach for it. There is no explicit when-not guidance or named alternative among the many ICD-11 siblings, 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 readOnly/idempotent/openWorld/non-destructive, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: results come from WHO official translations and are explicitly 'never machine-translated,' plus a note on the return shape (codes, titles, relevance scores).

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

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

Front-loaded with purpose, then scannable bullets, then return info – a sensible structure. Minor redundancy in restating the language/translation behavior that the schema already carries, but nothing is bloated.

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

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

With an output schema present and full annotation coverage, the description need not detail return values or safety. It covers purpose, use cases, language semantics, and a brief return summary; the only real gap is the absence of sibling routing for a namespace dense with search/lookup alternatives.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters well. The description's explanation of `language` (official Portuguese labels instead of machine translation) largely repeats the schema's own description, adding only the concrete pt-BR example.

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

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

States a specific verb and resource ('Search for medical conditions, diseases... in ICD-11') with an expansion of the acronym. It does not, however, differentiate itself from close siblings like icd11_lookup, icd11_hierarchy, or cid10_search, so an agent must infer the distinction from the name alone.

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

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

The 'Use this tool to' bullets sketch intended scenarios (find codes, search by name/keyword, multi-language lookup), which implies usage. But there is no when-not guidance and no explicit routing versus icd11_lookup or the CID-10/Loinc search siblings, leaving selection to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds the applicability constraint for non-question codes, which is genuinely useful, but says nothing about the return shape for codes without answer lists or error behavior. With annotations carrying the main burden, this is a modest addition.

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

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

Front-loaded with the core action, then a short bulleted list of use cases and one constraint sentence. Slightly padded by the three bullets, but each line is relevant and there is no filler.

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

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

An output schema exists, so return values need no explanation. Combined with the applicability caveat and use cases, an agent has enough to invoke this correctly; the only slight gap is behavior for codes lacking defined answer sets.

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 there is a single parameter whose pattern and example are fully documented in the schema. The description adds no syntax or format detail beyond it. Baseline 3 when the schema does the heavy lifting.

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

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

States a specific verb and resource: 'Get the list of valid answers for a LOINC questionnaire item.' An agent can tell this apart from loinc_details and loinc_panels by the resource. It stops short of explicitly naming a sibling alternative, but the scope is unambiguous.

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

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

Gives three concrete use cases (find response options, answer codes for validation, standardized answer lists) and an explicit exclusion ('Only applicable to LOINC codes that represent questions with defined answer sets'). No alternative tool is named for the exclusion case, 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/destructiveHint, fully covering the safety profile, so the bar is lower. The description adds only return-content context, which the existing output schema also supplies, and says nothing about pagination, auth, or error cases.

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

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

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

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

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

For a single-parameter, fully-annotated read tool with an output schema, the description is complete enough to call correctly. The only gap is routing guidance against the many sibling lookup tools, which is small given how simple invocation is.

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

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

Schema description coverage is 100% and the lone parameter already carries its own description and a regex pattern. The description restates the same format ('XXXXX-X') and example, adding no semantics beyond the schema, so baseline 3 applies.

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

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

States a specific verb+resource ('Get detailed information about a specific LOINC code') and enumerates the returned fields, which distinguishes it from the search/list family. It never names the sibling it complements (e.g. loinc_search, loinc_answers), so sibling differentiation is implied rather than explicit.

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

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

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

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

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

Annotations already establish readOnly, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds only the return summary (list of member LOINC codes), which is minor given an output schema exists.

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

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

Front-loaded purpose sentence followed by a tight, scannable bullet list. Slightly repetitive in restating 'structure' twice, but overall efficient.

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

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

A simple read-only, single-parameter lookup with an output schema: purpose, use cases, and return type are all stated. Minor gap is the lack of sibling disambiguation, but nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100% with a single documented, patterned loinc_num, so the schema carries parameter meaning. The description adds no format or syntax detail beyond it, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Get the structure of a LOINC panel or form') and reinforces it with concrete examples (CBC, metabolic panel). It does not explicitly differentiate from siblings like loinc_details or loinc_search, so it falls short of a 5.

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

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

The 'Use this tool to:' bullets give clear usage contexts (panel contents, form structure, grouped observations). There are no exclusions or named alternatives, so it stops short of the explicit when/when-not routing that earns 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 fully covered. The description's only added behavioral note is the shape of the return ('names, components, and properties'), which duplicates information better served by the output schema. Adds little beyond structured fields.

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

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

Front-loaded with a one-sentence definition, then scannable bullets, then the return summary. Sized appropriately, with only minor redundancy between the intro sentence's enumeration and the bullet list.

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

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

With annotations covering safety and an output schema covering the return shape, the description needs only to establish purpose and context, which it does. The remaining gap is disambiguation from sibling LOINC tools, which matters given this tool set's density.

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

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

Schema description coverage is 100% and both parameters (query, max_results) are fully documented in the schema with types, bounds, and defaults. The description adds no syntax, format, or matching-rule detail (e.g., partial vs exact matching), so the baseline 3 applies.

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

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

States a specific verb (Search) and resource (LOINC lab tests/clinical observations/measurements), which is unambiguous on its own. However, it never differentiates itself from the many LOINC siblings (loinc_details, loinc_answers, loinc_panels, map_loinc_to_snomed), so an agent must infer which LOINC tool fits.

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

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

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

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

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

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

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

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

Front-loads what the tool does, then explains return behavior, usage, coverage limits, input formats, and failure behavior. Each sentence adds distinct operational value with no filler.

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

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

Even with an output schema and safety annotations, the description supplies complete invocation context: scope, data source, coverage boundaries, accepted input formats, and what happens when no mapping exists. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the parameter is already documented with examples. The description adds useful semantic detail beyond the schema: both dotted and undotted code forms are accepted, and examples carry clinical labels such as 'E11' for Type 2 diabetes and 'A07.8' having four alternatives.

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

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

States a specific verb and resource: mapping ICD-10 codes to ICD-11 using authoritative WHO transition tables. It explicitly contrasts itself with fuzzy text-search candidates and defines coverage boundaries, so an agent can distinguish it from search/lookup siblings.

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

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

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

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

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

Annotations already declare readOnly/idempotent/openWorld/non-destructive, so safety is covered. The description adds the most important behavioral fact beyond annotations: it only returns guidance and performs no mapping, plus the licensing constraints that explain why. It stops short of describing what the guidance response actually contains, but the output schema covers returns.

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 critical caveat ('does not perform the mapping') before the rationale and alternatives. Every paragraph earns its place by preventing a likely mis-invocation, and it closes with the accepted input format.

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 no explanation. The description covers the one thing an agent could get wrong (assuming this performs a mapping), explains prerequisites, and points to real alternatives — everything needed to call it correctly.

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

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

Schema coverage is 100% with a regex pattern and an example, so the schema already documents the single parameter. The description repeats the format and adds a second example ('718-7'), which is marginal value over the schema. 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 (looks up) and resource (LOINC code in NLM Clinical Tables), then crucially clarifies what it does NOT do: 'It does not perform the mapping.' This distinguishes it from genuine mapping siblings like map_icd10_to_icd11, so an agent cannot confuse the two.

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 routing: use UMLS or the LOINC Expression Association files for programmatic mapping, and the SNOMED CT browser or RELMA for interactive lookup. Also states the licensing/prerequisite condition (UMLS license, authenticated loinc.org download), so usage conditions are fully specified.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds a genuinely useful behavior: translations are NLM's official ones and content is never machine-translated, which an agent could not infer from structured fields.

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

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

Front-loaded purpose followed by a compact bullet list; the bullets overlap somewhat with what the schema already conveys, but overall it is short and scannable.

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

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

With annotations covering safety and an output schema covering return shape, the description supplies the remaining essentials: the required ID pattern, the language option, and the translation guarantee. Adequate for a two-parameter lookup tool.

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

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

Schema coverage is 100% and both parameters are documented there, so baseline 3 applies. The description echoes the mesh_id example and language code example without adding syntax or constraints beyond the schema.

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

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

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

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

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

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

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

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

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

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

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

Well front-loaded: the core purpose is the first sentence, followed by scannable bullets and a concrete example. It is slightly redundant, since 'Find which qualifiers can be combined with a descriptor' restates the opening sentence, which keeps it off a 5.

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

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

An output schema exists, so return values need not be described. For a single-parameter read-only lookup, the description covers purpose, use cases, and the notation semantics; nothing essential is missing, though an explicit pointer to mesh_descriptor for the descriptor itself would complete the routing story.

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

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

Schema description coverage is 100% and the single mesh_id parameter is fully documented in the schema with a pattern and examples. The description adds no syntax, format, or validation detail beyond that, so the baseline 3 applies.

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

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

The opening sentence states a specific verb and resource: 'Get allowed qualifiers (subheadings) for a MeSH descriptor.' That is unambiguous and distinguishes it from the descriptor/lookup siblings. It stops short of naming an alternative (e.g., mesh_descriptor) to route the agent, so it lands at 4 rather than 5.

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

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

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

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

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

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

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

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

Front-loaded purpose sentence followed by a compact bullet list and a single sentence on language behavior and return values. Efficient overall, with only minor overlap between the prose language note and the identical schema text.

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

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

For a search tool whose annotations cover the safety profile and whose output schema exists, the definition supplies purpose, use cases, the non-obvious translation caveat, and the return shape. Nothing critical to correct invocation is missing.

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

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

Schema description coverage is 100%, including the match enum, language enum, and max_results bounds, so the baseline is 3. The description's language explanation with a 'pt' example largely restates what the schema already documents, adding little beyond it.

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

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

States a specific verb+resource ("Search for MeSH descriptors") and enumerates concrete use cases (indexing, PubMed subject headings, controlled vocabulary), which clearly separate it from lookup siblings like mesh_descriptor. It never names a sibling explicitly, so differentiation is functional rather than direct.

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

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

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

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and non-destructive behavior, so the safety profile is covered. The description adds genuinely useful return context by showing the tree-number format (e.g., C14.280.647 for Myocardial Infarction), which is not derivable from the annotations.

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

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

Front-loaded with the core purpose, then scannable bullets, then a concrete example. Slight redundancy between the opening line and the first bullet ('where a term fits in the MeSH hierarchy'), but nothing is wasted.

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

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

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

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

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

Schema description coverage is 100% with a single documented mesh_id parameter including its pattern and an example. The description adds nothing beyond the schema about the parameter, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get the tree hierarchy location(s) for a MeSH descriptor') and the bullet list narrows the scope to hierarchy/branch relationships. This is clearly distinguishable from siblings like mesh_descriptor, mesh_search, and mesh_qualifiers.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

States a specific verb and resource ('Get therapeutic and pharmacologic classes for a drug') with concrete examples (Beta-blockers, NSAIDs). It does not differentiate itself from siblings like rxnorm_concept or rxnorm_ingredients, which also serve the RxNorm space.

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

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

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

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds modest value by noting what data types are returned (status values such as active/remapped, related concepts), but says nothing about the data source, caching, or field completeness.

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

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

Purpose is front-loaded in the opening sentence and the bullet list is scannable without redundancy. It is slightly longer than strictly needed given the schema carries the parameter detail, but nothing is wasted.

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

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

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

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

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

Schema description coverage is 100%, so both parameters (rxcui and include_related) are already fully documented in the schema, including the string-or-integer format and the boolean/string acceptance. The description only repeats the RxCUI example, adding no meaning beyond the structured fields, so baseline 3 applies.

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

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

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

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

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

The 'Use this tool to' list gives positive use cases but no when-not guidance or named alternatives. It overlaps with siblings like rxnorm_ingredients (for 'ingredients') and rxnorm_search without clarifying which to pick, leaving the routing decision implied.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety and side-effect profile. The description adds that it returns ingredient RxCUIs and names, which is useful output context, though it doesn't describe error behavior or rate limits.

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

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

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

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

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

With one required parameter, 100% schema coverage, and a declared output schema, the description provides enough context to invoke the tool correctly. It could mention sibling alternatives for broader use-case routing, but it is largely complete.

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

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

Schema description coverage is 100%, so the schema fully documents the single 'rxcui' parameter with its type and pattern. The description does not add any syntax or format details beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'Get active ingredients for a drug by RxCUI.' It distinguishes the tool from sibling rxnorm_concept and rxnorm_search by focusing on ingredient-level lookup, and the bullet list clarifies the exact use cases.

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

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

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

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

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

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

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

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

Front-loaded with the one-line purpose followed by a short bulleted usage list; well sized. The usage bullets partially restate the opening line, but the redundancy is minor and it stays easy to scan.

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

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

An output schema exists, so return values need not be explained, and annotations carry the safety profile. The description covers the input modes adequately; only minor details (e.g., behavior if both parameters are omitted or supplied) are unaddressed.

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

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

Schema description coverage is 100%, so the two parameters are already documented as alternatives. The description restates the either/or relationship but adds no format, validation, or edge-case detail beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific verb (map) and both resources (RxNorm concepts / RxCUI and NDC codes), and makes the bidirectional nature explicit. An agent can distinguish this lookup/mapping tool from sibling search or concept tools without opening either schema.

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

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

It gives clear, enumerated usage cases: get NDCs for a drug by RxCUI, find the RxCUI for an NDC, or cross-reference systems. However, it names no alternatives or exclusions relative to siblings like rxnorm_concept or rxnorm_search, so a small inference gap remains.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety and idempotency profile is fully covered. The description adds only that results include RxCUI identifiers, names, and term types, which is largely redundant given the output schema exists. No auth needs, rate limits, or partial-match behavior are disclosed.

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

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

The purpose sentence is front-loaded and the bullet list is scannable and free of filler. Slightly more text than necessary for a two-parameter search tool, but nothing is wasted or duplicated.

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

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

With rich annotations, a fully described schema, and an output schema covering return values, the description needs only to convey purpose and scope, which it does. It falls short of 5 only because it leaves the boundary with sibling RxNorm tools (concept, ingredients, NDC) unstated.

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

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

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

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

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

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

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

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

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

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

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

Annotations already declare readOnly/openWorld/idempotent/destructive=false, so safety is covered. The description adds genuine behavioral context beyond them: a cap of 10 results, relevance ordering, empty-list semantics, and in-memory caching of a public-source catalog. Return field format is also stated, though that partly overlaps 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-loaded with purpose, then usage contract, then scope warning, then parameter and behavior notes. The Deep Research contract paragraph is a little dense but earns its place by justifying existence alongside richer siblings. No wasted sentences.

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

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

With an output schema present, return values need not be re-explained, and the description nonetheless covers result count, ordering, empty behavior, and the fetch follow-up. Purpose, usage, and behavior are all complete for a single-param 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 coverage is 100% and the single param is fully documented there. The description's note that queries accept natural language, Portuguese or English, with accents/case ignored largely repeats the schema's own parameter text, so it adds little beyond the structured field. 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 (searches) and resource (the medical terminologies catalog), names the exact data domains covered (CID-10, ICD-11, LOINC, RxNorm, MeSH, version records), and describes the return shape. It also explicitly distinguishes itself from the terminology tools, so an agent can tell what this is versus the ~30 siblings.

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

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

Gives explicit when-to-use (the OpenAI Deep Research contract requiring exactly `search` and `fetch`), when-not-to-use (direct questions and actual data should use the terminology tools), and names those alternatives. The `fetch` handoff for returned ids is spelled out.

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 readOnly/idempotent/openWorld, but the description adds rich behavior beyond them: that the server does not ship historical snapshots, that bundled_versions lists locally held versions, which specific fields the ICD cross-revision summary returns, and the omitted-argument defaults. This is exactly the governance context 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 and organized into behavior, special case, and inputs. Slightly long, and the 'guidance only' constraint is restated at top and bottom ('metadata + guidance layer, not a diff engine'), which costs a little economy.

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 three-parameter tool with an output schema, full annotation coverage, and enum constraints, this is complete: inputs, defaults, terminology-specific behavior, the ICD-11 special case, and the tool's limitations are all spelled out. No gap an agent would need to guess around.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning the schema lacks: what omitting from_version and to_version each do, and the special semantics of terminology='icd10' with no to_version. It stops short of documenting the enum values themselves, which remain entirely in the schema.

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

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

States a specific verb and resource ('Report what diff data is available between two versions of a terminology') and immediately qualifies the scope. It further distinguishes itself from siblings like terminology_versions and map_icd10_to_icd11 by clarifying that it is a metadata/guidance layer rather than a real diff engine.

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 tells the agent when the tool is useful (ICD-10 vs ICD-11 cross-revision summary with exact invocation), when it is guidance-only, and names the authoritative alternative (publisher's changelog) for fast-moving terminologies. The when-not condition is stated 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 declare readOnly/idempotent/non-destructive/openWorld, so safety is covered. The description adds genuine behavioral context: filtering returns one entry vs. the full set of 8, and that the ICD-10→ICD-11 version is read live from the bundled dataset while other versions are static project-release metadata. No return-format detail, but output schema exists.

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

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

Front-loads the core purpose in one sentence, then uses a compact bullet list tailored to the actual consumer. Slightly verbose in places (the research-artifact bullet) but every line adds a distinct use case; no filler.

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

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

For a read-only metadata tool with an output schema, the description adequately covers scope, filtering, result count, and the provenance of the version data. It need not explain return fields since the output schema does, leaving only minor gaps (e.g., freshness guarantees for the live-read entry).

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 enum is fully constrained, so the schema documents the input. The description nonetheless adds the default behavior ('omit to return all 8'), which is meaning beyond the schema's per-field documentation.

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

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

States a specific verb (List) and resource (version, release date, publisher, source URL, update cadence of every terminology), making scope unambiguous. It is clearly distinguishable from sibling tools like terminology_diff, map_icd10_to_icd11, and the various lookup/search tools, which all operate on codes rather than provenance 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?

Provides concrete when-to-use context via the maintainer personas (confirm release before batch run, verify frozen V2008 CID-10 and transition tables, cite data version in research). No explicit exclusions or named alternative for adjacent needs (e.g., terminology_diff), 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?

Beyond the annotations (readOnly/idempotent/openWorld true, destructive false), the description discloses a 50-code hard cap, parallel execution with ~10s worst-case latency tied to upstream rate limits, per-terminology null behavior for 'active', that 'replaced_by' is populated only for ICD-10, and the crucial error semantics distinguishing 'not found' from 'couldn't validate'. This is exactly the kind of operational context annotations cannot carry.

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

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

Purpose is front-loaded in sentence one and the parameter/behavior facts are well organized. However, the lengthy bulleted enumeration of return fields is partly redundant given a dedicated output schema exists, adding bulk that the schema already covers.

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 one parameter and an output schema, the description covers everything an agent needs: required per-code terminology with the reason it can't be auto-detected, the accepted enum values, the 50-code cap, latency expectations, and the null/error conventions. 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 description coverage is 100% and the schema already documents the codes array, the per-code code/terminology pair, the maxItems cap, and the auto-detection rationale. The description largely restates these facts rather than adding new parameter-level detail, so the baseline of 3 applies.

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

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

The opening sentence names a specific verb (validate) and resource (a mixed batch of medical codes) against source terminologies, and the retrospective-analysis framing distinguishes it from single-code lookup siblings like icd11_lookup or rxnorm_concept. An agent can tell what this does without opening any schema.

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

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

It states a clear context of use ('retrospective analysis of legacy databases') and enumerates the concrete outcomes (flag dead codes, surface ICD-10 → ICD-11 replacements, grade activity). It stops short of naming alternatives such as terminology_diff or map_icd10_to_icd11 or stating when NOT to use it, so no exclusions are provided.

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