Magpie — USDA Ag Markets: Grain, Fertilizer, WASDE & Export Sales

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 context beyond them: no API key required, the output is a computed aggregate across both stored datasets over all stored periods rather than a USDA-published figure, and totals are rounded to whole tons. These are exactly the provenance and precision caveats an agent needs before quoting a number.

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?

Three sentences with a clean front-to-back ordering: what it computes, when to use it versus alternatives, then provenance and rounding caveats. No sentence is redundant and the sign convention is stated inline where it is 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?

There is no output schema, so the description carries the return-value burden itself, and it does: it enumerates the three returned figures, defines the sign of the gap, and specifies the unit. Combined with the stated derivation and rounding, an agent has everything needed to call and interpret the result 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 description coverage is 100%, with the partner format (2-letter ISO/GENC) and commodity enum already documented in the schema, so the baseline is 3. The description clarifies the meaning of the "gap" sign convention and the metric-ton unit, but that is output semantics rather than added meaning for the two input parameters.

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 comparison operation between two named datasets (ESR contracted export sales vs GATS actual shipments) for one commodity, and spells out exactly what the result contains: total contracted, total shipped, and the gap. It explicitly distinguishes itself from get_export_sales and get_trade_flows, so an agent can route correctly without opening the schema.

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

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

Gives an explicit use case ("gauge the unshipped export backlog") and names the alternatives with the condition that selects them ("use get_export_sales or get_trade_flows instead for the underlying weekly or monthly detail"). Nothing about when to pick this tool is left to inference.

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, so the description doesn't need to re-state safety. It adds genuinely non-obvious context beyond annotations: no API key is needed, and the stored copy refreshes weekly so the returned `period` is the freshest stored week rather than the current one — a caveat an agent would otherwise get wrong. It stops short of describing the response shape or what happens when a commodity/geography combination has no stored data.

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 purpose and the alternatives are front-loaded, and the caveat about the stale `period` is placed last where it belongs. It is a dense single paragraph; the rating-bucket enumeration is slightly redundant with the purpose statement and could be tightened, but no sentence is wasted.

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 two-parameter read-only lookup with full schema coverage and existing annotations, the description covers everything an agent needs: what it returns, when to prefer siblings, the no-auth detail, and the freshness caveat. No output schema exists, yet the enumerated rating fields effectively communicate the return payload.

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 would be 3. The description earns an extra point by clarifying the geography domain beyond the schema: state coverage is limited to the major corn-belt states, which the schema's 'IA, IL, etc.' only implies. It does not add enum constraints or format detail for commodity beyond restating the three options.

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 and resource: most recent weekly NASS crop condition ratings, enumerating the exact rating buckets and the combined good+excellent percentage returned. It explicitly contrasts itself against get_crop_condition_history and get_crop_progress, so an agent can select it without opening either 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?

Gives explicit when-to-use ('current crop health') and names two alternatives with the conditions that select them ('week-by-week change across the season', 'growth-stage pace'). There is no inference required to route between these three tools.

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 readOnly/idempotent/non-destructive, but the description adds value beyond them: no API key required, a stored copy that refreshes weekly, and a coverage boundary (current season, national plus major corn-belt states). It stops short of describing failure modes or what happens when `weeks` exceeds available history.

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?

Front-loaded with the resource and metric set, then routing, then behavior — a logical order with no filler. The long em-dash-laden opening sentence is dense but every clause carries information.

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?

There is no output schema, yet the description enumerates the returned fields (excellent/good/fair/poor/very poor shares plus good+excellent) and the ordering and window limits, so an agent knows what it gets back. Nothing needed to invoke or interpret the call 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 baseline is 3; the description nonetheless adds meaning the schema lacks — result ordering ('oldest first') and the geographic constraint implied by the state code parameter. It does not clarify edge cases such as requesting 52 weeks early in the season.

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 and resource ('week-by-week NASS crop condition ratings') with the exact metric set returned and the source (USDA NASS QuickStats). It explicitly distinguishes itself from the sibling get_crop_condition, so an agent can pick between them without opening either 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?

Gives an affirmative use case ('track crop health trends or compare weeks within the season') and a negative one with the named alternative ('use get_crop_condition instead when only the latest week matters'). This is explicit when/when-not/alternative 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?

