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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), so the bar is lower; the description still adds useful behavior – return cardinality ('one entry per ATC code'), the single-ingredient vs combination-product distinction, and the NLM RxClass source. This is meaningful context beyond the structured fields.

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

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

Front-loaded with the core action, then a tight bulleted list, then return-shape notes. Structure is clean and scannable; the bullets border on restating the purpose but remain compact.

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

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

With annotations carrying safety hints and an output schema handling the return shape, the description supplies the remaining essentials: cardinality of results and the combination-product caveat. An agent has enough to call it correctly, though the missing sibling differentiation with atc_lookup is a small gap.

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

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

Schema description coverage is 100% and the schema itself documents drug_name as brand or generic with an example. The description repeats an example ('metformin') but adds no syntax, format, or edge-case semantics beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource: 'Look up the WHO ATC classification(s) for a drug by name', with a concrete example mapping ("metformin" → A10BA02). It does not differentiate itself from the sibling atc_lookup, which appears to address the same domain, leaving the agent to guess which to pick.

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

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

The 'Use this tool to' bullets give context (finding ATC codes, class hierarchy, cross-referencing), but they largely restate the purpose rather than stating when this tool is preferred over atc_lookup or atc_members. No exclusions or alternative routing is provided.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description adds real scope context: the endpoint does not expose substance-level 7-char codes and maps code length to hierarchy level, which is behavior an agent needs. It stops short of covering error handling on invalid codes.

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

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

Front-loaded purpose followed by a bulleted use-case list and a param note; every element earns its place. Minor redundancy: the substance-level caveat is repeated verbatim in both the description and the schema property.

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

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

With a single fully-documented parameter and an output schema that carries return values, the description supplies everything needed to invoke correctly, including the level semantics and the boundary against the sibling that handles substance 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%, so baseline is 3, but the description goes further by mapping each code length to a semantic level ('A' anatomical, 'A10' therapeutic, 'A10B' pharmacological, 'A10BA' chemical), which interprets the pattern rather than just restating it.

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

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

States a specific verb and resource (look up an ATC code to get its name and hierarchy level) and pins the scope to levels 1-4. It also distinguishes itself from the sibling atc_classify, so an agent can route without opening the schema.

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

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

Provides an explicit 'Use this tool to' list (resolve, confirm existence, identify level) and names an alternative plus the condition that selects it: substance-level 7-char codes are not exposed, use atc_classify instead. Both the when and the when-not are present.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description rightly focuses on other behavior: each member carries source_atc_code for disambiguation, class levels 1-4 return all substances while 5 returns one, and RxNorm's catalog is US-centric while ATC codes are international. That is genuine added context beyond the structured fields.

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

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

Front-loads the purpose in a single sentence, then uses a compact bulleted list for usage variants. Slightly repetitive (the level-1-4/level-5 behavior appears in both schema and prose), which keeps it from a 5.

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

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

With an output schema present, return values need not be explained, and the description still adds the source_atc_code field note and the US-centric vs international caveat. It omits any mention of result size, ordering, or pagination for potentially large classes, a minor gap for a subtree-expansion tool.

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

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

Schema coverage is 100%, so the schema already documents the atc_code regex and the level-1-4 vs level-5 behavior that the description restates. The description adds no syntax or format detail the schema lacks, so the baseline 3 applies.

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

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

Opens with a specific verb+resource: 'List the drugs (substances) that belong to an ATC class.' The scope is unmistakable and an agent can distinguish it from classification/lookup siblings like atc_classify or atc_lookup based on the phrasing alone.

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

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

Provides three concrete use cases (enumerate class members, build mechanism-based lists, explore a subtree at any level) with a worked example ('A10BA' → metformin, phenformin). It does not name exclusions or the sibling tools that would be chosen instead, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, and an output schema exists, so the safety/return profile is largely covered before the description speaks. The description contributes little beyond that — no note on what happens with an out-of-range chapter number, no mention of a fixed CID-10 V2008 dataset, and no pagination or cardinality remarks (how many groups per chapter).

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 scannable bullets and the input requirement. Slightly verbose: the long inline example occupies most of the first sentence, but it earns its place by showing the real 'chapter → groups with code ranges' payload.

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

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

For a single-parameter, read-only lookup with a rich annotation set and an output schema, the definition supplies purpose, usage scenarios and the input contract, so an agent can call it correctly. The only real gap is how it relates to sibling entry points (cid10_chapters, cid10_lookup) in a workflow.

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 'num' parameter already documents the 1-22 bound and the V2008 basis. The description only restates 'Provide a chapter number (1-22)', adding nothing about numbering conventions or whether the argument is a sequence index versus an official chapter designation, so the baseline 3 is appropriate.

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

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

Specific verb ('Get') plus a precisely scoped resource ('one CID-10 chapter and its constituent groups'), and the embedded example ("Chapter IX → I00-I02 Febre reumática aguda, I05-I09 ...") makes the returned shape unambiguous. The singular 'one chapter' cleanly separates it from the sibling cid10_chapters, which enumerates the chapter list.

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: drilling from a chapter into its groups, building hierarchical browsers, and resolving which group contains a code range. It states when to use it but never names an alternative or exclusion (e.g., use cid10_chapters first to discover valid chapter numbers, or cid10_lookup for a single code).

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context: the exact result size (22 entries) and the staleness caveat that CID-10 V2008 has not been updated since 2008, which an agent needs to reason about data currency.

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 opening sentence defines the tool, followed by a compact bulleted usage block and a one-line return note. Efficient, though the bullets restate part of the opening sentence (chapters I-XXII) rather than adding entirely new information.

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

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

