Kyrodata — Brazil Trade, Crop & Commodity Data

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

Annotations already mark the tool read-only, idempotent, and non-destructive, and the description adds meaningful behavioral context: the credit class and rate limit (comex, up to 2 tools per 60-second session = 1 credit), the monthly series cap at 24 months, and the result carrying both windows plus % change and season-crossing labels. This goes well beyond the structured annotations.

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 dense but well-organized: purpose first, then mode semantics, filters, result shape, sibling distinction, and credit cost. Each sentence earns its place, and the most decision-relevant contrast with siblings is clearly highlighted.

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 tool's complexity and the presence of an output schema, the description supplies everything an agent needs to select and invoke it correctly: metrics, mode behavior, filtering semantics, return contents, sibling boundaries, and credit implications. No critical operational context is missing.

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 coverage is 100%, so the baseline is 3. The description adds value by explaining how `mode` groups map to window semantics)Skip? It says `codes` and `countryIds` filter both windows alike and combine, with a concrete soybean-to-China examplechers, and notes that omitting them counts every product and partner. That supplements the schema's per-parameter descriptions.

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 opens with a specific verb and resource: 'Compares Brazil's exports or imports between two equal-length windows,' and names the metrics (USD FOB value, kg volume). It explicitly differentiates itself from siblings by stating this returns the FIGURES of a comparison while kyrodata_resolve_comparison_window only names the window and kyrodata_list_trade_series returns raw points without comparing.

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 explains exactly which mode to use for which kind of comparison: year-back windows that hold season constant versus monthly/semestral_sequential that cross a season. It also points to the sibling tools as alternatives and clarifies the division of labor, so an agent knows when to choose this tool over them.

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

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.

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.

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.

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.

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.

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.

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

Annotations already declare the tool read-only, idempotent, and non-destructive guardian, but the description adds valuable context: the id format ('heading:1201' or 'country:160'), the data contents (Brazilian exports/imports in USD FOB and kg), the data source, and the credit cost (1 credit, max 2 per session). It also notes the output is citable with a public URL. These details are not in the annotations and enhance transparency. The only minor gap is not covering the response_format parameter's quota implication in the description, but it's already in the schema.

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 structured into clear sentences with no filler. It front-loads the core action and output, then covers constraints and sibling tools, and ends with credit costing. It's appropriately sized given the tool's complexity and the need to distinguish from many siblings.

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?

For a tool with an output schema and detailed annotations, the description is complete. It covers purpose, id constraints, output content, sibling differentiation, and costing. There is no missing information an agent would need to call it correctly.

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?

With schema description coverage at 100%, the baseline is 3, but the description adds significant meaning beyond schema: it tells the agent that 'id' is not arbitrary text but must match specific shapes from kyrodata_search, and it explains the semantics of 'response_format' (concise vs detailed) and its quota implications. This goes well beyond the schema's brief descriptions.

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's purpose: opening one public foreign-trade document by id and returning it as citable prose. It specifies the verb, resource, and output (title, body text, URL). It explicitly distinguishes itself from siblings by noting it is the only tool that returns a document with a URL, and it names complementary tools (kyrodata_get_heading_overview and kyrodata_search) to avoid confusion.

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 provides explicit usage guidance: use this tool when you need a citable document, use kyrodata_get_heading_overview for structured figures, and use kyrodata_search to find an id. It also clarifies when not to use it and enforces the id constraint (not free text). This is exactly the kind of when/when-not alternative guidance that scores high.

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

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

Beyond the readOnlyHint/idempotent/destructive annotations, the description reveals important behaviors: scope changes only the risk/shock but not national loss tonnage, missing validated models yield a descriptive reading with no verdict, and an unmeasurable season falls back to the previous one with caveats. It also discloses the credit cost cap, which annotations do not provide.

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 core output is front-loaded in the first sentence, followed by scope semantics, edge cases, production clarification, alternatives, and credit class. Each sentence earns its place and there is no filler despite the length needed to explain a nuanced tool.

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?

