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 goes well beyond them: cardinality of results (one entry per ATC code, single-ingredient vs combination), the fact that an unresolved name or unmapped drug returns an empty `matches` list rather than an error, and the retrieval source (NLM RxClass, WHO codes). That empty-vs-error distinction is exactly the behavioral detail 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?

Front-loaded purpose sentence, then scannable bullets for use cases, then return semantics, then input caveats, then sibling routing. Length is justified by the routing decision it resolves; no sentence merely restates the title or the schema.

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

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

Single-parameter, read-only lookup with an output schema present — the description need not explain return structure, yet it still characterizes result cardinality and the empty-result case. Nothing an agent needs to invoke it correctly or interpret a null result is missing.

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

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

Schema coverage is 100%, so baseline is 3; the description earns more by adding naming semantics the schema lacks: brand or generic, English/US naming as in RxNorm, and what happens on a miss. It also warns against resolving outcomes as errors, which shapes how the parameter value should be constructed.

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 and resource ("Look up WHO ATC classification(s) for a drug by name") with a concrete worked example ("metformin" → A10BA02). The closing "Which ATC tool" paragraph explicitly separates it from atc_lookup and atc_members, so an agent can disambiguate without opening schemas.

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

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

States exactly when to start here ("when you have a drug name") and names the two alternatives with the precise condition that selects each (class code level 1-4 → atc_lookup; list drugs in a class → atc_members). It even prescribes a fallback path ("resolve the name first with rxnorm_search") for the empty-result case.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so safety is covered; the description adds real behavioral context by disclosing the endpoint's ceiling (only levels 1-4 exposed) and that lookups double as existence checks. It does not discuss error behavior for codes valid in format but absent from the index, which is the only notable gap.

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

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

Opens with a one-line purpose statement, then scannable bullets, then the key constraint — well front-loaded. The substance-level caveat appears both as a general statement and inside the code-length enumeration, a minor redundancy for a single-parameter tool.

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

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

One parameter, 100% schema coverage, a rich output schema, and full annotations mean the description needn't explain return values. It covers purpose, valid input space, exclusion of substance codes, and the sibling alternative — everything needed to invoke 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 baseline is 3, but the description goes beyond the schema by mapping each code length to its level name (A = anatomical, A10 = therapeutic, A10B = pharmacological, A10BA = chemical), which helps an agent construct valid input. The 7-char restriction is restated from the schema rather than added.

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

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

States a specific verb (look up) plus resource and scope (ATC code at level 1-4), and says what is returned (name and hierarchy level). The closing sentence explicitly names atc_classify as the sibling handling a different case, so the boundary is unambiguous.

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

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

Three bullets give concrete when-to-use cases (resolve a code, confirm existence, identify level), and the final sentence states an explicit exclusion plus the alternative to use instead (atc_classify for 7-char substance codes). No inference required.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety bar is low; the description adds real context beyond them — that each member carries a substance-level 7-char source_atc_code for disambiguation, and that RxNorm's catalog is US-centric while ATC names/codes are international. It stops short of discussing rate limits or result-size 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 core statement is front-loaded in the first line, with bullets doing scannable work afterwards; the closing caveat about US-centricity is the only part an agent might skip. Efficient, with minor redundancy against the schema wording.

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

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

Output schema exists, so return values need no explanation, yet the description still names a key returned field (source_atc_code) and its disambiguation use. Combined with the level/subtree guidance and the catalog-bias note, an agent has what it needs; only explicit sibling routing is absent.

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

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

Schema coverage is 100% and the schema's own property description already explains that levels 1-4 return all member substances and level 5 returns the single substance. The description's 'at any level' and subtree bullets restate that rather than adding format or validation guidance, 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?

Opens with a specific verb+resource ('List the drugs (substances) that belong to an ATC class') and immediately grounds it with a concrete example ('A10BA' → metformin, phenformin). An agent can distinguish this from atc_classify/atc_lookup without opening any schema.

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

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

Three explicit 'Use this tool to' bullets give concrete scenarios (enumerate class members, build mechanism-shared drug lists, explore a subtree). It lacks an explicit 'when not to use' or a named alternative among the ATC siblings, which keeps it short of a 5.

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

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

Beyond the readOnly/idempotent annotations, it discloses the out-of-range rejection behavior, that all groups come back in one response with no pagination (275 groups across 22 chapters, so response size is bounded), and that results come from the bundled CID-10 V2008 with no network call. The 'no network call' statement sits in mild tension with openWorldHint=true, but that hint describes the domain of entities rather than transport, so it reads as added context rather than a contradiction.

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

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

Front-loaded with a one-line purpose plus example, then a compact bulleted use list, a parameter note, and a sibling-routing line. Every sentence carries distinct information (validation behavior, response size, data source, alternatives) with no filler.

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

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

An output schema exists, yet the description still gives enough about the return payload (chapter title + code range + ALL groups, unpaginated) for an agent to plan around volume and shape. Combined with the validation rule and offline-data note, nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline would be 3; the description earns more by supplying the roman-numeral-to-integer mapping ('chapter I = 1, IX = 9') that the schema does not express, plus the explicit rejection of values outside 1-22. The remaining repetition of the 1-22 integer type is redundant with the schema, capping it below 5.

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

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

