trimtab-ais

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

While annotations already declare readOnlyHint=true and destructiveHint=false, the description adds meaningful context: it reveals the tool's data scope (US containerised imports), the specific outputs (trend, origins ranked by trade and duty, tariff rate comparison), and a caveat that code-level origin rankings are 'not honest' at chapter granularity. It also notes 'No API key required.' This goes beyond the annotations, though it doesn't fully describe failure modes or return formatting.

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 dense but every sentence earns its place. It front-loads the core promise ('One HS chapter, whole, in a single call'), then details the exact data points, gives usage examples, names alternatives, and adds a caveat. It is appropriately sized for the tool's complexity and contains no fluff.

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 tool's complexity (4 parameters, no output schema), this description is fairly complete: it explains the expected return content, when to use it, and how to avoid misuse. The main gaps are the unaddressed 'detail' and 'months' parameters and the vague term 'studies', but the overall context is sufficient for an agent to decide on 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?

With schema description coverage at 50%, the description partially compensates: it clarifies that 'commodity' accepts an HS2 chapter number or name and explicitly warns against 6-10 digit codes. However, it does not explain the 'detail', 'months', or 'top_n' parameters beyond implying a ranking limit ('top supplying origins'). The description adds meaning for the key parameter but leaves the optional parameters ambiguous.

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 clearly states the tool's function: it returns a comprehensive profile for one HS2 chapter, including import volume/value, trends, top origins by trade and duty paid, tariff rate changes, and related studies. It specifies the resource (HS2 chapter) and the verb (open a commodity-level question), and distinguishes itself from siblings like trade_query, tariff_burden, and tariff_story by explicitly naming when to use those alternatives.

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 explicitly tells the agent when to use this tool ('Use this to OPEN any commodity-level question') and when not to ('for a specific 6-10 digit code call tariff_story instead'). It also contrasts with assembling trade_query + tariff_burden per origin manually, providing clear alternative 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 readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral context: it returns both series aligned month-for-month, changes, ratio, and a stated finding; reveals special landed_cost calculations for two origins on a specific commodity; explains data sources (nationwide receipts for duties); and states no API key is required. No contradictions with 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 longer than average but every sentence contributes. It is front-loaded with the core action, then gives examples, then covers an advanced feature (landed_cost) and constraints. The length is justified by the tool's complexity, though it could be slightly tightened (e.g., bullets for the examples).

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 8 parameters, no output schema, and no nested objects, the description must be self-sufficient. It explains return values (series, changes, ratio, finding), the special landed_cost/headroom output, data source caveats (burden_pct/duty_usd not for gateway), and operational guidance (call twice for more than two). This is complete enough for an agent to invoke 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 only 25% (just origin/commodity have descriptions), so the description carries the burden. It clarifies the semantics of 'kind' (origin/commodity/gateway), 'measure' (weight, value, unit value, tariff burden, duty paid), and 'subject_a/subject_b' (two origins, commodities, or gateways). It also explains constraints like same-kind requirement and gateway limitations, which are not 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?

The description starts with a specific verb+resource: 'Put two subjects on the same axis...compute the difference' and clearly enumerates the supported subject types (origins, commodity chapters/HS6 codes, US gateways) and measures. It fully distinguishes this tool from siblings like origin_profile or tariff_burden by focusing on side-by-side comparison, and even gives concrete example questions.

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 explicitly states when to use this tool: 'Use for "is trade shifting from China to Vietnam"...' and provides multiple real-world queries. It also gives important constraints: subjects must be the same kind, compare more than two by calling twice, and burden_pct/duty_usd are not available for gateways. This is clear, actionable 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 mark the tool as read-only and non-destructive; the description adds valuable behavioral context: no API key required, data sources (NOAA AIS and Census), 7-year coverage, and the return structure of each study. It does not mention behavior for invalid slugs, but this is minor for a read-only 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 description is a single dense paragraph, but every element contributes: scope, examples, data sources, auth, and output. It could be slightly more structured, but it is concise enough and front-loads the core purpose.

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 one optional parameter and no output schema, the description covers the main return contract (registration, verdict, evidence, falsification test) and context such as data provenance. It is sufficient for selecting and invoking the tool, though it does not specify error handling or exact response format.

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 input schema fully documents the single optional slug parameter with examples and default behavior, so schema coverage is 100%. The description adds domain context that helps the agent understand the event universe (e.g., hidden-queue, Red Sea null) but provides no additional syntax or format details 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?