With an output schema present, return values are already covered. The description fills the remaining gaps: parameter interactions, edge cases, fallback behavior, sibling routing, and cost semantics. A calling agent has everything needed to select and invoke the tool correctly.

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 coverage is 100%, so the baseline is 3. The description goes further by explaining subtle behavior of the scope parameter—moving only risk level and shock while loss stays national—and reinforcing that hub is about production, not price. This adds real meaning beyond the schema descriptions.

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 opens with a specific verb and resource: 'Current climate reading for a commodity', then enumerates the concrete outputs: risk level, production shock in % of harvest, and projected physical loss in tonnes per horizon. It also distinguishes itself from siblings by explicitly naming kyrodata_get_hub_summary and kyrodata_get_supply_demand_balance, so an agent can tell what this tool is not.

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?

It states the core use case—climate-driven production reading—and explicitly gives alternatives for price questions (kyrodata_get_hub_summary) and the balance sheet (kyrodata_get_supply_demand_balance). It also says 'Climate here predicts PRODUCTION', effectively telling the agent when not to use this tool. This is explicit when/when-not guidance.

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

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

Annotations already establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description needs less safety disclosure. It adds real context beyond the annotations: only the authenticated key is ever described, no other key can be selected, the tool reads no market data, and the credit class is free (0 credits). This meaningfully clarifies behavior without contradicting the annotations.

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 a short, front-loaded paragraph: purpose first, then scope, then sibling routing, then credit class. Each sentence has a distinct purpose. It's slightly redundant in saying both 'reads no market data' and 'never about trade ... commodity', but overall it is tightly written and never wanders.

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?

The tool is simple (one optional parameter, output schema present), and the description fully covers the purpose, the input semantics, scope exclusions, the likely mis-generation of response_format, and the correct sibling alternative. An agent neither false nor has to inspect more than this definition to call the tool correctly.

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 coverage is 100%, so the baseline is 3. The description adds that response_format is the only input, that it changes verbosity and not scope, and that there is no argument for selecting another key—clarifying the parameter's role beyond the schema's own wording and preventing a likely agent assumption.

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 opens by naming the exact resource ('credit balance and the limits of the API key making the request') and lists concrete fields it reports (credits left, reset time, ceilings, reachable tools). It also explicitly contrasts with the sibling kyrodata_get_data_coverage, so an agent can distinguish the tool without opening schemas.

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?

It gives an explicit when-to-use (account/credit-limit questions) and when-not-to-use (never for trade, climate, or commodity data), and points directly to the right sibling, kyrodata_get_data_coverage, for data-depth questions. It also warns that response_format cannot change the scope, preventing a common misuse.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds meaningful context beyond those hints: it explains the response is a calendar, never figures, that the detailed response_format counts against the export quota, and that the tool is credit class free. No contradiction with annotations exists.

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 compact but information-dense; every sentence earns its place. It front-loads the return value, then states the input scope, addresses likely user questions, and closes with routing to sibling tools and credit cost. There is no filler or redundant restating of the schema.

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?

For a single-parameter read-only getter with a full input schema and an output schema, the description covers everything an agent needs: what it returns, what it doesn't return, how the parameter affects behavior, related sibling tools, and cost implications. None of the critical context is missing.

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 coverage is 100% with a well-described enum, so the baseline is 3. The description adds value by explicitly declaring that response_format is the only input and that the answer covers the whole dataset with no narrowing by window or product. It reinforces the parameter's role without relying solely on the schema.

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 opens with a precise verb and resource, stating it 'Returns the calendar of the trade data' and enumerates the concrete fields returned. It also explicitly contrasts itself with siblings: 'the CALENDAR, never figures' while routing figure-reading to kyrodata_get_heading_overview. This makes the tool unmistakably distinct from its sibling tools.

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?

It clearly states that the answer covers the whole dataset, so there is no window or product to narrow it with, and that it answers specific questions like 'até quando tem dado?' and 'qual o último mês?'. It also gives explicit alternatives: use kyrodata_resolve_comparison_window for building a like-for-like window and kyrodata_get_heading_overview for reading figures inside it.

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

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.

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.

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.

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.

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.

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.

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