States a specific verb and resource ('Get one CID-10 chapter and its constituent groups') and immediately illustrates the return shape with a concrete example (Chapter IX → I00-I02, I05-I09). It also distinguishes itself from the sibling navigation tools cid10_chapters, cid10_lookup and cid10_search, so an agent can select it without opening a schema.

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

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

Explicitly enumerates the three intended uses (drill into groups, build hierarchical browsers, resolve a code range to a group) and gives an ordered fallback: 'use cid10_chapters first if you do not know the chapter number'. It also names cid10_lookup for single codes, cid10_search for text search, and icd11_chapters for the international edition.

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, non-destructive behavior, and the description adds useful context: exactly 22 entries and the CID-10 V2008 version limitation. It does not need to explain safety further, though it could mention output shape or ordering more explicitly.

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, followed by three scannable use cases and a short return note. Each sentence adds practical value without unnecessary detail.

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

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

For a no-parameter list tool with an output schema and rich annotations, the description supplies enough context: scope, examples, intended uses, entry count, and version limitation. An agent has what it needs to select and 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?

The tool has zero parameters, so there are no parameter semantics to explain. Baseline 4 is appropriate because the schema is empty and no parameter-level description is required.

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

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

States a specific verb and resource: "List the 22 chapters of CID-10" with code ranges and Portuguese titles. It clearly describes the top-level chapter listing, which is distinguishable from singular chapter lookup and code-search siblings.

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

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

Provides explicit use cases: viewing top-level structure, mapping a code to a chapter by range, and building a table of contents. It does not explicitly name alternatives such as cid10_chapter or cid10_lookup, so it falls short of full when-not/alternative 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?

With readOnly/idempotent/non-destructive declared by annotations, the description adds real behavioral context: it normalizes input formats and returns a canonical display form, and it discloses that gender/cause-of-death restriction flags may come back. It does not mention behavior when a code does not exist (error vs. empty result), which matters for exact-match lookups.

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-sentence purpose followed by three scannable intent bullets; nothing is padded. Minor waste in the closing sentence, which restates the dotted/undotted acceptance already given in the schema and duplicates the first bullet's resolution concept.

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, idempotent read with an output schema, the description covers intent, input forms, and the kinds of values returned. The remaining gap is failure behavior on unknown or invalid codes, which an agent would want before relying on this for validation.

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 description already states that dotted and undotted forms are accepted, so the description's duplicate claim adds little. The only extra signal is that normalization produces a canonical display, which is a return-shape note rather than parameter meaning, so baseline 3 applies.

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

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

States a specific verb and resource ('look up a specific CID-10 code') plus the concrete return artifact ('its Portuguese name'), and the example 'I21' → 'Infarto agudo do miocárdio' makes the operation unmistakable. Against siblings like cid10_search or cid10_chapter, 'a specific code' clearly implies exact-code resolution rather than text search or hierarchy browsing.

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

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

'Use this tool to:' enumerates three concrete intents (resolve to description, confirm existence, retrieve restriction flags), which gives the agent clear selection criteria. It lacks an explicit exclusion pointing at cid10_search for when the agent has a name rather than a code, so it stops short of full alternative routing.

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

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

Annotations already declare read-only, idempotent, non-destructive, open-world, so the description rightly spends its budget on non-obvious search behavior instead: diacritic insensitivity, AND-across-words semantics, everyday-Portuguese vocabulary resolution with concrete mappings (câncer→neoplasia maligna, AVC→acidente vascular cerebral), the vocabulary_notes signal in the response, and the exact terminology version 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 purpose, then structured into use cases, behavior, and sibling disambiguation in a logical order. It runs somewhat long and the use-case bullets partially echo the opening sentence, but no sentence is genuinely expendable given the vocabulary-resolution detail.

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 correctly avoids explaining return shapes while still flagging the one response field an agent must interpret (vocabulary_notes). Query construction, level semantics, version scope, and sibling routing are all covered, leaving nothing an agent needs missing.

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

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

Schema description coverage is 100%, so the schema already documents query, level, and max_results including the accent-insensitive and vocabulary-resolution behavior. The description's query guidance largely restates the schema, and level/max_results are only indirectly illuminated by the '3-char categories and/or 4-char subcategories' line, so it meets but does not exceed the baseline.

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

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

States a specific verb and resource (search the Brazilian CID-10 by Portuguese text) with explicit scope: V2008, Portuguese, categories and subcategories. It explicitly names the sibling it is not (icd11_search) and the boundary between them (international/English ICD-11).

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 dedicated 'Use this tool to' block with three concrete scenarios (SUS/ANVISA coding, official CBCD/USP translation lookup, billing/epidemiology/clinical documentation) and closes with an explicit alternative for the ICD-11 case. Both when-to-use and when-to-use-something-else are covered.

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

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

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?

Goes well beyond the readOnly/idempotent/openWorld annotations by disclosing derived fields the server computes itself ('match_score', 'rank') because upstreams lack comparable relevance scores, and by explaining the 'groups' clustering signal plus the caveat that absence of a group is not evidence of non-equivalence. It also discloses the English-only upstream behavior, which materially affects result interpretation.

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 first, then three short usage bullets, then the mechanics (systems, source/target interaction, limit, scoring, grouping), then the language caveat — a deliberately ordered funnel. Every sentence adds either routing information or result-interpretation guidance; nothing is filler.

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

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