Annotations already declare readOnly/idempotent/non-destructive, and the description still adds real context beyond them: no API key required, weekly publication cadence in season, the stored copy refreshing weekly, and the meaning of the returned `period` value as the freshest stored week. The freshness caveat is exactly the kind of operational detail annotations cannot convey.

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?

Front-loaded with the core capability before routing and freshness caveats, and no sentence is pure filler. However, the em-dash parenthetical chain makes it denser than necessary for a two-parameter 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 no output schema, the description steps in to describe the return shape (share of crop at each growth stage, stages varying by commodity) and the meaning of the `period` field. Combined with the freshness and no-key notes, an agent has everything needed to call and interpret it.

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 both `commodity` and `geography` documented including defaults and the state-code form, so the schema carries parameter meaning. The description restates the three commodities but adds no format or scope detail beyond the schema's state-coverage note. Baseline 3 applies when the schema does the heavy lifting.

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 (most recent weekly NASS crop progress) and enumerates the actual payload (share of crop at each growth stage), noting stages vary by commodity. It also explicitly names what it is not (get_crop_progress_history, get_crop_condition), so an agent can separate it from siblings 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?

Gives an explicit selection rule: 'Use for current season pace; use get_crop_progress_history instead for week-by-week pace across the season, and get_crop_condition for health ratings.' That is when-to-use plus named alternatives and the condition that selects each.

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 readOnly/idempotent/non-destructive, so safety is covered; the description adds real behavioral context beyond that — 'no API key,' default and max week counts, oldest-first ordering, stage variability by commodity, and weekly refresh cadence. It stops short of describing error or empty-result behavior, so not a 5.

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?

Two sentences plus a coverage note, front-loaded with the core purpose, with no filler. Slightly dense with em-dash clauses but every phrase (stages list, default/max, coverage scope) carries decision-relevant information.

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 no output schema, the description compensates by explaining return shape (oldest-first weeks, stage variability) and coverage limits. Minor gaps remain around what happens for out-of-season or unsupported state requests, but it is sufficient 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 baseline is 3, but the description adds meaning the schema lacks: the ordering of returned weeks (oldest first), which commodities/states are actually supported for coverage, and that the stage set varies. It reinforces `weeks` semantics rather than merely repeating them.

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 names a concrete verb and resource ('Week-by-week NASS crop progress'), enumerates what each data point contains (share at each growth stage), and states the source. It is clearly distinguishable from sibling get_crop_progress by the explicit weekly-history framing.

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 a positive use case ('track season pace or compare against earlier weeks') and an explicit exclusion routing to the alternative: 'use get_crop_progress instead when only the latest week matters.' That is exactly the when/when-not/alternatives structure the rubric rewards.

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?

Adds genuine context beyond the annotations: return ordering ('most recent first'), the fact that every stored year is returned, the weekly refresh cadence of the stored copy, and that no API key is needed. 'Read-only lookup' partially restates readOnlyHint, which is the only reason this falls short of a 5.

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?

Five sentences with no filler, front-loaded with what the tool returns, followed by the sibling routing, then the return shape and input behavior. Every sentence adds information an agent would otherwise have to guess.

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?

There is no output schema, and the description compensates by stating exactly what comes back (all stored periods for the requested statistic, most recent first) and how fresh it is. Combined with the clarified input defaults and case-insensitivity, an agent has everything needed 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?

Schema coverage is 100% and documents defaults and allowed values, so the baseline is 3. The description adds that commodity, statistic, and geography are case-insensitive — useful behavior not captured in the schema — though the default values it restates are already in 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?

States a specific verb-free but precise resource: annual NASS survey statistics (yield, production, planted/harvested area) for a commodity at national or state level, sourced from USDA NASS QuickStats. It explicitly separates itself from market prices and from the in-season sibling tools, so an agent can identify it without opening the schema.

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

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

Names both the positive case ('Use for production fundamentals') and the alternatives with their selection condition ('use get_crop_condition or get_crop_progress instead for in-season weekly crop status'). Nothing about when to prefer it is left to inference.

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 readOnly/idempotent/closed-world, but the description adds real context: no API key required, rows are returned oldest first up to `periods`, and butter intentionally returns a withheld notice because USDA publishes only differentials. Minor inconsistency: it says cheese defaults to geography 'Oceania' while the schema says cheese uses US, which could confuse 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?

