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, but the description adds substantial context beyond them: one entry per ATC code, single-ingredient vs combination product behavior, the NLM RxClass data source, and critically the empty-`matches`-is-not-an-error semantics. That last point materially changes agent behavior on a failure path.

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 organized into bullets for use cases and a dedicated routing paragraph. Every section earns its place, though the tool-family routing paragraph runs somewhat long for a one-parameter lookup.

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 details are optional, yet the description still explains match cardinality and the empty-result case. Combined with the explicit sibling routing, an agent has everything needed to invoke this correctly.

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

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

Schema coverage is 100% and the single parameter is already documented, so the baseline is 3. The description goes further by specifying the accepted naming convention (brand or generic, English/US as in RxNorm) and the behavior on unrecognized input, which the schema does not convey.

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

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

States a specific verb and resource ('look up WHO ATC classification(s) for a drug by name') with concrete examples ('metformin' → A10BA02). It explicitly distinguishes itself from the sibling tools atc_lookup and atc_members, so an agent can route without opening any schema.

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

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

Provides explicit when-to-use guidance ('start here when you have a drug name'), names the two alternatives and the exact condition that selects each ('use atc_lookup when you already have a class code'; 'use atc_members to list the drugs inside a class'). Also gives a fallback path (rxnorm_search) for unrecognized names.

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 real scope behavior beyond that: the endpoint only exposes levels 1-4 and will not return substance-level codes, and it maps code length to hierarchy level. It does not say what happens on an unknown or malformed code, but the added constraint is valuable.

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

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

Front-loads the core purpose, then a scannable bullet list of use cases, then the length-to-level mapping and the exclusion. Efficient overall, though the substance-level caveat is repeated in both the description body and the schema parameter description.

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

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

An output schema exists, so return values need not be explained. The description covers scope, accepted input lengths with concrete examples, hierarchy levels, and the correct alternative for out-of-scope codes — 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% and the description restates the 1-5 char / 7-char exclusion, which is somewhat duplicative of the schema's own parameter description. However it adds semantics the regex alone cannot convey: the code-length-to-level mapping (A = anatomical, A10 = therapeutic, A10B = pharmacological, A10BA = chemical).

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 an ATC code at level 1-4 to get its name and hierarchy level') and scopes it precisely to levels 1-4. The concrete examples ("A10BA" → "Biguanides") make the resource unambiguous, and it is clearly separable from siblings like atc_classify and atc_members.

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

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

Explicitly enumerates three when-to-use cases (resolve a code, confirm existence, identify the level) and states an exclusion with a named alternative: substance-level 7-char codes are not exposed, so use atc_classify with the drug name instead. Nothing about routing 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 covered. The description adds useful behavioral context beyond annotations: each member includes source_atc_code for disambiguation at higher ATC levels, and RxNorm's catalog is noted as US-centric while ATC names/codes are international. It does not discuss rate limits, pagination, or auth, but those are less critical for a read-only 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?

The description is front-loaded with its purpose, followed by tightly scoped use-case bullets and a final contextual note. It is appropriately sized, though the three bullets for enumerating members, building mechanism lists, and exploring subtrees overlap somewhat, keeping it just short of maximal conciseness.

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, read-only list tool with an output schema and rich annotations, the description supplies everything needed: what it returns (member drugs with source_atc_code), how to interpret classes at different ATC levels, and a relevant catalog-origin caveat. No essential invocation or interpretation detail 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 input schema already explains that atc_code accepts any ATC level and that levels 1-4 return all member substances while level 5 returns a single substance. The description adds meaning with the concrete example 'A10BA' → metformin/phenformin and reinforces subtree exploration at any level, which helps an agent understand valid parameter values beyond the schema text.

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

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

The description states a specific verb and resource: listing drugs/substances belonging to an ATC class. It makes the tool's role clear through concrete use cases such as enumerating therapeutic class members and building mechanism-based drug lists. However, it does not explicitly differentiate itself from sibling tools like atc_lookup or atc_classify, 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:' section gives clear conditions for invoking the tool, including enumerating members, building pharmacological lists, and exploring ATC subtrees. It does not state when not to use it or name alternatives, so it lacks the exclusions and sibling routing that would earn a 5.

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

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

Goes well beyond the readOnly/idempotent/destructive annotations: out-of-range numbers 1-22 are rejected with a validation error, all groups are returned with no pagination, the 22 chapters hold 275 groups, and the data is served locally from the bundled V2008 with no network call. The only nuance is a mild tension with openWorldHint=true, since the description asserts purely local, pre-packaged behavior.

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

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

Front-loads the one-line purpose, then bullets the use cases and the sibling-routing guidance, so it is easy to scan. The illustration list inside the opening parenthesis is somewhat verbose, but every other sentence earns its place.

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

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

For a single-parameter lookup with an output schema present, the description still supplies the essentials an agent needs: valid range and rejection behavior, completeness of the group list (no pagination), execution model, and alternative tools. Nothing material is missing.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds real meaning: num is an integer 1-22 with worked examples (chapter I = 1, IX = 9) and the consequence of out-of-range values. That is more than the schema's bare min/max restatement.

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

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

States a specific verb+resource ("Get one CID-10 chapter and its constituent groups") and immediately disambiguates from siblings by naming cid10_chapters, cid10_lookup, cid10_search and icd11_chapters. An agent can distinguish this from the other CID-10/ICD-11 tools without opening any schema.

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

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

