un-comtrade-mcp-server

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds real behavioral context beyond them: publication-lag characteristics and pagination semantics ('Continue with nextOffset using the same filters and limit'). The list of returned fields is partly redundant with the existing output schema, which keeps this from a 5.

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?

Four dense sentences, front-loaded with the purpose, then the return shape, then the timing rationale, then pagination. No filler or restatement of the name.

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 zero-required-parameter index browser with an output schema and read-only annotations, the description covers purpose, motivation, default page size, and continuation procedure. An agent has everything needed to call it correctly and to chain pages.

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 freq, period, reporter_code, classification, limit and offset are already documented, including the 'omit to browse' behavior. The description only restates omission and pagination at a high level, adding little syntax or meaning beyond the schema; baseline 3 applies.

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

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

States a specific verb and resource: 'Check which reporter/period/classification combinations have published data'. The framing as a pre-flight index check clearly separates it from the sibling query tools (comtrade_get_trade_flows, comtrade_get_top_partners, etc.).

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

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

Gives explicit when-to-use guidance ('Call this before querying recent periods') plus the underlying reason (annual data published 3–12 months after reference year, not all countries report every year), and an alternative mode ('Omit filters to browse the availability index'). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds real value with the preview behavior: one paced request per served period, 500-record cap per request. It says less about pagination beyond the cap, error behavior, or how 'disclosed remainder' periods are handled.

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

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

Front-loaded with the core action and classification detail, then the category-lookup routing, then a workload warning. Nearly every sentence earns its place, though listing the returned fields (flow value in USD, period, reporter/partner/category metadata) is largely redundant when an output schema exists.

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 annotations, a full-coverage schema, and an output schema, the description covers the main agent-relevant extras: classification editions, category lookup prerequisite, per-period request pacing and 500-record cap, and limited services coverage. It leaves only minor gaps such as behavior when a reporter lacks services data.

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 every parameter is already documented in the schema. The description reinforces the service_code lookup workflow and the per-period request cost but adds no syntax or edge-case meaning beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Fetch annual international trade-in-services data') plus the classification scheme (combined EB) and the fact that each row carries its actual edition. It also implicitly contrasts with the goods trade tool by noting the 'same bilateral structure as goods trade,' so an agent can tell it apart from comtrade_get_trade_flows.

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

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

Gives a concrete prerequisite: use comtrade_list_service_categories to resolve the service code before querying. It also warns that services coverage is narrower than goods, which sets expectations. It stops short of saying when to prefer this over the general goods flow tool or what to do when a reporter has no services data.

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 readOnlyHint and openWorldHint annotations, the description discloses meaningful internals: matching TOTAL retrieval, chunked code queries, subdivision of capped chunks, and shares computed from the matching TOTAL. It also discloses degraded behavior (unranked categories and unresolved codes on incomplete coverage). Minor gap: no indication of failure or rate-limit behavior for the multi-chunk fan-out.

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 primary action is front-loaded in sentence one and each subsequent sentence adds distinct operational detail. It is dense to the point of being terse in the middle clauses, but no sentence is redundant filler.

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

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

For a tool with 6 parameters, partial-coverage risk, and chunked retrieval, the description covers inputs, ranking semantics, and partial-result behavior; the output schema carries return shape, so nothing essential is missing. An agent can call it correctly and interpret degraded responses from the description alone.

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 clarifying that reporter, flow, and period define a single ranking context and that omitting the bilateral reporter selects World. The limit/truncation interaction with chunking is also implied by the coverage caveat, though the exact threshold lives only in 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 first sentence states a specific verb (rank), resource (HS chapters/headings), and scope (one reporter, flow, and annual or monthly period). Naming comtrade_get_top_partners as the counterpart lets an agent separate this tool from its closest sibling without opening either schema.

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

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

Usage context is clear: default to World unless a single bilateral partner is supplied, and the counterpart pointer implicitly routes partner-level ranking to comtrade_get_top_partners. It stops short of explicit when-not guidance against the other siblings such as comtrade_search_commodities, so it is not a 5.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds genuinely useful behavior beyond them: it fetches a disaggregated breakdown across all partners and sorts locally, which warns about data volume and implies the limit is applied client-side. It stops short of stating rate limits or what happens when no partners exist.

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 sentences, front-loaded with the action and purpose, then the concrete question framing, then the execution note. No filler and nothing important buried.

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

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