Front-loaded with purpose and sibling routing, then defaults and the butter edge case. Every sentence carries information, though the cheese/geography clause is confusing enough that it doesn't fully earn its place.

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 no output schema, the description does the work of describing the returned rows (up to `periods`, oldest first) and the withheld-case behavior, plus defaults for all three params. Row fields aren't named, but the essentials for correct invocation are present.

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 parameter fields are already documented; the description still adds value by explaining ordering semantics (oldest first) for `periods` and by flagging the butter product as a special case that returns no base price. The conflicting cheese/geography claim slightly undercuts it.

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 (weekly price history for one dairy product) and anchors the data source to the USDA MARS reports behind get_dairy_price. The distinction from the sibling price tool is made explicit, so an agent can choose without opening the schema.

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

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

Gives explicit when-to-use (trends across report weeks) and names the alternative with its condition (get_dairy_price when only the latest quote matters). This is exactly the routing guidance needed in a family of sibling tools.

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 cover the safety profile (readOnly, idempotent, closed-world), and the description adds real operational context beyond them: no API key required, reports are stored/read-only, geography has an implicit default, and butter is deliberately withheld with the reason (USDA publishes only differentials). The butter caveat is exactly the kind of non-obvious behavior an agent cannot infer from 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?

Front-loaded with what the tool returns, then routing, then caveats — a sensible order. Four dense sentences with little waste, though "no API key" and the repeated butter note (echoed in the schema) could be trimmed.

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 no output schema, the description does the heavy lifting: it signals that butter returns a withheld notice rather than a number, and that other products return a current quote. It omits units/currency for the returned price, which matters for a commodity-price tool and is the main remaining gap.

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, but the description adds genuine semantics the schema lacks — that cheese maps to Oceania cheddar and therefore defaults to geography 'Oceania'. That nuance is decision-relevant. It stops short of 5 because it does not clarify the tension with the schema's claim that "cheese uses US" / default US-Central, nor state units or currency.

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 and resource ("latest price for one dairy product") plus the authoritative source ("USDA MARS weekly dairy reports"). It also names the sibling get_dairy_history as the time-extended variant, so the agent can distinguish the two without opening either 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?

Gives an explicit routing rule: "Use for a current quote; use get_dairy_history instead for the weekly trend." When-to-use, when-not, and the alternative are all spelled out.

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 (which already declare read-only, idempotent, closed-world), the description discloses data semantics that matter: sales are contracted by exporters, not necessarily shipped; the source updates weekly on Thursdays; only the most recent stored week is returned; no API key is needed. It stops short of describing behavior for edge cases (e.g., a commodity with no recent report), which keeps it below a 5.

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?

Each of the four sentences does distinct work: purpose, disambiguation, data semantics, and parameter default. Purpose is front-loaded and the alternative tools are named immediately after.

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 read tool with no output schema, the description covers what the rows contain (weekly exports, outstanding sales, net sales, total commitments per destination, with units), the refresh cadence, and the default for the optional parameter. Nothing an agent needs in order 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 parameter meanings are already fully documented. The description restates the 'omit country for all destinations' behavior, adding marginal value but no format or syntax detail 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?

States a specific verb (return latest week), resource (USDA/FAS ESR export sales), and scope (one commodity) in the first clause. It also explicitly names two sibling tools it is not, so an agent can route between them 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?

Gives an explicit when-to-use (current foreign demand), plus named alternatives with the conditions that select them: get_export_sales_history for the weekly trend and get_trade_flows for shipped volumes. That is the strongest form of routing 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 declare read-only, idempotent, non-destructive, closed-world behavior, but the description adds useful context: stored FAS ESR reports, no API key, and return ordering from oldest to newest. It also explains default and maximum week counts. It does not cover error behavior, but that is a minor gap given 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 front-loaded with the core purpose and then moves efficiently through alternatives, read-only behavior, and return shape. Every sentence contributes useful routing or behavioral information, with no wasted framing.

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 no output schema, the description still explains the return shape: weekly time series, scoped to commodity and optional country, with a configurable number of most recent weeks and oldest-first ordering. It also covers source, safety, and sibling alternatives, leaving no major decision gap for calling 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%, so the baseline is 3, but the description adds meaning beyond the schema: without a country, each week aggregates all destinations as stored, and results are the most recent weeks returned oldest first. This clarifies the aggregation semantics that the country parameter controls.

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 states a specific verb and resource: weekly export sales time series for one commodity and optionally one destination country. It explicitly distinguishes the tool from get_export_sales and compare_contracts_vs_shipments, so an agent can route correctly 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 explicit when-to-use guidance: demand trends across weeks. It also names alternatives and their selecting conditions: use get_export_sales when only the latest week matters, and compare_contracts_vs_shipments to compare contracted sales with actual shipments.

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, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely new context: provenance (twice-monthly USDA MARS production cost reports), 'no API key', and result ordering ('oldest first'), which the annotations do not convey. Rate limits or per-report field detail are absent, keeping it short of a 5.

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?