The description clearly identifies the tool as providing pre-registered event studies of US containerized trade shocks, enumerating specific events and stating that each study returns its registration, verdict, evidence, and falsification test. This distinguishes it from sibling query/series tools by focusing on the Event Atlas concept and study-level outputs. Although the main text lacks an explicit imperative verb, the parameter description 'Omit to list all studies' supplies the listing action.

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?

No explicit when-to-use or alternative-tool references are present. The description implies usage for retrieving pre-registered event studies, and the schema note about omitting slug to list all studies gives a basic usage trigger, but there are no exclusions or comparisons to siblings such as query_series or describe_series.

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 and destructiveHint=false; the description adds meaningful context by stating it searches all 29,845 tariff lines, includes the full hierarchy, reports CBP ruling counts as a confidence signal, and requires no API key. It adds non-obvious behavioral details 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 concise and well-structured: the first sentence states the core action, followed by scope/behavior, examples, and auth requirement in four tight sentences. Every sentence earns its place with no redundant 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 reasonably explains what the tool returns (candidate codes plus CBP ruling counts) and the full search scope. It is complete enough for an agent to select and invoke the tool, though it could be slightly more explicit about the output list shape or limit behavior.

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 already covers both parameters at 100% coverage, but the description adds value by elaborating on the product parameter's intended use ('plain words') and providing concrete examples. This goes beyond the schema's brief one-line parameter descriptions.

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 ('Find') with a clear resource ('HS/HTS code for a product') and scope ('current US tariff schedule'), making its purpose unmistakable. Concrete examples like 'electric standing desk' and 'lithium battery pack' reinforce the plain-language search intent and distinguish it from sibling tools.

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 explicitly frames the tool as 'the entry point to every tariff question,' giving clear guidance on when to use it. It does not name specific alternatives or exclusions, so it lacks the strongest possible when/when-not guidance, but the positioning is still clear.

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 only cover read-only/non-destructive. The description adds crucial behavioral context: the AIS archive is frozen (2026-07-26 to 2026-08-06) and cannot answer current questions, modelled quantities must be handled specially, and no API key is required. These are material behavioral disclosures 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?

The description is longer than a simple tool, but it is well-structured with labeled sections (REGISTRY, FROZEN AIS ARCHIVE, GRADE RULE) and front-loaded with the router pattern. Every sentence is informative, though it could be slightly tighter by reducing some parenthetical explanations.

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 tool has 8 sub-tools, no output schema, and a generic arguments object, the description covers a lot: sub-tool purposes, archive limitations, grade rule, and usage exclusions. However, it does not provide detailed argument schemas for each sub-tool (only one example), leaving some ambiguity for correctly constructing arguments for the other sub-tools.

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 only provides a tool enum and a generic arguments object, but the description enriches semantics by explaining what each sub-tool does and giving an explicit example for describe_series ('{series: "tt010.china.burden"}'). It also provides the grade rule that affects how argument values should be interpreted, going well 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?