Explicitly enumerates use cases (drill into groups, build hierarchical browsers, find the group containing a code range) and routes to alternatives conditionally: use cid10_chapters first if the chapter number is unknown, cid10_lookup for a single code, cid10_search for Portuguese text. When-not conditions are effectively covered.

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

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

With annotations already declaring readOnly, idempotent, non-destructive behavior, the description adds useful context: it returns exactly 22 entries and notes that CID-10 V2008 has not been updated since 2008. That version/staleness note is valuable beyond the structured annotations, though it doesn't cover rate limits or other operational traits.

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

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

The description is front-loaded with the core action, then organized into a bulleted use-case list, and closes with a return-count/version note. It is appropriately sized, though '22 chapters' is mentioned twice and the bullets slightly overlap with the opening sentence.

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

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

For a simple, zero-parameter list tool with an output schema, the description covers purpose, usage scenarios, return shape (22 entries), and data version. 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?

The tool takes zero parameters, so there are no parameter semantics to explain. Per the rubric, zero parameters establish a baseline of 4; the description correctly focuses on output and scope rather than inventing parameter details.

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: 'List the 22 chapters of CID-10 with their code ranges and Portuguese titles.' It makes the top-level scope clear. However, it does not explicitly differentiate from the singular sibling 'cid10_chapter' or from 'cid10_lookup', leaving some potential ambiguity.

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:' section gives three concrete scenarios (view structure, map code ranges, build TOC), which is clear usage context. But it does not state when *not* to use it or name alternatives like cid10_lookup for single-code resolution, so it stops short of explicit routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, covering the safety profile. The description adds genuinely useful behavior beyond that (dotted/undotted input normalization and canonical display output), but since an output schema already exists, the stated return contents add little.

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 three tight bullets and a closing format note. Every line carries information; a small trim of the parenthetical examples is possible but nothing is wasted.

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

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

For a single-parameter lookup with a full output schema and complete annotation coverage, the description supplies all an agent needs: exact-match semantics, input normalization rules, and the fact that restriction flags may come back.

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 already documents its pattern and both accepted forms, so the description's 'Accepts both dotted and undotted forms' merely repeats the schema. Baseline 3 applies 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?

The description names a specific verb and resource ('Look up a specific CID-10 code and return its Portuguese name'), and 'specific' plus 'return its Portuguese name' signals an exact-match resolver. It never names the sibling cid10_search, so an agent must infer that lookup requires an already-known code rather than partial text.

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

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

Three explicit 'Use this tool to' bullets give clear positive conditions: resolve a code, confirm existence of a 3/4-char category, and pull restriction flags. No when-not guidance is offered, e.g. no routing to cid10_search for the case where the code is unknown.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond them: diacritic-insensitive matching, AND semantics across words, everyday-Portuguese-to-CID-10 vocabulary resolution with examples, disclosure that vocabulary_notes surfaces this, and the exact V2008 edition searched.

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

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

Front-loaded with the core action, then structured bullets and a closing sibling disclaimer. Slightly redundant (Portuguese-language scope restated), but every sentence carries usable information and the length is justified by the number of behavioral caveats.

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 available and annotations covering safety, the description supplies everything else an agent needs: edition, language, matching semantics, synonym handling, and the correct alternative 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%, so all three parameters are already documented in the schema. The description reinforces query semantics (AND, accents, vocabulary resolution) but adds little about the level enum or max_results beyond what the schema states. 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 and resource (search the Brazilian CID-10 by Portuguese text) and immediately names the sibling it is not (icd11_search for ICD-11). The scope is unambiguous relative to the many sibling search tools.

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

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

Explicit bullet list of when to use it (SUS/ANVISA lookup, official Portuguese translation, billing/epidemiology/documentation), plus an explicit exclusion routed to icd11_search with the reasoning (different revision, different language).

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. The description adds real context beyond them: only ids from `search` are valid, an unknown id returns an error, and a live GET hits the public source. The error behavior is the most valuable disclosure. Minor gap: no mention of rate limits or failure modes on the live fetch.

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?

Return shape and the search dependency come first, which is the right front-loading. Three compact paragraphs with no filler. The listing of individual terminology tool prefixes is slightly noisy but functional.

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

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

An output schema exists, yet the description still clarifies the two fields an agent must reason about (Markdown `text`, canonical `url`), covers the id contract, error behavior and the read-only live-fetch model. Nothing needed to call it correctly is missing.

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

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

One parameter documented at 100% schema coverage, so the baseline is satisfied. The description goes further by constraining provenance of the id ('only ids returned by `search`'), which the schema's terse 'Identifier of a document returned by `search`' only partially captures.

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 (Returns) and resource (the full document for an id), with the exact return shape ({id, title, text, url, metadata}) spelled out. It names its only companion, `search`, and states the id must come from it, so the agent can distinguish it from every sibling at a glance.

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

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

Explicit when-to-use ('id obtained from `search`') and when-not: it tells the agent that unknown ids error out and that data queries belong to the terminology tools (`icd11_*`, `loinc_*`, etc.). This routing guidance is exactly what separates it from the ~30 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds context they cannot: match_score/rank are computed by this server rather than upstreams, lexical-title clustering signals same-concept, absence of a group is explicitly NOT evidence of non-equivalence, the search is English-only, and limit is a cap because there is no stable cursor. These are non-obvious behavioral traits an agent needs.

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

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

Front-loaded with purpose, then a bulleted use-case block, then a scoped paragraph covering parameters and ranking semantics, then a routed language note. Dense but every sentence carries distinct information; nothing is redundant boilerplate.

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

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