For a four-param, five-upstream fan-out tool with an output schema present, the description covers exactly what the schema cannot: cross-terminology semantics, score provenance, grouping interpretation, and language limitations. No gap remains that would cause an agent to mis-call or mis-read the output.

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 parameters are already well documented in-schema, but the description adds the non-obvious interaction rule that source is subtracted from targets, and reinforces that limit is a per-terminology cap rather than a page. Much of the remaining parameter text restates what the schema already says, so it sits just above the baseline rather than transforming understanding.

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 — 'ranked unified search for equivalent terms across multiple medical terminologies' — and immediately enumerates the covered systems (ICD-11, LOINC, RxNorm, MeSH). An agent can distinguish this cross-terminology mapper from single-vocabulary siblings like icd11_search or rxnorm_search without opening a schema.

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

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

Provides explicit 'use this tool to' cases (find the same concept in other systems, compare representations, support mapping/integration) and explains the source_terminology exclusion pattern with a concrete scenario. It also routes away to alternatives by name when official pt-BR content is needed (icd11_search, mesh_search, cid10_search).

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

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

Annotations only declare safety/idempotency; the description goes far past them with the 50-term hard limit and its validation error, per-row error isolation ('one failed lookup does not fail the batch'), dedup of repeated term+domain pairs, dropped-candidate rules (no shared word, 'Deprecated' LOINC, postcoordinated clusters), English-only searching, and a de-identification warning because terms go to WHO/NLM APIs.

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

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

Front-loaded with the core action, then a scannable bullet block, then limits, label semantics, and alternatives in that order — the structure is easy to navigate. Some content duplicates the schema (domain routing) and the match_type rules run long, but every sentence carries operational information.

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

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

For a batched, open-world, partially-failing lookup tool this covers everything an agent needs: batching limits, per-row error handling, label semantics for triage, data-sensitivity caveat, and a pointer to terminology_versions plus per-source provenance for reproducibility. Output schema exists, so return-shape detail is correctly omitted.

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

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

Schema coverage is 100%, so baseline is 3; the description still adds value by re-framing domain as a vocabulary route (RxNorm ingredients first, plus ATC classes of the term) and by spelling out that max_candidates keeps 1-5 per term with default 3, and that repeats are looked up once. It doesn't add syntax beyond the schema, so not a 5.

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

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

States a specific verb and resource ('Map a LIST of free-text clinical terms to standard codes') and names the output shape (ranked candidates with confidence labels). It also explicitly differentiates itself from siblings: find_equivalent for single terms across terminologies, cid10_search for pt-BR diagnoses, validate_codes for checking 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?

A dedicated 'Use this tool to' block enumerates the three concrete scenarios (dataset columns, triage by label, auditable crosswalk), and the closing paragraph names each alternative with the condition that selects it. Nothing is left to inference.

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

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

Goes well beyond the readOnly/idempotent annotations: it discloses the exact result size (28 entries, no pagination), the composition of the list (01-26 plus V and X), and the partial-failure contract where an individual chapter keeps its URI and carries an `error` instead of a title. It also notes WHO-side per-chapter fetching and result caching, which materially affects retry and cost decisions.

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 scenarios, then return/failure behavior, then exclusions — a logical order. The field enumeration ('number, code, title and URI') is redundant given the output schema, but the rest of the prose earns its place.

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

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

For a single-parameter, read-only listing tool with an output schema and full annotations, everything an agent needs is present: scope, result size, failure semantics, caching, language behavior, and sibling routing. No gap remains that would cause a misinvocation.

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 an enum, so the baseline is 3; the description still adds practical value by showing a concrete invocation (`language: "pt"`) and tying the parameter to a caching consequence. It slightly repeats the schema's 'official translation' wording rather than extending it, keeping it out of 5 territory.

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

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

Opens with a specific verb and resource ('List all ICD-11 chapters (top-level categories) of the pinned WHO release'), plus a parenthetical that defines what a chapter is. It is unambiguous against icd11_search and cid10_chapters, which are named explicitly later.

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 three explicit 'use this tool to' scenarios (structure overview, body-system routing, obtaining URIs to drill down) and a 'When NOT to use' block that names the correct alternatives (icd11_search for diseases, cid10_chapters for CID-10). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds non-obvious behavioral context, especially that blocks may come back from 'parents' with an empty code and a code_range. It does not discuss authentication, rate limits, or failure behavior, but those are less critical for a read-only hierarchy browse.

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 a clear purpose and bulleted use cases, then gives the key invocation details. It is somewhat longer than necessary and repeats the parents/children distinction in both the bullets and the direction sentence, but the redundancy is mild and the content remains useful.

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

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

Given the output schema and annotations, the description covers what an agent needs to invoke the tool correctly: when to use hierarchy navigation, how to specify the entity by code or URI, what direction means, and the special block-range caveat. Return-value details are appropriately left to the output schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema by clarifying that 'code' can be a leaf code or block range, that block ranges are returned by 'parents' with an empty code and code_range, and that 'uri' is any URI from a previous answer.

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: navigate the ICD-11 hierarchy to find parent or child entities. It immediately distinguishes the tool's two core operations (parents vs. children) and frames the classification structure use case, so an agent can tell this apart from lookup/search siblings.

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

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