With zero parameters, full annotation coverage and an output schema handling return structure, the description supplies everything else an agent needs: result cardinality, an example of the returned data, and a version/currency caveat. Nothing material is missing.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to clarify beyond confirming this is a parameterless listing call.

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

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

States a specific verb and resource with explicit scope: 'List the 22 chapters of CID-10 with their code ranges and Portuguese titles.' The word 'chapters' (top-level, 22 entries) clearly separates it from the singular sibling 'cid10_chapter' and from 'icd11_chapters' by naming the specific terminology.

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

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

The 'Use this tool to:' block gives three concrete scenarios (view top-level structure, map codes to chapters, build a table of contents), which is clear contextual guidance. It does not, however, state when to prefer the singular 'cid10_chapter' or 'cid10_lookup' instead, so exclusion/routing guidance is incomplete.

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 genuinely new behavior: it normalizes both dotted and undotted forms and returns the canonical display, plus it discloses that gender / cause-of-death restriction flags may be surfaced.

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 summary followed by a tight, scannable bullet list of use cases and a closing normalization note. No filler sentences; every line carries 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?

With annotations covering the safety profile and an output schema covering the return shape, the description needs only to explain purpose, usage, and input normalization — all of which it does. Nothing required to call the tool correctly is missing.

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

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

Schema coverage is 100% and the single parameter's description already documents the dotted/undotted examples and the regex pattern. The description's acceptance note and canonical-return statement largely restate the schema, so the baseline 3 is appropriate.

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

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

The description gives a specific verb and resource ("look up a specific CID-10 code") plus the concrete output ("return its Portuguese name"). The word "specific" implicitly contrasts with a search-style sibling, but it never names cid10_search or cid10_chapter, so sibling differentiation is only inferable.

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

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

Three explicit use cases are enumerated (resolve a code to its description, confirm existence of a 3/4-char category, retrieve restriction flags), which gives clear context for when to reach for this tool. However, it never states when NOT to use it or points to the alternative (e.g., cid10_search) for partial/name-based queries.

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 non-obvious behavior beyond annotations: it returns 3-char categories and/or 4-char subcategories, and it is diacritic-insensitive ('infeccoes' matches 'infecções'), which is genuinely useful for query construction. It does not describe rate limits or result ordering, but the added behavior is meaningful.

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

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

Front-loaded with the core action, followed by a scannable bullet list of use cases, then the return-shape and the sibling alternative. It is slightly longer than strictly necessary but every sentence (return granularity, diacritic-insensitivity, icd11_search alternative) carries information. No wasted framing.

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 read-only search tool with a full output schema, so the description need not explain return values. It covers language, edition/version, scope-of-match granularity, and the ICD-11 alternative. What is missing is how it differs from the other CID-10 lookup siblings, but for correct invocation of this tool it is essentially complete.

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

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

Schema coverage is 100% and all three parameters are documented in the schema, so the baseline is 3. The description adds real meaning: it explains the category/subcategory granularity that the 'level' enum controls and flags the Portuguese-language and diacritic-insensitivity constraints that shape the 'query' parameter. This is beyond what the schema alone states.

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 clear verb-and-resource: search the Brazilian CID-10 by Portuguese text, with explicit sub-use cases (SUS/ANVISA codes, official translation, billing/epidemiology). It explicitly distinguishes itself from icd11_search and names the CID-10 V2008 edition, so the agent can separate it from the international ICD-11 sibling. It does not clearly differentiate from the other CID-10 siblings (cid10_lookup, cid10_chapter, cid10_chapters), but the core purpose 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?

The 'Use this tool to' block gives concrete conditions (SUS/ANVISA contexts, official Portuguese translation, billing/epidemiology), and the closing sentence explicitly names the alternative icd11_search and the condition that selects it (international ICD-11 in English). There are no explicit exclusions for the sibling CID-10 lookup tools, but the contextual 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 declare readOnly, idempotent, openWorld, and non-destructive hints. The description adds useful behavioral context: unknown ids return an error, the operation is a live GET against the public source when needed, and the return payload has a defined shape. This goes beyond annotation-only information.

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 well-structured and front-loads the return contract, then context, then behavior. It is a bit longer than strictly necessary because it restates some annotation-backed properties, but every paragraph adds useful orientation.

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 tool with a rich output schema and complete annotations, the description covers return shape, valid input source, error behavior, positioning relative to siblings, and safety semantics. Nothing critical is missing for an agent 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 input schema already describes `id` as 'Identifier of a document returned by `search`' at 100% coverage. The description reinforces this by explaining the id must come from `search`, but it does not add new format or syntax details. With full schema coverage, the baseline 3 is appropriate.

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

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

The description uses a specific verb ('Returns') with a clear resource (the full document for an id from `search`) and specifies the exact output shape. It also separates itself from the terminology data-query tools, so an agent can distinguish it from siblings without ambiguity.

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

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

It explicitly states that `fetch` is the companion of `search`, that only ids returned by `search` are valid, and that terminology tools should be used for data queries instead. This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), but the description adds substantial non-obvious behavior: match_score/rank are server-computed because upstreams lack comparable scores, groups cluster lexically identical titles and their absence is explicitly NOT evidence of non-equivalence, and the search is English-only.

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

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