Although an output schema exists and return values need not be described, the definition still explains the meaning of match_score, rank, and groups plus the important caveat about absent groups, and it maps the language limitation to the right sibling tools. Complete for an agent to invoke and interpret results 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 further by explaining the interaction rule (source is subtracted from targets), the default/max for limit, and why limit should not be used for paging. This adds genuine meaning beyond the per-field schema text.

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

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

Opens with a specific verb+resource ('Ranked unified search for equivalent terms') and immediately differentiates itself from the single-terminology siblings by naming the four upstreams it unifies (ICD-11, LOINC, RxNorm, MeSH). An agent can tell this is a cross-terminology mapping tool rather than another search tool 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?

Enumerates three concrete use cases (find same concept, compare representations, support mapping/integration) and explicitly routes pt-BR queries to alternatives ('icd11_search'/'mesh_search' with language:"pt", 'cid10_search'). The source_terminology note also states exactly when to use it ('when you already have a code from that terminology').

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

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

Goes well beyond the read-only/idempotent annotations: 50-term hard cap with a validation-error failure mode, dedup of repeated term+domain pairs, per-row error isolation (one failed lookup does not fail the batch), English-only searching, and an outbound third-party API call (WHO/NLM) with an explicit de-identify warning. This is unusually rich operational 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 with a one-sentence summary and organized into bullets, so the structure is good. It is nonetheless long, and a sizeable middle block defines output fields (match_score, match_type, matched_label) that an existing output schema may already carry.

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 mapping tool with nested-ish term objects, external API calls and a multi-state response, the description supplies limits, error semantics, dedup behavior, terminology routing and provenance guidance. An agent can invoke and interpret it without guessing.

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 nuance the schema lacks: domain-to-terminology routing detail (drug -> ingredients first plus ATC classes), the one-word-term rule, and why lab terms need specimen/property. It mostly restates schema-level constraints like the 50 cap.

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 (map a LIST of free-text clinical terms to standard codes) and frames it as the batch building block of a reviewable crosswalk. Clearly separable from siblings like find_equivalent (single term) and validate_codes (existing codes).

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

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

Explicit 'Use this tool to' bullets cover the three mapping scenarios, and the closing paragraph names alternatives with the exact condition that selects each: cid10_search for Brazilian Portuguese diagnoses, validate_codes for existing codes, find_equivalent for one term across all terminologies. When-to-use and when-not-to-use are both covered.

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

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

Goes well beyond the annotations: discloses the exact result size (28 entries, chapters 01-26 plus V and X), that there is no pagination, per-chapter failure semantics (failed entry keeps URI and carries an `error` instead of a title while the rest still return), and that results are cached so repeats are cheap. This is precisely the operational context annotations cannot convey.

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

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

Front-loads the core action, then organizes usage, return shape, failure behavior, and exclusions into short bulleted blocks. Despite covering a lot, every sentence carries distinct decision-relevant information with no repetition.

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

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

An output schema exists, yet the description still usefully summarizes the return shape and partial-failure model. Combined with the annotations (readOnly, idempotent, openWorld) and the routing guidance, an agent has everything needed 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% and the single enum parameter is already documented, so the baseline is 3. The description adds real meaning on top: that the parameter returns WHO's OFFICIAL translation when it exists, is never machine-translated, and that output is cached per language, which clarifies cost/behavior beyond the schema text.

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

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

States a specific verb and resource ('List all ICD-11 chapters (top-level categories) of the pinned WHO release') and names the alternatives it is distinct from (icd11_search, cid10_chapters). An agent can distinguish this top-level chapter lister from the search/lookup/hierarchy siblings without opening any schema.

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

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

Provides explicit 'Use this tool to' bullets (structure overview, chapter-to-body-system mapping, obtaining URIs to drill down via icd11_hierarchy) plus an explicit 'When NOT to use' clause routing to icd11_search and cid10_chapters. When-to-use, when-not-to-use, and alternatives are all present.

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

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

Annotations already declare readOnly/idempotent/openWorld/non-destructive, so the description wasn't obligated to cover safety. It adds genuine behavioral context anyway: that 'parents' can return block nodes with an empty code plus a code_range, and that language selection returns only official translations and never machine-translated content.

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 action, then uses a short bullet list for use cases and a compact paragraph for argument semantics. Slight redundancy remains, since direction and the code/uri roles are re-explained relative to the schema, but nothing is padding.

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

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

With an output schema present, return values need no explanation. The description covers argument sourcing, direction semantics, language behavior, and the ICD-10 pitfall, so an agent has everything needed to call this tool correctly on the first attempt.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: the code argument accepts either a leaf code or a block range, and blocks surfaced by 'parents' arrive with an empty code and a code_range, which tells the agent how to feed results back in.

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

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

States a specific verb (navigate/browse) plus resource (ICD-11 hierarchy) and immediately scopes the two modes (parents vs children) so the agent can distinguish it from icd11_lookup and icd11_search. The example codes and block-range mention make the operation concrete rather than abstract.

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 when-to-use cases (find parents, find children, understand structure), and it explicitly routes ICD-10 input to map_icd10_to_icd11 and points at icd11_lookup/icd11_search for obtaining a URI. It stops short of an explicit when-not-to-use statement against the other icd11_* siblings, so it is strong but not fully exhaustive.

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

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