Annotations already mark the tool read-only and idempotent, and the description adds valuable behavior beyond that: omitted horizon centers on the model's leading horizon, all four horizons always come back, arrowless horizons name the reason, empty horizons mean no signal, and it never returns the price level. It also discloses the credit class and session cap, which are non-obvious runtime behaviors.

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 dense but every sentence earns its place: the headline capability is front-loaded, parameter behavior is explained, alternatives are named, and the credit quirk is placed at the end. It is long because the tool has genuine nuances, not because of filler.

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 rich schema with 100% parameter coverage, a present output schema, and strong annotations, the description covers everything needed to select and invoke the tool correctly. It explains the return contents, horizon semantics, no-price-level limitation, related tools, and credit cost. No meaningful gap remains.

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 coverage is 100%, so the baseline is 3. The description goes further by explaining the horizon parameter's re-centering behavior and that all four horizons return regardless, and it clarifies the response_format distinction including the export-quota implication for 'detailed'. This adds real meaning beyond the schema without needing to repeat the enum values.

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 opens with a specific verb and resource: it reads the Kyrodata pyramid verdict for a commodity hub, and then enumerates exactly what comes back (direction, expected move %, band, driving levels, accuracy). It also differentiates itself from siblings by naming kyrodata_explain_pyramid_level and kyrodata_get_climate_reading and stating what each is for.

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?

It explicitly says 'This is the tool for where a hub's price is heading' and points to alternatives: the arithmetic behind the verdict is kyrodata_explain_pyramid_level, and the physical harvest is kyrodata_get_climate_reading. This gives an agent clear routing decisions without needing to inspect sibling schemas.

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

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

The description states the data is published, identifies it as a balance sheet, clarifies the current season is a projection that 'still moves,' names the data source, and notes credit cost and session cap. Annotations declare read-only and idempotent, and the description adds context about changing projections without contradicting the hints.

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 dense but every sentence serves a purpose: data type, units, temporal behavior, source, credit cost, and sibling differentiators. It front-loads the core purpose before adding constraints and alternatives. No filler or repetition.

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?

Covers input restrictions (published hubs only), parameter semantics (closedOnly meaning), data domain (physical, seasonal), source attribution, output nuance (estimate vs closed), and how siblings differ. Combined with 100% schema coverage and output schema, the agent has everything to select and invoke the tool.

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 coverage is 100%, and the description reinforces important parameter semantics: hub is restricted to published balance sheets, and closedOnly excludes the projection. It also clarifies how response_format maps to result size. The description does not restate parameter names but provides valuable context beyond the schema.

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 this returns a published supply and demand balance sheet in physical tonnes, for one agricultural hub, by season. It enumerates the exact contents (production, imports, exports, etc.) and distinguishes itself from the related price and weather tools.

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 explicitly says when to use this tool versus get_hub_summary (price verdict) and get_climate_reading (weather risk). It also clarifies which hubs are valid, the meaning of `closedOnly`, and the special projection status of the current season.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real operational context beyond them: the credit class and rate limit (up to 2 comex tools per 60s = 1 credit), the quota cost of response_format=detailed, and the non-obvious withGrowth caveat that it ignores `from`.

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?

Dense but front-loaded: the ranking purpose and its output shape come first, then routing alternatives, then the credit note. Every clause carries information, though the single packed paragraph is heavier than strictly necessary.

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?

For a 7-parameter, one-required ranking tool with an output schema, the description covers purpose, window defaults, filtering semantics, growth behavior, sibling routing, and quota cost. Nothing an agent needs to call it correctly is missing.

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 coverage is 100%, so the baseline is 3; the description goes beyond the schema by tying `codes` to the ranking intent ('who buys THIS product'), restating the YYYYMM default window, and warning that withGrowth is the only channel for growth. It adds intent-level meaning rather than raw syntax.

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?