It provides explicit use cases for finding broader categories, subtypes, and understanding classification structure. It also gives an important alternative: ICD-10 codes must be converted first with map_icd10_to_icd11. However, it does not explicitly state when to prefer icd11_lookup or icd11_search over hierarchy navigation.

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

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

Annotations already cover safety (readOnly, idempotent, not destructive), but the description adds real behavioral context: at-least-one-of code/uri requirement with a validation error naming both, single-entity return with no pagination, unknown code returns a "not found" error rather than an empty record, and no machine translation. These are error/edge behaviors the annotations do not express.

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

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

Front-loaded with the core action and precondition, then structured bullets for capabilities, then a params paragraph, then exclusions. No redundant restatement of the name or title; every sentence adds usable information.

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

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

Output schema exists so return shape need not be described, and the description still covers error semantics, single-record behavior, and language handling. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value the schema cannot: it states that at least one of `code` or `uri` is required even though the schema lists zero required parameters, and it clarifies that `language` selects WHO's official translation rather than translating content.

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

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

States a specific verb and resource ("Get detailed information about ONE ICD-11 entity") and immediately scopes it to entities the caller already has a code or URI for. This cleanly separates it from icd11_search, icd11_hierarchy and map_icd10_to_icd11, which are all named.

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 lists the use cases (full definition, coding notes, inclusions/exclusions, title and synonyms) and then an explicit "When NOT to use" block routing to icd11_search, icd11_hierarchy and map_icd10_to_icd11, including the caveat that ICD-10 codes like "E11" are not valid here.

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

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

Beyond the readOnly/idempotent/openWorld annotations, the description discloses non-obvious behavior: it covers only MMS linearization at the pinned release, unknown or non-postcoordinated codes return an empty axes list rather than an error, and value_count is a count rather than the values. These are exactly the surprises that would otherwise cause an agent to mis-handle a response.

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

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

Front-loaded with the definition, then usage bullets, then return behavior, then exclusions. The middle paragraph explaining postcoordination is functional domain context rather than padding, and each subsequent sentence introduces a distinct fact.

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

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

An output schema exists, yet the description still summarizes the returned fields and their meaning, plus the empty-list edge case. For a single-parameter read tool with full annotations, there is no gap an agent would need to guess at before calling.

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 documented there, so the baseline is 3. The description adds a concrete code format example ('BA00') and ties the parameter to a validation path (check the code with icd11_lookup if the result is unexpectedly empty), which is modest but real added 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?

The opening sentence names a specific verb+resource ('List the postcoordination axes') scoped to one ICD-11 stem code, and the following paragraph defines what postcoordination actually is. An agent can distinguish this from icd11_lookup, icd11_hierarchy and icd11_search without opening any schema.

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

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

Three explicit 'Use this tool to' bullets give positive triggers (check axes before building a composite, check required vs optional, check cardinality). The 'When NOT to use' block names concrete alternatives — icd11_lookup for code verification, icd11_search for name-to-code — leaving nothing to inference.

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

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

Annotations already declare read-only, idempotent, open-world, non-destructive behavior, so the safety bar is met. The description adds genuinely non-obvious behavior: the language parameter selects WHO official translations only ('Never machine-translated') and that 'pt' maps to pt-BR. It does not mention result ranking/pagination behavior beyond 'relevance scores'.

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

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

Front-loaded with a one-line purpose, then a scannable use-case list and a note on language semantics. Some redundancy with the input schema descriptions (the official-translation point appears twice) keeps it short of 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 3-parameter, read-only search tool with an output schema and full annotation coverage, the description supplies everything needed to invoke it correctly: what it searches, what the language flag guarantees, and what comes back. Only sibling routing (search vs. lookup) is left unspecified.

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

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

Schema coverage is 100% and the schema already documents all three parameters, including the official-translation nuance and the pt-BR example — the description largely repeats this. It adds no new syntax or constraint detail (no max_results guidance, no query-matching semantics), 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 ('Search for medical conditions... in ICD-11') plus concrete outcomes (find codes, search by name/keyword). It does not explicitly differentiate from close siblings such as icd11_lookup or cid10_search, and 'Find ICD-11 codes for diagnoses' partially overlaps with what a lookup tool would do.

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

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

The bullet list gives clear usage contexts (find codes, keyword search, multilingual lookup), which is stronger than implied usage. However, it offers no exclusions — nothing says when to prefer icd11_lookup (exact code) or cid10_search / map_icd10_to_icd11 instead.

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

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

Goes well beyond the annotations by describing the return fields, including LA answer codes, text, display order, and score. It also discloses edge-case behavior: a valid LOINC code without an answer list returns an empty list, while an unknown code returns a not-found error.

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

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

Front-loads the core purpose, then uses a tight bullet list for use cases and a compact paragraph for return/error behavior. No sentence feels redundant or misplaced.

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 one-parameter read-only lookup tool: purpose, applicability, alternatives, return shape, and error cases are all covered. The output schema exists, and the description still adds useful behavioral context without over-explaining.

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 single parameter is fully documented in the schema with a pattern and example, so the baseline is 3. The description reinforces that the input is a LOINC code and gives contextual examples, but does not add syntax or format details beyond the schema.

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

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