With readOnlyHint/idempotentHint already carrying the safety profile, the description still adds genuine behavioral detail: single-entity return with no pagination, unknown codes yielding a "not found" error rather than an empty record, and a validation error when neither code nor uri is supplied. It stops short of mentioning auth/permissions or any rate limits, so it is strong but not exhaustive.

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, then bulleted capabilities, then parameter guidance, then exclusions — each block earns its place and nothing is repeated from the schema. No filler or redundant restatement of the title.

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

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

An output schema exists, so return shape needn't be explained; the description instead covers the things the schema doesn't — no pagination, not-found vs empty-record behavior, and the mutual-requirement of code/uri. For a 3-param read lookup this is complete enough to call correctly on the first try.

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

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

Schema coverage is already 100%, yet the description adds a constraint the schema cannot express: "at least one is required" for code/uri, which is invisible in the schema since required is empty. It also spells out the language semantics (WHO official translations, e.g. "pt", never machine-translated) and gives concrete code examples.

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

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

States a precise verb and resource ("Get detailed information about ONE ICD-11 entity") and immediately scopes the input to something the caller already holds ("a code or URI you already have"). This cleanly separates it from icd11_search (name→code) and icd11_hierarchy (parent/child traversal) 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?

Explicitly enumerates the intended jobs (definition, coding notes, inclusions/exclusions, title/synonyms) and closes with a "When NOT to use" block that names the correct sibling for each alternative case: icd11_search, icd11_hierarchy, map_icd10_to_icd11. Alternative routing is fully determined.

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 meaningful context beyond that: it discloses the empty-axes-list-not-an-error behavior and advises verifying with icd11_lookup if the result is unexpectedly empty, which is useful operational guidance.

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 definition is front-loaded with the purpose, then organized into usage bullets that each earn their place, without padding. It is slightly list-heavy, but every bullet adds distinct information rather than restating prior content.

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

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

Even though an output schema exists, the description still clearly summarizes the return shape (one entry per axis with axis_name, required, allow_multiple, value_count) and clarifies that value_count is a count, not the values. For a single-parameter read tool, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% with a single parameter that the schema already describes, so baseline is 3. The description adds a concrete example value ('BA00') and states the input expectations, providing marginal value beyond the schema's generic 'ICD-11 code' field description.

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 (List) and resource (postcoordination axes WHO allows for one ICD-11 stem code), and even qualifies the underlying data source (MMS linearization, pinned release). It clearly distinguishes itself from siblings like icd11_lookup and icd11_search by naming them explicitly.

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

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

It provides an explicit 'Use this tool to:' list of three concrete use cases and a 'When NOT to use:' section that routes the agent to icd11_lookup for empty codes and icd11_search for name-to-code resolution. Both when-to-use and when-not-to-use are covered, along with the alternatives.

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

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

Annotations already declare readOnly, idempotent, openWorld, non-destructive, so the safety profile is covered; the description goes further by disclosing that language results are WHO official translations and never machine-translated, and by naming the returned fields. That is real added context beyond the structured hints, though it omits pagination/empty-result behavior.

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

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

The description is front-loaded with the core purpose, then a scannable use-case list, then return shape and language caveat. Every sentence earns its place, though the language caveat partially duplicates the schema's own language description.

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

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

With an output schema present and annotations covering safety, the description needs only to frame usage and language nuance, which it does well. The remaining gap is routing guidance among the many ICD-11 siblings (lookup, hierarchy, chapters, postcoordination), which an agent must infer on its own.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: the language enum selects the source's OFFICIAL translation (e.g. 'pt' returns pt-BR labels) and is never machine-translated. The query parameter is only loosely described ('diagnoses', 'name or keyword'), matching the schema rather than extending it.

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

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

The description gives a specific verb and resource: search for medical conditions/diseases in ICD-11, with a parenthetical expansion of the acronym. It is unambiguous what the tool returns (matching entities with codes, titles, relevance scores), but it never differentiates itself from closely named siblings such as icd11_lookup or icd11_hierarchy, so it stops 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' bullet list gives clear contexts: finding codes for diagnoses, searching by name or keyword, and multi-language lookup. It tells the agent when to reach for this tool but offers no exclusions or routing advice (e.g., 'use icd11_lookup instead if you already have a code'), so it lacks the alternatives that would make it 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, and non-destructive. The description adds valuable edge-case behavior: empty list for valid codes without answer lists and a 'not found' error for unknown codes, plus score-null semantics. However, some listed return fields (code, text, display order) are likely covered by the output schema, reducing the net-new value.

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

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

Front-loads the purpose, uses a compact bullet list for use cases, then a returns paragraph and alternatives. Every sentence contributes; no redundancy.

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

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

With annotations and an output schema present, the description still covers purpose, usage conditions, alternatives, and error/empty-list behavior. An agent has everything needed to select and call the 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 single `loinc_num` parameter is fully documented in the schema (pattern and example). The description adds no syntax or format beyond the generic term 'LOINC questionnaire item' / 'LOINC code'.

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

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

States a specific verb 'Get' and resource 'list of valid answers for a LOINC questionnaire item', making the core purpose immediately clear. It also distinguishes itself from siblings by naming loinc_panels and loinc_search in the closing paragraph.

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

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

Provides a clear 'Use this tool to:' list and an explicit applicability constraint: 'Only applicable to LOINC codes that represent questions with defined answer sets.' It also names alternatives for related tasks (loinc_panels for whole questionnaires, loinc_search for name lookup).

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 structurally. The description adds the required input format constraint, but no failure behavior, coverage limits, or data provenance beyond that.

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

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