Front-loaded with the purpose, then a scannable bullet list, then parameter behavior, then the alternative tools — good ordering with no filler. It loses a point for mild redundancy, since the source/target combination rule and terminology list are stated in both prose and the schema.

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

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

With rich annotations, a full schema, and an output schema present, the description still covers the one thing the schema cannot: how to interpret the returned match_score/rank/groups and why paging is not an option. Nothing an agent needs to call or 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 the baseline is 3; the description still adds meaning by clarifying that limit is a per-terminology cap rather than a page cursor and by restating the subtraction rule for source_terminology. It stops short of adding anything new for term or target_terminologies that the schema does not already say.

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') and immediately bounds the scope to cross-terminology search over five named systems. It is clearly distinguishable from the per-terminology siblings (icd11_search, loinc_search, mesh_search), which it explicitly routes away from for pt-BR.

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

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

Gives three concrete use cases, explains exactly how source_terminology and target_terminologies interact ('source is subtracted from targets'), and names alternatives with their conditions (icd11_search/mesh_search with language 'pt', cid10_search for natively Portuguese content). Explicit when-to-use and when-to-use-something-else.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive behavior, so the safety profile is fully covered without prose. The description adds only the incidental fact that ICD-11 has 28 chapters; it says nothing about translation behavior (which lives in the schema) or result shape. This meets the reduced bar for an annotated tool but adds little beyond it.

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 definition in the first line, then uses a short bulleted list and a closing fact. No sentence is wasted, though the final '28 chapters covering all areas of medicine' line is mild filler rather than essential 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?

With an output schema present, return values need not be explained, and the single optional parameter is handled by the schema. The description covers purpose and use cases adequately for a simple read-only listing tool, with only sibling differentiation and any pagination/size hints left unstated.

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

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

Schema description coverage is 100%, and the single 'language' enum parameter is fully documented in the schema including the note about official translations vs. machine translation. The description does not mention the parameter at all, 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 (List) and resource (ICD-11 chapters), with the parenthetical '(top-level categories)' clarifying what a chapter is. It is distinguishable from siblings like icd11_search, icd11_lookup, and icd11_hierarchy by naming the chapters resource, but it never explicitly contrasts itself with the nearest sibling (icd11_hierarchy), so it stops short of a 5.

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

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

The 'Use this tool to:' block gives three concrete scenarios (overview of structure, mapping a body system to a chapter, navigating to categories), which is clear context for selection. It provides no exclusions or explicit alternatives, so the guidance is directional but not exhaustive.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description adds genuinely new behavior: block entities come back from 'parents' with an empty code and a code_range, and language returns official translations rather than machine-translated content.

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

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

Front-loaded with the one-line purpose, then a tight bulleted use-case list, then the naming/direction rules. Every sentence earns its place, including the ICD-10 caveat.

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

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

An output schema exists, so return values need no explanation. With annotations carrying the safety profile, the description fully covers identification, direction semantics, input naming, and the cross-terminology boundary.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by explaining that a block range can be passed as a code, that blocks surface with an empty code plus code_range, and that uri means any URI from a previous answer — all details the schema does not spell out.

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

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

States a specific verb (navigate) and resource (ICD-11 hierarchy) and pins the exact scope: parent and child entities. It is clearly distinguishable from siblings like icd11_lookup and icd11_search, which resolve entities rather than traverse relationships.

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 (broader parents, specific children, understanding classification structure), defines what each direction value returns, and pre-empts the common mistake that ICD-10 codes are not ICD-11 codes by routing to map_icd10_to_icd11.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive, so the safety profile is fully covered. The description adds the useful note that content is never machine-translated, but says nothing about rate limits, error behavior for invalid codes, or response shape. Given annotations carry the safety burden, a 3 is fair.

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 opening sentence, then a tight bulleted list of use cases, plus a compact note on the language parameter. 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?

Output schema exists, so return values need not be described. For a read-only lookup with 100% schema coverage, the description is nearly complete; only a note on invalid-code handling or the uri-vs-code precedence would make it fully self-sufficient.

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 each param is documented in the schema, including enums and defaults. The description reinforces the code/URI choice and adds a concrete language example, but adds little semantic detail beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb (get) and resource (detailed information about a specific ICD-11 entity), and the by-code-or-URI mechanism clearly separates it from siblings like icd11_search or icd11_hierarchy.

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

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

The bulleted 'Use this tool to' list gives concrete retrieval scenarios (definition, coding notes/exclusions, title/synonyms), which orients usage well. However, it never explicitly says when NOT to use it or names siblings like icd11_search as the alternative for fuzzy lookup.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered without the description's help. The description adds only domain framing (severity, laterality, anatomy) and says nothing about authorization, rate limits, or error behavior, so it clears the lowered bar but adds modest value.

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

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

The core purpose is front-loaded in the first sentence and the bullets are scannable. The trailing "Postcoordination allows adding..." line is somewhat illustrative padding, keeping it just short of ideal.

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 is not obligated to explain return values, and it adequately conveys what the tool produces and why. It is complete enough for a single-parameter lookup tool, though a one-line distinction from icd11_lookup would close the remaining gap.

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

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