States a specific verb and resource: getting valid LOINC answers for a questionnaire item. It clearly distinguishes itself from loinc_panels and loinc_search by naming what each sibling is for.

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

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

Provides explicit use cases and applicability constraints, including that it only applies to LOINC codes representing questions with defined answer sets. It names alternatives for whole questionnaires (loinc_panels) and code lookup by name (loinc_search).

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

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

Annotations already declare readOnly, idempotent, open-world, and non-destructive, so the safety profile is fully covered. The description adds the shape of the returned record (component, property, timing, system, scale, method), but since an output schema exists this largely restates structured data; nothing is said about behavior for unknown or malformed codes.

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

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

Short, front-loaded, and scannable with a bulleted capability list followed by the input format note. The only slack is the format sentence, which repeats the schema's example.

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

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

With rich annotations, a fully documented single parameter, and an output schema, the definition covers what an agent needs to call it correctly. Missing only the relationship to loinc_search and any error behavior for invalid codes.

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

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

Schema coverage is 100% and the schema already provides the pattern and the '2339-0' example. The description's format note ('XXXXX-X', Glucose example) duplicates that, so it adds no semantics beyond the schema.

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

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

States a specific verb and resource ('Get detailed information about a specific LOINC code'), which is unambiguous. However, it never distinguishes itself from siblings like loinc_search, loinc_answers, or loinc_panels, so the agent must infer that this is the lookup-by-identifier path.

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

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

The bulleted 'Use this tool to' list implies usage when you already hold a LOINC number, but it names no alternatives and gives no exclusion criteria. The sibling loinc_search is the obvious companion (find a code, then detail it) and is never mentioned.

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 fully covered without prose. The description adds only that the result is a list of LOINC codes making up the panel — which the output schema already conveys — and says nothing about panel-vs-form differences, missing/empty panels, or hierarchy depth. Adequate but thin beyond structured data.

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

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

The purpose sentence is front-loaded, the bullets are short and scannable, and there is no filler. The final 'Returns the list of LOINC codes...' sentence partially duplicates the output schema, which is the only 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 one required parameter, full schema coverage, four annotations, and an output schema, the description covers everything needed to invoke correctly: what it does, when to reach for it, and what shape the answer takes. Nothing essential is missing for a tool of this complexity.

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

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

Schema coverage is 100% with a documented pattern and example ('2339-0'), so the schema fully carries the parameter burden. The description adds only the implication that loinc_num must identify a panel or form rather than an arbitrary LOINC code, which is a small semantic gain. Baseline 3 applies.

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

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

States a specific verb+resource ('Get the structure of a LOINC panel or form') and the bullet list clarifies the resource types (panels, assessment forms, grouped observations). It does not explicitly name how it differs from close siblings like loinc_details or loinc_answers, 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 triggering scenarios (CBC/metabolic panel contents, assessment form structure, related grouped observations), which is clear context for selection. However, it names no exclusions or alternatives — e.g. it never says to use loinc_answers for answer lists or loinc_details for a single test — leaving the agent to disambiguate against 30+ siblings on its own.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that results include names, components, and properties, but because an output schema exists this return-value detail is largely redundant and no further behavioral context such as ranking or pagination is provided.

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 and then uses a compact use-case list. It is slightly repetitive with the opening sentence and examples, but still efficient and easy to scan.

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

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

For a simple search tool with full schema description coverage, annotations covering safety and open-world behavior, and an output schema, the description provides enough purpose, use cases, and return context for correct invocation. No critical information appears missing.

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

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

Schema coverage is 100%, so the schema already documents both query and max_results, including defaults and bounds. The description adds examples of query terms but no additional parameter semantics beyond the schema.

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

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

States a specific verb and resource: search LOINC for laboratory tests, clinical observations, and measurements. It clearly distinguishes the domain from non-LOINC siblings, but does not explicitly distinguish it from LOINC siblings such as loinc_details, loinc_answers, or loinc_panels.

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

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

Gives clear usage context with examples like finding LOINC codes for glucose or hemoglobin and looking up diagnostic observations. It does not name alternatives or state when not to use this tool versus sibling LOINC tools.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), so the bar is lower, yet the description still adds substantial context: data provenance and release version, 11,243-category coverage envelope, split-mapping behavior, and the explicit "no mapping" outcome instead of a fuzzy fallback. That last point is particularly valuable for an agent deciding how to interpret an empty result.

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 mapping statement and organized into provenance, return contents, usage, and input format. Slightly long for a single-parameter tool, and the return-value paragraph overlaps with the output schema, but no sentence is filler.

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

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

Given an output schema exists, the description needn't explain returns, yet it adds the one thing the schema can't convey: what a negative result means ("honest answer rather than a fuzzy search fallback") and what the mapping's domain boundaries are. Nothing an agent needs to call 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%, so baseline is 3, but the description adds real meaning the schema lacks: both dotted ("A07.8") and undotted ("A078") forms are accepted, and it gives worked examples including one with known multiple alternatives. This directly changes how an agent formats input.

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

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

States a specific verb and resource (ICD-10 → ICD-11 mapping) and names the authoritative source (WHO transition tables). It explicitly contrasts itself with text-search siblings ("rather than text-search candidates"), so an agent can distinguish it from icd11_search or find_equivalent without opening schemas.

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

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