The description clearly identifies the tool as 'Router to the ledger's meta and archive tools' and enumerates all 8 sub-tools with specific verbs (list, search, describe, check). It distinguishes from siblings by stating that trade/tariff answers live in the primary tools, making the purpose unambiguous.

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 explicitly says 'Most questions never need this router: trade/tariff answers live in the primary tools,' providing a clear when-not-to-use directive. It also explains the frozen archive date range and the grade rule (never quote modelled quantities as measurements), which guides appropriate usage.

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 indicate read-only and non-destructive, so the bar is lower. The description adds meaningful behavior: 'Numbers are collected receipts and counted cargo — never announcements', clarifying data provenance and that it's fact-based rather than forward-looking. It also notes default-to-latest-month behavior, adding context beyond 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 dense but efficient: it front-loads the value proposition, then gives use cases, parameter usage, data caveat, and auth note in four sentences. Every clause serves a purpose, with no filler or repetition. The structure is logical and easy to parse.

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 tool's simplicity (2 optional params, no output schema) and rich annotations, the description covers the essential context: what data is included, how to use parameters, data source caveat, and default behavior. It doesn't detail the return format or what the 'detail' levels produce, but for a report-generating tool with no output schema, it's sufficiently complete for an agent to decide and invoke.

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 50%: 'month' has a description and pattern, while 'detail' has only enum values and default. The description clarifies 'month' format and default behavior ('pass month:"YYYY-MM" for history') but does not explain the meaning of 'answer', 'standard', or 'full'. With one parameter well-documented in schema and another only partially in description, the description partially compensates but leaves a gap.

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 clearly states a specific verb ('Use for') and resource ('US trade last month'), enumerating exactly what the report contains: tariff bill comparisons, duty movements, gateway imports, and trade-war measures with Federal Register citations. This rich detail distinguishes it from sibling tools like query_series or tariff_story, making its purpose unambiguous.

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 explicitly provides usage triggers: 'what happened in US trade in June', 'any new tariffs this month', or opening a briefing. It also clarifies default behavior (latest complete month) and history mode via the 'month' parameter. While it doesn't name alternative tools or exclusions, the use cases are concrete and actionable.

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 and destructiveHint=false, so the safety profile is known. The description adds context beyond that: it warns that 'Containerised gateway trade and nationwide duty receipts are different universes — the response says so where they sit side by side,' and states that no API key is required. This provides additional operational context without contradicting 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 a single, information-dense paragraph that front-loads the core purpose, then gives usage guidance, a caveat, and an exclusion. Every sentence contributes value, and it is not overly verbose despite covering many aspects of 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?

With no output schema, the description lists what the response contains: volume, value, trend, top commodity chapters, gateways, tariff burden, and pre-registered studies. It also clarifies the two different data universes and provides exclusions for other tool uses. This gives a comprehensive picture of the tool's output and scope.

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 50% (origin and top_n have descriptions, detail and months do not). The description partially compensates by referencing 'top commodity chapters' (top_n) and 'the trend' (months), but it does not explain the detail parameter or the specific meaning/constraints of months. It adds marginal value beyond the schema but does not fully cover the undocumented 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?

The description opens with 'One origin country, whole, in a single call' and explicitly lists the data components (import volume, value, gateways, commodity chapters, tariff burden, studies), giving a clear verb+resource scope. It distinguishes from siblings by explicitly excluding HS-code (tariff_story) and two-way comparison (compare) use cases.

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 explicit when-to-use guidance: 'Use this to OPEN any country-level question... instead of firing trade_query and tariff_burden separately.' It also gives clear exclusions: 'Do NOT use for a specific HS code (tariff_story) or a two-way comparison (compare).' This covers both positive and negative usage with named alternatives.

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?

The description discloses meaningful behavior beyond the annotations: suspended periods are withheld and counted, a fully-suspended span fails with the reason, and the data is free with no API key. This adds valuable context without contradicting the readOnlyHint or destructiveHint 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 three sentences long, front-loaded with the main action, and every sentence serves a distinct purpose: scope, behavior, and access/licensing. There is no redundancy or 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 an output schema present and annotations providing read-only/destructive hints, the description covers the data scope, error behavior, licensing, and auth requirements. It does not explicitly address usage alternatives, but for a straightforward data-fetching tool it is sufficiently 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?