Short, front-loaded with the core action, and the format requirement is placed last where it belongs. The three-bullet return list is mildly redundant against the output schema, but it costs little and is scannable.

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

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

With an output schema present, the return-value detail need not be explained, and annotations cover the safety profile, so the description only needs to nail purpose and input format — which it does. The missing piece is sibling routing guidance, a minor gap for a single-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 description coverage is 100% for the single parameter, and the schema already carries both the pattern and the '2339-0' example, so the description's restatement of the format adds essentially nothing. Baseline 3 applies 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 detailed information about a specific LOINC code') and singles out the lookup-by-identifier case, which implicitly contrasts with the search-style siblings (loinc_search, loinc_answers). It stops short of naming those siblings explicitly, so an agent must infer the distinction rather than read it.

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 reads as a description of returned content rather than when-to-use guidance, and it names no alternative. The single-code framing implies a lookup scenario, but there is no explicit when-not or routing rule against loinc_search or loinc_panels.

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 only the return content ('list of LOINC codes'), which duplicates the existing output schema, and says nothing about behavior for a non-panel code or invalid LOINC number.

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

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

Front-loaded with the core action, followed by a short scannable bullet list. Minor redundancy: the final sentence restates the return value, which the output schema already documents, and the bullets largely rephrase the opening statement.

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

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

For a single-parameter read tool with an output schema and complete annotation coverage, the description supplies everything an agent needs to select and call it. Nothing critical is missing; edge-case error behavior is the only untold detail and is minor here.

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%: the single parameter loinc_num has a format pattern and an example ('2339-0'), so the schema carries full burden. The description adds no syntax, format, or constraint information beyond what is already in 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 and resource ('Get the structure of a LOINC panel or form') and clarifies the domain with examples (CBC, metabolic panel). It is clear what the tool does, but it never names the sibling it must be distinguished from, notably loinc_details, whose scope overlaps with 'structure' information.

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

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

The bulleted 'Use this tool to' list gives concrete usage contexts (seeing all tests in a panel, form structure, related observations). However, there are no exclusions and no explicit routing to loinc_details or loinc_search for non-panel lookups, so the agent must infer the boundary.

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 names, components, and properties, and the output schema already carries return structure. No extra behavioral context (matching behavior, ranking) is provided, so a 3 is appropriate.

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

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

Front-loaded with the core purpose, then structured use cases, then the return summary. The bullet list is slightly padded and the return sentence is partly redundant with the output schema, but there is little waste.

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

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

With annotations covering the safety profile and an output schema defining return values, the description only needs to convey scope and use cases, which it does. The one gap is not distinguishing search from the loinc_details/loinc_answers/loinc_panels siblings.

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

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

Schema description coverage is 100%, with both 'query' and 'max_results' fully documented including range and default. The description adds no syntax, matching rules, or format guidance beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource: 'Search for laboratory tests, clinical observations, and measurements in LOINC.' The examples (glucose, hemoglobin) anchor what is searchable. It does not, however, differentiate itself from sibling lookups like loinc_details, loinc_answers, or loinc_panels, 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 'Use this tool to:' list gives three concrete search scenarios, which is useful implied guidance, but there is no when-not condition and no named alternative (e.g., use loinc_details once you have a code). Usage is suggested rather than routed.

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 the safe read-only, idempotent profile, so the description's job is to add beyond that — and it does: dedicated release/version of the table, 11,243-category coverage with exclusions, alternative-candidate behavior for split concepts, and a deliberate 'no mapping' response instead of fuzzy fallback. Return shape is described but partly duplicated by the output schema.

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

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

Front-loaded with the highest-value sentence, and the coverage limit and no-mapping behavior are placed after the core capability where they belong. Mild redundancy in repeating the 'authoritative rather than text-search' framing, and five paragraphs is slightly more than needed.

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 returns, yet it still covers coverage limits, input formats, edge-case alternatives, and the no-mapping outcome. Nothing an agent needs to invoke and interpret this tool is missing.

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

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

Schema coverage is 100% and the schema carries the baseline examples, but the description adds real input semantics not present there: both dotted ('A07.8') and undotted ('A078') forms are accepted, and chapter/block codes such as 'A00-A09' are explicitly out of scope for input.

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

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

States a precise verb+resource pair ('ICD-10 → ICD-11 mapping') and immediately qualifies it as 'authoritative ... using WHO transition tables', which separates it from the search-based siblings like icd11_search and find_equivalent. An agent can identify its role without opening the schema.

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

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

Gives explicit use contexts (clinical coding, billing migration, retrospective analysis) and states the selection rule 'authoritative mapping rather than text-search candidates', which effectively routes away from icd11_search. It stops short of naming the alternative tool or stating when-not to use it.

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 openWorld, so the safety profile is covered. The description adds a meaningful behavioral nuance: translations are the source's OFFICIAL translation only and never machine-translated, which an agent cannot infer 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?

Front-loads the one-line purpose, then scopes usage with bullets, then gives the ID example — a clean top-down structure. Slight redundancy between the 'Provide a MeSH Descriptor ID' line and the schema, 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?

With an output schema present, return values need not be explained, and annotations cover safety; the description adds the translation caveat and ID format. The only real gap is routing guidance relative to mesh_search for obtaining the ID.

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

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