Names concrete use cases (clinical coding, billing migration, retrospective analysis) and explicitly routes agents away from fuzzy/text-search alternatives. The coverage note (excludes chapter/block codes like "A00-A09") is an implicit when-not-to-use rule that prevents a common mis-call.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is fully covered. The description adds that translations are NLM-official and never machine-translated, but that same fact is already stated verbatim in the schema's language property description, so net new behavioral disclosure is thin.

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 lead sentence is front-loaded and the bullet list is tight, with no filler or repetition across sentences. The example parentheticals are slightly redundant with the schema but do not bloat the text.

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

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

A two-parameter read-only lookup with full schema coverage and an output schema needs little more; the description covers input format, the nature of the returned content, and language behavior. Nothing an agent needs in order to invoke it correctly is missing.

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

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

Schema description coverage is 100% and the regex pattern plus enum already constrain both parameters, so baseline 3 applies. The description's ID example ('D015242' Ofloxacin) and language example duplicate material already present in the schema rather than adding new semantics.

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

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

States a specific verb and resource ('Get detailed information about a MeSH descriptor by ID') and enumerates what is returned (scope note, tree numbers, related concepts, synonyms). However, it never names the sibling lookup tools (mesh_search, mesh_tree, mesh_qualifiers) to draw a boundary, so differentiation is left implicit through the 'by ID' framing.

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

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

The 'Use this tool to:' bullets give clear positive contexts (full definition, hierarchy location, synonyms) and the ID example shows the expected input form. It stops short of stating when NOT to use it or naming the alternative (e.g. use mesh_search when you only have a term string).

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 behavior, so the bar is lower. The description adds domain meaning (qualifiers are subheadings that refine descriptors) and an example, but it does not disclose any further behavioral traits such as error conditions or constraints beyond what the schema and annotations already 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?

The description is short and front-loaded: the core action appears in the first sentence, followed by a compact usage bullet list and a one-line clarifying example. Every sentence contributes without 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?

Given the simple one-parameter lookup, rich schema, and presence of an output schema, the description covers what the tool does and when to use it. The only notable omission is sibling differentiation, which would help an agent choose between this and mesh_descriptor or mesh_search.

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 mesh_id parameter has a pattern and examples in the schema. The description adds no parameter-specific information beyond what the schema provides, so baseline 3 is appropriate.

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

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

States a specific verb and resource: 'Get allowed qualifiers (subheadings) for a MeSH descriptor.' The purpose is unmistakable, but the description never names or distinguishes it from related siblings like mesh_descriptor or mesh_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?

A 'Use this tool to' bullet list gives clear usage contexts (finding combinable qualifiers, building queries, understanding specified aspects). It lacks explicit when-not-to-use guidance or alternative-tool routing, but the positive guidance is strong.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the description only needs added context — and it supplies a real behavioral fact: translations are official NLM translations and content is never machine-translated. It also notes results carry MeSH IDs and labels, which helps the agent know the output is usable for downstream indexing.

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

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

The purpose is front-loaded in the first line, followed by a scannable use-case list and a tightly scoped language note. The language paragraph duplicates the schema field description, which is the one piece of text that does not fully earn 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?

With an output schema present and 100% schema coverage plus full annotations, the description covers what an agent needs: what it searches, why, and the translation caveat. Minor remaining gap is ranking/ordering expectations for results, but that is not essential to invoke 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 description coverage is 100%, so all four parameters (including both enums) are already fully documented in the schema. The description's language sentence restates the schema's language description almost verbatim and adds nothing about `match` semantics or ordering/truncation behavior for `max_results`. 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 for MeSH ... descriptors') and the bullet list pins down the intent (indexing terms, PubMed subject headings, controlled vocabulary). It does not, however, distinguish itself from the nearby siblings mesh_descriptor, mesh_tree and mesh_qualifiers, so an agent must infer that this is the keyword-search entry point rather than the lookup/traversal one.

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 where this tool is the right choice (finding indexing terms, PubMed heading lookup, controlled vocabulary lookup). There are no exclusions or named alternatives telling the agent when to switch to mesh_descriptor or mesh_tree instead.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds real value beyond them by explaining what tree numbers represent and giving a concrete example format (C14.280.647), which tells the agent how to interpret the result.

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 use cases and a clarifying example. Slightly more verbose than strictly necessary since the bullets partly restate the hierarchy idea, but every line is relevant.

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 lookup with an output schema, the description covers purpose, use cases, and output interpretation. Nothing about return shape needs explaining because the output schema handles it; only sibling disambiguation is missing.

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

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

Schema description coverage is 100% and the single mesh_id parameter is fully documented with pattern and examples in the schema. The description only restates that the input is a MeSH descriptor, adding no format or constraint detail beyond the structured field, so the baseline applies.

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

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

The first sentence states a specific verb and resource ('Get the tree hierarchy location(s) for a MeSH descriptor'), which is unambiguous. It does not explicitly distinguish itself from the close sibling mesh_descriptor, so the agent must infer the boundary rather than being told.

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

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

The bullet list gives clear positive triggers (see hierarchy placement, understand broader/narrower relationships, find related terms in a branch). It stops short of stating when not to use it or naming mesh_descriptor/mesh_search as alternatives for those cases, which is why this is not a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds only that it returns class IDs, names and classification sources – information that duplicates the output schema. Nothing is said about data source (RxClass), coverage, or latency, so it adds modest value beyond structured fields.

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

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

