tariffmonitor-mcp

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

Far exceeds the annotations: it enumerates exactly what is returned (base rate, each stacked layer, total, data-checked date, notes), which programs are computed versus merely flagged as 'needs review' (vehicles, wood, trucks, semiconductors, drones), and which are explicitly not computed (Section 338 Canada lists published only as images, IEEPA tariffs ended 20 Feb 2026). It also discloses accuracy caveats ('Figures are estimates') and that 8- then 6-digit fallback may occur, so the agent knows the answer may be for a different code than requested.

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?

One enormous run-on sentence carries hundreds of words of legal citation detail — FR Doc numbers, the exclusion end date stated twice in 'both official wordings', heading ranges, exact percentages per program. Much of this is reference minutiae that does not help an agent decide to call the tool, and it buries the useful parts (returns, notes, estimates) mid-paragraph.

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 calculation tool with 100% schema coverage and no output schema, the description is more than complete: it explains return values, caveats, and known non-computed cases. The only shortfall is structural — the completeness is achieved through density rather than organization, and sibling routing is absent.

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 all three parameters are already documented in the schema, including the CN default and the annual-value option. The description only restates that dollar impact is optionally computed, adding no format or interpretation detail beyond what the schema provides; baseline 3 applies.

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 opening sentence states a precise verb and resource: calculate a stacked US import tariff rate for an HTS code from an origin country. That is unmistakably different from lookup_hts_code, but the description never names the siblings or explicitly contrasts itself with compare_origins, so the differentiation is left implicit.

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 is only implied: an agent infers it should call this when it has an HTS code and origin and wants a total rate. There is no explicit 'use this instead of compare_origins when...' routing, no statement of prerequisites, and no guidance on when a rate lookup is inappropriate (e.g. a code that must be resolved first with lookup_hts_code).

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/non-destructive safety, so the bar is lower; the description adds real value with the return structure (total rate plus per-layer breakdown: MFN, Section 301 China, Section 232, Section 301 Brazil, forced-labor tariff), the post-exclusion rate, sort order, and a concrete expiry date with a cited source and noted discrepancy. It also discloses the important limitation that estimates exclude preferential/FTA rates because rules of origin are not assumed.

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 it does and the scope constraint, then moves to return shape and caveats; nearly every clause carries information. It is dense to the point of being a single long paragraph, and the parenthetical about the Federal Register vs USTR date discrepancy is more detail than an agent needs to select or invoke the 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?

No output schema exists, so the description must explain the return value — and it does, enumerating the rate layers, the post-exclusion rate, sorting, and optional dollar duty. Combined with the estimate-only disclaimer and the code-lookup pointer, 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% and the schema already states the 6–10 digit HTS format, the 2–8 country limit with default set, and that annual_import_value_usd adds a duty figure. The description merely echoes these ('with the dollar duty when an annual import value is given'), adding no syntax or unit detail beyond structured data.

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 (compare) + resource (estimated US import tariff) + explicit scope constraint (ONE HTS code across several origin countries), with concrete examples (China vs Vietnam vs Mexico vs India). It is clearly distinguishable from calculate_tariff (single-origin computation) and lookup_hts_code (code resolution).

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 decision context (sourcing / 'China plus one') and the scope rule (one HTS code, multiple origins, sorted lowest first), and the schema points to lookup_hts_code when only a product name is known. It does not explicitly say when to use calculate_tariff instead, so siblings are separated by implication rather than statement.

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/openWorld, but the description adds substantive behavior beyond them: a 19,856-code dataset, a cap of 12 returned codes, ambiguity handling (multiple headings listed with 10-digit lines ranked by match), and a documented fallback where a failed phrase match retries single words and reports which word was used. Those are exactly the runtime traits an agent can't infer from 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?

Purpose is front-loaded and the sentence order follows the actual call flow. The parenthetical list of seven example products plus the illustrative heading mapping is more example volume than strictly needed, but nothing is genuinely off-topic.

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 covers the return shape (up to 12 codes, named heading, ranked 10-digit lines) and the ambiguous-query and no-match paths. For a one-parameter lookup tool, an agent has everything needed to call it and interpret 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% and the single parameter already documents keyword vs. code prefix and the 2-character minimum. The description still adds matching semantics the schema lacks — everyday shopping words are mapped to official headings, phrases are matched whole then word-by-word, and 'single keywords match best' — which tells the agent how to phrase the query.

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 ('Find the US HTS code for a product') and immediately scopes the input as a plain-language name or numeric prefix from the official USITC schedule. It also names the sibling tools that consume its output, so the agent can place it in the workflow without reading further.

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 this first whenever you have a product name rather than a code ... then pass a code to calculate_tariff or compare_origins.' That gives both the trigger condition and the downstream handoff to both siblings.

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