Three sentences ordered purpose → usage/alternative → behavior, each carrying distinct information. No filler, and the purpose is front-loaded.

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 no output schema, the description still tells the agent what comes back (a sequence of report periods, oldest first, bounded by `periods`) and where the data originates. It stops short of describing the per-report fields, which is the main remaining unknown for a history 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%, so the baseline is 3; the description nonetheless adds meaning the schema lacks, notably the 'oldest first' ordering of the returned periods and the 'roughly two years' framing of max 52. It repeats default/max from the schema rather than extending it further.

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 and resource ('Price history for one fertilizer product across report periods') and immediately identifies the data source. It explicitly distinguishes itself from the sibling get_fertilizer_price, so an agent can route correctly without opening either 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?

Gives both directions explicitly: 'Use for input-cost trends' and 'use get_fertilizer_price instead when only the latest quote matters.' The alternative and the condition that selects it are named, leaving nothing to inference.

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 still adds meaningful context beyond them: no API key required, reports publish twice monthly and are fetched on the 1st/15th, so data can be roughly two weeks stale. The staleness disclosure is exactly the kind of trait an agent needs and cannot infer from 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?

Purpose and source are front-loaded, and every sentence carries distinct information (alternatives, auth, refresh cadence, return shape). It is somewhat dense with parenthetical detail, but no sentence is 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?

No output schema exists, but the description compensates by naming the return components (price, unit typically USD per ton, change vs prior report) alongside freshness expectations. An agent has everything needed to call and interpret this single-parameter lookup.

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 single enumerated product slug, so the schema fully documents the parameter. The description adds no per-parameter syntax or format guidance beyond the schema, which is the expected baseline here.

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 ('Latest price for one fertilizer product') with source (USDA MARS production cost reports) and scope (Illinois-led regional coverage). It explicitly distinguishes itself from get_fertilizer_history (time-series extension) and get_spreads (cost-relation view), so an agent can route 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?

Gives a direct when-to-use ('current input-cost quote') and names the alternative for a different need ('use get_spreads instead to relate fertilizer cost to corn or cattle prices'). Both the selection condition and the exclusion are explicit.

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 (read-only, idempotent, non-destructive, closed-world), yet the description still adds real context: the upstream source (USDA MARS daily reports), that no API key is needed, oldest-first ordering, and the row-vs-calendar-day caveat. It stops short of describing row contents or behavior at empty results, which keeps it below 5.

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?

Four tight sentences, front-loaded with purpose then the sibling alternative then the return semantics. No sentence is filler; the periods caveat is placed where the agent will read it before calling.

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 no output schema, the description carries the return burden and does it adequately: up to periods rows, most recent first collected but returned oldest first, default 30 cap 365. Missing only the shape of an individual row (price field, date field), a minor gap for a history lookup.

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 baseline 3 applies, but the description adds meaning beyond the schema: periods counts report rows rather than calendar days, results are ordered oldest first, and scope is limited to one commodity and one state. This is a genuine clarification of an easily-misread parameter.

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 and resource: daily cash price history for one grain commodity in one state, sourced from the same USDA MARS reports as get_grain_price. An agent can distinguish it from the latest-quote sibling without opening either 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?

Explicit routing: 'Use for trends or day-over-day comparison; use get_grain_price instead when only the latest quote matters.' Both the when and the alternative are named with the selecting condition.

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, so the safety profile is covered. The description adds valuable context beyond that: no API key needed, the no-data error behavior instead of returning a stale price, and what the return includes (unit and market location). It stops short of describing report freshness windows or rate behavior, but for a stored-report lookup this is strong.

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?