Schema coverage is 100%: mesh_id already documents its pattern and examples, and language already documents the enum, default, and official-translation behavior. The description's examples (D015242, language: 'pt') merely restate 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 and resource ('Get detailed information about a MeSH descriptor by ID') and enumerates the concrete payload (scope note, tree numbers, synonyms). The 'by ID' framing implicitly separates it from mesh_search and mesh_tree, but 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 'Use this tool to:' bullets describe what the tool returns rather than when to choose it over mesh_search (to find the ID) or mesh_tree (hierarchy browsing). Usage is implied by output content but no condition or alternative is 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, and an output schema exists, so the safety and return profile are covered. The description adds only the domain concept (qualifiers refine descriptors, with the 'Diabetes Mellitus/drug therapy' example), not behavioral traits like rate limits or error cases, so it is adequate but not rich.

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

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

Purpose is front-loaded in the first sentence, followed by a scannable use-case list and a clarifying example. Slight redundancy between the opening line and the first bullet ('Find which qualifiers can be combined with a descriptor') keeps it from a 5.

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

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

For a single-parameter read tool with a full output schema and complete safety annotations, the description supplies enough to call it correctly and understand the concept. It could note edge cases (e.g., descriptors with no qualifiers) but nothing essential 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% with a single fully documented mesh_id parameter including pattern and examples. The description adds no syntax or format detail beyond what the schema already 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?

States a specific verb and resource: 'Get allowed qualifiers (subheadings) for a MeSH descriptor.' This clearly distinguishes it in practice from siblings like mesh_descriptor and mesh_tree, though it never names an alternative tool explicitly, so it lands just short of the 5 bar for sibling differentiation.

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

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

The 'Use this tool to:' list gives three concrete scenarios (find combinable qualifiers, build precise search queries, understand specifiable aspects), which is clear usage context. However, it offers no exclusions or explicit when-not-to-use guidance or named alternatives.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world behavior, so the safety profile is covered. The description adds genuinely useful context beyond that: language returns NLM's official translations only and content is never machine-translated, plus a note on what the response contains (matching 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-loads the purpose in one sentence, then a short scannable bullet list, then the language caveat and return summary. The three bullets are near-duplicative of each other, costing a little density, but nothing is padded or off-topic.

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 in depth; the description still gives a one-line summary. With 100% schema coverage on all four parameters and full annotation coverage, the definition supplies what an agent needs to invoke the tool correctly, though it omits how results are ranked or truncated.

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 query, match, language, and max_results — baseline 3. The description's language sentence adds no meaning beyond the schema, which already states the identical 'official translation, never machine-translated' semantics, so it earns no lift.

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

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

States a specific verb and resource ('Search for MeSH (Medical Subject Headings) descriptors') and spells out the domain purpose in three bullets. It does not explicitly differentiate itself from siblings like mesh_descriptor or mesh_tree, so an agent must infer the split between searching, fetching a descriptor, and walking the tree.

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

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

The bulleted use cases ('find MeSH terms for indexing', 'look up subject headings for PubMed searches', 'find controlled vocabulary terms') imply when the tool is appropriate, but they largely restate the same scenario three ways. There is no guidance on when to prefer this over mesh_descriptor or mesh_tree, and no stated preconditions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety and repeat-call profile is fully covered by structured data. The description's one genuinely additive piece of behavior is the tree-number format example (C14.280.647), which helps an agent interpret output, but it says nothing about multi-branch placement (a descriptor can map to several tree numbers) or pagination, which is the one behavior worth flagging here.

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

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

Front-loaded with the core action in the first sentence, then three short scannable bullets and a single illustrative example. Every element earns its place; the bullets are slightly redundant with each other but not wasteful.

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 whose annotations cover the safety profile and which has an output schema to describe the return shape, the description supplies what is needed to call it correctly. The only real omission is whether multiple tree numbers can be returned for one descriptor, which is a meaningful expectation-setting detail for this specific tool.

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

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

Schema description coverage is 100% for the single mesh_id parameter, including its pattern and D-prefixed examples, so the schema already carries the semantics and the baseline is 3. The description adds nothing about the parameter — its example is a tree number (output), not an input ID — so no credit above baseline.

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

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

States a specific verb and resource — 'Get the tree hierarchy location(s) for a MeSH descriptor' — and the bullets clarify it returns hierarchical path/placement rather than descriptor metadata. However, it never names the adjacent siblings (mesh_descriptor, mesh_qualifiers, mesh_search), so the agent must infer the boundary between 'details about a descriptor' and 'hierarchy location' on its own.

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 situations (locating a term in the hierarchy, understanding broader/narrower relationships, finding same-branch terms), which is clear positive guidance. It stops short of any when-not condition or an explicit pointer to mesh_descriptor for the non-hierarchical case, so it lands at clear-context-but-no-exclusions rather than full routing guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is fully covered without the description. The description adds only that results include classification sources, which is largely return-value information already carried by the output schema; no auth, rate-limit, or coverage caveats are 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 purpose sentence followed by a short bulleted list; nothing is padded. The bullets largely restate the opening sentence's scope rather than adding new constraints, which is the only minor waste.

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

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

A one-parameter, read-only lookup with full annotation coverage and an output schema; the description is sufficient for correct invocation. Only the sibling routing (which RxNorm/ATC class tool to pick) is left 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?

With a single parameter at 100% schema description coverage ('RxCUI of the drug', with a numeric pattern), the schema does the documentation work. The description adds no format hints or guidance about supplying a name versus an RxCUI, so it meets the baseline without exceeding it.

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

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