An output schema exists so return values need no explanation, and all five parameters are schema-documented at full coverage. The only meaningful gap is that it does not clarify how ties or missing partner data are handled, which for a ranking tool is a minor omission.

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 the limit and cmd_code semantics ('Omit or pass TOTAL') are already fully documented in the schema. The description's 'top N' and 'Omit cmd_code' remarks largely restate that, adding little meaning beyond structured fields. Baseline 3 applies.

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

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

States a specific verb (rank) and resource (trading partners) with the scoping dimensions (reporter, commodity, flow), and the two quoted example questions make the output shape unambiguous. It is clearly distinguished from sibling comtrade_get_top_commodities, which does the inverse ranking.

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 context is clear: single-period ranking, and 'Omit cmd_code to rank partners for total trade' gives a concrete decision rule. However, no sibling is named as an alternative, so an agent comparing this against comtrade_get_trade_flows or comtrade_get_top_commodities must infer the routing itself.

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

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

Goes well beyond the readOnlyHint/openWorldHint annotations by disclosing the request cost model ('preview makes two paced requests per served period; authenticated calls batch periods') and the truncation behavior for periods and commodity codes. It also flags the mirror-asymmetry caveat that the balance reflects only the reporter's own values, which is a substantive data-quality warning an agent could not infer from structured fields.

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

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

Front-loaded with the computation and formula, then progressively adds cost model, return shape, and caveat. It is dense with four long sentences but nearly every clause carries operational value; the enumerated return fields are the only part that mildly duplicates the output schema.

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

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

Given a six-parameter tool with a full input schema, an output schema, and safety annotations, the description covers the remaining gaps: request cost, batching, truncation, return composition, and the mirror-asymmetry interpretation risk. Nothing an agent needs to call or interpret the result 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 every parameter is already documented with defaults and formats. The description adds only a light gloss on the commodity filter and reporter-code resolution, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Compute the trade balance for a country over one or more periods') and defines the metric inline ('total exports minus total imports'), which distinguishes it from the raw-flow sibling comtrade_get_trade_flows. The optional commodity filter scope is also named.

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

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

Implies the correct usage context via the commodity-filter option and explicitly points to comtrade_lookup_countries for resolving reporter codes. It does not explicitly state when to prefer this over comtrade_get_trade_flows or comtrade_get_top_partners, so the routing guidance is inferred rather than stated.

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

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

Annotations already declare readOnlyHint and openWorldHint, yet the description adds substantive behavior: return fields and their valuation basis (FOB for exports, CIF for imports), the paced one-request-per-period pattern in Preview mode, and a 500-record cap per request. The truncation behavior (first 12 periods, first 20 codes, first 20 reporters with the remainder disclosed) is also surfaced rather than left buried in the schema.

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

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

The description is front-loaded with purpose and return shape before moving into calling conventions and helper tools, and each sentence carries information. There is minor redundancy, such as restating that multiple periods and commodity codes can be accepted per call, which the array schema already conveys.

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 7-parameter, open-world retrieval tool with an output schema, this is close to complete: it covers aggregation semantics, code resolution, classification caveats, and request pacing limits. The remaining gap is the unexplained 'Preview' mode and the cap/truncation interplay across parameters, which an agent may still misjudge in combination.

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 a baseline of 3 applies, but the description adds real meaning on top: the FOB/CIF interpretation of primaryValue, the World-total shortcut of partner_code 0, the disaggregated default when partner_code is omitted, and the TOTAL/omit convention for cmd_code. It does not clarify the freq defaults or the 'Preview' notion that has no corresponding schema parameter, which keeps it short of a 5.

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

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

The first sentence names a specific verb and resource (fetch bilateral trade flow records) and frames it as the primary data retrieval tool, which pairs well with the read-only annotations. It does not explicitly contrast itself with the closest siblings that could be confused with it (comtrade_get_services_trade, comtrade_get_top_commodities), so the agent must infer that this tool covers goods flows rather than services or rankings.

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

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

It gives concrete operational guidance: pass partner_code 0 to aggregate across all partners, omit cmd_code or pass TOTAL to aggregate commodities, and use comtrade_lookup_countries and comtrade_search_commodities to resolve codes before calling. It also notes the SITC revision dependency. What's missing is an explicit when-not clause or a direct pointer to the services/rankings siblings for those use cases.

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

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