Front-loads purpose and sibling differentiation, then layers behavioral detail. Five sentences are dense but each earns its place except for mild redundancy around the current-quote vs history distinction, which is stated twice.

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?

Even without an output schema, the description covers the return shape (most recent price, unit, market location) and the failure mode (no-data error rather than stale price). Combined with annotations and full schema coverage, an agent has everything needed 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?

Schema description coverage is 100%, with both parameters documented and an enum for product, so the schema carries the parameter burden. The description reinforces that the pair is commodity/state and that geography must come from a tracked MARS report, but adds no syntax or format detail beyond the schema. Baseline 3 is appropriate.

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 and resource (latest cash grain price for one commodity in one state) and names the data source (USDA MARS daily market reports). It explicitly distinguishes itself from get_grain_history by describing the sibling as the same series extended over time.

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?

Gives explicit when-to-use guidance ('Use for a current quote') and names the alternative with its selecting condition ('use get_grain_history instead for trends across days'). The current-quote vs trend distinction is exactly what an agent needs to choose between the two.

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 still adds real context: no API key required, the underlying USDA MARS report types, and the ordering guarantee ('oldest first'). That is genuine added value beyond 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?

Four sentences, all front-loaded and zero waste: purpose, sibling routing, access model, return semantics. Each sentence carries a distinct piece of information the agent needs.

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 no output schema, the description carries the return-value burden and does explain row count, default/max, and ordering. It leaves the per-row fields (e.g. what price columns a report row contains) unstated, a small but real gap for an agent parsing the response.

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 clarifying that `periods` counts report rows rather than calendar days and by specifying the sort order, which materially changes how an agent should interpret results.

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 resource (price history for one livestock category in one region) and names its data source, and explicitly distinguishes itself from get_livestock_price by framing itself as the trends tool. An agent can tell the two apart without opening either 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?

Gives an explicit when-to-use ('Use for trends') and a named alternative with the exact condition that selects it ('use get_livestock_price instead when only the latest quote matters'). Nothing is left to inference.

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?

Goes well beyond the annotations by disclosing that no API key is needed, that direct-trade reports may skip weeks without trades, and that a missing category/region pair returns a no-data error rather than a stale price. These are meaningful behavioral details for correct interpretation and error handling.

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 purpose and sibling routing are front-loaded, and the paragraph is information-dense rather than padded. It is slightly long and repeats read-only safety context already covered by annotations, but every sentence contributes operational value.

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?

