comex_trade_flow

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

With no annotations provided, the description carries the full burden. It discloses significant behavioral details: the 'air' channel is corrected by dispatch point because the dataset's modal field is contaminated and should not be used raw, and the response always includes applicable caveats and file provenance. This is valuable transparency about data quality and output structure. It does not cover all typical behaviors (e.g., read-only nature, pagination, rate limits), but the critical data correction and output caveat information is highly informative.

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, two sentences, and front-loaded with the main purpose. The first sentence states the core function, filters, and grouping; the second adds critical caveats about channel correction and response contents. There is no fluff, and the structure is efficient. It earns a 4 rather than 5 because it could be slightly more structured with bullets, but it is already clear and compact.

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

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

Given the complexity of 8 parameters (all optional) and no output schema, the description covers key aspects: it specifies the metrics returned, the correction for the 'air' channel, and that responses always include caveats and file provenance. This is fairly complete for a data retrieval tool. However, it does not mention typical response format details (e.g., units, pagination, or whether results are aggregated by default), and it omits any prerequisites like authentication. These are minor gaps but not critical.

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 all 8 parameters already have explanatory text in the schema. The description text itself does not add new semantics for parameters beyond what the schema provides, even though the channel parameter's complex behavior is fully explained in the schema. According to the rubric, when schema coverage is high, the baseline is 3, and the description adds no additional value here.

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 provides Brazil foreign trade flow data (value, weight, and value density) from official Comex Stat microdata, including filters and grouping. It mentions the specific resource and the metrics returned, making the purpose evident. It lacks an explicit verb like 'retrieve' but the noun-based phrasing is still clear. It is distinguishable from siblings, which focus on freight, code resolution, and caveats.

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 does not mention when to use this tool versus the sibling tools (comex_data_caveats, comex_freight_cost, comex_resolve_code). It provides no explicit conditions for selecting this tool over alternatives, nor any 'when not to use' guidance. The only implicit hint is that it covers trade flows, but that is not sufficient for guiding tool selection.

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