The readOnlyHint/openWorldHint annotations already establish a safe, local read, so the description only needs to add context — which it does by disclosing the catalog's provenance (combined EB), the returned fields (codes, descriptions, parent codes), and domain anchors like "Code 3 is transport; SA is manufacturing services." It does not discuss exhaustiveness or whether the catalog is static, a minor remaining gap for a lookup tool.

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

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

The definition is front-loaded with purpose, then filtering behavior, then the downstream handoff — a sensible order with no filler sentences. A small amount of space is spent repeating limit/query behavior already covered by the schema.

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

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

For a three-optional-parameter, read-only catalog tool with a 100%-covered schema and an output schema, this is nearly complete: usage modes, downstream linkage, and code semantics are all present. Return-value explanation is slightly redundant given the output schema, and catalog exhaustiveness remains unstated.

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

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

Schema coverage is 100%, so limit, query, and parent_code are already fully documented; the description's filter/browse sentences largely restate those schema descriptions. The one piece of genuinely added meaning is the mapping of a returned id to the service_code parameter of comtrade_get_services_trade, which the schema cannot express.

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?

"List service trade categories from the combined EB catalog" gives a specific verb and resource, and the mention of numeric EBOPS and SDMX codes plus keyword/parent filtering separates it cleanly from siblings like comtrade_search_commodities and comtrade_lookup_countries.

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

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

It states the two usage modes (keyword filter vs. browsing direct children of a parent code) and explicitly routes the agent onward: "Use the returned id as service_code in comtrade_get_services_trade." It stops short of an explicit exclusion naming comtrade_search_commodities as the alternative for commodity lookups.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and an output schema exists, so the bar is lower. The description's genuinely additive piece is the domain semantics of validAsReporter — regional groupings such as 'World' (code 0) are valid partners but not valid reporters — which warns the agent off a plausible misuse; the rest largely restates the return payload and the schema's case-insensitivity.

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?

Four short sentences, front-loaded with the core action and then the invocation prerequisite. Every sentence carries information an agent needs: input forms, return fields, the validAsReporter caveat, and the partner-0 shortcut.

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, the schema is fully documented, and an output schema covers return values, so the description only needed to add the sequencing rule and the reporter/partner distinction — it does both. Nothing required to call this correctly before a trade-data call is missing.

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

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

Schema description coverage is 100%, including an inline enum explanation for `role` and a documented default for `include_groups`, so the baseline is 3. The description reinforces input flexibility and adds the aggregation shortcut (partner code 0), but it does not explain how `role` and `include_groups` interact or what happens with an ambiguous partial name.

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: 'Resolve country and area names to Comtrade M49 numeric codes used in all data queries.' It also names the accepted input forms and the returned fields, so an agent can distinguish this pure-lookup tool from every sibling data-retrieval tool without opening a schema.

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

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

Explicitly routes usage: 'Use this before any trade data tool that requires reporter_code or partner_code,' and gives an exclusion — aggregation across all partners needs no lookup, just partner code 0. Both the when and the when-not are stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely new context: the caveat that the default HS catalog is a discovery catalog rather than an authoritative historical-edition reference, and the hierarchy/leaf-status semantics that shape interpretation of 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?

Three tight sentences with the core capability front-loaded and the caveat placed last where it belongs. Some content (the HS 2/4/6 and SITC 1–5 level mapping) duplicates the schema verbatim and could be trimmed.

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

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

With an output schema present and full parameter documentation, the description need not explain return values, and it correctly focuses on classification-edition semantics. It could go one step further by stating the explicit handoff to comtrade_get_trade_flows using recommendedQueryCode, but nothing essential 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 description coverage is 100%, so the schema already documents all four parameters, including the aggr_level level mapping and the classification enum caveats. The description restates the level scheme and adds only the edition-matching heuristic, so it adds marginal meaning beyond structured fields.

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 ("Find HS or SITC commodity codes") plus the three search modes (keyword, partial description, code prefix) and the scoping constraint ("in the selected classification"). This is clearly distinguishable from siblings like comtrade_lookup_countries or comtrade_get_top_commodities.

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?

Implies the workflow position by noting it returns "recommendedQueryCode for subsequent trade queries," and gives edition-selection guidance ("Select the edition matching the trade records when interpreting historical codes"). It stops short of explicit when-not guidance or naming a specific sibling as an alternative.

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