Medical Terminologies MCP

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

Annotations already establish read-only, open-world, and idempotent behavior. The description adds valuable behavioral context: one entry per ATC code, single-ingredient versus combination mapping differences, and that data comes from NLM RxClass. There is no contradiction with the annotations.

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

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

The description is well-structured and front-loaded with a clear one-sentence definition, followed by actionable bullets and a concise return-behavior note. Every section earns its place without redundancy or filler.

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

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

For a single-parameter read-only tool with an output schema and rich annotations, this description is complete. It covers what the tool does, example usage, return cardinality, multi-code behavior, and data source. Nothing critical is missing for correct invocation.

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

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

The input schema already fully documents the single parameter with brand/generic details and an example, so description-level parameter explanation adds limited value. The metformin-to-A10BA02 example reinforces the parameter but does not materially expand semantic understanding.

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

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

The description clearly states the tool looks up WHO ATC classifications for a drug by name and provides a concrete example. However, it does not explicitly distinguish itself from sibling atc_lookup, leaving some potential ambiguity for an agent choosing between similar-sounding 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 bullet list gives clear, actionable scenarios for when to use the tool: finding ATC codes, identifying class hierarchy, and cross-referencing drugs. It does not explicitly state when not to use it or name alternatives, but the guidance is specific enough for most selection contexts.

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

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

Annotations already establish readOnly, idempotent, and non-destructive behavior. The description adds useful operational context: accepted code lengths, the fact that substance-level codes are not exposed, and the tool's function of confirming existence in the current ATC index. It does not contradict annotations, and no error-behavior detail is necessary for this simple read-only lookup.

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

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

The description is front-loaded with a clear purpose, uses compact bullet points, and keeps examples short. There is slight redundancy because the substance-code caveat appears in both the description and the parameter schema, but the description remains appropriately sized and scannable.

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

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

For a single-parameter, read-only lookup with an output schema, the description is complete: it defines input format, valid levels, edge cases, what the result represents, and which sibling tool should be used for unsupported codes. No significant context 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 input schema already covers the parameter fully with a pattern and a note about substance-level codes. The description goes beyond the schema by mapping code lengths to hierarchy levels (A, A10, A10B, A10BA) and explaining the alternative for 7-character codes, which adds semantic meaning for the agent.

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 and resource: 'Look up an ATC code at level 1-4 to get its name and hierarchy level.' It gives concrete examples (e.g., A10BA -> Biguanides) and explicitly distinguishes itself from atc_classify, making sibling differentiation 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?

The description provides an explicit 'Use this tool to' bullet list and states a clear exclusion: substance-level codes (7 chars) are not exposed and should be handled by atc_classify instead. This gives the agent an explicit when-to-use and when-not-to-use condition with a named alternative.

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, openWorldHint, idempotentHint, and non-destructive behavior. The description adds useful behavioral context beyond those flags: the returned members include substance-level 7-char ATC codes via source_atc_code, and it notes the RxNorm catalog is US-centric while ATC identifiers are international.

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

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

The description is front-loaded with the core purpose, then uses bullets for actionable uses, followed by a concise caveat about output fields and data scope. It is slightly longer than strictly necessary but every sentence adds useful information.

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

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

The tool is simple with a single documented parameter, an output schema, and rich annotations. The description covers purpose, usage scenarios, output field details, and data-source caveats, so an agent has enough context to select and invoke the tool correctly.

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

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

The schema already fully documents the single atc_code parameter, including the pattern and the behavior at different ATC levels. The description adds a concrete example and emphasizes the substance-level code in results, but the parameter meaning is already well covered by the schema.

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

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

The description opens with a specific verb and resource: 'List the drugs (substances) that belong to an ATC class.' It also gives concrete examples and distinguishes the tool's membership-listing purpose from sibling tools like atc_lookup and atc_classify.

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 provide clear scenarios: enumerate class members, build lists by pharmacological mechanism, and explore ATC subtrees. It does not explicitly name alternatives or exclusion criteria, but the intended use cases are well communicated.

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 disclose readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description only needs to add context. It adds meaning by explaining that results include constituent groups and code ranges, which is useful. However, it doesn't go deeper into response behavior, and the output schema already carries some of that burden.

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 compact and front-loaded with the core behavior and an illustrative example. The bullet list is useful and readable, though the final sentence 'Provide a chapter number (1-22)' repeats schema information and could be trimmed, keeping it from a 5.

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

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

For a low-complexity tool with one well-documented parameter, an output schema, and safety annotations, the description is largely complete. It explains the use cases and the returned chapter-group structure. It doesn't discuss sibling alternatives, but that isn't critical given the focused scope and available context.

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 fully documents the single 'num' parameter with type, range 1-22, and a description, giving 100% schema coverage. The description merely repeats 'Provide a chapter number (1-22)' without adding new semantic detail, so the baseline score of 3 is appropriate.

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

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

The description states a specific action — 'Get one CID-10 chapter and its constituent groups' — with a concrete example showing chapter IX expanded into ranges like I00-I02. It clearly distinguishes this from sibling tools such as cid10_chapters (which lists all chapters) and cid10_search/lookup by focusing on one chapter's hierarchical groups.

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

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

