List Corrected USDA Market Reports

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

Annotations already communicate read-only, idempotent, open-world, and non-destructive behavior. The description adds valuable context beyond annotations: corrections supersede previously published data, the source is USDA AMS MyMarketNews, and no authentication is required. This gives the agent useful expectations about data reliability and access 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 appropriately sized and front-loaded with the core purpose, followed by data-quality context, market coverage, and a useful parameter tip. Every sentence earns its place, including the source/authentication note, without padding or redundancy.

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 one optional parameter, a rich output schema, and annotations covering safety and idempotency, the description is complete. It explains what the tool returns (corrected/amended reports), why it matters, what markets are covered, how to widen the search, and that no auth is needed. Nothing essential is missing for an agent 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 schema fully documents the 'days' parameter including valid range and default, so the baseline is 3. The description adds a small extra hint ('Use days=all to see the full correction history') that reinforces the parameter's intended usage, but does not significantly expand on the schema's meaning.

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 and resource: 'List USDA AMS market news reports that have been corrected or amended within the specified period.' It clearly scopes the tool to corrected/amended reports, distinguishing it from sibling tools like usdamars.reports.list, .search, and .get. The market coverage list reinforces the resource scope without ambiguity.

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 clear context for when this tool is relevant: when the user needs reports that supersede previously published data for accurate commodity price analysis, and it names the covered commodity sectors. It gives practical guidance on 'days=all' for full history, but it does not explicitly state when to use an alternative sibling such as usdamars.reports.search or .list.

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