Schema description coverage is 100% and there is a single required "code" parameter whose schema description already documents it. The description adds no format or syntax detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource ("Get postcoordination information for an ICD-11 code") plus a domain gloss on what postcoordination means. An agent can identify the tool's function, though it never explicitly contrasts itself with the heavily-overlapping icd11_lookup/icd11_hierarchy 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?

The "Use this tool to:" bullets give concrete contexts (find composite-code axes, check required vs optional postcoordination, understand extension possibilities). Clear usage context, but no explicit when-not or named alternative among the sibling ICD-11 tools.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: results are official WHO translations and 'never machine-translated', with a concrete pt-BR example, which affects how an agent should trust and present labels.

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

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

Front-loaded with the core verb+resource, then a scannable bullet list, then a behavior note. It is appropriately sized, with only mild redundancy in restating the official-translation point that the schema also carries.

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 the description needn't explain return values, and annotations cover the safety profile; params are fully schema-documented. The remaining description content (language translation behavior, search scope) rounds out what an agent needs to call this correctly.

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

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

Schema description coverage is 100%, so query, language, and max_results are already documented in the schema, including the official-translation note. The description largely restates the schema's language semantics rather than adding new meaning, so the baseline 3 applies.

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

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

States a specific verb and resource ('Search for medical conditions, diseases, and health problems in ICD-11') plus the full expansion of the acronym, so the agent immediately knows what it does. It does not, however, differentiate itself from siblings like icd11_lookup or cid10_search, so an agent still has to infer which is exact-match versus keyword search.

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

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

The 'Use this tool to' bullets give clear positive context: find codes for diagnoses, search by name/keyword, and look up conditions in multiple languages. There is no explicit when-not guidance or named alternative (e.g. 'use icd11_lookup for a known code'), so it stops short of full 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 readOnly, idempotent, openWorld, and non-destructive behavior, so the safety profile is covered. The description adds the applicability constraint, which is genuinely useful, but says nothing about what happens for a code with no answer list (empty result vs. error) or any rate/format behavior. With annotations carrying the main burden, this is adequate but 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 purpose and constraint are front-loaded and the whole thing is short, but the three bullets are largely restatements of one another ('find valid response options', 'get answer codes', 'look up answer lists') and could collapse into a single sentence without losing meaning.

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

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

For a single-parameter lookup with a full output schema, the description covers purpose, use cases, and the key applicability constraint, so an agent has enough to call it correctly. The only gap is failure/empty-result behavior, which is minor given the output schema exists.

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 and schema description coverage is 100% — the schema documents loinc_num, its pattern, and an example. The description adds no format or semantics beyond that, so the baseline of 3 applies.

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

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

The opening sentence gives a specific verb (Get) and resource (list of valid answers) scoped to a LOINC questionnaire item, which clearly separates it from siblings like loinc_details or loinc_panels. The closing constraint ('Only applicable to LOINC codes that represent questions with defined answer sets') further narrows scope, though no sibling is named explicitly.

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

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

The 'Use this tool to:' bullets give concrete scenarios (survey response options, data-entry validation, standardized answer lists), and the final sentence supplies a when-not condition (codes without defined answer sets). It lacks explicit routing to alternatives such as loinc_details, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so safety and repeatability are covered. The description adds only that an exact code format is required; it says nothing about behavior on an unknown code (error vs empty) or the provenance of the returned data, which is the useful behavior gap here.

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

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

Front-loaded with the core action in the first sentence, followed by a short bulleted enumerations of outputs and the required input format. Well sized for a single-parameter lookup, though the bullets restate fields the output schema likely already carries.

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

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

For a simple one-parameter, read-only lookup with an output schema present, the description covers purpose, inputs, and returned field categories. The only real gap is routing relative to sibling LOINC tools, which is arguably a usage-guideline omission rather than a completeness one.

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 loinc_num with a regex pattern and an example. The description repeats the format 'XXXXX-X' and gives the same '2339-0' example, adding no meaning beyond the schema, so the baseline 3 is appropriate.

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

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

States a specific verb and resource: 'Get detailed information about a specific LOINC code', then enumerates the fields returned (name, component, property, timing, system, scale, method). Clear purpose, but it does not distinguish itself from siblings like loinc_search, loinc_panels, or loinc_answers beyond the code-vs-query distinction, which the agent must infer.

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

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

The 'Use this tool to' list describes what the tool returns, not when to pick it over loinc_search or loinc_panels. There is no explicit when-to-use/when-not or alternative routing, so the agent must infer that this is the detail-by-exact-code tool rather than the search tool.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=true, so the safety and idempotency profile is clear. The description adds that it returns a list of LOINC codes, which is helpful, but doesn't mention any behavioral aspects like rate limits or potential errors. With annotations covering most, a 3 is appropriate.

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

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

The description is structured with a clear opening sentence, followed by a bulleted list of use cases, and a closing sentence about returns. It's concise and front-loaded, though the bulleted list could be seen as slightly verbose for the amount of information conveyed.

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 that there is an output schema, the description needn't explain return values in detail, but it does summarize that it returns a list of LOINC codes. The description covers the purpose, usage examples, and return summary, making it largely complete for an agent to use. It could benefit from noting that the output schema provides further details, but that's 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%, so the loinc_num parameter is fully documented in the schema with pattern and example. The description doesn't add any parameter-specific details beyond what's in the schema. Baseline 3 is correct 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 states a specific verb and resource: 'Get the structure of a LOINC panel or form.' This clearly distinguishes it from siblings like loinc_details or loinc_search, which retrieve details or search for codes. However, it doesn't explicitly differentiate from loinc_answers, which might also relate to LOINC code groupings, leaving a small ambiguity.

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

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