The 'Use this tool to' bullet list gives explicit contexts: drilling into groups, building hierarchical browsers, and finding which group contains a code range. It provides clear when-to-use guidance but does not explicitly mention when not to use it or contrast it with alternatives like cid10_search, so it stops short of a 5.

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

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

Annotations already cover read-only and idempotent behavior, and the description adds useful context beyond them: the exact fixed result count ('22 entries') and the caveat that CID-10 V2008 has not been updated since 2008. This is meaningful behavioral/version information not present in 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?

The description is compact, front-loaded with the main action, and organized as scannable bullet points. Each sentence adds information: scope, use cases, and a version caveat; there is no filler.

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

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

For a no-parameter tool with an output schema and strong read-only/idempotent annotations, the description fully covers what the tool returns, the main use cases, and an important version limitation. Nothing needed to select or 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?

The tool has zero parameters and 100% schema coverage, so the description cannot add parameter-level meaning. The baseline of 4 applies because no parameter documentation burden exists.

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 opens with a specific verb and resource: 'List the 22 chapters of CID-10 with their code ranges and Portuguese titles.' This clearly distinguishes it from siblings like cid10_lookup, cid10_search, and singular cid10_chapter.

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 define when to use it: seeing top-level structure, mapping a code range to a chapter, and building a table of contents. It does not explicitly name alternatives or exclusions, so it stops short of a 5.

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

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

Annotations already declare readOnly and non-destructive behavior, so the bar is lower. The description adds valuable behavioral details beyond annotations: dotted/undotted input normalization, canonical display output, and gender/cause-of-death restriction flags. There is 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?

The description is compact, front-loaded with the core purpose, and uses bullets efficiently. Every sentence contributes functional guidance without redundancy or filler.

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

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

For a single-parameter lookup tool with a rich input schema and an output schema, the description provides all necessary context: input forms, return value, example, and additional flags. Nothing critical is missing for an agent to invoke it correctly.

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

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

Schema coverage is 100% and the schema description already explains accepted forms with examples. The description reinforces dotted/undotted acceptance but does not materially add 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?

The description states a specific action ('Look up a specific CID-10 code'), the exact resource (CID-10), and the output (Portuguese name), with a concrete example. It clearly differentiates this lookup tool from broad search or chapter-level tools in the sibling 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?

The 'Use this tool to' bullets give clear context: resolving a code, confirming existence, and retrieving restriction flags. It does not explicitly name alternatives or exclusions (e.g., 'use cid10_search for free-text queries'), but the intended use is well 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, the description discloses diacritic-insensitive matching, the V2008 Brazilian revision, the official CBCD/USP translation basis, and category/subcategory result scope. These are non-obvious behavioral traits that affect query formulation and result interpretation.

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

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

The description is compact, front-loaded with the core action, and organized into scannable bullets. Every sentence adds either a use case, a behavioral constraint, or an alternative-tool pointer, with no filler.

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

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

For a search tool with an output schema and clear annotations, the description covers purpose, language, version, diacritics, result granularity, and the key alternative tool. Nothing needed for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by giving example Portuguese queries ('infarto', 'diabetes', 'tuberculose'), clarifying the query language, and explaining the categories/subcategories distinction that maps to the level parameter. It does not add much to max_results, but the schema already fully documents that.

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 opens with a specific verb and resource: 'Search the Brazilian CID-10 ... by Portuguese text,' and immediately distinguishes itself from the international ICD-11 tool by naming icd11_search. It also states the granularity (3-char categories and 4-char subcategories), making the tool's scope unambiguous.

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

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

A dedicated 'Use this tool to' list defines concrete clinical, billing, and translation scenarios, and the final sentence explicitly routes international ICD-11 lookups to icd11_search. This gives an agent clear decision criteria for selecting this tool over the most likely sibling alternative.

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 mark the tool read-only, idempotent, non-destructive, and open-world, and the description reinforces and extends this. It discloses server-computed match_score and rank, the grouping heuristic with the caveat that absence of a group is not evidence of non-equivalence, and the no-stable-cursor limitation that makes limit a cap rather than a page.

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 information-dense but well-structured with a clear opening, bulleted use cases, and focused paragraphs. Every sentence adds value, including the pt-BR routing guidance and the semantics of match_score/groups. Nothing feels redundant or filler.

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

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

Given the tool's complexity and the rich output schema, the description is complete: it covers supported terminologies, parameter interactions, result scoring, grouping semantics, open-world caveats, and language limitations. It also routes the agent to sibling tools when appropriate, leaving no critical ambiguity for selecting or invoking the 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?