States a specific verb and resource: 'Get therapeutic and pharmacologic classes for a drug,' with concrete examples of the class types returned. It is clearly distinct from rxnorm_search/rxnorm_concept in kind, but it never explicitly contrasts itself with the other class-oriented siblings (atc_members, atc_classify, atc_lookup), 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 'Use this tool to:' bullets describe what the tool returns rather than when to choose it over alternatives. There is no guidance on when to prefer atc_classify/atc_members or what to do if no classes are found, so usage is implied rather than directed.

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 bar is lower. The description adds genuine value by disclosing the content categories returned (name/synonyms, concept status, related concepts) and the effect of include_related, going beyond the structured hints.

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 scannable bullet list of capabilities and a closing format note. Efficient and well-ordered, with only mild redundancy between the bullets and the return fields.

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 re-explained, and annotations carry the safety profile. The description covers input format and capability scope adequately; the only real gap is the absence of routing to rxnorm_search for users who lack an RxCUI.

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

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

Schema description coverage is 100%, so both parameters are already documented, giving a baseline of 3. The description repeats the RxCUI format example ('161' as string or integer) and restates the related-concepts behavior, matching rather than extending the schema.

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

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

The description states a specific verb+resource ('Get detailed information about a specific RxNorm concept by RxCUI') and enumerates the fields returned (name, synonyms, status, related concepts). It clearly implies an ID-based lookup, distinguishing it from rxnorm_search, but never explicitly names that sibling to route the agent.

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 describes what you can retrieve, which implies the lookup use case, but gives no explicit when-to-use/when-not guidance and never tells the agent to call rxnorm_search first to obtain an RxCUI. Usage is inferable 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 cover the safety profile (readOnly, idempotent, openWorld, non-destructive), and the description adds a meaningful trait beyond that: results may be single- or multi-ingredient. It doesn't speculate on failure modes for an invalid RxCUI, but the added semantic detail is genuine.

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

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

Front-loaded with the core action, followed by scannable bullets. Slightly padded by the 'Use this tool to' framing and a return line that the output schema already handles, but nothing is truly 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 spelled out, and annotations carry the safety profile. The description is adequate for a single-param lookup; only sibling routing is left implicit.

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

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

Schema coverage is 100% and the sole parameter is documented in the schema, so baseline is 3. The description hints that RxCUI may reference a brand drug as well as a generic, adding slight meaning, but the pattern/format details remain entirely with 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 active ingredients for a drug by RxCUI'), and the bullets clarify scope (single vs. multiple ingredient products, generic components of brand drugs). However, it does not differentiate itself from the sibling rxnorm_concept, which a reader might also expect to expose ingredients.

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 bullets give clear usage contexts, effectively stating what tasks the tool answers. There is no explicit 'when not to use' clause or pointer to an alternative sibling, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and non-destructive, so the safety profile is covered. The description adds the useful bidirectional semantics and the either/or input contract, but says nothing about behavior when both parameters are supplied (or neither, given zero required params), nor about result completeness 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?

Front-loaded one-line purpose followed by a tight bulleted use-case list and a closing input rule. No filler sentences; every line carries operational content.

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

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

With an output schema present, return formatting need not be explained, and the description covers both directions plus the input selection rule. The one residual gap is that a 0-required-parameter tool does not state what happens if neither or both codes are provided.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by spelling out the directional meaning of each parameter (rxcui returns NDCs, ndc returns the RxCUI) and reinforcing that they are mutually exclusive alternatives, which the schema only implies for the ndc field.

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: bidirectional mapping between RxNorm concepts (RxCUI) and National Drug Codes. The enumerated use cases (get NDCs by RxCUI, get RxCUI by NDC, cross-reference coding systems) make it clearly distinguishable from siblings like rxnorm_search, rxnorm_concept, or validate_codes.

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

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

Gives clear context for each direction of use and states the invocation rule: 'Provide either an RxCUI to get NDCs, or an NDC to get the RxCUI.' However, it never names an alternative tool or states when another sibling (e.g., rxnorm_concept) would be preferred, so it stops short of explicit routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety behavior is fully covered without the description. The description adds little beyond that: it notes results carry RxCUI, names and term types, but with an output schema present this is largely redundant, and no matching semantics (prefix vs. full-text, ambiguity handling) 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?

Front-loaded with the core purpose and organized into a short bullet list, which is easy to scan. It loses a point for mild redundancy: 'Search for drug formulations' echoes the opening sentence, and the return-value sentence duplicates what the output schema already provides.

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

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

For a two-parameter, read-only search tool with a full output schema and complete annotations, the description covers the essentials. What is missing is the boundary against sibling tools (rxnorm_concept in particular) and any matching behavior, which is the main thing an agent could still get wrong.

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 1-100 bound and default on max_results, so the schema carries parameter semantics fully. The description's mention of 'brand or generic name' mildly reinforces the query parameter but adds no format or syntax information beyond the schema. Baseline 3 applies when 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 (search drugs in RxNorm) and clarifies the corpus, which separates it from the ICD/LOINC/mesh search siblings. It does not distinguish itself from the closest sibling, rxnorm_concept (lookup vs. search), or from rxnorm_ingredients/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 three 'Use this tool to' bullets give concrete usage contexts (brand/generic lookup, prescribing, formulations), which is better than nothing. However, there is no when-not guidance and no named alternative, so the agent gets no help choosing between this and rxnorm_concept or the generic search tool.

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

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

