usitc-tariffs-mcp-server

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

Annotations already mark this as read-only and idempotent, but the description adds useful domain-specific behavior: Chapters 98 and 99 expose actual published entries, grouping depends on sourced markers, and reserved chapters can return a successful empty collection. The wording is dense, but the extra behavioral context is substantive and does not contradict 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 reasonably short and starts with the browse action, but it is written as a dense run of domain jargon rather than clearly structured guidance. The edge-case sentences earn their place, but the overall phrasing is harder to parse than necessary.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the existing output schema and complete parameter schema, the description supplies the main non-obvious behavioral caveats an agent would need. It does not cover routing among siblings, but for calling the tool correctly the edge-case coverage is fairly complete.

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 chapter, limit, and cursor are already well documented in the schema. The description does not add parameter-specific semantics beyond what the schema provides, making the baseline 3 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?

The description states a specific verb and resource: browsing numbered headings, with rate-line and statistical-count details. It is clear enough to identify this as an HTS chapter browsing tool, but it does not explicitly differentiate the tool from siblings such as usitc_get_heading or usitc_search_hts.

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 gives no explicit guidance on when to use this tool versus the sibling lookup/search tools. It mentions edge cases like Chapters 98 and 99 and reserved chapters, but those are behavioral notes rather than selection 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 readOnly/idempotent/openWorld, yet the description adds real behavioral caveats an agent cannot infer: coverage is partial, empty candidates never establish clearance, and unknown/different-country evidence is retained in comparisons. It also enumerates what is deliberately out of scope (applicability, stacking, combined duties), which prevents over-trusting the output.

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 the action and its input constraint, then the caveats; nearly every sentence carries distinct information. Density borders on cryptic ('unmapped views', 'different-country evidence') and could be slightly more readable, but nothing is padded.

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 a full output schema and rich annotations, the description covers domain limits, coverage gaps, and mode selection adequately. Paging behavior and return shape are handled by the schema, so remaining gaps are minor; a brief note on what a candidate result means for follow-up would make it complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the parameters are already fully documented structurally. The description only restates the candidateCode/noteId/noteCursor constraints already present in the schema, adding no syntax, format, or edge-case value beyond 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 and resource ('Find Chapter 99 candidate headings and source references') scoped to an exact eight- or ten-digit commodity number. The closing disclaimer ('No applicability, current legal status... are determined') implicitly separates it from the duty-rate and search siblings, though no sibling is named directly.

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 selection guidance across the three modes ('Use candidates, evidence with a returned candidateCode, or unmapped views') and a workflow instruction for noteId/noteCursor. It omits an explicit 'use this instead of usitc_lookup_duty_rate / usitc_browse_chapter' routing statement, so the alternative-selection half is missing.

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, openWorld), and the description adds genuine behavioral context beyond them: ancestry is computed from the whole containing heading before filtering, section titles live in a separate 'sections' field outside legal ancestry, and chapters 98/99 preserve published forest roots without inventing four-digit records. These are non-obvious semantic rules an agent could not get from annotations or schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The what-is-it sentence is front-loaded, and each subsequent sentence carries a distinct fact (ancestry construction order, section titles, nodeId follow-ups, chapter 98/99 edge case). It is dense with domain jargon ('published forest roots', 'unnamed superior rows') that an unfamiliar agent may find opaque, but nothing reads as 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?

An output schema exists, so return values need no explanation, and the description instead covers the non-obvious edge cases (whole-heading ancestry, section titles kept separate, chapter 98/99 roots). Together with a fully documented 4-parameter schema and safety annotations, this is sufficient 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 description coverage is 100%, so the schema already documents code, limit, cursor and nodeId thoroughly; the baseline is 3. The description adds some meaning to nodeId via the 'exact nodeId follow-up' note, but it does not explain the dotted/bare code convention or limit behavior beyond what the schema 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?

The description opens with a specific verb and resource ('Inspect a four-, six- or eight-digit HTS classification and its complete indented descendants'), which clearly separates it from a flat search tool. It never names the sibling tools (e.g. usitc_browse_chapter, usitc_search_hts), so an agent still has to infer the boundary itself.

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 by the phrasing: 'omit to browse' (on nodeId) and 'Each parent and inherited-rate source has an exact nodeId follow-up' hint at drill-down behavior, but there is no explicit when-to-use versus search_hts or browse_chapter. No exclusions or prerequisites are given.

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

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