Although schema coverage is 100%, the description adds meaning beyond the schema: it explains that source_terminology is subtracted from target_terminologies, that limit is a per-terminology cap due to lack of stable pagination, and that omitting target_terminologies searches all five. These are non-obvious operational details that help an agent use parameters correctly.

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 opens with a specific verb and resource: 'Find equivalents across terminologies', and the 'Use this tool to' list clarifies the exact intent. It clearly differentiates this tool from per-terminology search siblings by emphasizing unified multi-terminology search and mapping support.

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 gives concrete usage conditions: when to use target_terminologies versus source_terminology, how they combine, and when to prefer dedicated pt-BR tools. It explicitly names the alternatives (icd11_search, mesh_search, cid10_search) and the language conditions that should trigger their use.

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 state readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds the top-level categories scope and the 28-chapter count but no additional behavioral details such as ordering, pagination, or response variations; this is adequate but not rich.

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

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

The description is short, front-loaded, and scannable with a lead sentence and three bullet uses. It is mostly efficient, though the final clause about covering all areas of medicine is broad and adds marginal 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?

For a single-optional-parameter, read-only listing tool with a rich output schema and full annotations, the description covers what the tool does, why an agent would use it, and what scope to expect. Nothing critical 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%: the language parameter is fully documented in the input schema, including default, enum, and official-translation behavior. The tool description adds nothing about parameters, so the baseline of 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 opens with a clear verb and resource, 'List all ICD-11 chapters (top-level categories)', and the bullet list explains what this is for. It does not explicitly contrast itself with sibling tools such as icd11_hierarchy or icd11_search, so it falls short of full differentiation.

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

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

The bullet list provides concrete use cases: get an overview, find which chapter covers a body system or condition type, and navigate to specific disease categories. It omits explicit exclusions or when-not-to-use guidance compared with sibling tools, giving clear context but no 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 the tool read-only, idempotent, and non-destructive, so the description does not need to repeat that. It adds useful behavioral detail by explaining that 'parents' returns ancestors and 'children' returns subcategories, which goes slightly beyond the schema. However, it does not describe output behavior beyond direction semantics, and the output schema covers return structure.

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 compact, front-loaded with the core purpose, and uses a clear bulleted list for use cases. The final sentence adds essential direction clarification without redundancy.

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

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

For a simple two-parameter tool with full schema coverage, an output schema, and clear annotations, the description covers everything needed to invoke it correctly. It explains the two directions and the kinds of results to expect, making it complete in context.

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

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

Schema description coverage is 100%, so the schema already documents both parameters well. The description restates the direction semantics already present in the schema but adds no new parameter-level detail or format guidance.

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 ('Navigate') with a clear resource (ICD-11 hierarchy) and states exactly what it returns: parent and child entities. It distinguishes itself from sibling lookup/search tools by focusing on hierarchical navigation rather than general lookup or 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 description clearly states when to use the tool: to find broader categories, subtypes, or understand classification structure. It does not explicitly name alternative tools or state when not to use it, but the intended use cases are unambiguous.

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, openWorldHint, idempotentHint, and non-destructive behavior. The description adds useful context beyond annotations: it clarifies that language parameter returns official WHO translations only when they exist and that content is never machine-translated. This helps set expectations about localization behavior.

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

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

The description is concise, front-loaded with the core purpose, and structured with useful bullets that are easy to scan. Every sentence adds value, and there is no redundant restatement of the tool name or generic filler.

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

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

For a read-only lookup tool with an output schema and 100% schema coverage, the description is complete. It covers input alternatives, typical use cases, and language behavior. Nothing essential is missing for an agent to select and invoke this tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all parameter semantics well. The description adds the important relationship that code and URI are alternatives ('Provide either...'), which is not explicit in the schema. However, the language translation nuance is already fully captured in the schema, so the marginal addition is modest.

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 ICD-11 entity by code or URI.' This clearly differentiates the tool from siblings like icd11_search (search by text) and icd11_hierarchy (navigation) by emphasizing lookup of a known entity identifier. The bullet list further specifies what kind of information is returned.

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: fetching definitions, coding notes, exclusions, official titles, and synonyms. It also gives concrete guidance on inputs ('Provide either an ICD-11 code or a full foundation URI') and language selection. It does not explicitly mention when NOT to use this tool versus alternatives like icd11_search, so it loses a point.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds useful behavioral context beyond annotations by explaining that the tool surfaces available axes and distinguishes required vs optional postcoordination. No contradiction with annotations exists.

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

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

The description is concise and front-loaded with the core action, followed by a scannable bullet list of use cases. The final conceptual sentence about postcoordination adds helpful domain context without much redundancy.

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

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

Given the single required parameter, full schema coverage, existing output schema, and strong annotations, the description is sufficiently complete for an agent to understand when and why to invoke this tool. Minor gaps like code format examples or explicit exclusions are not critical here.

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

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

The schema already fully documents the single 'code' parameter with 100% coverage. The description only repeats that it applies to an ICD-11 code, adding no format, validation, or syntax details beyond what the schema provides, so the baseline score of 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 opens with a specific verb and resource: 'Get postcoordination information for an ICD-11 code.' This clearly identifies what the tool does and differentiates it from siblings like icd11_lookup, icd11_hierarchy, and icd11_search, none of which focus on postcoordination axes.

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 concrete use cases: finding axes, checking required vs optional postcoordination, and understanding extension possibilities. It gives clear context for when to call the tool, though it does not explicitly state when not to use it or name 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 indicate read-only, idempotent, non-destructive behavior, so the description does not need to restate safety. It adds meaningful behavioral context by emphasizing that language selection uses WHO's official translations and is never machine-translated, and it discloses that results include codes, titles, and relevance scores.

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

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