States a specific verb ('Ranks') and resource ('Brazil's partner countries for exports or imports') plus the row granularity (one row per country) and returned measures. It explicitly contrasts itself with kyrodata_compare_trade and kyrodata_list_trade_series, so an agent can distinguish it without opening a schema.

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?

Explicitly states when to use it (ranking partners inside one window, 'who buys THIS product') and when not to (a question about one known country belongs on kyrodata_compare_trade or kyrodata_list_trade_series; comparing two windows is kyrodata_compare_trade). Alternatives and the selecting condition are named.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond that: the 200-month cap is refused rather than silently truncated, missing months are ABSENT rather than zero, and the credit class (comex, up to 2 tools per 60-second session = 1 credit) is disclosed. It doesn't detail pagination or exact response shape, but the output schema exists and the description covers the non-obvious behaviors that would surprise an agent.

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 dense but every sentence earns its place: the return shape, the date semantics, the cap behavior, the absence-vs-zero semantics, the filter combination, the sibling routing, and the credit cost. It is front-loaded with the core purpose and scoping constraints before the sibling differentiation and credit note. No filler or repetition of schema content.

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?

For a read-only, idempotent list tool with a 100%-covered schema and an output schema present, the description is complete. It covers the default window, the cap, the missing-month semantics, how filters combine, how to resolve entity references, which sibling handles related questions, and the credit cost. An agent has everything needed to select and invoke the tool correctly without opening the schema.

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 the baseline is 3. The description adds meaning beyond the schema: it explains that `from`/`to` are YYYYMM and default to the last 24 published months, that `codes` and `countryIds` can combine to draw a single product-and-partner line, and that the span cap is enforced by refusal. It also cross-references kyrodata_resolve_entity for codes and countryIds, which the schema mentions but the description reinforces. This is meaningful added value over the schema, though not exhaustive.

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 opens with a specific verb and resource: 'Returns Brazil's monthly export or import series as rows' and immediately specifies the row structure (month, value USD FOB, volume kg, implied price per kg). It distinguishes itself from siblings by naming kyrodata_compare_trade and kyrodata_list_trade_partners as the tools for different question shapes, so an agent can tell them apart without opening schemas.

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 explicitly states when to use this tool ('This hands over the POINTS') and when not to: '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.' It also gives concrete behavioral constraints: default window, 200-month cap, refusal rather than truncation, and absence-vs-zero semantics. This is explicit when/when-not guidance with named alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds that it returns ONLY metadata (from, to, label, months, season-crossing flag) and no figures, and that it is free (0 credits). It also explains the behavioral consequence of crossing a season for certain modes. This is more than the annotations alone convey, though it doesn't detail the exact output structure (but an output schema exists).

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 moderately long but every sentence carries weight: purpose, mode family explanation, usage note, reason for existence, alternative, and credit cost. It is front-loaded with the core purpose and flows logically. Slightly dense, but not wasteful.

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 9 enum modes and the need to pick correctly, the description fully covers the mode semantics, what is returned (metadata fields), the cost, and the alternative for value/volume. An agent can confidently select and invoke this tool without further ambiguity.

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 coverage is 100%, so both parameters are documented. The description adds significant meaning to the 'mode' parameter by grouping the nine enums into two families (year-over-year vs sequential) and explaining the season-crossing implication, plus the special 'ytd' behavior and the 'use ytd when no period is named' rule. This goes well beyond the schema's per-value descriptions.

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?

States a specific verb ('Resolves') and resource ('equal-length comparison window') anchored on the last fully published month, and explicitly distinguishes itself from kyrodata_compare_trade by noting it exists only to NAME a window in prose. This is unambiguous and clearly separate from siblings.

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?

Provides explicit when-to-use guidance: it names the alternative (kyrodata_compare_trade) that handles value/volume in one call, and instructs to use 'ytd' when no period is named. It also explains the mode split into two families, so an agent knows exactly which mode fits the question.

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

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 safe, non-mutating nature is covered. The description adds meaningful behavioral context beyond that: the output is an identifier to pass to another tool, carries no document and no URL, and returns up to 10 matches per kind with ambiguous terms yielding candidates rather than a single guess. It also states the credit cost. No contradictions with annotations. It could go further with details on pagination or rate limits, but for a resolver tool this is sufficient.

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 a single paragraph of about 80 words, densely packed with useful information. It front-loads the core purpose, provides concrete examples and alternate-tool guidance, and ends with the credit cost. Every sentence contributes value; there is no filler, repetition, or unnecessary elaboration. The structure leads with the main action and then systematically covers output, ambiguity handling, and contrast.

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 that an output schema exists (so return format is already structured), the description does not need to detail the return shape. It covers everything an agent needs to call correctly: what identifiers look like, how ambiguity is handled, which sibling to use instead, and the cost. The covered scope is complete for the tool's complexity; no critical information is missing.

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?

The input schema has 100% coverage: all three parameters (q, kinds, response_format) are documented with types and constraints. The description adds semantic nuance beyond the schema, notably that 'query takes a name already known rather than a topic to explore,' and clarifies the kinds parameter by listing the entity types and saying to omit for all. The response_format parameter is described in the schema, but the description reinforces the distinction between concise and detailed with a note about export quota, which is extra context. Overall, the description compensates well despite schema coverage being high.

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 leads with a precise verb–resource pair: 'Resolves a free-text name into platform identifiers for FILTERING other tools,' and enumerates the exact entity kinds and their output forms (commodity hubs with slug plus SH4, HS headings SH4, NCM 8-digit, country id). It also gives concrete examples ('soja' → hub and SH4 1201; 'China' → country id 160), making the purpose unmistakable. This clearly differentiates it from sibling kyrodata_search, which is about finding documents, not identifiers.

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 explicitly states when to use this tool: for resolving a name already known into an ID to pass to other tools, and explicitly contrasts it with kyrodata_search for finding things in the public catalog and getting citable documents. It also explains behavior for ambiguous terms, telling the caller they get candidates to pick from, which is a clear usage guideline. The credit class mention ('free (0 credits)') further guides cost-aware routing.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses concrete behavioral traits: the 50-row cap, the projection behavior for locked paid-plan columns (headers returned, values withheld), the export-quota accounting, and the credit-class rate limit. These are material operational details an agent needs and are not present in the annotations or schema.

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 dense and front-loaded, with the core action in the first sentence and behavior details following logically. It is longer than average because it covers many nuances (locked columns, quota, credit, alternatives), and nearly every sentence earns its place. The phrase 'This serves a report that already exists as a product' is slightly redundant with the opening, but it does set up the contrast with alternatives.

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?

For a tool with 5 parameters, a 16-value enum, nested objects, quotas, and credit accounting, the description covers all the essential operational context: how reportId is self-contained, how params and columnIds interact, default-column behavior, locked-column handling, export quota, and credit class. The output schema exists, so return-value details are appropriately left to the schema.

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?

Although schema description coverage is 100%, the description adds meaningful semantics: it explains why no lookup call is needed (the reportId enum carries the whole catalogue), how params relates to the chosen report's declared parameters, and exactly how columnIds behaves when omitted or provided. This goes well beyond the baseline of restating schema text.

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 opens with a specific verb and resource: 'Runs one of the product's pre-built catalogue reports by id and returns its rows'. It clearly identifies the tool's scope (pre-built reports) and immediately distinguishes it from ad-hoc tools like kyrodata_compare_trade and kyrodata_list_trade_series. The purpose is unmistakable even without reading the schema.

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 explicitly states when this tool is appropriate ('serves a report that already exists as a product') and names precise alternatives for other cases: 'An ad-hoc question about trade is kyrodata_compare_trade or kyrodata_list_trade_series, and a citable public document is kyrodata_fetch.' No inference is required to decide between this and its siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds meaningful context beyond that: the tool costs 0 credits, returns documents with URLs, and clarifies the semantic quirk that free text and codes converge on the same result. 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.

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

The description is denser than the calibration examples but every sentence earns its place: purpose, return value, query semantics with examples, the discovery framing, the sibling distinction, and the credit cost. It is front-loaded with purpose and contains no filler, though it is slightly long.

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?

For a 2-parameter tool with an output schema and full annotations, the description is complete. The output schema covers return structure, annotations cover safety, and the description covers purpose, alternatives, query semantics, examples, and credit cost. Nothing an agent needs to call it correctly is missing.

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 coverage is 100%, so the baseline is 3. The description adds real value by clarifying that `query` accepts either Portuguese free text or a code and that both reach the same place, with concrete examples ('soja' and '1201' both land on soybean, 'China' on partner country). This goes beyond the schema's terse 'plain words' description.

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 uses a specific verb ('Searches') and resource ('public Brazilian foreign-trade catalogue') and states exactly what it returns: document ids for kyrodata_fetch covering HS headings and partner countries, each with a public URL. It actively distinguishes itself from the sibling kyrodata_resolve_entity by naming it, so an agent can tell them apart without opening schemas.

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 explicitly frames this as DISCOVERY ('when the caller has words rather than an id') and names the alternative tool for the opposite case ('Turning a name already known into an id for filtering another tool is kyrodata_resolve_entity'). This is an explicit when/when-not with the alternative named.

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