Skip to main content
Glama

comercio_exterior

Read-onlyIdempotent

Query Brazilian foreign trade exports, imports, and balance by country, bloc, state, transport mode, section, or product using official MDIC/Secex ComexStat data.

Instructions

Exportações, importações ou saldo do Brasil (MDIC/Secex, ComexStat), por país, bloco, UF, via, seção ou produto.

Valores em US$ milhões (FOB) e peso em mil toneladas, somados no período; sem datas, usa os 12 meses fechados mais recentes. Para totais mensais como série, use obter_serie (tema comercio_exterior). O ComexStat recusa requisições de forma irregular: se recusar, tente de novo em instantes.

Args: fluxo: "exportacao", "importacao" ou "saldo". por: "pais", "bloco", "uf", "via", "secao", "capitulo", "sh4" ou "nenhum" (só o total). inicio, fim: mês (AAAA ou AAAA-MM); ano inteiro: inicio="2025", fim="2025". pais, bloco, uf, via, secao, capitulo: filtros por nome ou código; pais aceita lista separada por vírgula. limite: itens do ranking (até 50); o restante vai em "demais". mensal: inclui os totais mês a mês.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "comercio_exterior"
  }
}

Input Schema

NameRequiredDescriptionDefault
ufNo
fimNo
porNopais
viaNo
paisNo
blocoNo
fluxoNoexportacao
secaoNo
inicioNo
limiteNo
mensalNo
capituloNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so safety is covered; the description adds genuinely non-structured behavior: aggregation semantics (values summed over the period), units, the implicit 12-month default window, the ranking truncation into a 'demais' bucket, and the upstream rejection/retry behavior. It stops short of describing the response shape or how the 'saldo' flow is signed, but with annotations carrying the safety profile this is well above the bar.

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

Conciseness4/5

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

The lead sentence front-loads purpose, units and default window, followed by an Args block that maps cleanly onto the parameters. Dense but nearly every line carries information; the retry sentence is the one item that sits oddly outside the domain narrative rather than being wasted.

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

Completeness4/5

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

For a 12-parameter, no-output-schema statistical query tool, the definition covers units, defaults, filter syntax, ranking truncation and upstream failure behavior — enough to call it correctly. The remaining gap is the return structure (field names, how 'demais' and 'mensal' blocks appear), which the description only implies.

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

Parameters5/5

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

Schema description coverage is 0% across 12 parameters, so the description carries the full burden and does so: it enumerates the accepted values for 'fluxo' and 'por' (which the schema leaves as free-form strings with no enum), specifies the date format ('AAAA ou AAAA-MM', whole year as inicio=fim), explains that country filters accept comma-separated lists, and clarifies that 'limite' caps ranking items with the remainder in 'demais'. This adds meaning that no structured field provides.

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

Purpose5/5

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

The description states a specific resource (Brazilian exports, imports or trade balance from MDIC/Secex ComexStat) and the exact dimensions of aggregation (country, bloc, UF, route, section, product). It also fixes the unit conventions (US$ millions FOB, thousand tonnes), so an agent knows both what the tool returns and how it is measured without opening the schema.

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

Usage Guidelines5/5

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

It explicitly states the default temporal window when dates are omitted ('sem datas, usa os 12 meses fechados mais recentes') and routes a distinct use case to an alternative: 'Para totais mensais como série, use obter_serie (tema comercio_exterior)'. It even supplies a retry condition for an upstream quirk ('se recusar, tente de novo em instantes'), leaving little to inference.

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