The description is front-loaded with a clear first sentence, followed by a concise bullet list of use cases and a focused note on language behavior. It is appropriately sized with minimal redundancy, though the second bullet repeats some of the first sentence's content.

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

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

Given the output schema and 100% schema coverage, the description provides enough context for invoking the tool correctly: it explains search intent, language behavior, and result contents. It does not fully address how this tool relates to similar ICD-11 siblings like icd11_hierarchy or icd11_lookup, which is a minor completeness gap for selection.

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?

Input schema coverage is 100%, so parameters are already documented in detail. The description adds a helpful example for the language parameter ('pt' returns official Portuguese labels) and reinforces the official-translation guarantee, but it does not meaningfully extend the schema's existing parameter explanations.

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 for medical conditions, diseases, and health problems in ICD-11. It also lists concrete use cases such as finding ICD-11 codes and searching by keyword. It does not explicitly contrast itself with sibling tools like icd11_lookup, so it is clear but not fully differentiated.

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 provides clear context for when to use the tool: 'Use this tool to find ICD-11 codes for diagnoses, search for diseases by name or keyword, and look up conditions in multiple languages.' It gives practical guidance on language selection with an example, but it does not mention exclusions or when to prefer an alternative such as icd11_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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds a meaningful scope constraint about LOINC codes with defined answer sets, but does not disclose behavior for non-applicable codes or the open-world nature of results hinted by openWorldHint. 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?

The description is front-loaded with the core purpose and then organized into helpful bullets. It is concise, though the three bullets overlap somewhat, and 'Look up standardized answer lists' adds little beyond the first two use cases.

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 lookup tool with rich annotations and an output schema, the description is sufficient. It states what the tool returns, when it applies, and typical use cases. No critical information needed to call it correctly is missing.

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

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

Schema description coverage is 100%, and the parameter already includes a pattern and example ('2339-0'). The description adds no extra parameter-level meaning beyond what the schema provides, so the baseline of 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 action and resource: 'Get the list of valid answers for a LOINC questionnaire item.' It clearly differentiates from sibling LOINC tools like loinc_details, loinc_search, and loinc_panels by focusing specifically on answer sets for question items.

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 clear use cases via bullets: finding valid response options, answer codes for data entry validation, and standardized answer lists. It also adds an important scope constraint: 'Only applicable to LOINC codes that represent questions with defined answer sets.' It stops short of explicitly naming alternatives or stating when not to use it, so it misses the top score.

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

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

Annotations already cover read-only, open-world, idempotent, and non-destructive behavior, so the description need not repeat those. It adds modest behavioral context by indicating what data can be retrieved, but it does not address edge cases like invalid LOINC format or nonexistent codes. This is acceptable given the strong annotation 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?

The description is tight, uses a short lead sentence and three scannable bullets, and includes a concrete example. Every sentence earns its place without redundancy.

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

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

With one well-documented parameter, strong annotations, and an output schema present, the description provides enough context for correct invocation. The bullets define the scope of returned details, and no additional operational guidance seems necessary.

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 schema already fully documents the single parameter with a pattern, example, and description. The description repeats the format and example, adding little beyond the schema. With 100% schema coverage, 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 the tool's purpose: getting detailed information about a specific LOINC code, with a concise list of the kinds of details returned (name, component, property, timing, system, scale, method). It does not explicitly differentiate from siblings like loinc_search or loinc_panels, but the 'specific LOINC code' framing and the field list make the scope clear enough.

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 concrete scenarios where this tool is appropriate, such as retrieving full LOINC metadata for a known code. It does not explicitly mention when not to use it or name alternatives, but the context is clear and actionable for an agent deciding to look up a 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds that the result is a list of LOINC codes, which is useful but does not disclose any additional behavioral traits beyond the annotations.

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

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

The description is concise and front-loaded with the core action, followed by compact usage bullets and a one-line result statement. It is slightly verbose in the bullets but each contributes useful context.

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 tool with an output schema and strong annotations, the description covers query intent and result shape sufficiently. A small omission is that it does not mention the open-world nature of panel membership, so an agent might assume the returned code list is exhaustive.

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 loinc_num is documented with a pattern and example in the schema. The description itself says nothing further about the parameter, so it adds no semantic value beyond the schema, keeping this at baseline.

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

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

The description opens with a specific verb and resource ('Get the structure of a LOINC panel or form') and clarifies the output: the list of LOINC codes that make up the panel. The examples (CBC, metabolic panel, assessment forms) distinguish it from search/detail sibling 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' bullets give clear contexts where the tool is appropriate, such as seeing all tests in a panel or getting assessment-form structure. It does not name sibling tools or explicitly state when not to use it, but the intended usage is evident.

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

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

