Kyrodata — Brazil Trade, Crop & Commodity Data

Overview of an HS heading (SH4)

kyrodata_get_heading_overview

Read-onlyIdempotent

Structured read of ONE HS heading (SH4, 4 digits) for exports or imports: totals of the published year (USD FOB, kg), the last closed month against the previous one (average price per kg and volume), and a monthly price-by-volume series. year centres the overview and defaults to the most recent published year, with coverage starting in 2000; months sets only how far the series reaches back from the last published month, and leaves the totals untouched. A caveat states that US$/kg is an average unit value, not a quoted price. Public data. The output here is FIGURES and a series to reason over. The same heading as a citable document with a URL is kyrodata_fetch, and a comparison between two windows is kyrodata_compare_trade. Credit class: comex (up to 2 comex tools per 60-second session = 1 credit).

Input Schema

TableJSON Schema

Name	Required	Description
`sh4`	Yes	The 4-digit HS heading to describe.
`flow`	Yes	Direction of the trade flow, from Brazil’s side: `export` leaves the country, `import` enters it.
`year`	No	Calendar year of the TOTALS (USD FOB, kg). Omit for the most recent published year; coverage starts in 2000. The month-over-month figures and the price-by-volume series always describe the latest published months, whatever `year` says.
`months`	No	Length of the monthly series returned, counting back from the last published month.
`response_format`	No	How much of the answer to return. `concise` (the default) carries the headline figures; `detailed` adds the row-level series behind them and counts against the export quota.

Output Schema

TableJSON Schema

Name	Required	Description
`data`	Yes	Raw numbers behind the text.
`memo`	Yes	true = identical call in the last 10 min, served again: 0 credits.
`rows`	No	Table rows; detailed only, capped per tool.
`error`	No	Failure message when status = error.
`links`	Yes	screen = product page with these numbers.
`denied`	No	When status = denied: reason, feature, upgradeUrl.
`status`	Yes	ok = data; denied = plan; error = failure or timeout.
`window`	No	Like-for-like window: from, to (YYYY-MM), label, months, crossesSeason.
`caveats`	Yes	Reading caveats.
`credits`	Yes	charged, balance (null = unlimited), resetAt, session {charged, endsAt} of the 60-s billing session.
`sources`	Yes	Per source: label, nameable, asOf.
`dataVersion`	Yes	Identity of the data that answered.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedSep 12, 2026

changedInput schema / properties / year / description

Previous value: -"Calendar year to centre the overview on. Omit for the most recent published year; coverage starts in 2000."New value: +"Calendar year of the TOTALS (USD FOB, kg). Omit for the most recent published year; coverage starts in 2000. The month-over-month figures and the price-by-volume series always describe the latest published months, whatever `year` says."

Changed5 schema fields changedSep 7, 2026

addedInput schema / properties / flow / description

Added value: +"Direction of the trade flow, from Brazil’s side: `export` leaves the country, `import` enters it."

addedInput schema / properties / months / description

Added value: +"Length of the monthly series returned, counting back from the last published month."

addedInput schema / properties / response_format / description

Added value: +"How much of the answer to return. `concise` (the default) carries the headline figures; `detailed` adds the row-level series behind them and counts against the export quota."

addedInput schema / properties / sh4 / description

Added value: +"The 4-digit HS heading to describe."

addedInput schema / properties / year / description

Added value: +"Calendar year to centre the overview on. Omit for the most recent published year; coverage starts in 2000."

First observedSep 6, 2026

TDQS

A4.6/5.0

Behavior4/5

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

Annotations already cover the safety profile (readOnly, idempotent, closed-world, non-destructive), but the description goes further with public-data status, a documented caveat that US$/kg is an average unit value rather than a quoted price, a credit cost rule (up to 2 comex tools per 60-second session = 1 credit) and the fact that `detailed` counts against the export quota. These are genuine operational traits not present in 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.

Conciseness4/5

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

Dense but front-loaded: the core action and output shape come first, then parameter semantics, then caveat, then sibling routing and cost. Each sentence carries information, though the credit-class sentence is appended rather than integrated, making the block slightly longer than needed.

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

Completeness5/5

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

For a 5-parameter analytical read with an output schema, the description covers the action, both axis semantics, the data caveat, sibling routing and cost model. Nothing needed to invoke it correctly or interpret the result is missing.

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

Parameters4/5

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 the non-obvious interaction semantics that `year` centres the overview (defaulting to latest published, coverage from 2000) while `months` only extends the series backwards and never alters the totals. That clarifies a genuinely ambiguous coupling the schema states only in passing.

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?

States a specific verb+resource+scope: 'Structured read of ONE HS heading (SH4, 4 digits) for exports or imports', then enumerates the three things returned (yearly totals, month-over-month, price-by-volume series). It explicitly differentiates itself from siblings kyrodata_fetch (citable document with URL) and kyrodata_compare_trade (two-window comparison).

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?

Names the two nearest alternatives and the condition that selects each: kyrodata_fetch for a citable URL-backed document, kyrodata_compare_trade for comparisons. It also clarifies the scope split between `year` (centres totals) and `months` (only series depth), which prevents a common misuse.

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

All Kyrodata — Brazil Trade, Crop & Commodity Data tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?