The 'Use this tool to' section provides clear examples of when to use it: seeing tests in a panel, understanding assessment form structure, and finding related observations. It doesn't state when not to use it or which alternative tools to consider for similar tasks (e.g., loinc_details for specific code info).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so safety and repeatability are covered. The description adds only that results include names, components, and properties, and implies partial-code matching; it discloses nothing about breadth limits, ranking, or rate considerations beyond the schema's max_results cap.

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, leading with scope before the example list. Minor redundancy: 'laboratory tests' and 'lab tests' cover the same ground in the opening sentence and first bullet.

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

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

An output schema exists, so return-value explanation is unnecessary and correctly omitted. The schema covers all parameters and the annotations cover the safety profile; the only material gap is routing among the many LOINC-category siblings, which is exactly where an agent is most likely to misfire.

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

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

Schema description coverage is 100%, with both 'query' (test name, keyword, or partial LOINC code) and 'max_results' (1-100, default 25) fully documented in the schema. The description adds no syntax, matching-behavior, or formatting detail beyond what the schema already states, so baseline 3 applies.

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

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

The description uses a specific verb ('Search') on a specific resource (LOINC codes for lab tests, clinical observations, measurements) and lists concrete query examples like 'glucose' and 'hemoglobin'. It does not, however, explicitly differentiate itself from LOINC siblings such as loinc_details, loinc_panels, 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 clear positive scenarios (finding codes for lab tests, measurements, vital signs, diagnostic observations), which is better than nothing. But there is no when-not guidance and no mention of the LOINC alternatives (loinc_details for a known code, loinc_panels for panel structure), leaving the selection boundary implied.

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

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

Beyond the readOnly/idempotent annotations, it discloses that mappings may be 1:1 or split into multiple candidates, what fields come back (code, title, chapter, Foundation/Linearization URI), the 11,243-category coverage and its exclusion of blocks like 'A00-A09', and the explicit 'no mapping' outcome instead of a fuzzy fallback.

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

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

Front-loaded with purpose and source, then progressively adds return shape, use cases, coverage limits, and examples. Every sentence carries information, though the separate 'returns...' and 'coverage...' statements could be tightened slightly.

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 a one-parameter tool with full schema coverage, an output schema, and rich annotations, the description covers everything an agent needs: usage scope, accepted input formats, coverage boundaries, and fallback behavior.

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 self-describing, so the baseline is 3; the description adds value by stating that both dotted ('A07.8') and undotted ('A078') forms are accepted and by giving worked examples with known behavior.

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

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

States a specific verb+resource ('ICD-10 → ICD-11 mapping') with the source of truth (WHO transition tables, release 2025-01). It also distinguishes itself from text-search siblings ('rather than text-search candidates'), so an agent can route correctly without opening schemas.

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

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

Explicitly names use cases (clinical coding, billing migration, retrospective analysis) and contrasts with the text-search alternative. It does not name the specific sibling (icd11_search / find_equivalent) that would be the fallback, leaving that routing to inference.

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

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

Annotations already declare readOnly/idempotent/openWorld/non-destructive, so the safety profile is covered; the description goes further and discloses the crucial behavioral trait that it returns guidance rather than a mapping, plus the licensing/auth constraints (UTS license, Regenstrief authenticated download) behind the alternatives. No contradiction with annotations.

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

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

Front-loads the key limitation and then routes to alternatives; the license/dependency paragraph is somewhat dense but each sentence carries decision-relevant information. Slightly longer than strictly necessary for a one-parameter lookup.

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

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

An output schema exists, so return values need no explanation, and the description fully covers the unusual semantics (guidance, not mapping), the reason for the limitation, and all workable alternatives. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100% and the single parameter already documents its pattern and example, so the baseline is 3. The description adds a second realistic example ('718-7' Hemoglobin) but no format or validation semantics beyond what the schema states.

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 ('looks up a LOINC code in NLM Clinical Tables') and immediately bounds the scope with 'It does not perform the mapping.' That negative statement cleanly separates it from mapping siblings like map_icd10_to_icd11 and from loinc_details/loinc_search.

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

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

Explicit when-to-use routing: programmatic mapping -> UMLS or LOINC Expression Association files; interactive lookup -> institutional SNOMED CT browser or RELMA. It also states why the tool exists (direct mappings are not freely available via API), which is exactly the context an agent needs to avoid mis-selecting it.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds useful behavioral context beyond that: it enumerates what is returned (scope note, tree numbers, related concepts/synonyms) and clarifies the non-obvious language rule that content is never machine-translated and only official NLM translations are returned.

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

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

Front-loaded one-line purpose followed by a tight, scannable bullet list of retrievable fields, then a compact note on ID and language. Minor redundancy with the language parameter already documented in the schema, but no wasted prose.

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

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

With an output schema present, the description needn't explain return values, yet it helpfully summarizes the key ones. The one real gap is sibling disambiguation among mesh_search/mesh_tree/mesh_qualifiers, but coverage of inputs and behavior is otherwise complete.

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

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

Schema coverage is 100% and the schema already documents the ID pattern/example and the 'official translation, never machine-translated' caveat. The description's parameter text (example ID, language example) largely restates the schema, so the baseline 3 applies.

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

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

