Kyrodata — Brazil Trade, Crop & Commodity Data

Explain one level of the forecast pyramid

kyrodata_explain_pyramid_level

Read-onlyIdempotent

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).

Input Schema

TableJSON Schema

Name	Required	Description
`hub`	Yes	Which commodity hub to read.
`horizon`	Yes	How far ahead the forecast looks: 1, 3, 6 or 12 months from the last published month.
`levelKey`	No	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`	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.

Changed4 schema fields changedSep 7, 2026

addedInput schema / properties / horizon / description

Added value: +"How far ahead the forecast looks: 1, 3, 6 or 12 months from the last published month."

addedInput schema / properties / hub / description
```
Added value: +"Which commodity hub to read."
```

addedInput schema / properties / levelKey / description

Added value: +"One level of the pyramid. Given, the answer follows that level across all four horizons instead of showing the seven side by side."

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."

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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to repeat safety. It adds valuable behavioral context beyond annotations: the credit class ('level' tools cost 2 credits per 60-second session, capped at 3) and that the 'detailed' response_format counts against the export quota. This extra context is useful for an agent deciding whether to invoke the tool. No contradiction with annotations.

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 description is a single dense paragraph, but every sentence serves a purpose: it defines the output, explains the two modes, names the parent tool and the alternative for different questions, and states the credit cost. It is front-loaded with the core purpose and uses efficient phrasing. Slightly long but justified given the tool's complexity.

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 read-only, idempotent tool with an output schema and full parameter schema coverage, the description is remarkably complete. It covers the two usage modes, the relationship to sibling tools, credit costs, and the export quota impact. Nothing an agent needs to decide whether to call this tool and how to format the request 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 meaning beyond the schema: it explains that 'horizon' fixes the month and shows the seven levels, while 'levelKey' flips the cut to follow one level across all four horizons. It also clarifies that 'response_format' with 'detailed' adds row-level series and counts against the export quota. This enriches parameter understanding without redundancy.

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 clearly states the tool's purpose: 'Explains the pyramid's arithmetic for one commodity and horizon,' listing the seven levels side by side and reasons for excluded levels. It explicitly distinguishes itself as the drill-down of kyrodata_get_hub_summary and contrasts with kyrodata_get_climate_reading for physical harvest questions. The verb 'Explains' plus the specific resource (pyramid levels) makes the purpose unambiguous and differentiated from siblings.

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?

Usage guidance is explicit: it is the drill-down for a verdict already given by kyrodata_get_hub_summary, and it specifies that questions about physical harvest belong to kyrodata_get_climate_reading. It also explains the two invocation modes (horizon vs levelKey) and the credit cost implications, giving the agent clear conditions for when and when not to use this tool.

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?