Search and retrieve international statistical classifications and survey codelists, with deterministic matching, definitions, codes and provenance for comparable data collection and analysis.
Scored across 10 tools
Most tools have clearly distinct purposes, but list_classifications and recommend_classifications both help select a classification, and browse_hierarchy and list_codelists both navigate related structures. The descriptions clarify the differences, so confusion is limited.
All tools follow a consistent verb_noun snake_case pattern (e.g., list_classifications, get_code_definition, validate_codes). There are no deviations in convention or style.
With 10 tools, the set is well-scoped for the domain of international classifications, covering discovery, exploration, retrieval, mapping, validation, and export without redundancy.
The surface covers the core lifecycle—listing, recommending, browsing, searching, retrieving definitions, mapping, validating, and exporting. A direct bulk code listing tool is absent, but browse_hierarchy and export_choice_list provide workarounds.
Browse top-level nodes or immediate children. Curated families return node_kind=codelist containers at root; pass that code as parent_code to browse its options.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| parent_code | No | ||
| classification_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds non-obvious domain behavior: curated families expose node_kind=codelist containers at root, and those codes act as parent_code filters. It does not, however, mention pagination or that 'limit' caps returned nodes.
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?
Two tight sentences with no filler, and the core behavior (top-level vs. children) is front-loaded. The codelist quirk in the second sentence earns its place, though it could be split for readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, return-value explanation is unnecessary, and annotations cover safety. The remaining gap is pagination/limit semantics and the meaning of classification_id, which are omitted across both schema and description for a 3-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the full burden. It explains parent_code well (null = root, a codelist code = its options) but leaves classification_id and especially limit (default 200, max 500) entirely unexplained.
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 pairs a specific verb ('Browse') with a specific resource ('top-level nodes or immediate children'), making it clearly a hierarchy-navigation tool rather than a search or lookup tool. It is distinguishable from search_codes and get_code_definition by scope, though it never explicitly names an alternative to route against.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied through the parent_code workflow ('pass that code as parent_code to browse its options'), which tells an agent how to descend the tree. However, there is no explicit when-to-use vs. when-to-use-an-alternative guidance relative to search_codes, get_classification, or list_codelists.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return a structured choice list at a selected hierarchy level. MICS exports require one codelist_id and never merge unrelated answer lists.
| Name | Required | Description | Default |
|---|---|---|---|
| level | No | ||
| limit | No | ||
| format | No | xlsform | |
| codelist_id | No | ||
| classification_id | Yes |
| Name | Required | Description |
|---|---|---|
| rows | Yes | |
| level | Yes | |
| format | Yes | |
| warning | No | |
| codelist_id | No | |
| option_count | Yes | |
| codelist_title | No | |
| classification_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and closed-world behavior, so the safety profile is covered. The description adds one genuinely useful behavioral rule ('never merge unrelated answer lists'), but says nothing about output format, pagination, or how the selected level affects the result. Modest value on top of 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?
Two tight sentences with the core action front-loaded and no filler. It is efficient, though the second sentence is a domain-specific aside rather than a usage rule.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists so return values need not be described. However, for a 5-parameter tool with zero schema descriptions and no sibling differentiation, the description leaves real gaps in parameter meaning and when-to-use.
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 0%, so the description must carry the load for 5 parameters, yet it only vaguely touches on codelist_id and level. The meaning of classification_id, limit, and the format enum ('xlsform' vs 'simple') is left entirely unexplained.
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 ('Return a structured choice list') and adds scope via 'at a selected hierarchy level,' which separates it from list_codelists or search_codes. It is clear but does not explicitly name any sibling it should be chosen over.
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 only guidance is an implicit constraint ('MICS exports require one codelist_id'), which hints at a required input but never states when to use this over list_codelists, browse_hierarchy, or search_codes. No exclusions or alternatives are offered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get authoritative metadata and coverage for one classification_id returned by list_classifications.
| Name | Required | Description | Default |
|---|---|---|---|
| classification_id | Yes |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| name | Yes | |
| domain | Yes | |
| status | Yes | |
| acronym | Yes | |
| version | Yes | |
| coverage | Yes | |
| custodian | Yes | |
| code_count | No | |
| source_url | Yes | |
| description | Yes | |
| licence_note | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, closed-world, non-destructive behavior, so the safety profile is covered. The description adds 'authoritative', indicating this is the source-of-truth record rather than a cached/derived view, but says nothing about response size, pagination, or error behavior for an invalid id.
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?
One compact sentence that front-loads the verb and the payload ('authoritative metadata and coverage') before the id constraint. No filler, though 'authoritative' carries a little marketing weight rather than operational detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, return values need not be described, and annotations cover the safety profile; the description only needs to supply purpose and the id's provenance, which it does. The remaining gap is that 'coverage' is never defined, leaving the agent unsure what coverage means in the response.
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 0%, so the single classification_id parameter is undocumented structurally. The description compensates partially by stating the id must come from list_classifications (provenance and expected form), but gives no format, length, or invalid-id semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific verb ('Get') and resource ('metadata and coverage' for a classification), and ties the id back to the sibling list_classifications, so the agent can place it in the workflow. It stops short of distinguishing itself from get_code_definition, which also fetches single-item definitions.
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?
'returned by list_classifications' makes the prerequisite and sequencing explicit: call list_classifications first, then fetch detail for one id. No when-not guidance or alternative tools (e.g., get_code_definition) are named, keeping it below a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve one exact code or codelist container, including its node_kind, hierarchy position and explanatory notes.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | ||
| classification_id | Yes |
| Name | Required | Description |
|---|---|---|
| code | Yes | |
| label | Yes | |
| level | No | |
| score | No | |
| excludes | No | |
| includes | No | |
| language | No | |
| node_kind | No | |
| definition | No | |
| source_url | No | |
| codelist_id | No | |
| parent_code | No | |
| source_title | No | |
| classification_id | Yes | |
| classification_version | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, non-destructive, non-open-world behavior, so the safety profile is covered. The description adds that a single container is returned with node_kind, hierarchy position, and notes, but omits error/not-found behavior, authorization needs, and scope constraints.
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?
One front-loaded sentence states the action and resource without padding or repetition. Every element earns its place, and there is no redundancy with annotations.
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 tool with annotations and an output schema, the description adequately covers what is returned. However, it leaves parameter meaning and usage context under-specified, which matters because schema description coverage is 0%.
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 0% for two required parameters. The description only implies the "code" parameter and never explains what classification_id means or what format the code should take, so it does not compensate for the missing schema-level parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States the verb "Retrieve" and the resource "one exact code or codelist container," plus key returned attributes such as node_kind, hierarchy position, and explanatory notes. It distinguishes itself from search/list/browse siblings by emphasizing "one exact," though it does not name a specific 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?
There is no explicit when-to-use or when-not-to-use guidance; usage is only implied by "one exact," suggesting it is for known identifiers rather than searching. It does not point to search_codes, browse_hierarchy, or any alternative for discovery-oriented tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List classification families, versions, custodians, coverage and licensing notes. Start here when the correct standard is unknown.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | No | ||
| status | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is fully covered. The description adds the informational payload (families, versions, custodians, coverage, licensing notes), but says nothing about volume, pagination, or ordering.
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?
Two sentences, front-loaded with the resource and payload, followed by the usage cue. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists so return structure needn't be explained, and annotations cover safety. However, the two undocumented optional filter parameters leave a real gap for an agent trying to narrow the listing.
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?
Two parameters (`domain`, `status`) have 0% schema description coverage and no enums, and the description never mentions them. It does not compensate for the schema gap by explaining what these filters accept or how they constrain results.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (List) and resource (classification families), and enumerates the content returned: versions, custodians, coverage, licensing notes. It does not explicitly distinguish itself from `get_classification` or `recommend_classifications`, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Start here when the correct standard is unknown" clearly signals an entry-point/exploration use case and implies the alternative is to go straight to a known-standard tool. No when-not conditions or named siblings, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List independent option lists within a classification before searching or exporting one list.
| Name | Required | Description | Default |
|---|---|---|---|
| classification_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered. The description adds the domain clarification that codelists are 'independent option lists' scoped to a classification, but says nothing about pagination, ordering, or auth needs. With an output schema present, return format need not be described, so a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with the scope stated first and the sequencing hint last; no wasted words. It is arguably too terse for the gaps it leaves, but as a structure it is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read-only listing tool with a full annotation set and an output schema, the description covers the essential who/what/scope. The main remaining gap is that classification_id's accepted format is documented nowhere in either the schema or the description.
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 0% for the single parameter, so the description must carry the load. 'Within a classification' does establish that classification_id scopes the listing, but it gives no format, valid values, or source for the id. Partial compensation, not full.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('List') and resource ('independent option lists within a classification'), which an agent can separate from list_classifications (classifications) and export_choice_list (exporting). The term 'codelists' is rephrased as 'independent option lists', which adds domain meaning. It stops short of naming the sibling it is not, so differentiation is inferable rather than explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'before searching or exporting one list' gives an implied precondition for calling this tool, which is more than nothing. However, it never names the alternatives (search_codes, export_choice_list) or states when this tool should be skipped, so the routing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Apply official stored correspondences and expose splits, merges, changed meanings and unmapped codes. Never assume one-to-one equivalence.
| Name | Required | Description | Default |
|---|---|---|---|
| codes | Yes | ||
| source_classification_id | Yes | ||
| target_classification_id | Yes |
| Name | Required | Description |
|---|---|---|
| results | Yes | |
| sources | No | |
| warnings | No | |
| source_classification | Yes | |
| target_classification | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely new behavioral context: the result exposes splits, merges, changed meanings and unmapped codes, and that one-to-one equivalence must not be assumed. That cardinality warning is exactly the kind of nuance annotations cannot express.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences, front-loaded with the core action and closed with the single most important caveat. Every clause 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?
An output schema exists, so return values need not be explained, and the operation semantics are conveyed. However, with three fully required, undocumented parameters, an agent still lacks the guidance needed to populate the source/target classification IDs and the code list correctly, leaving a real gap for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the three parameters carry only bare titles ('Codes', 'Source Classification Id', 'Target Classification Id'), all required. The description never explains that codes is a list of source codes, nor that the two IDs select the source and target classification versions, so it fails to compensate for the schema gap.
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 (map) on a specific resource (codes between two classification versions) and clarifies the mechanism: 'Apply official stored correspondences.' It conveys the operation clearly, though it never names a sibling (e.g. validate_codes or search_codes) to sharpen 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 warning 'Never assume one-to-one equivalence' hints at expected behavior but gives no when-to-use, when-not-to-use, or alternative tool guidance. With nine sibling tools, the agent must infer from the name alone that this is the cross-version mapping tool rather than validate_codes or get_code_definition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return a deterministic ranked shortlist of all relevant classification concepts and codelists. Ranking supports user choice; it is not an automatic selection. Include answer options and context.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| question_text | Yes | ||
| answer_options | No | ||
| survey_context | No |
| Name | Required | Description |
|---|---|---|
| warnings | No | |
| next_action | Yes | |
| recommendations | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false. The description adds genuine value by asserting determinism and that results are a shortlist for user choice rather than an automatic pick, but says nothing about ordering criteria, result size behavior, or failure modes.
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?
Three short sentences with no filler, and the core behavior (ranked shortlist, advisory not automatic) is front-loaded. Slightly clipped phrasing ('Include answer options and context') costs it the top mark.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-value explanation is not required. Still, with four parameters at 0% schema coverage, the description documents only two of them obliquely and never explains the required question_text, leaving the agent to infer how to frame a call.
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 0%, so the description must compensate. It does partially: 'Include answer options and context' maps to the answer_options and survey_context parameters, giving an agent a hint about their role. However, the required question_text and the limit/cap behavior are not addressed.
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 ('Return a deterministic ranked shortlist') and resource ('classification concepts and codelists'), which distinguishes it from list_classifications and search_codes by the notion of relevance ranking. It never names a sibling explicitly, so the differentiation is inferred rather than stated.
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?
'Ranking supports user choice; it is not an automatic selection' clarifies that output is advisory, which is useful guidance. But it gives no explicit when-to-use condition versus alternatives like search_codes or browse_hierarchy, leaving the routing decision to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full-text search labels and notes. Results restrict to one option list only when codelist_id is explicitly supplied.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| codelist_id | No | ||
| classification_ids | No |
| Name | Required | Description |
|---|---|---|
| query | Yes | |
| total | Yes | |
| results | Yes | |
| warnings | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety and repeatability are covered. The description adds the useful scoping behavior that omitting codelist_id broadens results across option lists, but says nothing about result ranking, truncation, or interaction with classification_ids.
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?
Two short sentences, front-loaded with the core action and immediately followed by the key scoping caveat. No filler or 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?
An output schema exists so return values needn't be described, but with four parameters at 0% schema coverage the definition is incomplete: limit and classification_ids are undocumented anywhere, and the interplay between codelist_id and classification_ids is ambiguous. An agent could invoke it, but not confidently tune it.
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 0%, so the description carries the full burden, yet it only clarifies codelist_id's narrowing effect. The required 'query' string, 'limit' (1-100, default 20), and especially 'classification_ids' — including whether it can combine with codelist_id — are left completely unexplained.
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 target (full-text search over labels and notes), which is clear enough to distinguish it from map_codes or validate_codes. It doesn't explicitly name a sibling or contrast its scope against the other search/list tools, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus list_classifications, browse_hierarchy, or get_code_definition. The only conditional statement ('results restrict to one option list only when codelist_id is explicitly supplied') describes a parameter effect, not a selection criterion for the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate exact codes against one named classification version.
| Name | Required | Description | Default |
|---|---|---|---|
| codes | Yes | ||
| classification_id | Yes |
| Name | Required | Description |
|---|---|---|
| results | Yes | |
| valid_count | Yes | |
| invalid_count | Yes | |
| classification_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and closed-world behavior, so the safety profile is covered. The description adds that validation is scoped to a single named classification version and operates on a batch of codes, but it discloses nothing about the return semantics or what happens to invalid codes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with zero filler, front-loaded with the verb and resource. Every phrase (exact, one named, version) adds scoping 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?
Because an output schema exists, the description need not explain return values, and it correctly covers the batch-validate-single-version model. However, with 0% parameter description coverage and no usage guidance among nine siblings, it is only minimally complete for an agent choosing between this and search_codes or recommend_classifications.
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 0%, so the description carries the burden for both parameters. It clarifies that 'codes' are exact strings and 'classification_id' refers to one named version, but it gives no format details, no source for the identifier, and no indication of how validation results map back to individual codes.
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 (validate) and resource (codes) with a scoping qualifier ('exact', 'one named classification version'). The word 'exact' implicitly distinguishes it from fuzzy-search siblings like search_codes and recommend_classifications, though no sibling is named explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use or when-not guidance. The phrase 'exact codes' weakly implies this is for codes you already hold rather than discovery, but no alternative tool is named and no prerequisites or context are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
browse_hierarchyexport_choice_listget_classificationget_code_definitionlist_classificationslist_codelistsmap_codesrecommend_classificationssearch_codesvalidate_codes
Add one secure layer between your agents and this server.