Annotations already establish read-only, idempotent, open-world behavior. The description adds meaningful context beyond that: country membership remains unknown without verified lists, release records identify editions but do not enable historical lookup, and pagination must be followed via nextCursor. That is useful behavioral scope for a reference-list tool.

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 content is front-loaded and compact, with no filler. However, the first sentence is a dense list of disparate topics, and the relation between clauses is not always immediately clear. It earns its place but could be more scannable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the description needn't explain return values. It covers the topic families, pagination expectation, and important exclusions about country membership and historical lookup. It is complete enough for correct invocation, though a clearer when-to-use statement would strengthen 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 description coverage is 100%, and the schema already documents limit clamping, cursor opacity, and topic enumeration. The description only restates that several topic families exist and says to follow nextCursor, adding little semantic 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?

The description names a specific retrieval action and enumerates the five reference topics (identifiers, SPIs, chapters, units, releases), matching the topic enum. It also implicitly distinguishes itself from sibling tariff-lookup tools by noting that release records do not enable historical tariff lookup. It is clear, though somewhat terse about being a reference-table tool.

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 provides useful exclusions: program names are decoded separately from country membership, and release metadata does not support historical tariff lookup. This helps an agent avoid misusing the tool. It does not explicitly name sibling alternatives or state the primary 'use this before/after' workflow, keeping it below a 5.

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

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

Annotations already establish read-only, idempotent, open-world behavior, yet the description adds real substance: eight-digit rows take precedence, absent rows resolve only through a unique ten-digit source row, multiple suffixes stay unresolved, blank statistical cells inherit from the matching eight-digit ancestor. It also discloses limits (Special-program membership stays unknown; neither comparison establishes qualification or selects a column). Deduction only because several clauses ("retaining its identity") are cryptic rather than clarifying.

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 purpose, which is good, but the body is a run of dense, comma-chained legal-technical clauses with no structure; sentences like "Multiple suffixes stay unresolved" and "retaining its identity" cost parsing effort without clear payoff. Shorter, separated statements would serve better.

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 need not be described. For a two-parameter, read-only lookup the description covers the essential caveats an agent needs: resolution precedence, unresolved cases, inheritance of blank cells, and the countryCode limitation. Complete enough to call correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning for `code` by explaining how eight- versus ten-digit forms resolve and what happens when resolution is ambiguous. It reinforces that countryCode is a local comparison never sent upstream — though that is already in the schema, so the gain is modest.

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: retrieve an eight-digit rate line or ten-digit statistical number with all General, Special and Column 2 cells. It is clearly distinguishable from browse/search/get_heading siblings and explicitly hands off Chapter 99 work to usitc_check_additional_duties. It stops short of a plain one-line statement of purpose, burying the core action under resolution jargon.

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 only explicit routing is "Follow usitc_check_additional_duties for partial Chapter 99 research." Nothing tells the agent when to use this rather than usitc_get_heading or usitc_search_hts, which is the more likely confusion given the sibling set. Usage is largely implied by the tool's narrow input (a single 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 declare readOnly, idempotent and openWorld, so the bar is lower; the description still adds the valuable caveat that matches carry unresolved rates and that pagination requires identical arguments. It stops short of describing result shape or page-size behavior, which are covered elsewhere, so it is strong but not exhaustive.

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 dense sentences: purpose and scope first, then alternatives, then pagination mechanics. Each sentence carries distinct information and none restates the name or title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present and full parameter documentation, the description only needs to cover routing, the unresolved-rate caveat, and continuation semantics, and it does all three. An agent can call and resume this tool correctly from the description alone.

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 clarifying that the query accepts either commodity text or a code prefix and that the cursor must be replayed with unchanged arguments. The limit parameter is left entirely to 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 ('Search') and resource ('published USITC descriptions or complete HTS code prefixes') plus ordering ('source order'), which is enough to distinguish it from usitc_browse_chapter and usitc_get_heading. The clause about flat published rows with unresolved rates further pins down what kind of result this is.

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 routes the agent to two named alternatives with the condition that selects each: usitc_get_heading for legal ancestry and usitc_lookup_duty_rate for exact base rate columns. It also gives the continuation rule ('follow nextCursor with identical arguments'), 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.