UN Comtrade Trade Data Query

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 substantial behavioral context beyond those hints: the 500-record cap, 500 calls/day limit, no authentication requirement, annual and monthly coverage starting years, CIF/FOB valuation conventions, USD primary value, and HS/SITC classification handling. This gives an agent a clear operational picture of what happens when the tool is called.

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 tightly written and front-loaded with the core action and result, then progresses through coverage, valuation, classification, usage hints, and API constraints. Every sentence carries operational value, and none are redundant filler. It is compact despite covering many important details.

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 12 parameters with 100% schema documentation, an output schema, and read-only/idempotent annotations, the description is complete enough for correct invocation. It covers what the query returns, scope limits, valuation units, classification systems, required registration codes, sibling lookup guidance, authentication needs, and rate limits. No critical operational 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?

Schema coverage is 100%, so the baseline is 3. The description adds practical parameter orientation: examples of HS chapter codes for machinery, petroleum, and electronics; flow_code M/X abbreviations; and direction to use comtrade.reporters for reporter codes. Much of this overlaps with schema text, but the examples and the explicit linkage to sibling lookup tools add marginal value beyond the raw 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 names a specific verb and resource: "Query international merchandise trade statistics from the UN Comtrade database," and clearly states what it returns (up to 500 records of imports/exports for reporter, period, commodity, partner). However, it does not explicitly contrast itself with closely related sibling tools like comtrade.trade.availability or comtrade.trade.metadata, so the differentiation comes from the reader's inference rather than direct statement.

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 usage context: how to get reporter codes via comtrade.reporters, example HS chapter codes, flow code meanings, and API constraints such as no auth and 500 calls/day. It does not, however, state when to prefer this tool over trade.availability or trade.metadata, nor does it give explicit exclusions or 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.