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

Annotations already mark it read-only and non-destructive, and the description adds substantial context: US Census port-level provenance, mirrored and revision-tracked data, 2017→present coverage with HS6 detail only from 2024, no API key required, and the crucial caveat that customs value excludes duty. It also discloses that two previously available aggregate measures are withdrawn and how to respond instead.

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 one dense block that leads with two long refusal instructions before stating what the tool does, so the purpose is not front-loaded. The refusal content is operationally relevant and earns its place, but it would be far more usable placed after the capability sentence. The example queries and the duty/landed_vs explanation are efficient.

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?

An output schema exists so return values needn't be explained, yet the description still usefully explains the two conditional fields (duty, landed_vs) and the landed-cost head-to-head semantics. Coverage windows, gateway scope and provenance are all present. Minor gap: the interaction between months and the HS6-from-2024 boundary is left implicit.

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 real semantics: origin limited to the 30 largest origins with name examples, commodity accepting HS2 chapter names or any 2/6-digit HS code, gateway names like us_la_longbeach/savannah, and the pairing rule that origin plus 6-digit commodity unlocks duty and landed_vs. It does not discuss months or share_draft beyond what the schema says.

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: 'Query US containerised import trade directly: monthly weight (kg) and customs value (USD) through the 8 major US container gateways.' It also distinguishes itself from the sibling 'compare' by noting duty/landed_vs are returned in this one call. The purpose is buried beneath three sentences of refusal policy, which delays rather than obscures it.

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 concrete invocation examples ('US furniture imports from Vietnam monthly; plastics through Houston; imports from India last 36 months') and explicitly routes away from the sibling compare tool. It states the trigger condition for the enhanced duty/landed_vs response (origin + 6-digit commodity) and what is out of scope (aggregate $/kg trend, nationwide-duty quotient). No explicit guidance on when to prefer query_series, tariff_burden or month_in_review among siblings.

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