States a specific verb+resource (get detailed info about a MeSH descriptor) and pins it to lookup-by-ID, which is genuinely distinct from a search tool. However, it never names the obvious siblings (mesh_search, mesh_tree, mesh_qualifiers), so an agent must infer the boundary between this and mesh_tree (which also surfaces tree numbers).

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 of what you can retrieve implies the usage context (when you already have a Descriptor ID), but there is no explicit when-to-use/when-not guidance and no alternative tool is named. An agent can infer it, but nothing routes it away from mesh_search or mesh_tree.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered without the description. The description adds domain context (that qualifiers refine descriptors, with an example) but no behavioral traits beyond annotations such as coverage or response characteristics. With annotations doing the heavy lifting, a 3 is appropriate.

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

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

Front-loaded with the core action, then a compact bulleted list of use cases, and a clarifying example sentence. Every element earns its place, though the bullets are slightly repetitive with the opening sentence.

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

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

An output schema exists, so return values need not be explained, and the single required parameter is fully documented in the schema. Annotations cover the safety profile. The description is complete enough for correct invocation, missing only sibling routing guidance.

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

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

Schema description coverage is 100% and there is a single parameter (mesh_id) with a documented pattern and examples. The description implies the input is a MeSH descriptor but adds no format or syntax detail beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb and resource: 'Get allowed qualifiers (subheadings) for a MeSH descriptor.' The parenthetical and the example ('Diabetes Mellitus/drug therapy') make the concept unambiguous. It does not explicitly differentiate itself from siblings like mesh_descriptor or mesh_tree, but the resource is narrow enough to distinguish it.

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

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

The 'Use this tool to' list gives three concrete scenarios (finding combinable qualifiers, building search queries, understanding specifiable aspects). That is clear usage context, but no explicit exclusions or named alternatives (e.g., when to use mesh_descriptor instead) are provided.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds genuinely useful behavioral context the annotations cannot convey: language requests return only NLM's official translations and content is never machine-translated, which sets a real expectation about result quality and coverage.

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

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

Front-loaded with the core purpose, then a tight bulleted use-case list, then the language caveat. Every element is short and scannable, though the language paragraph and the closing returns-line partially duplicate the schema and could be trimmed.

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

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

With an output schema present, the description needn't explain return values, and it doesn't over-explain. Combined with rich annotations and 100% schema coverage, the definition gives an agent everything needed to invoke it correctly; 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 description coverage is 100%, so match/query/language/max_results are already fully documented in the schema. The description's language note largely restates the schema's own language description rather than adding new syntax or format guidance, so the baseline 3 is appropriate.

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

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

States a specific verb+resource ("Search for MeSH descriptors") and enumerates three concrete use cases (indexing, PubMed subject headings, controlled vocabulary). It is clearly distinguishable from lookup-style siblings like mesh_descriptor, mesh_tree, and mesh_qualifiers, though it never names them explicitly.

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

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

The "Use this tool to" block gives clear task-oriented context for when this search is appropriate. It stops short of stating exclusions or naming alternatives (e.g., mesh_descriptor for ID-based lookup), so the agent must infer the boundary itself.

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 a useful tree-number format example (C14.280.647), but says nothing about pagination, missing descriptors, or error behavior beyond what annotations provide.

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

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

Front-loaded with the core purpose, then a short scannable bullet list and one clarifying example. Slightly list-heavy for a one-parameter tool, but nothing is padded and the key information leads.

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

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

An output schema exists, so return values need not be described, and the description covers purpose, use cases, and tree-number format. For a simple read-only lookup this is essentially complete, with only minor gaps in edge-case behavior.

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

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

Schema description coverage is 100%: the single mesh_id parameter is documented with its pattern and descriptor-ID examples. The description does not elaborate on the parameter at all, so baseline 3 is appropriate for a one-parameter tool whose schema does the work.

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

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

The first sentence states a specific verb and resource ('Get the tree hierarchy location(s) for a MeSH descriptor'), which clearly separates it from mesh_search or mesh_descriptor. It never names those siblings explicitly, so an agent must infer the boundary, but the scope ('tree hierarchy locations') 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?

The bullet list gives concrete use cases (find hierarchy position, broader/narrower relationships, related terms in the same branch), which is clear when-to-use guidance. It stops short of naming alternatives or exclusions, so the agent gets context but no routing rules.

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

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

Annotations already declare the full safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint), so the description need not restate safety. It does add a return-content hint ('class IDs, names, and classification sources'), but since an output schema exists, this is modest added value. No auth, rate-limit, or edge-case context is given.

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

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

The purpose is front-loaded in one sentence, followed by a short scannable bullet list and a returns line. It is appropriately sized, though the bullets largely restate 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?

With an output schema present and annotations covering safety, the description needs only to establish purpose and basic return shape, which it does. The main gap is the absence of any sibling disambiguation against the ATC classification tools, but nothing essential for a correct single-param call is missing.

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

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

Schema coverage is 100% with a single, fully described parameter (rxcui with a numeric pattern), so the schema carries the semantic load. The description adds nothing about what the rxcui represents or where to obtain it, which is the correct baseline of 3 when the schema already documents the 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?

The first sentence gives a specific verb+resource ('Get therapeutic and pharmacologic classes for a drug') that an agent can act on. The bulleted examples reinforce the concept with concrete instances (Beta-blockers, NSAIDs). However, it does not distinguish itself from close siblings like atc_classify/atc_members, which are also drug-classification tools.

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

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