The schema already documents to, from, and limit with concise descriptions, so the baseline is 3. The description contributes no new parameter-specific details but does give examples of series types, which contextualizes the `series` parameter. The `series` parameter itself remains somewhat ambiguous in format.

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 clear verb+resource statement ('Fetch the data of a series') and lists specific example series types, making the tool's purpose unmistakable. It also implicitly distinguishes itself from analytical siblings by positioning itself as the raw data retrieval endpoint.

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 implicit usage context, such as the series types it covers and the 'No API key required' access note, but it does not explicitly state when to use this tool over siblings like compare or trade_query. There are no when-not statements or alternative tool mentions, leaving usage guidance partly implied.

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 and destructiveHint=false, so the description adds value by disclosing corpus limits (2017-present, backfill in progress), that coverage count is included in every response, and that no API key is required. It also specifies what each ruling contains, giving the agent a realistic expectation of the data without contradicting 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 three sentences, each serving a distinct purpose: defining the tool's role, explaining how to query and what to expect, and setting expectations about corpus scope and access. There is no redundant or filler content; the structure is front-loaded and information-dense.

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 search tool with no output schema, the description adequately covers key aspects: the input method, the type of results returned, the temporal/corpus limitations, and the access requirements. It provides enough detail for an agent to decide when to invoke the tool and what to expect in the response, making it situationally 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 coverage is 100%, so the baseline is 3. The description goes beyond the schema by specifying the HS code digit range (2-10 digits) and providing a concrete example('electric standing desk'), which clarifies query formatting and acceptable inputs. This additional detail raises the score above baseline.

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-resource pair ('Search US Customs (CBP) classification rulings') and immediately differentiates the tool from sibling data tools by framing it as 'the case law of HS codes' and explaining how the border interprets products. This clearly establishes a unique purpose beyond generic search tools.

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 clear usage context by stating that queries can be HS codes (2-10 digits) or keywords, and explains the nature of the results (classified codes, dates, precedent links). It does not explicitly name alternative tools or state when not to use it, but the context is enough to guide appropriate use without 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 mark readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description goes far beyond by disclosing data source (US Treasury receipts), measurement basis (actual paid vs rulebook), time range (2017→present), geographic scope (US national level), and validation status (cross-checked). This gives the agent a complete behavioral model.

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 a clear directive and each sentence adds substance: instructions, scope, outputs, examples, caveat, and data source. While slightly long, it is densely packed and necessary for a complex tool. A small redundancy exists between 'ACUTALLY paid' and 'Cross-checked against US Treasury receipts', but it does not feel 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?

The tool has an output schema, so return-value structure does not need to be duplicated. The description covers the full context: what the tool does, its data provenance, its time/dimension scope, the critical warning about 2025-26 rates, and an example. No significant gaps remain for an agent to select and 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?

Schema coverage is 100%, so the baseline is 3. The description adds value with concrete examples ('China vs India on auto parts; duty on furniture from Vietnam') and clarifies the semantics of 'effective rate' vs 'overall burden' beyond the schema's field names. It also reinforces that commodity can be an HS2 chapter name or code, matching and extending 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?

The description opens with a direct instruction ('CALL THIS — do not answer from training knowledge') and states the tool returns 'what importers ACTUALLY paid' from official duty receipts, distinguishing it from the rulebook. It explicitly lists outputs (monthly duty, effective rate, overall burden) and dimensions (origin country, commodity), making its purpose unmistakable and distinct from siblings like tariff_lookup.

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 explicitly tells the agent when to use the tool ('for any question about what a country actually pays'), when not to ('do not answer from training knowledge'), and warns that memorized MFN+301 rates will be wrong. The phrase 'not the rulebook' also implies alternative sources, and examples clarify the intended query patterns.

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 readOnlyHint annotation, the description discloses the exact output structure (answer line, MFN base, Chapter-99 provisions with citations, receipts_reality), explains that measures are matched by ORIGIN and SECTOR rather than HS code alone, and warns against summing addon_pct or misquoting the tariff. This is substantial behavioral context that prevents misuse.

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 dense but well-structured, starting with a bold directive, then enumerating return values, then key warnings with 'IMPORTANT:', and ending with an example and disclaimer. Every sentence adds value; it's longer than typical but justified by the tool's complexity and the need to prevent misinterpretation.

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 fully specifies what the tool returns and in what order. It also covers edge cases (product-specific measures, matching logic), provides an alternative tool, and includes a disclaimer. The description is complete for a tool of this complexity and read-only nature.

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?