With readOnlyHint, openWorldHint, and idempotentHint already declared, the description does not need to restate the safety profile. It adds useful context by stating the return content (codes, names, components, properties) but does not go into pagination or result-selection behavior beyond the schema's max_results.

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

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

The definition is tightly structured: a scoped one-sentence summary, three short intent bullets, and a one-sentence return description. There is no filler or repetition of schema details, and the key purpose appears immediately.

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 low-complexity search tool with a simple two-parameter schema and an output schema, the description covers what the agent needs to call it correctly. It could have mentioned loinc_details or loinc_panels as follow-ups for richer code information, but the absence is not a significant 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 coverage is 100%, so the schema already documents both query and max_results. The description adds only example query terms and clarifies that partial LOINC codes are valid search terms, a small increment over the schema rather than a substantive contribution.

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 identifies a specific verb ('Search'), a specific resource ('LOINC'), and the content domain (laboratory tests, clinical observations, measurements). The opening sentence plus the return-value sentence distinguish this from lookup/detail siblings like loinc_details and loinc_panels without needing to open the schema.

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

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

The 'Use this tool to' bullets explicitly list the intended cases: finding LOINC codes for lab tests, clinical measurements, and diagnostic observations. It does not name exclusions or mention alternative siblings such as loinc_details or loinc_panels, so the usage guidance is clear but not fully differentiated.

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, and non-destructive. The description adds meaningful behavior beyond that: the bundled WHO release version, the distinction between primary and alternative mappings, acceptance of dotted and undotted forms, and the deliberate 'no mapping' response instead of a fuzzy fallback. This gives the agent a clear model of the tool's behavior.

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

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

The description is detailed but every sentence earns its place: purpose, return content, use cases, coverage, accepted input format, and no-match behavior. It is front-loaded with the authoritative mapping statement and structured so an agent can quickly decide whether to invoke it.

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 required parameter, a rich input schema, and an output schema present, the description covers all practical concerns: what the mapping is based on, what is returned, which codes are in scope, how to format input, and what happens for unmapped codes. Nothing essential is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by giving concrete examples (E11, I21, A07.8), stating that both dotted and undotted forms are accepted, and noting that some codes have multiple alternatives. This is helpful but not exhaustive; the schema already carries the core parameter meaning.

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

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

States a specific verb ('map') and resource ('ICD-10 to ICD-11') using authoritative WHO transition tables, and details the output: primary 1:1 category plus alternative candidates with codes, titles, chapters, and URIs. This clearly distinguishes it from search or lookup siblings by emphasizing authoritative mapping rather than fuzzy text search.

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

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

Explicitly lists when to use: clinical coding, billing migration, retrospective analysis, and any workflow needing authoritative mapping rather than text-search candidates. It also explains coverage boundaries (excludes chapters/blocks) and the no-mapping behavior, so an agent knows what to expect and when this tool is not appropriate.

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, the description discloses the tool's core behavioral limitation: it does not perform the mapping, only returns guidance. It also explains the licensing constraints behind direct LOINC→SNOMED mappings, setting accurate expectations for what the tool can and cannot deliver.

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 remaining paragraphs are organized logically (limitation, alternatives, input). The licensing paragraph is somewhat lengthy and overlaps with 'does not perform the mapping,' but each section earns its place for a domain-specific tool.

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

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

For a single-parameter, read-only tool with an output schema, the description covers everything an agent needs: purpose, limitations, alternatives, input format, and expected type of result. No critical operational details are 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 schema fully documents the loinc_code parameter with pattern and example, so baseline is 3. The description adds examples with semantic labels ('2339-0 (Glucose)'), but this is a minor supplement to an already well-documented parameter.

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

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

The description opens with a specific verb and resource: 'looks up a LOINC code in NLM Clinical Tables and returns guidance...' It then explicitly declares 'It does not perform the mapping,' which distinguishes this tool from sibling mapping tools like map_icd10_to_icd11 and 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 provides explicit when-to-use and when-not-to-use guidance, naming alternatives: 'For programmatic LOINC → SNOMED mapping, use UMLS or the LOINC Expression Association files. For interactive lookup, use the SNOMED CT browser... or RELMA.' This leaves no ambiguity about when to choose this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the description does not need to restate those. It adds useful behavioral context by noting that language enables NLM's official translations only where they exist, and it lists the kind of data returned. This goes beyond the annotations without contradicting them.

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 compact and front-loaded: the main action comes first, followed by a tight bullet list and a practical example. Every sentence earns its place, and there is no filler or redundant restating of the tool title.

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

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

For a simple read-only lookup with two parameters, an output schema, and strong annotations, the description covers everything an agent needs: the lookup key, the optional language behavior, and the kind of information returned. Nothing critical is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the mesh_id example and language usage, but it does not add substantial meaning beyond what the schema already documents. It is adequate but not additive.

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 opens with a specific verb and resource: 'Get detailed information about a MeSH descriptor by ID.' It then lists concrete outputs (scope note, tree numbers, concepts, synonyms), and the 'by ID' framing clearly separates it from search-style siblings like mesh_search and mesh_tree.

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

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