The 'Use this tool to' list describes what the tool can find, not when to choose it over alternatives. There is no explicit when-not guidance and no sibling is named, even though ATC class tools overlap heavily. Usage is implied by the capability list rather than contrasted against alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, destructiveHint=false, so the safety profile is covered. The description adds the scope note that a valid RxCUI identifier is required, but discloses nothing about rate limits, status semantics (what 'remapped' means for follow-up calls), or failure behavior for unknown RxCUIs. With annotations carrying the core profile, this is adequate but 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?

Reasonably short and front-loaded: the first sentence states the core action and the parameter. The bulleted 'Use this tool to' block is useful but slightly redundant with the intro sentence. No wasted filler.

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

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

With a 2-parameter schema at full coverage, an output schema present, and annotations covering safety, the description needs only to orient the agent, which it does. Its only notable gap is routing guidance versus sibling lookup/search tools, which matters given the large sibling set.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description restates the RxCUI requirement and gives an example value ('161'), which adds a concrete format example beyond the regex pattern, but does not explain include_related semantics beyond what the schema already says. Baseline 3 is appropriate.

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

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

The description clearly states a specific verb (Get detailed information) and resource (a specific RxNorm concept by RxCUI), and the bullet list of what it returns (name/synonyms, status, related concepts) adds concrete scope. It doesn't explicitly distinguish itself from siblings like rxnorm_search or rxnorm_ingredients, but the 'by RxCUI' framing implies lookup-by-identifier versus search.

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

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

Usage is implied by the list of things you can do ('Use this tool to: ...'), but there is no explicit when-to-use guidance and no named alternatives. An agent can infer this is for direct identifier lookup rather than search, but the description never says to prefer rxnorm_search when you lack an RxCUI.

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 structurally. The description adds the return payload form ('ingredient RxCUIs and names') but discloses nothing about rate limits, auth, or behavior for invalid/unknown RxCUIs. With annotations carrying the safety burden, a 3 is appropriate.

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

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

The core action is front-loaded in the first sentence, followed by a short scannable bullet list and a one-line return note. It is tight, though the bullets largely restate the purpose and could be trimmed.

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

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

With a fully documented single parameter, rich annotations, and an existing output schema, the definition supplies enough for an agent to call it correctly. The only modest gap is the lack of routing to sibling tools for obtaining the input RxCUI.

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

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

Schema description coverage is 100% with a single required 'rxcui' parameter that already documents its pattern. The description only restates 'by RxCUI' and adds no syntax, format, or edge-case meaning beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific verb and resource ('Get active ingredients for a drug by RxCUI') and names the required identifier, making the operation unambiguous. It does not explicitly differentiate itself from siblings like rxnorm_concept or rxnorm_search, so it stops short of a 5.

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

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

The 'Use this tool to:' bullets give three concrete scenarios (finding ingredients, single vs. multi-ingredient checks, generic components of brands), which implies when the tool applies. However, it never names an alternative or states when NOT to use it (e.g., use rxnorm_search first to obtain the RxCUI), so guidance is only partially fulfilled.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, fully covering the safety profile. The description adds no behavioral context beyond the input/output mapping, and with an output schema present, return-value details are not needed.

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 purpose and followed by bulleted use cases and a concise input directive. No wasted words, though the bullet list slightly repeats the mapping 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?

Complete for a read-only mapping tool: purpose, usage, and parameter semantics are all clear. Annotations and output schema cover safety and return values, so the description need not repeat them.

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 documented in the schema. The description reinforces their roles ('RxCUI to get NDC codes for' and 'NDC code to look up RxCUI'), adding the explicit directional semantics and mutual exclusivity beyond the schema's basic descriptions.

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

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

States a specific bidirectional transformation: mapping RxNorm concepts (RxCUI) to NDC codes and back. The bulleted use cases distinguish it from sibling tools like rxnorm_concept or rxnorm_search, which focus on concept metadata or searching rather than NDC cross-referencing.

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 says 'Provide either an RxCUI to get NDCs, or an NDC to get the RxCUI', telling the agent exactly which input drives which direction. The mutual exclusivity is clear, though it doesn't name a sibling alternative, but no sibling overlaps this function.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety and idempotency profile is fully covered by structured data. The description adds that results include RxCUI, names and term types, but no mention of matching semantics (prefix vs fuzzy), result ranking, or open-world behavior from a live terminology service.

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 return-value line. Slightly over-listed for such a simple tool but no wasted sentences.

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

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

Given the output schema exists and annotations cover safety/idempotency, the description is largely complete: it says what to search, why, and what comes back. Missing only how the search matches (exact vs partial) and pagination behavior, which are minor for this complexity.

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

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

Schema description coverage is 100%, so both parameters are already fully documented with type, default, and range. The description adds no syntax, format, or matching details beyond what the schema provides; baseline 3 applies.

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

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

Clear verb+resource: search drugs in RxNorm, with the expansion of the acronym. Distinguishes from rxnorm_concept/rxnorm_ingredients implicitly by being the name-search entry point. Sibling differentiation is not explicit but the scope is clear.

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 concrete when-to-use scenarios (find by brand/generic, look up for prescribing, search formulations). No explicit when-not-to-use or named alternatives among the many rxnorm_* siblings, which prevents a 5.

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

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