Front-loaded with a one-line purpose, then a short bulleted usage list and a return summary. Structurally clean and short, though the bullets largely echo the opening sentence rather than adding new information.

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

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

For a simple read-only lookup tool with one parameter, full schema coverage and an output schema, the description is adequate but leaves gaps that matter in this family of tools: no differentiation from the ATC classification siblings and no note on what RxCUI granularity is expected.

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

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

There is a single parameter, rxcui, and schema description coverage is 100%, so the schema already documents it. The description's 'for a drug' adds no format or constraint detail (e.g., whether an ingredient or clinical-drug RxCUI is acceptable). 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 therapeutic and pharmacologic classes for a drug.' An agent can tell it returns RxNorm/RxClass classification data. It does not explicitly distinguish itself from the similarly-purposed sibling 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' bullets give implied usage contexts (find drug class, therapeutic categories, mechanism of action), but they restate the purpose rather than discriminate. There is no guidance on when to prefer this over atc_classify or atc_lookup, which are plausible alternatives for the same classification question.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and open-world, so the safety profile is handled. The description adds what the payload contains (full name, synonyms, concept status values like active/remapped, related concept types), which is useful beyond structured fields, though it says nothing about behavior for an unknown or invalid RxCUI.

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-sentence purpose followed by scannable bullets adds structure. The final sentence re-encodes the RxCUI format already given in the schema, which is mild duplication but not enough to hurt usability.

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

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

With an output schema present and fully covered annotations, the description needn't explain return shapes, and it correctly focuses on input and scope. The only gap is unstated error behavior for invalid RxCUIs, minor for a simple read-only lookup.

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

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

Schema coverage is 100%, so both parameters are already documented; the description mostly restates the rxcui format ("161", digits or integer) that the schema pattern/anyOf already conveys. It does link 'related concepts (ingredients, brands, forms)' to include_related, a small value-add, but doesn't note the default-false behavior beyond what the schema says.

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 details), resource (RxNorm concept), and identifier (RxCUI), plus an enumerated list of what the details include (name/synonyms, status, related concepts). This clearly separates it from rxnorm_search (querying) and rxnorm_ingredients/rxnorm_classes (targeted sub-views).

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 conditions for invoking it, and the closing line makes the input requirement explicit. It never states when not to use it or names alternatives such as rxnorm_search for callers who don't yet have an RxCUI, so no exclusions are covered.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, covering the main behavioral profile. The description adds that it returns ingredient RxCUIs and names, but does not describe error behavior for unknown RxCUIs or other edge cases.

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

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

The description is front-loaded and well structured, with the core action in the first sentence and use cases in bullets. The bullets partially restate the first sentence, but the overall text is efficient.

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

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

This is a simple one-parameter tool with an output schema and rich annotations, so the description covers the essential purpose and usage. A minor gap remains around unknown-RxCUI behavior, but nothing critical for correct invocation is missing.

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

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

Schema coverage is 100%, and the single rxcui parameter is already documented in the schema. The description only says 'by RxCUI' and does not add format, validation, or lookup semantics beyond what the schema provides.

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

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

The description states a specific verb and resource: get active ingredients for a drug by RxCUI. It is clear what the tool does, but it does not explicitly distinguish itself from nearby RxNorm siblings such as rxnorm_concept or rxnorm_classes.

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

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

The 'Use this tool to' bullets give clear usage contexts, including finding active ingredients and distinguishing single- vs. multiple-ingredient products. However, it does not state when not to use it or name alternative tools for related lookups.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds that the tool is bidirectional and takes exactly one identifier, but says nothing about cardinality of results (one NDC vs many), unmatched-code behavior, or partial-match handling — the openWorldHint suggests external lookups, yet no failure mode is described.

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

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

Front-loaded one-line purpose followed by scannable bullets and a closing input rule; nothing is buried. The 'Cross-reference between coding systems' bullet is somewhat redundant with the opening sentence, a minor bit of 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 an output schema present and rich annotations, the description need not explain return values, and it correctly covers the input contract. What a caller would still want — what happens when neither parameter is supplied (both are optional) or when a code has no mapping — is left implicit.

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

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

Schema description coverage is 100% and each property already documents its direction ('NDC code to look up RxCUI', 'RxCUI to get NDC codes for'). The description restates the either/or contract, which is useful for signaling mutual exclusivity but adds little beyond the schema wording — baseline 3.

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

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

The first sentence names a specific operation and both resource types (RxNorm concepts and NDC codes), and the bullets spell out the two directions of the mapping. It is clearly distinguishable from rxnorm_search or rxnorm_concept by virtue of being a cross-terminology mapping, though it never names a sibling explicitly.

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

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

The 'Use this tool to' bullets give concrete tasks and the closing line states the input contract ('Provide either an RxCUI ... or an NDC ...'). It lacks any when-not guidance or named alternative (e.g., use rxnorm_search to find an RxCUI first), which keeps it below a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so safety and mutation behavior are covered. The description adds modest context by naming returned fields (RxCUI, names, term types), but it omits search behavior such as matching strategy, ranking, pagination, or rate limits. With annotations carrying the safety profile, this 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?