The 'Use this tool to:' section gives explicit, actionable use cases for when the tool is appropriate. It does not mention alternative tools or when not to use it, but the intended usage context is clear enough for an agent to select it correctly.

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, openWorldHint, idempotentHint, and non-destructive behavior, so the description is not burdened with safety disclosure. It adds the useful context that qualifiers refine descriptors with an example, but does not describe edge cases such as descriptors with no qualifiers or retrieval limits. This is acceptable for a simple read-only lookup.

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

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

The description is well-organized with a front-loaded main sentence followed by concise bullets. It is appropriately sized and avoids redundancy for the most part, though 'Understand aspects that can be specified' is somewhat vague and overlaps with the earlier bullet about finding qualifiers.

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 tool with an output schema and strong annotations, the description fully covers purpose, usage, and a concrete example. No critical information is missing for an agent to invoke this tool correctly.

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

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

Schema description coverage is 100% and the single parameter mesh_id is already documented with a pattern and examples. The description reinforces the semantic relationship between descriptors and qualifiers via the 'Diabetes Mellitus/drug therapy' example, but does not add substantial parameter-level detail beyond the schema.

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

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

The description opens with a specific verb and resource: 'Get allowed qualifiers (subheadings) for a MeSH descriptor.' It clearly defines the tool's focus on qualifiers rather than descriptors themselves, distinguishing it from siblings like mesh_descriptor, mesh_search, and mesh_tree.

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

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

The 'Use this tool to' bullets provide clear context: finding combinable qualifiers, building precise search queries, and understanding specifiable aspects. It does not explicitly name alternatives or state when not to use it, but the intended use cases are concrete enough for an agent to pick this tool appropriately.

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 carry the safety profile (readOnlyHint, idempotentHint, non-destructive), so the bar is lower. The description adds genuine value beyond annotations: the guarantee that 'content is never machine-translated' and the return format ('matching descriptors with MeSH IDs and labels'). It does not cover pagination or error behavior, but for a search tool with strong annotation coverage, this is solid.

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: core purpose first, then use cases, then the critical language caveat, then return format. It is compact with no wasted sentences. The bullet list slightly rephrases the opening line, but each bullet adds a distinct usage angle, so it earns its place.

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

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

Given the presence of an output schema, annotations covering safety, and 100% schema param coverage, the description is complete. It states what is searched, why an agent would use it, the one non-obvious behavior (no machine translation), and what results contain. 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 description coverage is 100%, so the baseline is 3. The description reinforces the language parameter's special behavior (official translations only, e.g., Portuguese), but that nuance is already documented in the schema's language property. The description adds no new parameter semantics beyond what the schema provides, so a 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 opening sentence states a specific verb and resource: 'Search for MeSH (Medical Subject Headings) descriptors.' The bulleted use cases (indexing literature, PubMed searches, controlled vocabulary) further anchor what the tool does and differentiate it from domain-specific siblings like cid10_search or atc_lookup without needing to open their schemas.

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

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

The description gives clear context for when to use the tool via three concrete use cases, but it never names alternatives or states when NOT to use it (e.g., no routing to mesh_descriptor for looking up a specific known MeSH ID). This meets 'clear context, no exclusions,' which fits 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?

Annotations already declare the tool as read-only, idempotent, and non-destructive, so the description does not need to cover safety. It adds a useful explanatory detail about MeSH tree numbers showing hierarchical paths with an example, but it does not disclose much additional behavioral context beyond what the title and annotations imply.

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

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

The description is front-loaded with a clear purpose statement and uses compact bullet points. Some redundancy exists between the opening sentence and the first bullet, but overall it is appropriately sized and easy to scan.

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

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

The tool is simple, with one required parameter, a fully documented schema, annotations covering side effects, and an output schema available. The description provides enough information for correct invocation, including a concrete tree-number example. It lacks explicit sibling differentiation, but that is not critical for this tool's completeness.

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 mesh_id fully documented by its pattern and examples. The description mentions MeSH descriptors and tree numbers, but it does not add new parameter-level semantics beyond what the schema already provides, 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 opens with a specific verb and resource: 'Get the tree hierarchy location(s) for a MeSH descriptor.' This clearly identifies the tool's function and differentiates it from related MeSH tools like mesh_descriptor or mesh_search, though it does not explicitly name sibling alternatives.

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

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

The description provides explicit use cases via bullet points: seeing where a term fits in the MeSH hierarchy, understanding broader/narrower relationships, and finding related terms in the same branch. It gives clear context for when to use the tool, though it does not state when not to use it or directly point to an alternative.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral detail by stating the output includes class IDs, names, and classification sources, which goes beyond the annotation metadata without contradicting 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?

The description is compact and well-structured: a one-sentence summary, a short bulleted list of use cases, and a one-line output summary. No redundant or filler content is present, and the key purpose is front-loaded.

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

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