Beyond the annotations, the description discloses meaningful behavioral details: it returns at most 10 documents ordered by relevance, uses an empty list for no matches, works in Portuguese or English, ignores accents and case, and is backed by an in-memory cache of a public source. These details help an agent predict results accurately.

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 capability and then provides routing context, query guidance, and behavior in separate sections. It is somewhat dense and repeats the read-only/idempotent hints already present in annotations, but every paragraph earns its place by helping agents choose and use the 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?

With one optional-free parameter, an output schema present, and clear return-shape details in the description, there is no missing information needed to invoke the tool correctly. The description even covers the no-match case and the follow-up `fetch` step, making it complete for an agent.

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 input schema already covers the single `query` parameter at 100%, so the baseline is 3. The description adds value by specifying Portuguese or English as accepted languages and clarifying that natural language or keywords are both valid, slightly extending 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?

The description states a specific verb and resource: it searches the medical terminologies catalog and returns matching documents with an explicit shape and limit. It also distinguishes itself from the terminology data tools by clarifying it is a catalog index, not a data query, which prevents confusion with sibling `*_search` tools.

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

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

The description explicitly says when this tool is required — the OpenAI Deep Research contract requires `search` and `fetch` — and explicitly routes direct data questions to the terminology tools (`icd11_*`, `cid10_*`, etc.). It also tells the agent to pass returned ids to `fetch`, giving clear workflow guidance.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), and the description adds substantial context beyond them: the server ships no historical snapshots, bundled_versions exposes what is on hand, and the ICD-10 path returns counts of 1:1 vs split mappings and average alternatives. This is real behavioral disclosure not present in structured fields.

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

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

Well front-loaded with the general case first, then the ICD-10 exception, then inputs, then a scope caveat. Slightly long, and the Inputs block partially restates schema properties, but each section carries distinct value.

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

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

Output schema exists, so return values don't need spelling out, yet the description still characterizes the ICD-10 summary payload. For a tool whose behavior varies sharply by terminology, the definition covers both modes and the fallback guidance adequately.

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 genuine meaning: it explains the default behavior of from_version (currently-bundled version) and to_version (publisher's latest known release) and the special ICD-10 invocation with terminology only. It goes beyond the schema's terse per-property text.

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

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

States a specific verb (report) and resource (diff data between two terminology versions) and immediately frames itself as a metadata/guidance layer rather than a diff engine, cleanly separating it from map_icd10_to_icd11 and terminology_versions. An agent can tell what this returns without opening the schema.

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

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

Explicitly distinguishes the general case (guidance only, use the publisher changelog for SNOMED/LOINC/RxNorm/MeSH) from the one case with real data (ICD-10→ICD-11), and gives the exact invocation shape for it. It even names the authoritative alternative for frequent-change terminologies.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), but the description adds real behavioral context beyond them: the ICD-10→ICD-11 entry reads live from the bundled dataset while the rest is static release metadata, plus the fact that the full set of 8 is returned by default.

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

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

Front-loaded with the core purpose, then a scannable bullet list of use cases, then the parameter note and provenance caveat. Every sentence carries information; nothing is redundant padding.

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

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

An output schema exists so return values need no explanation. Between the purpose, use cases, parameter default behavior, and data-freshness caveat, an agent has everything needed to select and call it correctly.

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

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

Schema coverage is 100% and the single enum parameter is fully documented in the schema, including the 'omit to return all 8' behavior. The description restates the same filter/default behavior without adding format or usage nuance, so the baseline 3 applies.

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

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

States a specific verb (List) and a precise resource (version, release date, publisher, source URL, update cadence of every terminology), which no sibling covers. It never explicitly names a sibling it is not (e.g., terminology_diff or validate_codes), so it falls just 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?

Gives concrete when-to-use contexts via the 'pipeline maintainers who need to' list: pre-batch release confirmation, verifying the frozen CID-10/transition tables, and citing versions in research. No explicit alternatives or when-not-to-use conditions are given, keeping it at a 4.

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

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

With annotations already covering the safety profile, the description adds substantial operational context: the 50-code hard cap, parallel execution via per-terminology clients, worst-case ~10 s latency tied to upstream rate limits, and precise error semantics distinguishing 'not found' (valid:false, error:null) from 'couldn't validate' (error set).

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 purpose, then structures return-field semantics as a scannable bullet list, ending with operational limits. Some return-value detail is verbose given an output schema exists, but nearly every sentence carries meaning for a batch tool with unusual null/error semantics.

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 a batch mutation-free validator with nested input items, an output schema, and per-terminology nuances, the description covers scope, field semantics, null behavior, error distinction, accepted terminologies, cap, and latency. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% and the enum values, per-item structure, minLength, and maxItems are already documented in the schema. The description reinforces why terminology is required per code (category codes like 'A00' collide across ICD-10/CID-10) but adds little beyond what the schema already states, so the baseline 3 applies.

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

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

States a specific verb and resource ('Validate a mixed batch of medical codes against their source terminologies') plus a concrete use case (retrospective analysis of legacy databases). The batch/mixed-terminology framing implicitly separates it from single-terminology siblings like icd10_lookup or loinc_details, but no sibling is named explicitly.

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

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

Usage is implied through 'retrospective analysis of legacy databases' and the flagging/replacement features, which suggests when it is valuable. However, it never states when to prefer this over alternatives such as map_icd10_to_icd11, find_equivalent, or terminology_diff, nor any explicit exclusions.

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