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 cover read-only and non-destructive behavior. The description adds valuable behavioral context: the studies are pre-registered, responses include specific components (registration, verdict, evidence, falsification test), and no authentication is needed. This goes beyond what annotations provide.

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 cover scope, examples, return contents, data sources, and authentication. No filler or repetition; the most distinguishing information (pre-registered, specific shocks) is front-loaded.

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, no output schema, and read-only annotations, the description fully equips an agent: what it is, what it returns, what data it runs on, and access requirements. Nothing essential is missing.

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 explains the optional slug parameter with examples and the omission behavior. The tool description itself does not add parameter-level detail, so the baseline of 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 description names a specific resource ('Event Atlas' pre-registered event studies) and explains what each study returns (registration, verdict, evidence, falsification test). It is clearly distinct from sibling trade tools by its focus on curated shocks and pre-registration methodology.

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 clearly implies when to use it — when the agent needs pre-registered event studies of major shocks to US containerized trade. It also specifies the data sources and notes no API key is required. It does not explicitly name alternatives or exclusions, but the context is sufficiently clear for selection.

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 already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavior beyond annotations: the GRADE RULE (OBSERVED/REPORTED/MODELLED, with a clear prohibition on quoting modelled values), the fact that no API key is required, and a specific detail about check_agreement ('the failed one that suspended the Indian series'). These enrich the agent's understanding 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 compact yet information-dense: it lists sub-tools, explains the grade rule, notes when not to use it, and mentions no API key requirement. It is front-loaded with the router's purpose and structured with a list and a rule, with every sentence serving a functional 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?

As a router with four sub-tools and no output schema, the description adequately covers the calling convention (call with {tool, arguments}), provides an example, explains the grade rule, and gives routing context. It does not detail return formats for each sub-tool, but that is not critical since the sub-tools are separate operations and the description gives enough to invoke them correctly. The note about primary tools helps agents decide when this router is unnecessary.

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% (both tool and arguments have descriptions). The description goes beyond the schema by giving a concrete example argument object for describe_series ('{series: "tt010.china.burden"}') and clarifies that arguments are sub-tool-specific. This adds practical meaning to the generic 'That sub-tool's own arguments' 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 clearly identifies the tool as a router to the ledger's registry tools and enumerates all four sub-tools with concise one-line explanations. It explicitly distinguishes itself from sibling trade/tariff tools by stating 'Most questions never need this router', so an agent can immediately tell when this is relevant.

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 guidance on when not to use it ('Most questions never need this router: trade/tariff answers live in the primary tools') and implies when to use it via the sub-tool list. It names the sub-tools and their purposes but does not explicitly exclude individual sibling tools beyond the general routing rule, which is acceptable for a meta-tool.

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?

Annotations already declare readOnlyHint and destructiveHint, and the description adds meaningful behavior beyond them: suspended periods are 'withheld and counted, never silently dropped,' and a fully-suspended span 'fails with the reason.' It also discloses licensing, cost, and authentication requirements, which is useful operational context.

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 sentences, each carrying distinct value: what the tool returns, how suspension is handled, and access constraints. The core behavior is front-loaded and there is no 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?

With an output schema present and annotations covering safety, the description adds the critical behavioral edge case (suspended periods) and access requirements. It does not describe parameter interactions like pagination or date-range formatting, but those are either in the schema or minor for a read-only fetch 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?

Schema description coverage is 75%, so most parameter meanings are already in the schema. The description adds that results are 'periods and values' but does not explain the core 'series' parameter beyond the tool name, nor clarify how to/from/limit relate to the series output beyond what the schema already 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 states a clear verb ('Fetch') and resource ('data of a series'), and enumerates what the series contains ('monthly US port trade by country and commodity, tariff rates, collected duty') and its output shape ('periods and values'). It does not explicitly contrast with sibling tools like trade_query, but the content detail makes the purpose specific and identifiable.

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 guidance on when to prefer query_series over any of its 12 sibling tools, nor does it describe exclusions or alternatives. The free/CC BY/no-key notes are access facts, not usage selection guidance, so the agent is left to infer suitability from the purpose alone.

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.