The tool has a single documented parameter, rich annotations covering safety and idempotency, and an output schema, so the description's brief mention of return contents is sufficient. There are no hidden prerequisites, complex flags, or pagination concerns that would demand additional explanation.

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 only one parameter, rxcui, and the schema itself already describes it as the 'RxCUI of the drug' with a validation pattern, so schema coverage is 100%. The description does not add extra parameter-level meaning beyond the schema, which makes the baseline 3 appropriate.

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

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

The description opens with a specific verb and resource: 'Get therapeutic and pharmacologic classes for a drug.' It gives concrete examples (Beta-blockers, NSAIDs) and clarifies the tool returns class IDs, names, and sources. This clearly distinguishes it from sibling RxNorm tools like rxnorm_concept or rxnorm_ingredients.

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

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

The 'Use this tool to' section lists concrete use cases: finding drug classes, therapeutic categories, and mechanism-of-action classifications. It does not explicitly name sibling alternatives or state when not to use it, so it misses the full when/when-not guidance, but the provided context is clear and actionable.

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 readOnlyHint, idempotentHint, openWorldHint, and destructiveHint, so the bar is lower. The description adds useful context about the kind of data returned (synonyms, status, related concepts) but does not disclose additional behavioral traits such as error handling or response shape, which is acceptable given the output schema and 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?

The description is tight and front-loaded: the main action is in the first sentence, followed by compact bulleted uses and an example. Every sentence earns its place with no redundant content.

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

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

Given the existing output schema, annotations, and 100% schema parameter coverage, the description covers purpose, use cases, and an example format. A small gap is the lack of explicit routing guidance relative to sibling search tools, but overall the context is sufficient for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds an example RxCUI ('161') but does not meaningfully enrich the parameter semantics beyond what the schema already documents for rxcui and include_related.

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 opens with a specific verb and resource: 'Get detailed information about a specific RxNorm concept by RxCUI.' The bulleted list further clarifies the exact value (name, synonyms, status, related concepts). This clearly distinguishes it from sibling tools like rxnorm_search (search by name) and rxnorm_ingredients (list ingredients).

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

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

The description provides explicit 'Use this tool to' bullets, giving an agent clear scenarios for invocation. However, it does not explicitly name alternatives or state when not to use this tool, which would be helpful given the many overlapping RxNorm sibling tools.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds useful behavioral context beyond that: results are limited to active ingredients, it can reveal single vs. multi-ingredient status, and it returns ingredient RxCUIs and names.

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, front-loaded with the core action, and uses a tight bullet list plus a return-summary line. Each sentence adds functional or scoping value rather than repeating schema content.

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

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

For a one-parameter tool with a full schema and output schema, the description covers input, scope, use cases, and return contents. It does not address invalid/missing RxCUI behavior, but that is a minor gap given the output schema and simple validated input.

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 schema already covers the only parameter fully with a description, pattern, and required status. The description only restates 'by RxCUI' and does not add extra parameter semantics, so this is at the baseline.

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

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

The description opens with a specific verb and resource: 'Get active ingredients for a drug by RxCUI.' The follow-up bullets clarify intended use cases, and the tool is easily distinguished from sibling RxNorm tools like rxnorm_search or rxnorm_concept because it is explicitly scoped to ingredient lookup.

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

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

The 'Use this tool to' section gives explicit contexts: find active ingredients, check single vs. multiple ingredients, identify generic components. It does not name alternatives or say when not to use it, so it falls one step short of full routing guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds value beyond these by stating that the tool supports either an RxCUI or an NDC as input, implying a mutually exclusive lookup behavior. This is useful operational detail not present in the annotations.

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

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

The description is concise, front-loaded with the core purpose, and uses bullets to enumerate the tool's functions. The final sentence provides the essential input convention. There is 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?

For a simple two-parameter lookup tool with full schema coverage, relevant annotations, and an output schema present, the description provides all necessary guidance: what the tool maps, the supported directions, and the expected input. Nothing critical is missing.

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

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

Schema description coverage is 100%, so both parameters are already described in the input schema. The description reinforces the 'either/or' semantics but does not add substantial new meaning beyond the schema entries, so the baseline score 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 bidirectional mapping action between RxNorm concepts and NDC codes, then enumerates the two main use cases: getting NDCs for an RxCUI and finding an RxCUI for an NDC. This clearly differentiates the tool from sibling RxNorm tools such as rxnorm_search or rxnorm_concept, which handle different lookup concerns.

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 explicitly lists the scenarios where the tool applies, and the final sentence tells the caller which input to provide. It does not mention alternatives or exclusion conditions, but the context is clear enough for an agent to select this tool for NDC/RxCUI cross-referencing.

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, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral context about return contents (RxCUI, names, term types) and the normalized-name scope, but does not go deeper into search matching behavior, limits, or ambiguity handling.

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

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

The description is well-structured with a short opening line and bulleted use cases, making it scannable. Every sentence adds some value, though the bullet 'Look up medications for prescribing' is somewhat generic and overlaps with the 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?