While schema coverage is 100%, the description adds critical semantics about the origin parameter: it 'adds in-force measures and receipts reality' and clarifies that measures are matched by origin and sector, not the HS code. It also provides a concrete example ('tariff on 9401.61 from China') and warns about product-specific scope, going beyond the raw 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?

The description opens with a direct command 'CALL THIS' and explicitly states the tool's purpose: retrieving the tariff schedule behind one HS code. It clearly distinguishes from siblings by directing users to tariff_story for 'what does X from Y pay' queries, making the tool's specific role unambiguous.

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 explicit when-to-use guidance ('CALL THIS for the schedule behind one HS code'), warns against reciting from memory, and explicitly excludes the alternative ('For 'what does X from Y pay' prefer tariff_story'). It also cautions about product-specific measures not applying, giving clear behavioral boundaries.

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 and non-destructive. The description adds meaningful behavioral context: it uses official duty receipts, reports confidence on code resolution, includes Federal Register citations, and notes the 2025-26 rate changes. While it doesn't disclose edge-case behavior (e.g., invalid HS code handling), it is quite transparent given the read-only nature.

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 dense but well-structured, front-loaded with 'USE THIS FIRST.' Every sentence adds value, though there is slight redundancy between 'USE THIS FIRST' and the later statement about 2025-26 rate changes. It could be tightened without losing meaning.

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 enumerating the return components (paid rate, MFN base, measures, citations, rulings count). It covers inputs, outputs, alternatives, exclusions, and data freshness. It lacks error-handling details and concrete output formatting examples, but is largely complete for a query 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?

The input schema covers all 5 parameters with detailed descriptions (HS/product OR relationship, defaults, enums). The description adds minimal extra value beyond schema, mainly re-emphasizing the HS-or-product duality and adding that it resolves the code and reports confidence. Since schema coverage is 100%, a baseline of 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 states a clear, specific purpose: answering tariff questions with a single call that returns paid rates, statutory MFN base, trade-war measures, and citations. It distinguishes from siblings by explicitly replacing hs_search, tariff_lookup, and tariff_burden, and by excluding trade volumes (trade_query).

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?

Provides explicit when-to-use guidance ('USE THIS FIRST', 'ANY ... question'), alternatives ('It replaces hs_search + tariff_lookup + tariff_burden'), and exclusions ('Do NOT use for trade volumes (trade_query) or as customs advice'). Also warns against training knowledge, reinforcing when this tool is appropriate.

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 (readOnlyHint=true, destructiveHint=false), the description adds rich behavioral context: data source (US Census port-level records), time range (2017→present), revision tracking, HS6 detail from 2024, the exclusion of duty from customs value, and the automatic computation of duty and landed_vs when origin and 6-digit commodity are provided. This goes far 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?

The description is long but every sentence earns its place. It front-loads the core purpose, then systematically covers filters, data quality, computed outputs, usage examples, and a warning. There is no redundant filler or repetition of schema details.

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 tool's complexity and the presence of an output schema, the description is fully complete. It covers data provenance, time coverage, parameter nuances, special computed outputs, usage examples, and the absence of an API key. No gaps remain for the agent to infer.

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?

Although schema coverage is 100%, the description adds crucial context to each parameter: origin accepts country names or Schedule C codes, commodity can be HS2 chapter names or HS codes, gateway examples are given, and months default/max are clarified. It also explains how parameters interact (origin+6-digit commodity triggers duty and landed_vs). This meaningfully enriches 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?

The description opens with a specific verb ('Query') and clearly identifies the resource: US containerised import trade with monthly weight and customs value via 8 gateways. It explicitly differentiates itself from the sibling tool 'compare' by stating 'no need to call compare', making its unique scope unmistakable.

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?

Provides explicit when-to-use guidance with concrete examples ('Ask it things like: US furniture imports from Vietnam monthly...'), an exclusion ('no need to call compare'), and a critical caution ('never compare invoice $/kg across origins without it'). This clearly signals when the tool should be selected over alternatives.

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