Servidor MCP

Kyrodata — Brazil Trade, Crop & Commodity Data

com.kyrodata/kyrodata
Datos y analítica Ciencia e ingeniería Público y accesible MCP 2025-11-25

Qué hace este MCP

Provides Brazilian trade, crop, climate, supply-demand, commodity, and forecast data with comparison, reporting, and provenance tools.

kyrodata_compare_trade
Compare exports/imports between equal windows
Compares Brazil's exports or imports between two equal-length windows (like-for-like), in value (USD FOB) and in volume (kg). `mode` changes the reading: quarterly, semestral, annual, ytd and rolling_3m/6m/12m look a year back and hold the season constant, while monthly and semestral_sequential compare against the period immediately before and cross one. `codes` and `countryIds` filter both windows alike and combine: together they isolate one product to one partner (1201 soybean to 160 China); omitted, every product and partner counts. The result carries both windows, the % change of each metric, the window label, whether it crosses a season, and the monthly series spanning both, capped at 24 months. This returns the FIGURES of a comparison — kyrodata_resolve_comparison_window only names the window, and kyrodata_list_trade_series hands over raw monthly points without comparing them. Credit class: comex (up to 2 comex tools per 60-second session = 1 credit).
Solo lectura Idempotente
Esquema de entrada
{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['flow', 'mode'], 'properties': {'flow': {'enum': ['export', 'import'], 'type': 'string', 'description': 'Direction of the trade flow, from Brazilâ\x80\x99s side: `export` leaves the country, `import` enters it.'}, 'mode': {'enum': ['monthly', 'quarterly', 'semestral', 'semestral_sequential', 'annual', 'ytd', 'rolling_3m', 'rolling_6m', 'rolling_12m'], 'type': 'string', 'description': 'Which pair of equal-length windows to compare. Against the same period a year earlier: `quarterly`, `semestral`, `annual`, `ytd` (January to the last published month) and `rolling_3m`/`6m`/`12m`. Against the period immediately before, which crosses a season: `monthly` and `semestral_sequential`. Use `ytd` when the question names no period.'}, 'codes': {'type': 'array', 'items': {'type': 'string', 'pattern': '^\\d{4}(\\d{2}|\\d{4})?$'}, 'maxItems': 10, 'description': 'Products to filter by, as HS codes â\x80\x94 4 digits (heading), 6 (subheading) or 8 (Brazilian NCM), up to 10. Omit for every product. kyrodata_resolve_entity turns a product name into its code.'}, 'countryIds': {'type': 'array', 'items': {'type': 'string', 'pattern': '^[A-Za-z0-9]{1,6}$'}, 'maxItems': 5, 'description': 'Partner countries to filter by, as ids from kyrodata_resolve_entity. Omit for every partner.'}, 'response_format': {'enum': ['concise', 'detailed'], 'type': 'string', 'description': '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.'}}, 'additionalProperties': False}
Esquema de salida
{'type': 'object', 'required': ['status', 'data', 'sources', 'caveats', 'credits', 'memo', 'dataVersion', 'links'], 'properties': {'data': {'type': 'object', 'description': 'Raw numbers behind the text.'}, 'memo': {'type': 'boolean', 'description': 'true = identical call in the last 10 min, served again: 0 credits.'}, 'rows': {'type': 'array', 'items': {'type': 'object'}, 'description': 'Table rows; detailed only, capped per tool.'}, 'error': {'type': 'string', 'description': 'Failure message when status = error.'}, 'links': {'type': 'object', 'description': 'screen = product page with these numbers.'}, 'denied': {'type': 'object', 'description': 'When status = denied: reason, feature, upgradeUrl.'}, 'status': {'enum': ['ok', 'denied', 'error'], 'type': 'string', 'description': 'ok = data; denied = plan; error = failure or timeout.'}, 'window': {'type': 'object', 'description': 'Like-for-like window: from, to (YYYY-MM), label, months, crossesSeason.'}, 'caveats': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Reading caveats.'}, 'credits': {'type': 'object', 'description': 'charged, balance (null = unlimited), resetAt, session {charged, endsAt} of the 60-s billing session.'}, 'sources': {'type': 'array', 'items': {'type': 'object'}, 'description': 'Per source: label, nameable, asOf.'}, 'dataVersion': {'type': 'string', 'description': 'Identity of the data that answered.'}}, 'additionalProperties': False}
kyrodata_explain_pyramid_level
Explain one level of the forecast pyramid
Explains the pyramid's arithmetic for one commodity and horizon: the seven levels side by side (label, push %, weight share, confidence, contribution %) and, for the levels that did not enter, the reason with its ruler (hit rate vs base rate, number of origins). `horizon` fixes the month and shows the seven levels; `levelKey` flips the cut, following one level across all four horizons instead. This is the drill-down of kyrodata_get_hub_summary — the 'por quê?' behind a verdict that tool already gave. A question about the physical harvest rather than the arithmetic belongs to kyrodata_get_climate_reading. Credit class: level (any level tool in a 60-second session = 2 credits; a session is capped at 3).
Solo lectura Idempotente
Esquema de entrada
{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['hub', 'horizon'], 'properties': {'hub': {'enum': ['sugar', 'beef', 'coffee', 'ethanol', 'chicken', 'corn', 'soybean', 'pork', 'crude-oil', 'natural-gas', 'iron-ore', 'aluminum', 'copper', 'gold', 'urea', 'potash', 'phosphate', 'cotton', 'cocoa', 'orange-juice', 'wheat', 'rice'], 'type': 'string', 'description': 'Which commodity hub to read.'}, 'horizon': {'enum': ['m1', 'm3', 'm6', 'm12'], 'type': 'string', 'description': 'How far ahead the forecast looks: 1, 3, 6 or 12 months from the last published month.'}, 'levelKey': {'enum': ['climate', 'costs', 'production', 'logistics', 'trade', 'macro', 'supply_demand'], 'type': 'string', 'description': 'One level of the pyramid. Given, the answer follows that level across all four horizons instead of showing the seven side by side.'}, 'response_format': {'enum': ['concise', 'detailed'], 'type': 'string', 'description': '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.'}}, 'additionalProperties': False}
Esquema de salida
{'type': 'object', 'required': ['status', 'data', 'sources', 'caveats', 'credits', 'memo', 'dataVersion', 'links'], 'properties': {'data': {'type': 'object', 'description': 'Raw numbers behind the text.'}, 'memo': {'type': 'boolean', 'description': 'true = identical call in the last 10 min, served again: 0 credits.'}, 'rows': {'type': 'array', 'items': {'type': 'object'}, 'description': 'Table rows; detailed only, capped per tool.'}, 'error': {'type': 'string', 'description': 'Failure message when status = error.'}, 'links': {'type': 'object', 'description': 'screen = product page with these numbers.'}, 'denied': {'type': 'object', 'description': 'When status = denied: reason, feature, upgradeUrl.'}, 'status': {'enum': ['ok', 'denied', 'error'], 'type': 'string', 'description': 'ok = data; denied = plan; error = failure or timeout.'}, 'window': {'type': 'object', 'description': 'Like-for-like window: from, to (YYYY-MM), label, months, crossesSeason.'}, 'caveats': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Reading caveats.'}, 'credits': {'type': 'object', 'description': 'charged, balance (null = unlimited), resetAt, session {charged, endsAt} of the 60-s billing session.'}, 'sources': {'type': 'array', 'items': {'type': 'object'}, 'description': 'Per source: label, nameable, asOf.'}, 'dataVersion': {'type': 'string', 'description': 'Identity of the data that answered.'}}, 'additionalProperties': False}
kyrodata_fetch
Open one public trade document by id
Opens ONE public foreign-trade document by id and returns it as prose to quote: title, body text and a public URL for citation. `id` is not free text — it is an id kyrodata_search returned, shaped `heading:1201` (an HS heading) or `country:160` (a partner country); anything else is refused rather than guessed. The body carries the measured figures of the latest published year, Brazilian exports and imports in USD FOB and kg, plus the window, the source and its caveats. Public government trade data only. The output here is a citable DOCUMENT with a URL, and this is the only tool that returns one. A heading as structured figures and a monthly series to reason over is kyrodata_get_heading_overview; free text to find an id in the first place is kyrodata_search. Credit class: comex (up to 2 comex tools per 60-second session = 1 credit).
Solo lectura Idempotente
Esquema de entrada
{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['id'], 'properties': {'id': {'type': 'string', 'maxLength': 64, 'minLength': 3, 'description': 'Identifier of a document returned by kyrodata_search. Not a free-text query.'}, 'response_format': {'enum': ['concise', 'detailed'], 'type': 'string', 'description': '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.'}}, 'additionalProperties': False}
Esquema de salida
{'type': 'object', 'required': ['id', 'title', 'text', 'url', 'metadata'], 'properties': {'id': {'type': 'string', 'description': 'The document id that was fetched.'}, 'url': {'type': 'string', 'description': 'Public page with the same data, for citation.'}, 'text': {'type': 'string', 'description': 'The document body: the measured figures, the window, the source.'}, 'title': {'type': 'string', 'description': 'Human-readable name of the document.'}, 'metadata': {'type': 'object', 'description': 'kind, code, flow, window, sources, caveats and dataVersion.'}}, 'additionalProperties': False}
kyrodata_get_climate_reading
Climate reading and physical crop loss
Current climate reading for a commodity: risk level, the measured production shock in % of the harvest, and the projected physical loss in tonnes per horizon (1, 3, 6 and 12 months) with its range. `scope` sets the geographic cut — 'br' (the default) reads the country, 'region:SE' a macro-region (N, NE, CW, SE, S), 'uf:MG' a single state — and moves only the risk level and the shock: the loss in tonnes stays national at any scope. A commodity without a validated model returns a descriptive reading with no verdict, and a season not yet measurable returns the previous one, each flagged in the caveats. Climate here predicts PRODUCTION. The price question for the same hub is kyrodata_get_hub_summary, and the published season-by-season balance sheet is kyrodata_get_supply_demand_balance. Credit class: level (any level tool in a 60-second session = 2 credits; a session is capped at 3).
Solo lectura Idempotente
Esquema de entrada
{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['hub'], 'properties': {'hub': {'enum': ['sugar', 'beef', 'ethanol', 'chicken', 'pork', 'cocoa', 'orange-juice', 'wheat'], 'type': 'string', 'description': 'Which commodity hub to read. Climate forecasts PRODUCTION, never price.'}, 'scope': {'type': 'string', 'pattern': '^(br|region:(N|NE|CW|SE|S)|uf:[A-Z]{2})$', 'description': 'Geographic cut: `br` for the whole country, `region:<N|NE|CW|SE|S>` for a macro-region, or `uf:<XX>` for a state. Defaults to the country.'}, 'response_format': {'enum': ['concise', 'detailed'], 'type': 'string', 'description': '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.'}}, 'additionalProperties': False}
Esquema de salida
{'type': 'object', 'required': ['status', 'data', 'sources', 'caveats', 'credits', 'memo', 'dataVersion', 'links'], 'properties': {'data': {'type': 'object', 'description': 'Raw numbers behind the text.'}, 'memo': {'type': 'boolean', 'description': 'true = identical call in the last 10 min, served again: 0 credits.'}, 'rows': {'type': 'array', 'items': {'type': 'object'}, 'description': 'Table rows; detailed only, capped per tool.'}, 'error': {'type': 'string', 'description': 'Failure message when status = error.'}, 'links': {'type': 'object', 'description': 'screen = product page with these numbers.'}, 'denied': {'type': 'object', 'description': 'When status = denied: reason, feature, upgradeUrl.'}, 'status': {'enum': ['ok', 'denied', 'error'], 'type': 'string', 'description': 'ok = data; denied = plan; error = failure or timeout.'}, 'window': {'type': 'object', 'description': 'Like-for-like window: from, to (YYYY-MM), label, months, crossesSeason.'}, 'caveats': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Reading caveats.'}, 'credits': {'type': 'object', 'description': 'charged, balance (null = unlimited), resetAt, session {charged, endsAt} of the 60-s billing session.'}, 'sources': {'type': 'array', 'items': {'type': 'object'}, 'description': 'Per source: label, nameable, asOf.'}, 'dataVersion': {'type': 'string', 'description': 'Identity of the data that answered.'}}, 'additionalProperties': False}
kyrodata_get_credit_balance
Credit balance and limits for this key
Reports the credit balance and the limits of the API key making the request: credits left in the current cycle and when it resets, the daily credit and daily call ceilings of the key, and which tools the key reaches. `response_format` is the only input and it changes verbosity, not scope — there is no argument that selects another key, since the answer describes whichever key authenticated this call. It reads no market data, so it answers a question about the ACCOUNT, never about trade, climate or a commodity. A question about how far the data itself goes is kyrodata_get_data_coverage. Credit class: free (0 credits).
Solo lectura Idempotente
Esquema de entrada
{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'response_format': {'enum': ['concise', 'detailed'], 'type': 'string', 'description': '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.'}}, 'additionalProperties': False}
Esquema de salida
{'type': 'object', 'required': ['status', 'data', 'sources', 'caveats', 'credits', 'memo', 'dataVersion', 'links'], 'properties': {'data': {'type': 'object', 'description': 'Raw numbers behind the text.'}, 'memo': {'type': 'boolean', 'description': 'true = identical call in the last 10 min, served again: 0 credits.'}, 'rows': {'type': 'array', 'items': {'type': 'object'}, 'description': 'Table rows; detailed only, capped per tool.'}, 'error': {'type': 'string', 'description': 'Failure message when status = error.'}, 'links': {'type': 'object', 'description': 'screen = product page with these numbers.'}, 'denied': {'type': 'object', 'description': 'When status = denied: reason, feature, upgradeUrl.'}, 'status': {'enum': ['ok', 'denied', 'error'], 'type': 'string', 'description': 'ok = data; denied = plan; error = failure or timeout.'}, 'window': {'type': 'object', 'description': 'Like-for-like window: from, to (YYYY-MM), label, months, crossesSeason.'}, 'caveats': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Reading caveats.'}, 'credits': {'type': 'object', 'description': 'charged, balance (null = unlimited), resetAt, session {charged, endsAt} of the 60-s billing session.'}, 'sources': {'type': 'array', 'items': {'type': 'object'}, 'description': 'Per source: label, nameable, asOf.'}, 'dataVersion': {'type': 'string', 'description': 'Identity of the data that answered.'}}, 'additionalProperties': False}
kyrodata_get_data_coverage
Data coverage and latest closed month
Returns the calendar of the trade data: first and last published month (YYYYMM), whether the current year is partial, the last fully closed month, and when the aggregates were last refreshed. `response_format` is the only input; the answer covers the whole dataset, so there is no window or product to narrow it with. This answers 'até quando tem dado?' and 'qual o último mês?' — the CALENDAR, never figures. Turning that calendar into a like-for-like window is kyrodata_resolve_comparison_window; reading the figures inside it is kyrodata_get_heading_overview. Credit class: free (0 credits).
Solo lectura Idempotente
Esquema de entrada
{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'response_format': {'enum': ['concise', 'detailed'], 'type': 'string', 'description': '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.'}}, 'additionalProperties': False}
Esquema de salida
{'type': 'object', 'required': ['status', 'data', 'sources', 'caveats', 'credits', 'memo', 'dataVersion', 'links'], 'properties': {'data': {'type': 'object', 'description': 'Raw numbers behind the text.'}, 'memo': {'type': 'boolean', 'description': 'true = identical call in the last 10 min, served again: 0 credits.'}, 'rows': {'type': 'array', 'items': {'type': 'object'}, 'description': 'Table rows; detailed only, capped per tool.'}, 'error': {'type': 'string', 'description': 'Failure message when status = error.'}, 'links': {'type': 'object', 'description': 'screen = product page with these numbers.'}, 'denied': {'type': 'object', 'description': 'When status = denied: reason, feature, upgradeUrl.'}, 'status': {'enum': ['ok', 'denied', 'error'], 'type': 'string', 'description': 'ok = data; denied = plan; error = failure or timeout.'}, 'window': {'type': 'object', 'description': 'Like-for-like window: from, to (YYYY-MM), label, months, crossesSeason.'}, 'caveats': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Reading caveats.'}, 'credits': {'type': 'object', 'description': 'charged, balance (null = unlimited), resetAt, session {charged, endsAt} of the 60-s billing session.'}, 'sources': {'type': 'array', 'items': {'type': 'object'}, 'description': 'Per source: label, nameable, asOf.'}, 'dataVersion': {'type': 'string', 'description': 'Identity of the data that answered.'}}, 'additionalProperties': False}
kyrodata_get_heading_overview
Overview of an HS heading (SH4)
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).
Solo lectura Idempotente
Esquema de entrada
{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['sh4', 'flow'], 'properties': {'sh4': {'type': 'string', 'pattern': '^\\d{4}$', 'description': 'The 4-digit HS heading to describe.'}, 'flow': {'enum': ['export', 'import'], 'type': 'string', 'description': 'Direction of the trade flow, from Brazilâ\x80\x99s side: `export` leaves the country, `import` enters it.'}, 'year': {'type': 'integer', 'maximum': 2099, 'minimum': 2000, 'description': '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': {'type': 'integer', 'maximum': 60, 'minimum': 3, 'description': 'Length of the monthly series returned, counting back from the last published month.'}, 'response_format': {'enum': ['concise', 'detailed'], 'type': 'string', 'description': '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.'}}, 'additionalProperties': False}
Esquema de salida
{'type': 'object', 'required': ['status', 'data', 'sources', 'caveats', 'credits', 'memo', 'dataVersion', 'links'], 'properties': {'data': {'type': 'object', 'description': 'Raw numbers behind the text.'}, 'memo': {'type': 'boolean', 'description': 'true = identical call in the last 10 min, served again: 0 credits.'}, 'rows': {'type': 'array', 'items': {'type': 'object'}, 'description': 'Table rows; detailed only, capped per tool.'}, 'error': {'type': 'string', 'description': 'Failure message when status = error.'}, 'links': {'type': 'object', 'description': 'screen = product page with these numbers.'}, 'denied': {'type': 'object', 'description': 'When status = denied: reason, feature, upgradeUrl.'}, 'status': {'enum': ['ok', 'denied', 'error'], 'type': 'string', 'description': 'ok = data; denied = plan; error = failure or timeout.'}, 'window': {'type': 'object', 'description': 'Like-for-like window: from, to (YYYY-MM), label, months, crossesSeason.'}, 'caveats': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Reading caveats.'}, 'credits': {'type': 'object', 'description': 'charged, balance (null = unlimited), resetAt, session {charged, endsAt} of the 60-s billing session.'}, 'sources': {'type': 'array', 'items': {'type': 'object'}, 'description': 'Per source: label, nameable, asOf.'}, 'dataVersion': {'type': 'string', 'description': 'Identity of the data that answered.'}}, 'additionalProperties': False}
kyrodata_get_hub_summary
Commodity hub summary and forecast verdict
Reads the Kyrodata pyramid verdict for a commodity hub: direction of the leading horizon, expected move in % per horizon (1, 3, 6 and 12 months), the 80% band as a half-width in percentage points, which levels drive the verdict and the measured accuracy. A horizon without an arrow names the reason, and an empty one means no level passed the confidence gate: no signal, not a stable price. `horizon` re-centres the verdict on the month given; omitted, it centres on the horizon the model leads with, and all four come back either way. It also carries the month-over-month and year-over-year % change of the reference price and its kind (doméstico, mundial or paridade de exportação), never the price level. This is the tool for where a hub's price is heading. The arithmetic behind the verdict is kyrodata_explain_pyramid_level, and the physical harvest of the same hub is kyrodata_get_climate_reading. Credit class: level (any level tool in a 60-second session = 2 credits; a session is capped at 3).
Solo lectura Idempotente
Esquema de entrada
{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['hub'], 'properties': {'hub': {'enum': ['sugar', 'beef', 'coffee', 'ethanol', 'chicken', 'corn', 'soybean', 'pork', 'crude-oil', 'natural-gas', 'iron-ore', 'aluminum', 'copper', 'gold', 'urea', 'potash', 'phosphate', 'cotton', 'cocoa', 'orange-juice', 'wheat', 'rice'], 'type': 'string', 'description': 'Which commodity hub to read.'}, 'horizon': {'enum': ['m1', 'm3', 'm6', 'm12'], 'type': 'string', 'description': 'How far ahead the forecast looks: 1, 3, 6 or 12 months from the last published month. Omitted, the verdict centres on the horizon the model leads with; given, it re-centres on that one â\x80\x94 either way all four horizons come back.'}, 'response_format': {'enum': ['concise', 'detailed'], 'type': 'string', 'description': '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.'}}, 'additionalProperties': False}
Esquema de salida
{'type': 'object', 'required': ['status', 'data', 'sources', 'caveats', 'credits', 'memo', 'dataVersion', 'links'], 'properties': {'data': {'type': 'object', 'description': 'Raw numbers behind the text.'}, 'memo': {'type': 'boolean', 'description': 'true = identical call in the last 10 min, served again: 0 credits.'}, 'rows': {'type': 'array', 'items': {'type': 'object'}, 'description': 'Table rows; detailed only, capped per tool.'}, 'error': {'type': 'string', 'description': 'Failure message when status = error.'}, 'links': {'type': 'object', 'description': 'screen = product page with these numbers.'}, 'denied': {'type': 'object', 'description': 'When status = denied: reason, feature, upgradeUrl.'}, 'status': {'enum': ['ok', 'denied', 'error'], 'type': 'string', 'description': 'ok = data; denied = plan; error = failure or timeout.'}, 'window': {'type': 'object', 'description': 'Like-for-like window: from, to (YYYY-MM), label, months, crossesSeason.'}, 'caveats': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Reading caveats.'}, 'credits': {'type': 'object', 'description': 'charged, balance (null = unlimited), resetAt, session {charged, endsAt} of the 60-s billing session.'}, 'sources': {'type': 'array', 'items': {'type': 'object'}, 'description': 'Per source: label, nameable, asOf.'}, 'dataVersion': {'type': 'string', 'description': 'Identity of the data that answered.'}}, 'additionalProperties': False}
kyrodata_get_supply_demand_balance
Supply and demand balance sheet
Published supply and demand balance (physical, in tonnes) for one agricultural hub, season by season: production, imports, exports, consumption, initial and final stock, whether the season is still an estimate, and how many months a partial season measures. `hub` accepts only the hubs that have a published balance sheet, which is fewer than the hubs the forecast tools cover; `closedOnly` drops the current season, which is a projection and still moves. The source is a Brazilian government body and is named in the result. This is the physical BALANCE of a season. The price verdict for the same hub is kyrodata_get_hub_summary, and the weather risk behind production is kyrodata_get_climate_reading. Credit class: level (any level tool in a 60-second session = 2 credits; a session is capped at 3).
Solo lectura Idempotente
Esquema de entrada
{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['hub'], 'properties': {'hub': {'enum': ['soybean', 'corn', 'wheat', 'rice', 'cotton', 'beef', 'chicken', 'pork', 'coffee', 'sugar'], 'type': 'string', 'description': 'Which commodity hub to read. Only hubs with a published balance sheet appear here.'}, 'closedOnly': {'type': 'boolean', 'description': 'Restrict to seasons already closed. The current season is a projection and still moves.'}, 'response_format': {'enum': ['concise', 'detailed'], 'type': 'string', 'description': '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.'}}, 'additionalProperties': False}
Esquema de salida
{'type': 'object', 'required': ['status', 'data', 'sources', 'caveats', 'credits', 'memo', 'dataVersion', 'links'], 'properties': {'data': {'type': 'object', 'description': 'Raw numbers behind the text.'}, 'memo': {'type': 'boolean', 'description': 'true = identical call in the last 10 min, served again: 0 credits.'}, 'rows': {'type': 'array', 'items': {'type': 'object'}, 'description': 'Table rows; detailed only, capped per tool.'}, 'error': {'type': 'string', 'description': 'Failure message when status = error.'}, 'links': {'type': 'object', 'description': 'screen = product page with these numbers.'}, 'denied': {'type': 'object', 'description': 'When status = denied: reason, feature, upgradeUrl.'}, 'status': {'enum': ['ok', 'denied', 'error'], 'type': 'string', 'description': 'ok = data; denied = plan; error = failure or timeout.'}, 'window': {'type': 'object', 'description': 'Like-for-like window: from, to (YYYY-MM), label, months, crossesSeason.'}, 'caveats': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Reading caveats.'}, 'credits': {'type': 'object', 'description': 'charged, balance (null = unlimited), resetAt, session {charged, endsAt} of the 60-s billing session.'}, 'sources': {'type': 'array', 'items': {'type': 'object'}, 'description': 'Per source: label, nameable, asOf.'}, 'dataVersion': {'type': 'string', 'description': 'Identity of the data that answered.'}}, 'additionalProperties': False}
kyrodata_list_trade_partners
Top partner countries with growth
Ranks Brazil's partner countries for exports or imports, one row per country with value (USD FOB), volume (kg), price per kg and share of the window. `from`/`to` are YYYYMM and default to the last 12 published months; `codes` narrows to HS codes (4, 6 or 8 digits) so the ranking answers 'who buys THIS product'; `withGrowth` adds the last 12 months against the previous 12, which is the only way growth enters the answer. The country is the OUTPUT of this tool, so it takes no country filter — a question about one known country is a filter on kyrodata_compare_trade or kyrodata_list_trade_series instead. This ranks partners inside one window; comparing two windows is kyrodata_compare_trade. Credit class: comex (up to 2 comex tools per 60-second session = 1 credit).
Solo lectura Idempotente
Esquema de entrada
{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['flow'], 'properties': {'to': {'type': 'integer', 'maximum': 209912, 'minimum': 200001, 'description': 'Last month of the window, as YYYYMM. Omit for the last published month.'}, 'flow': {'enum': ['export', 'import'], 'type': 'string', 'description': 'Direction of the trade flow, from Brazilâ\x80\x99s side: `export` leaves the country, `import` enters it.'}, 'from': {'type': 'integer', 'maximum': 209912, 'minimum': 200001, 'description': 'First month of the window, as YYYYMM (200403 = March 2004). Omit for the last twelve published months.'}, 'codes': {'type': 'array', 'items': {'type': 'string', 'pattern': '^\\d{4}(\\d{2}|\\d{4})?$'}, 'maxItems': 10, 'description': 'Products to filter by, as HS codes â\x80\x94 4 digits (heading), 6 (subheading) or 8 (Brazilian NCM), up to 10. Omit for every product. kyrodata_resolve_entity turns a product name into its code.'}, 'limit': {'type': 'integer', 'maximum': 300, 'minimum': 1, 'description': 'How many partner countries to return, largest first by value.'}, 'withGrowth': {'type': 'boolean', 'description': 'Also return each partnerâ\x80\x99s growth: the twelve months ending at `to` against the twelve before them. It does NOT follow `from` â\x80\x94 with a window of any other length, the ranking and the growth describe different periods.'}, 'response_format': {'enum': ['concise', 'detailed'], 'type': 'string', 'description': '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.'}}, 'additionalProperties': False}
Esquema de salida
{'type': 'object', 'required': ['status', 'data', 'sources', 'caveats', 'credits', 'memo', 'dataVersion', 'links'], 'properties': {'data': {'type': 'object', 'description': 'Raw numbers behind the text.'}, 'memo': {'type': 'boolean', 'description': 'true = identical call in the last 10 min, served again: 0 credits.'}, 'rows': {'type': 'array', 'items': {'type': 'object'}, 'description': 'Table rows; detailed only, capped per tool.'}, 'error': {'type': 'string', 'description': 'Failure message when status = error.'}, 'links': {'type': 'object', 'description': 'screen = product page with these numbers.'}, 'denied': {'type': 'object', 'description': 'When status = denied: reason, feature, upgradeUrl.'}, 'status': {'enum': ['ok', 'denied', 'error'], 'type': 'string', 'description': 'ok = data; denied = plan; error = failure or timeout.'}, 'window': {'type': 'object', 'description': 'Like-for-like window: from, to (YYYY-MM), label, months, crossesSeason.'}, 'caveats': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Reading caveats.'}, 'credits': {'type': 'object', 'description': 'charged, balance (null = unlimited), resetAt, session {charged, endsAt} of the 60-s billing session.'}, 'sources': {'type': 'array', 'items': {'type': 'object'}, 'description': 'Per source: label, nameable, asOf.'}, 'dataVersion': {'type': 'string', 'description': 'Identity of the data that answered.'}}, 'additionalProperties': False}
kyrodata_list_trade_series
Raw monthly trade series as rows
Returns Brazil's monthly export or import series as rows — one row per month, with value (USD FOB), volume (kg) and the implied price per kg. `from`/`to` are YYYYMM and default to the last 24 published months; the span is capped at 200 months and a wider one is refused rather than silently truncated. A month with nothing published is ABSENT from the series rather than present as zero, so gaps stay visible instead of reading as collapse. `codes` and `countryIds` narrow the same series and can combine, which is how a single product-and-partner line is drawn. This hands over the POINTS. A question about them — two equal windows compared — is kyrodata_compare_trade, and a ranking of partners inside one window is kyrodata_list_trade_partners. Credit class: comex (up to 2 comex tools per 60-second session = 1 credit).
Solo lectura Idempotente
Esquema de entrada
{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['flow'], 'properties': {'to': {'type': 'integer', 'maximum': 209912, 'minimum': 200001, 'description': 'Last month of the window, as YYYYMM. Omit for the last published month.'}, 'flow': {'enum': ['export', 'import'], 'type': 'string', 'description': 'Direction of the trade flow, from Brazilâ\x80\x99s side: `export` leaves the country, `import` enters it.'}, 'from': {'type': 'integer', 'maximum': 209912, 'minimum': 200001, 'description': 'First month of the window, as YYYYMM (200403 = March 2004). Omit for the last twenty-four published months.'}, 'codes': {'type': 'array', 'items': {'type': 'string', 'pattern': '^\\d{4}(\\d{2}|\\d{4})?$'}, 'maxItems': 10, 'description': 'Products to filter by, as HS codes â\x80\x94 4 digits (heading), 6 (subheading) or 8 (Brazilian NCM), up to 10. Omit for every product. kyrodata_resolve_entity turns a product name into its code.'}, 'countryIds': {'type': 'array', 'items': {'type': 'string', 'pattern': '^[A-Za-z0-9]{1,6}$'}, 'maxItems': 5, 'description': 'Partner countries to filter by, as ids from kyrodata_resolve_entity. Omit for every partner.'}, 'response_format': {'enum': ['concise', 'detailed'], 'type': 'string', 'description': '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.'}}, 'additionalProperties': False}
Esquema de salida
{'type': 'object', 'required': ['status', 'data', 'sources', 'caveats', 'credits', 'memo', 'dataVersion', 'links'], 'properties': {'data': {'type': 'object', 'description': 'Raw numbers behind the text.'}, 'memo': {'type': 'boolean', 'description': 'true = identical call in the last 10 min, served again: 0 credits.'}, 'rows': {'type': 'array', 'items': {'type': 'object'}, 'description': 'Table rows; detailed only, capped per tool.'}, 'error': {'type': 'string', 'description': 'Failure message when status = error.'}, 'links': {'type': 'object', 'description': 'screen = product page with these numbers.'}, 'denied': {'type': 'object', 'description': 'When status = denied: reason, feature, upgradeUrl.'}, 'status': {'enum': ['ok', 'denied', 'error'], 'type': 'string', 'description': 'ok = data; denied = plan; error = failure or timeout.'}, 'window': {'type': 'object', 'description': 'Like-for-like window: from, to (YYYY-MM), label, months, crossesSeason.'}, 'caveats': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Reading caveats.'}, 'credits': {'type': 'object', 'description': 'charged, balance (null = unlimited), resetAt, session {charged, endsAt} of the 60-s billing session.'}, 'sources': {'type': 'array', 'items': {'type': 'object'}, 'description': 'Per source: label, nameable, asOf.'}, 'dataVersion': {'type': 'string', 'description': 'Identity of the data that answered.'}}, 'additionalProperties': False}
kyrodata_resolve_comparison_window
Build a like-for-like comparison window
Resolves an equal-length comparison window (like-for-like) for the trade data, anchored on the last fully published month, and returns ONLY the window metadata — from, to, label, months and whether it crosses a season. No figures. `mode` splits into two families, and the split is what matters: quarterly, semestral, annual, ytd and rolling_3m/6m/12m compare against the same period a year earlier and hold the season constant, while monthly and semestral_sequential compare against the period immediately before and therefore cross one. `ytd` runs January to the last published month, in both years. This exists to NAME a window in prose before it is described. The same window resolved internally and answered with value and volume in one call is kyrodata_compare_trade. Credit class: free (0 credits).
Solo lectura Idempotente
Esquema de entrada
{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['mode'], 'properties': {'mode': {'enum': ['monthly', 'quarterly', 'semestral', 'semestral_sequential', 'annual', 'ytd', 'rolling_3m', 'rolling_6m', 'rolling_12m'], 'type': 'string', 'description': 'Which pair of equal-length windows to compare. Against the same period a year earlier: `quarterly`, `semestral`, `annual`, `ytd` (January to the last published month) and `rolling_3m`/`6m`/`12m`. Against the period immediately before, which crosses a season: `monthly` and `semestral_sequential`. Use `ytd` when the question names no period.'}, 'response_format': {'enum': ['concise', 'detailed'], 'type': 'string', 'description': '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.'}}, 'additionalProperties': False}
Esquema de salida
{'type': 'object', 'required': ['status', 'data', 'sources', 'caveats', 'credits', 'memo', 'dataVersion', 'links'], 'properties': {'data': {'type': 'object', 'description': 'Raw numbers behind the text.'}, 'memo': {'type': 'boolean', 'description': 'true = identical call in the last 10 min, served again: 0 credits.'}, 'rows': {'type': 'array', 'items': {'type': 'object'}, 'description': 'Table rows; detailed only, capped per tool.'}, 'error': {'type': 'string', 'description': 'Failure message when status = error.'}, 'links': {'type': 'object', 'description': 'screen = product page with these numbers.'}, 'denied': {'type': 'object', 'description': 'When status = denied: reason, feature, upgradeUrl.'}, 'status': {'enum': ['ok', 'denied', 'error'], 'type': 'string', 'description': 'ok = data; denied = plan; error = failure or timeout.'}, 'window': {'type': 'object', 'description': 'Like-for-like window: from, to (YYYY-MM), label, months, crossesSeason.'}, 'caveats': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Reading caveats.'}, 'credits': {'type': 'object', 'description': 'charged, balance (null = unlimited), resetAt, session {charged, endsAt} of the 60-s billing session.'}, 'sources': {'type': 'array', 'items': {'type': 'object'}, 'description': 'Per source: label, nameable, asOf.'}, 'dataVersion': {'type': 'string', 'description': 'Identity of the data that answered.'}}, 'additionalProperties': False}
kyrodata_resolve_entity
Resolve country, HS code or commodity
Resolves a free-text name into platform identifiers for FILTERING other tools: commodity hubs (slug plus anchor SH4), HS headings (SH4), NCM codes (8 digits) and partner countries (country id). 'soja' resolves to the soybean hub and SH4 1201; 'China' to country id 160. `query` takes a name already known rather than a topic to explore, and up to 10 matches per kind come back — an ambiguous term returns the candidates instead of one guess, so the caller picks. The output is an ID to pass to another tool, and it carries no document and no URL. Finding what exists in the public catalog, and getting a citable document back, is kyrodata_search. Credit class: free (0 credits).
Solo lectura Idempotente
Esquema de entrada
{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['q'], 'properties': {'q': {'type': 'string', 'maxLength': 64, 'minLength': 2, 'description': 'What to look up, in plain words: a country, a product, or a code. Portuguese and English both work.'}, 'kinds': {'type': 'array', 'items': {'enum': ['country', 'heading', 'ncm', 'hub'], 'type': 'string'}, 'description': 'Narrow the search to these kinds of entity. Omit to search all of them.'}, 'response_format': {'enum': ['concise', 'detailed'], 'type': 'string', 'description': '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.'}}, 'additionalProperties': False}
Esquema de salida
{'type': 'object', 'required': ['status', 'data', 'sources', 'caveats', 'credits', 'memo', 'dataVersion', 'links'], 'properties': {'data': {'type': 'object', 'description': 'Raw numbers behind the text.'}, 'memo': {'type': 'boolean', 'description': 'true = identical call in the last 10 min, served again: 0 credits.'}, 'rows': {'type': 'array', 'items': {'type': 'object'}, 'description': 'Table rows; detailed only, capped per tool.'}, 'error': {'type': 'string', 'description': 'Failure message when status = error.'}, 'links': {'type': 'object', 'description': 'screen = product page with these numbers.'}, 'denied': {'type': 'object', 'description': 'When status = denied: reason, feature, upgradeUrl.'}, 'status': {'enum': ['ok', 'denied', 'error'], 'type': 'string', 'description': 'ok = data; denied = plan; error = failure or timeout.'}, 'window': {'type': 'object', 'description': 'Like-for-like window: from, to (YYYY-MM), label, months, crossesSeason.'}, 'caveats': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Reading caveats.'}, 'credits': {'type': 'object', 'description': 'charged, balance (null = unlimited), resetAt, session {charged, endsAt} of the 60-s billing session.'}, 'sources': {'type': 'array', 'items': {'type': 'object'}, 'description': 'Per source: label, nameable, asOf.'}, 'dataVersion': {'type': 'string', 'description': 'Identity of the data that answered.'}}, 'additionalProperties': False}
kyrodata_run_report
Run one of the catalog reports
Runs one of the product's pre-built catalogue reports by id and returns its rows, up to 50. `reportId` is an enum of the catalogue's ids, so the whole catalogue travels in this schema and no lookup call is needed; `params` carries the values the chosen report declares, and `columnIds` narrows the projection — omitted, the report's default columns come back, and the columns that identify each row are included either way. Columns locked behind a paid plan are declared, with a header stating what an upgrade unlocks, while their values stay out. Rows count against the account's export quota. This serves a report that already exists as a product. An ad-hoc question about trade is kyrodata_compare_trade or kyrodata_list_trade_series, and a citable public document is kyrodata_fetch. Credit class: comex (up to 2 comex tools per 60-second session = 1 credit).
Solo lectura Idempotente
Esquema de entrada
{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['reportId'], 'properties': {'limit': {'type': 'integer', 'maximum': 50, 'minimum': 1, 'description': 'Maximum rows to return.'}, 'params': {'type': 'object', 'description': 'Values for the parameters the chosen report declares.', 'propertyNames': {'type': 'string'}, 'additionalProperties': {'anyOf': [{'type': 'string'}, {'type': 'number'}, {'type': 'boolean'}]}}, 'reportId': {'enum': ['comex.exports.1', 'comex.imports.1', 'comex.partners.1', 'comex.opportunities.1', 'comex.series.1', 'comex.elasticities.1', 'comex.heading.partners.1', 'comex.country.basket.1', 'hub.trade.flow.1', 'hub.trade.flow.2', 'hub.production.regions.1', 'hub.production.regions.2', 'hub.balance.sheet.1', 'hub.climate.regions.1', 'costs.survey.1', 'climate.history.1'], 'type': 'string', 'description': 'Which catalogue report to run, by id. Each report declares its own parameters, which go in `params`.'}, 'columnIds': {'type': 'array', 'items': {'type': 'string', 'minLength': 1}, 'maxItems': 20, 'minItems': 1, 'description': 'Only these columns, by id. Omit for the reportâ\x80\x99s default set; the columns that identify a row are always returned.'}, 'response_format': {'enum': ['concise', 'detailed'], 'type': 'string', 'description': '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.'}}, 'additionalProperties': False}
Esquema de salida
{'type': 'object', 'required': ['status', 'data', 'sources', 'caveats', 'credits', 'memo', 'dataVersion', 'links'], 'properties': {'data': {'type': 'object', 'description': 'Raw numbers behind the text.'}, 'memo': {'type': 'boolean', 'description': 'true = identical call in the last 10 min, served again: 0 credits.'}, 'rows': {'type': 'array', 'items': {'type': 'object'}, 'description': 'Table rows; detailed only, capped per tool.'}, 'error': {'type': 'string', 'description': 'Failure message when status = error.'}, 'links': {'type': 'object', 'description': 'screen = product page with these numbers.'}, 'denied': {'type': 'object', 'description': 'When status = denied: reason, feature, upgradeUrl.'}, 'status': {'enum': ['ok', 'denied', 'error'], 'type': 'string', 'description': 'ok = data; denied = plan; error = failure or timeout.'}, 'window': {'type': 'object', 'description': 'Like-for-like window: from, to (YYYY-MM), label, months, crossesSeason.'}, 'caveats': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Reading caveats.'}, 'credits': {'type': 'object', 'description': 'charged, balance (null = unlimited), resetAt, session {charged, endsAt} of the 60-s billing session.'}, 'sources': {'type': 'array', 'items': {'type': 'object'}, 'description': 'Per source: label, nameable, asOf.'}, 'dataVersion': {'type': 'string', 'description': 'Identity of the data that answered.'}}, 'additionalProperties': False}
kyrodata_search
Search the public trade catalog
Searches the public Brazilian foreign-trade catalogue and returns document ids for kyrodata_fetch — HS headings (SH4, 4 digits) and partner countries — each with a public URL. `query` is free text in Portuguese or a code, and both reach the same place: 'soja' and '1201' land on the soybean heading, 'China' on the partner country. This is DISCOVERY: it finds what exists when the caller has words rather than an id. Turning a name already known into an id for filtering another tool is kyrodata_resolve_entity, which returns no document and no URL. Credit class: free (0 credits).
Solo lectura Idempotente
Esquema de entrada
{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['query'], 'properties': {'query': {'type': 'string', 'maxLength': 120, 'minLength': 2, 'description': 'What to look for, in plain words. Returns document ids to pass to kyrodata_fetch.'}, 'response_format': {'enum': ['concise', 'detailed'], 'type': 'string', 'description': '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.'}}, 'additionalProperties': False}
Esquema de salida
{'type': 'object', 'required': ['results'], 'properties': {'results': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'title', 'url'], 'properties': {'id': {'type': 'string', 'description': 'Stable document id to pass to kyrodata_fetch.'}, 'url': {'type': 'string', 'description': 'Public page with the same data, for citation.'}, 'title': {'type': 'string', 'description': 'Human-readable name of the document.'}}, 'additionalProperties': False}, 'description': 'Matching documents, most relevant first.'}}, 'additionalProperties': False}
Modificado
kyrodata_get_supply_demand_balance
1 de October de 2026 a las 02:54
Modificado
kyrodata_get_climate_reading
27 de September de 2026 a las 02:53
Añadido
kyrodata_search
17 de September de 2026 a las 12:35
Añadido
kyrodata_run_report
17 de September de 2026 a las 12:35
Añadido
kyrodata_resolve_entity
17 de September de 2026 a las 12:35
Añadido
kyrodata_resolve_comparison_window
17 de September de 2026 a las 12:35
Añadido
kyrodata_list_trade_series
17 de September de 2026 a las 12:35
Añadido
kyrodata_list_trade_partners
17 de September de 2026 a las 12:35
Añadido
kyrodata_get_supply_demand_balance
17 de September de 2026 a las 12:35
Añadido
kyrodata_get_hub_summary
17 de September de 2026 a las 12:35
Añadido
kyrodata_get_heading_overview
17 de September de 2026 a las 12:35
Añadido
kyrodata_get_data_coverage
17 de September de 2026 a las 12:35
Añadido
kyrodata_get_credit_balance
17 de September de 2026 a las 12:35
Añadido
kyrodata_get_climate_reading
17 de September de 2026 a las 12:35
Añadido
kyrodata_fetch
17 de September de 2026 a las 12:35
Añadido
kyrodata_explain_pyramid_level
17 de September de 2026 a las 12:35
Añadido
kyrodata_compare_trade
17 de September de 2026 a las 12:35