Because no output schema exists, the description steps in to explain the return value (most recent report's price and unit, typically USD per cwt), error behavior for missing data, and reporting gaps. Together with the annotations, an agent has everything needed to call and interpret 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 description coverage is 100%, so both parameters are already documented, including the product enum and geography default. The description adds only light framing ('one livestock category in one region') without expanding on slug choices or region code formats beyond what the schema provides.

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 and resource ('Latest price for one livestock category in one region'), names the data source (USDA MARS direct-trade and auction reports), and explicitly distinguishes itself from get_livestock_history as the trend-oriented sibling. An agent can identify the exact operation without opening the schema.

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

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

Gives explicit routing guidance: 'Use for a current quote; use get_livestock_history instead for trends.' This directly states when to select this tool and when to select the alternative, leaving no ambiguity.

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 read-only/idempotent safety, but the description goes well beyond them: no API key required, data provenance (Magpie calculations over stored USDA MARS prices, not official USDA figures), and the omission rule when either side lacks a stored price. The provenance caveat is material for an agent reporting these numbers as facts.

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?

Definition is front-loaded in the first sentence, followed by routing, then provenance and edge-case behavior. Dense but every clause carries information; nothing is 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?

With no output schema, the description must describe return content and does so by enumerating each spread and its units. Combined with the omission rule and provenance note, an agent can call and correctly interpret this tool without further context.

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 single parameter already documents the default IL and its dual application. The description restates that geography applies to both sides of each spread, which reinforces interpretation but adds little the schema does not already say, so the baseline 3 fits.

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?

Names a specific derived resource and enumerates its three outputs (corn-to-nitrogen cost per product and per pound of N, soybean-to-corn ratio, feeder-to-fed spread), so an agent knows exactly what comes back. It also explicitly separates itself from the raw quote tools, which is the main confusion risk among these 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?

States the use case ('planting and feeding economics') and names the exact alternative tools (get_grain_price, get_fertilizer_price, get_livestock_price) with the condition that selects them (you want the quotes behind a spread). When-to-use and when-not-to-use are both explicit.

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 read-only/idempotent/no destruction, yet the description adds substantive context: no API key required, a rolling 24-month coverage window refreshed monthly, metric-ton/USD units, and — most importantly — that commodities failing a dollars-per-ton sanity check are withheld with an explicit signal rather than returning bad numbers. That withholding behavior is a non-obvious trait an agent could not infer from 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?

Purpose and sibling routing are front-loaded, and the data-quality caveat is well placed at the end. Minor redundancy: 'Read-only lookup ... no API key' partly restates the readOnlyHint annotation, though the no-key detail is genuinely new.

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?

No output schema exists, and the description compensates by specifying units, coverage window, refresh cadence, source system, and the withheld-data edge case. An agent has everything needed to call it and interpret results without a return-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 coverage is 100%, so the baseline is 3; the description adds meaning by explaining the rolling 24-month coverage window (which explains the max-24 constraint on 'months') and by specifying metric tons and USD for the returned quantities and values. It does not elaborate on the partner code format beyond what the schema already states.

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 ('Monthly US agricultural export shipments by destination') with source attribution (USDA GATS/Census) and a precise scope distinction: quantities actually shipped, not sales contracted. It explicitly names the siblings get_export_sales and compare_contracts_vs_shipments, letting an agent disambiguate 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?

Gives an explicit when-to-use ('realized trade volumes') and when-to-use-alternatives with the selecting condition ('contracted-but-unshipped demand' → get_export_sales; 'sold-versus-shipped gap' → compare_contracts_vs_shipments). No inference is required to route correctly.

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 readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds genuinely new traits: no API key required, results capped at 24 monthly values, oldest-first ordering, and per-value report date and unit. It does not cover pagination limits or behavior when a commodity/attribute combination has no stored history, which keeps it off a 5.

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?

Three sentences, front-loaded with the core purpose and followed by the routing hint and return shape. The final clause listing 'commodity, attribute, and country (default WORLD)' partly repeats the schema, which is minor waste but not harmful.

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 no output schema and only three parameters, the description covers everything an agent needs: scope, defaults, ordering, result cap, and what each returned value contains. Nothing essential is missing for correct invocation.

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 both enums are fully documented, so the schema already does the heavy lifting. The description restates the defaults (ending_stocks, WORLD) that already appear in the schema's default fields, adding no syntax or format detail beyond it. Baseline 3 is appropriate.

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 and resource — the revision history of one WASDE projection figure across monthly reports — and explicitly contrasts with the sibling get_wasde_projection. An agent can identify both what it returns and what it is not without opening the schema.

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

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

Gives direct usage context ('use to study estimate revisions') and names the alternative tool plus the condition that selects it ('use get_wasde_projection instead for the full current balance sheet'). The routing decision is fully determined.

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 readOnly/idempotent/non-destructive/closed-world, so the bar is lower; the description still adds value by noting it is a read-only lookup of stored data, needs no API key, and returns the newest stored report's values (a freshness/recency behavior not encoded in annotations). It stops short of describing pagination or failure modes, but the essential behavioral profile is covered.

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?

Front-loaded with the resource and purpose, then the when/when-not routing in the second sentence, then data defaults. Roughly 80 words with no filler; every clause carries information.

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?

No output schema exists, yet the description enumerates the returned balance-sheet components (beginning stocks, production, imports, exports, domestic consumption, ending stocks) and the scoping defaults, so an agent knows what it will receive. Annotations cover the safety profile; nothing material is missing for correct invocation.

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 baseline is 3; the description goes slightly beyond by clarifying that WORLD is an aggregate, that US/BR/AR are the other tracked countries (data coverage, not just param names), and by restating the marketing-year convention (2026 = 2025/26) and defaulting behavior in prose.

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 (latest USDA WASDE supply/demand projections for one commodity) and enumerates the balance-sheet fields returned, plus the underlying source (FAS PSD behind the monthly WASDE report). Explicitly contrasts with sibling get_wasde_history, so an agent can route correctly without opening either 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?

Gives an explicit when-to-use ('current balance-sheet outlook') and names the alternative with the condition that selects it ('use get_wasde_history instead to see how a single figure has been revised across reports'). No inferences required.

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, so the safety profile is covered. The description adds useful context beyond that: 'no API key' and the caveat that butter is listed for completeness but its price is withheld in price tools because USDA reports no US base price. This is meaningful behavioral context for an agent planning downstream calls.

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?

Three tight sentences with zero waste. The core purpose and downstream usage are front-loaded, followed by the butter caveat.

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 zero-parameter discovery tool with no output schema, the description is complete: it explains what is returned (slugs plus display labels), why to call it, and the butter exception. Nothing an agent needs in order 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?

The tool takes zero parameters, so the baseline is 4. The description does not need to explain parameter semantics, though it does clarify the meaning of the `product` values returned for use in sibling tools.

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 (Lists) and resource (dairy product slugs) and even enumerates the tracked slugs. It is clearly distinguishable from sibling list_* tools for other commodities.

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 says to use it to discover valid `product` values before calling get_dairy_price or get_dairy_history, naming the exact downstream tools. This leaves no ambiguity about when to invoke 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 carry readOnly, idempotent, non-destructive, so 'Read-only' is partly redundant, but the description adds real context: no API key required, and the important nuance that slugs map to FAS 'all' aggregate commodity codes where available. That aggregation detail is a behavioral trait not derivable from any structured field. It does not describe paging or exact response shape, a minor gap for a zero-arg list call.

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?

Three short sentences, each earning its place: what it lists, when to call it, and the mapping caveat. The key content (what and when) is front-loaded before the edge-case note.

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 no output schema and no parameters, the description must carry the return-value burden, and it does so by enumerating the commodity set and stating that FAS codes accompany them. The aggregate-code caveat pre-empts the main downstream ambiguity, so nothing an agent needs to call this 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?

Zero parameters, so the baseline is 4, and the description goes further by explaining that the output values are `commodity` slugs usable as input to sibling tools. That is directly useful semantic framing the empty schema cannot convey.

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 and resource ('Lists the commodities tracked in USDA export sales reporting') and enumerates exactly what comes back (nine named commodities plus FAS commodity codes). The phrase 'USDA export sales reporting' separates it from siblings like list_wasde_commodities and list_gats_commodities without opening either 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 names the downstream tools this enables ('Use to discover valid `commodity` slugs before calling get_export_sales or get_export_sales_history'), which is clear when-to-use guidance. It stops short of an explicit exclusion such as 'not for WASDE or GATS commodity slugs, use list_wasde_commodities/list_gats_commodities instead' — the most likely sibling confusion.

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 read-only, idempotent, non-destructive, closed-world behavior, yet the description adds real value: 'no API key' and, crucially, that the list is a configured catalog over tracked MARS production cost reports rather than a live availability check. That caveat prevents a plausible misinterpretation. It stops short of describing the return shape (label/slug pairing structure), keeping it from a 5.

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?

Three tightly packed sentences: what it returns, when to call it, and the one caveat that matters. Purpose, routing, and the non-live-availability qualifier are all front-loaded with zero waste.

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 zero-param discovery tool with full annotation coverage and no output schema, the description supplies everything the agent needs: contents, intended downstream use, auth requirements, and the static-catalog caveat. Nothing material 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?

Zero parameters, so the baseline is 4 per the rubric. There is nothing for the description to disambiguate, and it does not waste space restating an empty 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?

States a specific verb and resource ('Lists the fertilizer product slugs this API tracks') and even enumerates the concrete slugs with display labels. It is immediately distinguishable from sibling list_* tools by resource (fertilizer vs dairy/grain/livestock/etc.).

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 prescribes the use case ('Use to discover valid `product` values before calling get_fertilizer_price or get_fertilizer_history'), naming the exact downstream tools it feeds. No inference is left to the agent about when to reach for this over the price/history tools.

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, so the safety profile is covered. The description adds value beyond that with 'no API key' (auth requirement) and the important caveat that listing here does not guarantee a commodity appears in get_trade_flows when source data fails sanity checks.

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?

Three compact sentences, front-loaded with the purpose, then usage routing, then behavioral caveat. Every sentence carries distinct information with no repetition of the schema or annotations.

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 zero-parameter, read-only catalog tool with no output schema, the description covers what is returned (commodities with display labels, matched by HS chapter), why to call it, auth needs, and a subtle caveat about the catalog versus actual data availability. An agent has everything needed to invoke 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?

The tool takes no parameters (0 params, empty object schema), so there is nothing for the description to disambiguate; baseline 4 applies. The description does not need to explain any inputs and correctly focuses on outputs and usage.

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 (Lists) plus resource (commodities tracked in GATS trade flows) and scoping detail (matched to Census data by HS chapter, with display labels). This distinguishes it cleanly from the other list_ siblings like list_esr_commodities and list_wasde_commodities, which cover different datasets.

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 says to use it to discover valid `commodity` slugs before calling get_trade_flows or compare_contracts_vs_shipments, naming the downstream tools and the condition that selects this one. Nothing is left to inference about when this tool is the right choice.

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 safety (readOnly, idempotent, non-destructive, closed-world), so the description correctly spends its words on new traits: no API key required, and the important caveat that a listed product may still lack a report for a given state. It doesn't describe ordering or the exact return shape, which keeps it from a 5.

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?

Three short sentences, front-loaded with what is returned, then the usage routing, then the caveat. Nothing is repeated from the annotation block and no sentence is 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?

For a zero-parameter, read-only list tool with full annotation coverage and no output schema, the description supplies everything an agent needs: what comes back, what to do with it, and the one caveat that could cause a wrong inference. 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?

The tool takes zero parameters, so the baseline is 4; there is no parameter semantics to explain. The description does clarify the meaning of the values returned (slugs plus display labels), which is the only semantic surface available.

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 and resource ('Lists the grain commodity slugs this API tracks') and enumerates the actual items returned, plus mentions display labels. It is clearly separable from the sibling list_* tools (list_dairy_products, list_fertilizer_products, etc.) which cover different catalogs.

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 names the downstream tools it feeds ('before calling get_grain_price or get_grain_history'), giving a concrete when-to-use rule. It also sets a negative expectation ('not a live availability check'), preventing misuse as a data-availability probe.

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 read-only/idempotent safety. Description adds value beyond them: no API key needed, static catalog vs. live availability, sporadic trading caveat, and the cows_cwt vs cows_head unit split. Doesn't describe response format but content is implied by the enumeration.

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?

Front-loaded purpose, then usage, then caveats. Slightly dense with three sentences of caveat, but every sentence carries actionable information (catalog vs live, sporadic reports, unit split).

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 zero-param list tool with no output schema, the description supplies the actual contents, the return format intent, usage routing, and domain caveats. Nothing needed 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?

Zero parameters, so baseline is 4. Description nonetheless clarifies the semantics of the output values (slugs, labels, unit distinctions) that feed the `product` parameter of sibling tools.

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?

Specific verb+resource: lists livestock category slugs with display labels, enumerates them explicitly (fed_cattle, hogs, sheep...), and distinguishes from sibling list_* tools by domain. An agent knows exactly what this returns.

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: discover valid `product` values before calling get_livestock_price or get_livestock_history, naming both alternatives. Also warns the list is a configured catalog, not a live availability check — a critical usage caveat.

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, destructiveHint=false, openWorldHint=false, so safety is covered. The description adds genuinely new context — 'no API key' required — and specifies what the response contains (commodity names plus FAS PSD codes). 'Read-only' mildly restates the annotations, which keeps it from a 5.

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?

Two sentences, no waste: the first identifies the resource and its contents, the second gives the action-guiding usage. The parenthetical list is compact and informative rather than noise.

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 no input params and no output schema, the description must convey what comes back — and it does, naming the commodities and the FAS PSD codes. Nothing an agent needs to invoke 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?

Zero parameters, so the baseline is 4. The description correctly implies no arguments are needed to call it, and the mention of 'commodity slugs' clarifies how the output connects to other tools' parameters.

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 (Lists) and resource (commodities tracked in WASDE projections), plus enumerates the actual members and notes the FAS PSD commodity codes are returned. This distinguishes it from the many sibling list_* tools (list_esr_commodities, list_gats_commodities, etc.) that cover other datasets.

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 the use case ('Use to discover valid `commodity` slugs') and names the two downstream tools it feeds (get_wasde_projection, get_wasde_history). An agent knows exactly when to reach for this versus a projection/history call.

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