The description is front-loaded with the core purpose and uses a short bullet list for use cases, making it easy to scan. There is mild redundancy between 'Find drug concepts' and 'Look up medications for prescribing,' but overall it is efficient.

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

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

Given the simple two-parameter schema, full schema coverage, annotations covering safety, and an output schema that handles return values, the description is largely complete. The main gap is lack of sibling differentiation, which keeps it from a 5.

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

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

Schema description coverage is 100%, so both parameters are fully documented in the schema. The description reinforces that 'query' accepts brand or generic names but adds no syntax, format, or filtering nuance beyond that. Baseline 3 is appropriate 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 clearly states a specific verb and resource: searching drugs in RxNorm, with brand/generic names and formulation lookups. However, it does not distinguish this tool from closely related siblings such as rxnorm_concept, rxnorm_ingredients, or rxnorm_ndc, so an agent must infer the boundary.

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

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

It gives implied usage through bullet points ('Find drug concepts', 'Look up medications for prescribing', 'Search for drug formulations'), which helps an agent understand context. But it never states when to prefer alternatives like rxnorm_concept for details or rxnorm_ingredients for ingredient-level queries, and provides no exclusions.

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

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

Annotations already declare 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?

Goes well beyond the readOnly/idempotent annotations by disclosing the crucial behavioral caveat that the server ships no historical snapshots, that bundled_versions reveals what is actually on hand, and what the ICD-10 path returns (total mapped categories, 1:1 vs split counts, average alternatives). This prevents an agent from expecting a real diff.

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 key caveat and organized with an Inputs list plus a closing summary. Slightly verbose — the final paragraph largely restates the opening "guidance only" framing — but the redundancy is mild and each block carries useful routing information.

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

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

For a 3-parameter, read-only metadata tool with annotations and an output schema, the description covers scope, defaults, expected return shape for the non-trivial case, and explicit fallback guidance. 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 default semantics the schema only hints at: omitting from_version reports against the bundled version, omitting to_version reports against the publisher's latest known release, and terminology: "icd10" with no to_version triggers the cross-revision path.

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

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

Clear specific verb + resource: reports what diff data is available between two versions of a terminology. It explicitly disclaims being a diff engine and frames itself as a metadata/guidance layer, which separates it functionally from map_icd10_to_icd11 and terminology_versions, though it never names those siblings directly.

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

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

It states exactly when this tool is useful (ICD-10 vs ICD-11 cross-revision summary) and when it is not (LOINC, RxNorm, MeSH — go to the publisher's official changelog instead). It also gives the concrete invocation recipe: terminology "icd10" with no to_version.

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 readOnly/idempotent annotations already covering the safety profile, the description adds genuinely new behavioral facts: the default result set is 7 entries, and the ICD-10 → ICD-11 version is read live from the bundled dataset while the rest is release-maintained metadata. That provenance distinction is real value; it just doesn't discuss ordering or freshness caveats for the metadata entries.

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 statement, then a scannable bullet list, then the filtering and data-provenance notes. Slightly long for a one-parameter read tool, and a stray 'CID-10' spelling versus the 'cid10' enum value could momentarily confuse the mapping, but nothing is padded.

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

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

An output schema exists, so return values need no prose explanation; the description still covers what is returned, the default cardinality, filtering behavior, and where each entry's data comes from. For a simple read-only metadata tool, 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 already 100% and the enum is self-documenting, yet the description still adds meaning beyond the schema by stating the exact set size returned when the filter is omitted ('otherwise the full set of 7 is returned'). This makes the omit-vs-filter tradeoff concrete.

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 ('List') and resource (terminology versions), and enumerates the returned fields (version, release date, publisher, source URL, update cadence). It is unmistakably distinct from siblings like terminology_diff or validate_codes, which operate on codes rather than server metadata.

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

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

Three concrete use cases are given (pre-batch-run version check, verifying bundled ICD-10/transition tables, citation in research artifacts), which establishes clear context for invocation. It stops short of explicitly naming alternatives or when-not-to-use cases, so it is a strong 4 rather than a 5.

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

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

Annotations already cover the safety profile, yet the description adds substantial beyond structured fields: 50-code cap with latency rationale, parallel execution, rate-limit dependency, and precise null/error semantics distinguishing 'not found' from 'couldn't validate'.

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

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

Front-loaded with purpose then a clean bullet enumeration of return fields, with the terminology-requirement and cap explained last. Dense but each section is justified; the return-field bullets edge toward restating the output schema.

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

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

A complex batch tool with an output schema, yet the description still clarifies the non-obvious null semantics of active/replaced_by and the valid+error truth table that the schema alone wouldn't convey. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% so the baseline is 3; the description adds the rationale for why terminology is mandatory per code (A00 ambiguity) and enumerates the accepted values, plus the cap's performance justification. Minor redundancy with the schema, hence 4 not 5.

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

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

States a specific verb (validate) and resource (mixed batch of medical codes against source terminologies). The 'mixed batch' framing plus per-code terminology requirement distinguishes it from the single-code lookup siblings like icd10_lookup and rxnorm_concept.

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?

Frames the use case clearly ('retrospective analysis of legacy databases') with the three outcomes it produces. It doesn't explicitly route away from sibling lookup tools for single-code cases, but the batch/fleet context is clear enough to imply the distinction.

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