For a simple two-parameter search tool with rich annotations and an output schema, the description covers purpose, use cases, and result contents. It is complete enough to call correctly, though it would benefit from a brief pointer to sibling tools for follow-up concept detail or NDC lookups.

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 and max_results are already fully documented in the input schema. The description adds limited extra meaning for parameters, mostly reinforcing that query can be a brand or generic name. Baseline 3 is appropriate because the schema carries the weight.

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

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

The description clearly states a specific verb and resource: 'Search for drugs in RxNorm' and explains the return payload (RxCUI identifiers, names, term types). It is not a tautology and is easy to understand, but it does not explicitly distinguish this tool from sibling tools like rxnorm_concept or rxnorm_ingredients.

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

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

The 'Use this tool to' section gives clear usage context: find drugs by brand/generic name, look up medications for prescribing, and search formulations. There are no explicit when-not-to-use instructions or named alternatives, but the intended scenarios are concrete enough for an agent to select this tool appropriately.

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 declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: the server often does not ship historical snapshots, bundled_versions is the source of what is actually available, and this tool intentionally returns guidance rather than computed diffs. That goes beyond what annotations alone convey.

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

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

The description is longer than average but each section earns its place: the general guidance rule, the ICD-10/11 special case, the parameter behavior, and the closing caveat all contribute distinct information. It is well structured and front-loaded with the core purpose; minor redundancy exists between the early 'guidance only' statement and the closing changelog-authoritative caution.

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

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

For a metadata/guidance tool with an output schema present, the description is complete: it covers the general behavior, the notable exception, exactly how to invoke the special case, and what information will be returned. No critical operational detail is missing.

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

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

Schema coverage is 100%, so the schema already documents each parameter at a basic level. The description adds real value above that by explaining the consequence of omitting from_version and to_version and by specifying the special icd10/no-to_version invocation for the cross-revision summary. This is more than the schema alone provides.

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

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

The description opens with a precise verb and resource: 'Report what diff data is available between two versions of a terminology.' It then distinguishes itself from actual diff or mapping tools by calling itself 'a metadata + guidance layer, not a diff engine,' and it names the special ICD-10 vs ICD-11 behavior, making it easy to separate from siblings like map_icd10_to_icd11.

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

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

Explicit guidance is given for when this tool is appropriate: most terminologies get guidance-only changelog info, while ICD-10 vs ICD-11 gets a real cross-revision summary. The description also tells the agent exactly how to trigger that case ('Use terminology: "icd10" with no to_version') and warns that for frequently changing terminologies the publisher changelog is authoritative.

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 operation read-only and non-destructive. The description adds valuable nuance beyond annotations by noting that the ICD-10 → ICD-11 version reads live from the bundled dataset while other metadata is maintained with the release. It also clarifies that some bundled data is frozen at specific versions.

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 with a clear opening sentence, bulleted use cases, and a final note on filter behavior and data freshness. It is slightly longer than strictly necessary but every section adds useful context.

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

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

For a simple read-only tool with one optional parameter, rich annotations, and an output schema, the description is complete. It covers returned fields, filtering, use cases, data versions, and the distinction between live and static metadata.

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

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

Schema description coverage is 100%, and the description repeats the same key behavior: pass `terminology` to filter, omit to get all 8. No new parameter-level meaning is added, but the schema already fully documents the single optional parameter and its enum values.

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 the tool's purpose: listing version metadata (version, release date, publisher, source URL, update cadence) for every terminology the server queries. It is specific enough to be distinguished from sibling lookup/search tools, though it does not explicitly name a sibling alternative.

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 provides concrete use cases for pipeline maintainers and explains when to pass the optional filter versus returning all 8 entries. It does not explicitly state when to prefer an alternative tool, but the usage context is clear and actionable.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description goes well beyond annotations by explaining return-field semantics, the valid:false + error:null vs. error:set distinction, terminology auto-detection being unsupported, parallel validation, hard cap of 50, and the SNOMED feature-flag dependency. This is rich, honest behavioral disclosure.

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

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

Though fairly long, the description is information-dense and every section earns its place: purpose, return semantics, required-terminology rationale, accepted values, and performance characteristics. The most important purpose statement is front-loaded, and the detailed return-field explanation is well structured.

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

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

Even though an output schema exists, the description supplies the interpretive context an agent needs: what valid/active/title/replaced_by/source/error each mean, the difference between 'not found' and 'couldn't validate', and practical constraints like the 50-code cap and worst-case latency. Nothing critical is missing for correct invocation.

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

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

The input schema already documents the codes array and its nested objects at 100% coverage, so the baseline is 3. The description adds meaningful semantic context beyond the schema by explaining why terminology is required (ambiguous category codes), listing accepted values, and clarifying the per-code hard cap and parallel execution 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?

The description opens with a specific verb and resource: 'Validate a mixed batch of medical codes against their source terminologies.' It clearly distinguishes itself from sibling lookup/search/mapping tools by emphasizing batch validation, legacy-database analysis, replacement surfacing, and activity grading.

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 targets retrospective analysis of legacy databases and mixed-batch scenarios, which signals when this tool is the right choice. It does not explicitly name sibling tools to avoid, but the batch/multi-terminology framing is clear enough to select this over single-terminology lookup tools.

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