Annotations already declare read-only/idempotent/non-destructive, and the description adds genuine context beyond them: result limit (up to 10), relevance ordering, empty-list semantics, and in-memory caching from the public source. This discloses what the agent needs to interpret results correctly.

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 behavior in the first sentence, then layers on contract context and routing guidance in clearly separated paragraphs. Slightly long, but each block earns its place and nothing is redundant 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?

Complete for a search tool: it covers input interpretation, output shape, ordering, limits, and the required pairing with `fetch`. With an output schema present, the return-value detail is a bonus rather than a necessity, and nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds that queries may be natural language or keywords in Portuguese or English—information the schema does not carry. Minor additional value over the single well-documented parameter.

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 (medical terminologies catalog), and explicitly frames itself as a catalog index rather than a data query. It clearly distinguishes itself from the many sibling search/data tools by noting it returns catalog documents ({id,title,url}), not values.

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 when to use it (the OpenAI Deep Research contract requiring exactly `search` and `fetch`), how to chain it (pass returned ids to `fetch`), and when not to use it (prefer `icd11_*`, `loinc_*`, etc. for direct data questions). Names the alternatives directly.

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

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

Annotations only tell the agent this is a safe idempotent read. The description goes further and discloses the critical non-obvious behavior: for most terminologies there are no shipped historical snapshots, so the tool returns guidance plus `bundled_versions`, while a genuine structural summary exists only for the ICD-10 → ICD-11 path. That is exactly the kind of context an agent cannot get 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?

Well front-loaded with the general behavior, then the ICD-10 exception, then params. The 'Inputs' section partially restates schema descriptions, and the guidance-layer point is made twice ('guidance only' and 'intentionally a metadata + guidance layer'), so a little trimming is possible without loss.

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 the description compensates by covering the two behavioral regimes (guidance vs real diff) end to end. For a 3-param read tool with a special-case branch, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description earns above baseline by defining the omitted-value behavior for both optional params (omit `from_version` → compare against the bundled version; omit `to_version` → compare against the publisher's latest known release) and by contrasting the ICD-10 no-`to_version` special case, which the schema does not convey.

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

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

It states a specific verb and resource ('report what diff data is available between two versions') and immediately scopes itself as a metadata/guidance layer rather than a diff engine. It even carves out the one real-diff case (ICD-10 vs ICD-11), making it trivially distinguishable from siblings like terminology_versions and map_icd10_to_icd11.

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

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

Explicit when-to-use: the ICD-10 vs ICD-11 cross-revision case with the exact call (`terminology: "icd10"` and no `to_version`). Explicit when-not/alternative: for LOINC/RxNorm/MeSH the publisher's official changelog is named as the authoritative source. 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 read-only/idempotent safety. The description adds genuinely non-derivable behavior: the ICD-10 → ICD-11 version is read live from the bundled dataset while all other entries are release-maintained metadata, which tells the agent about data freshness and reliability differences.

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 resource and field list, then uses a tight bulleted rationale block. Slightly verbose in the use-case bullets, but each bullet supplies a distinct scenario rather than filler.

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

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

With an output schema present, return values need not be described, and annotations cover the safety profile. The description adds filtering behavior and per-entry data provenance, leaving little an agent needs for correct invocation.

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

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

Schema description coverage is 100% and the enum is fully documented, so the baseline is 3. The description restates the filter behavior ('pass terminology to filter... otherwise the full set of 7'), which the schema already conveys, adding no new syntax or format meaning.

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 the exact resource fields returned (version, release date, publisher, source URL, update cadence) for every terminology. No sibling tool exposes terminology metadata like this, so the agent can distinguish it immediately.

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

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

Gives concrete when-to-use contexts (pre-batch version confirmation, verifying frozen CID-10/transition table versions, citing data versions in research). It does not name exclusions or point to terminology_diff as the alternative when comparison rather than enumeration is wanted, so it falls short of a 5.

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

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

Annotations already establish read-only/idempotent safety, and the description layers substantial extra disclosure on top: a hard cap of 50 codes, parallel execution whose wall time scales with the slowest upstream (~10 s worst case), and precise error semantics distinguishing 'code not found' (valid:false, error:null) from 'couldn't validate' (error set). It also honestly scopes what the backend can't do today (active is null for most terminologies, replaced_by only for ICD-10→ICD-11).

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 scannable bullet list of return fields and a limits paragraph — structure is good. It runs long, and since an output schema exists, part of the field-by-field enumeration restates structured data rather than adding new meaning.

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

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

For a batched, network-bound validation tool the definition covers everything an agent needs: accepted terminologies, per-code requirement, batch cap, latency profile, null semantics per field, and error handling. Nothing material is left for the caller to infer.

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 enum values and per-code shape are already documented, which sets the baseline at 3. The description adds genuine meaning beyond the schema by explaining why terminology is required per code (category codes like "A00" are ambiguous between ICD-10 and CID-10) and by framing the array as a batch subject to upstream rate limits.

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

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

The opening sentence gives a specific verb (validate), an explicit resource (a mixed batch of medical codes), and the scope (against their source terminologies). It is clearly distinguishable from the sibling search/lookup/chapter tools, which fetch rather than validate.

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

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

It gives a concrete usage context — retrospective analysis of legacy databases, flagging dead codes, surfacing ICD-10→ICD-11 replacements — which tells the agent when this tool pays off. It stops short of naming alternatives or exclusions, e.g. how it relates to map_icd10_to_icd11 or find_equivalent, which overlap on the replacement use case.

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