--- name: calculate-duty description: Calculate an evidence-backed duty estimate for a tariff system and ordinary tariff code the user already supplies. Use for duty-rate, customs-duty, or Chapter 99 calculation questions; do not use to select a product classification. --- # Calculate Duty Use this workflow when the user already has an ordinary tariff classification and wants a duty estimate. The result is a calculation from versioned tariff evidence, not a classification decision, legal advice, a binding customs ruling, or a final customs-entry amount. ## Boundaries - Require the user to supply the ordinary tariff system and code. Never choose, recommend, correct, or silently substitute the Chapter 1-97 classification in this workflow. If the code is missing or does not resolve exactly, ask the user for the code or confirmation instead of using search results to select one. - Tariff Code Compliance tools only read tariff evidence. Do not write a classification, customs entry, product record, or duty result to another system. - Let the selected runtime guide define the treatment families and calculation semantics. Keep every base, preferential, alternative, conditional, and supplemental treatment it exposes as a separate path and line item. For US HTS, this includes General, Special, Column 2, and every supplemental Chapter 99 measure. - Origin, a preference/program symbol, or a graph reference does not establish eligibility. Calculate a preferential, alternative, conditional, or supplemental path only as an explicitly conditional scenario unless the user supplies the facts and evidence needed to establish that treatment. - Never mix nodes, rates, or edges from different tariff-system versions. Treat the selected exact version and effective date as part of every result. - Follow the selected tariff system's runtime `guide_markdown`. If the guide says an expression is not computable, preserve it as unresolved even when its raw text resembles arithmetic. - Send only the tariff and shipment facts needed for the calculation. Do not send personal information, credentials, authentication secrets, or unrelated commercial data. ## Starter request The native MCP prompt and public skill use the request delimited below. Calculate an evidence-backed duty estimate for this tariff classification: - Tariff system: [tariff system] - Ordinary tariff code: [ordinary tariff code] - Known shipment facts: [known shipment facts] The user must supply the ordinary tariff system and code. If either is omitted, ask for it and do not select or recommend a classification. Require the legally relevant entry/effective date; an exact version does not replace the date. If the date is missing, ask for it before making tariff graph calls. Use tariff-system discovery to resolve the exact version internally only when returned authoritative validity metadata maps that date to one version. If discovery exposes only version labels, ordering, or a default flag, explain that the available metadata does not establish date coverage and ask the user to confirm the exact version. From the known shipment facts, identify whether origin, entered value and currency, or other facts are still missing. Ask only for facts needed to retrieve the treatment paths and calculate the expressions actually found, such as a quantity and unit for a specific rate or evidence for a claimed conditional treatment defined by the selected runtime guide. Use Tariff Code Compliance to verify the supplied code in the requested system, one exact version, and the legally relevant entry/effective date; pass that date as `effective_at` on every graph call that accepts it. If the date is missing, ask for it before retrieving or calculating time-bounded treatments. If the user supplies only an entry/effective date and discovery does not return version-validity metadata, ask the user to confirm the exact version; do not infer date coverage from a version label or the default version. Let the selected runtime guide define the treatment families and keep each one separate. For US HTS, keep General, Special, Column 2, and supplemental Chapter 99 measures separate. Do not infer eligibility or supplemental-measure applicability from origin, a program symbol, or a reference alone. Lead the customer answer with a concise calculation snapshot in this order: the supported duty subtotal (or that no subtotal is supportable yet), excluded or unresolved charges and treatments, and the single most valuable next question. Never describe a subtotal as full landed cost. Treat unresolved antidumping or countervailing duty as unresolved, never as zero. Prefer an early bounded first-pass answer over exhaustively expanding every reachable conditional branch. Once the ordinary rate and directly connected treatment paths are known, do not delay the answer to fetch every referenced supplemental node. Exclude unresolved treatments from the subtotal, identify the returned treatment or family and missing applicability evidence, and ask the one question that most improves the next calculation pass. After that snapshot, show the reviewable detail. For every supported scenario, show each line-item formula, substituted values, amount, currency and unit, the rate owner and graph path, source provenance, assumptions, unresolved conditions, the exact system version, and the calculation total. Add line items only when they share one currency or a supplied, supported exchange rate converts them to one currency; never invent or silently assume a conversion rate. If currencies cannot be reconciled, keep the total unresolved and ask for the missing conversion evidence. A parser result such as `expression.type=unknown` is not a reason to stop when the raw source text, operands, units, and operation are unambiguous; distinguish the source text from your interpretation and show the arithmetic. Preserve genuinely ambiguous or guide-defined non-computable expressions without inventing a number. If evidence or shipment facts are insufficient, return what was verified and the highest-value focused follow-up question before any lower-priority questions instead of forcing a total. This is a non-binding estimate from published tariff evidence, not legal advice, a binding customs ruling, or a final customs-entry amount. It does not include fees, taxes, freight, brokerage, customs valuation adjustments, quotas, antidumping or countervailing duties, or other charges unless the user explicitly asks for them and the retrieved evidence supports them. Use only the customer-facing `reference` and `references` fields returned by Tariff Code Compliance when naming graph evidence. For every relevant recommended, ancestor, candidate, or rejected code and every decisive note, exclusion, term, or annotation, render a Markdown link in the exact form `[]()` only when `reference.url` is present, substituting both values verbatim from that returned reference. When `reference.url` is absent, show `reference.label` as plain text with readable official provenance; never guess or hand-build a link. Never print or transform node IDs, `system_version_id`, source or storage keys, UUIDs, or page or continuation tokens, including values beginning `ent:`, `sysv:`, or `NATIONAL_`. If an entity-specific reference is unavailable, use the returned exact system/version reference under the same URL-present rule; do not expose the opaque value. Never print a raw `source.locator` field or a path-like locator such as `exportList[...]`; it is an internal storage coordinate, not customer-facing provenance. ## Workflow 1. Confirm that the user supplied both the tariff system and ordinary tariff code. Preserve their classification exactly. Normalize punctuation only as the selected runtime guide permits. 2. Gather the legally relevant entry/effective date first; require it before tariff graph calls or any time-bounded calculation. If the date is missing, ask for it even when an exact version is already known. If the exact version is missing, call `list_tariff_systems` and select a returned version only when authoritative validity metadata explicitly maps the supplied date to that one version. If discovery returns version identifiers without validity intervals, state that coverage gap and ask the user to confirm the exact version. Never infer coverage from a revision label, year, ordering, or default status. 3. Call `describe_tariff_system` for that exact system and version. Treat its profile and `guide_markdown` as the contract for identifiers, node kinds, relations, properties, rate expressions, inheritance, dates, and source fields. 4. Resolve the supplied code exactly with `resolve_nodes` and validate its declarable/reporting status as required by the guide. If it is unknown, ambiguous, outside the selected version, non-reportable, or not the kind required by the guide, report that result and ask the user to confirm the system/code. Do not search for a replacement classification. 5. Follow only stored hierarchy and rate relations described by the guide. Begin with one bounded pass from the exact resolved classification: retrieve its ordinary rate owner, inheritance path, and directly connected treatment paths with `get_node`, `list_node_edges`, and bounded `traverse_nodes`. Expand only the nodes needed to calculate the requested scenario or answer the single highest-value applicability question; do not recursively chase every reachable note, program, or supplemental code in one customer turn. Use `search_nodes` only for a known classification provision or supplemental classification code—not for rate, note, or program kinds and not to choose the ordinary code. Discover rate and program evidence through the exact resolved classification, its stored edges, and `get_node`. 6. Inventory the treatment paths defined by the selected runtime guide before calculating. Do not request or invent a US-specific family in another system. Include: - every ordinary or base path named by the guide; - each preferential, alternative, or conditional path and its unresolved eligibility or applicability condition; - each supplemental measure, its effective dates, inclusions and exclusions, and the evidence still needed to establish applicability; - raw, parsed, inherited, unknown, or reference expressions and their owners. For US HTS, the inventory is General, each Special path, Column 2, and each possible Chapter 99 or other supplemental measure. 7. Ask only for the inputs demanded by those expressions and paths: entered value and currency for an ad valorem component; quantity and matching unit for a specific component; a supported exchange rate and its effective date/source when line-item currencies differ; origin or program qualification evidence for a conditional treatment; and shipment/entry dates for time-bounded measures. Do not ask for irrelevant product-description facts or re-open classification. 8. Calculate each supported scenario separately. Keep the original precision visible and state any rounding convention: - `free`: duty = 0; - `ad_valorem`: duty = entered value × basis points ÷ 10,000 (or the equivalent stored percentage); - `specific`: duty = source amount per unit × matching quantity, converting cents to the named currency only when the conversion is exact; - `compound` or stacked structured expressions: calculate each supported component as its own line item, then add only components expressed in the same currency. If currencies differ, convert only with a supplied, supported exchange rate and show the conversion; otherwise leave the total unresolved; - inherited rate: use the same formula but identify the ancestor or other owner and the stored `applies_to`/hierarchy path; - base-duty-plus or other referential expression: calculate only when the same-version graph and runtime guide establish every referenced component, its applicability, and the stacking rule. If the runtime guide classifies it as a non-computable `reference`, preserve the raw expression and do not calculate it; - `unknown` parser result: inspect the raw source text. If its operands, units, and operation are unambiguous and the applicable rate path is supported, calculate it, label the interpretation, and retain the raw text and provenance. The parser label is assistance, not a veto; - ambiguous or unsupported expression: preserve the raw source text and state exactly what prevents a calculation. 9. For effective-date comparisons, repeat retrieval and calculation independently in each exact version. Never carry a rate or relationship from one version into another merely because the visible code is unchanged. 10. Stop the bounded first pass once the supported subtotal can be stated and every directly returned unresolved treatment is excluded with a focused question. Do not delay the customer answer to exhaust conditional branches; continue the next evidence pass after the user supplies the requested fact. ## Sufficient-evidence response Return a structured result containing: - a calculation snapshot first: supported duty subtotal, excluded or unresolved charges and treatments, and the single most valuable next question; - the user-supplied ordinary system and code, resolved node label/identifier, exact version, and effective or entry date used; - shipment facts used, including entered value/currency, quantities/units, origin, and any eligibility facts; - separate scenarios for every treatment family defined by the selected runtime guide; for US HTS, General, Special, Column 2, and supplemental measures; - for every computed line: raw rate text, parsed expression, rate kind, owner, inheritance/reference/application path, formula, substituted values, amount, currency/unit, and source provenance; - a total for each supported scenario only when every included line item shares one currency or has a supported, explicit conversion, without presenting mutually exclusive scenarios as additive; - assumptions, rounding, unresolved conditions, and evidence that was not available; - the non-binding-estimate boundary and the charges deliberately excluded. ## Insufficient-evidence response When a safe calculation is not possible, do not force a number. Return: - a calculation snapshot first: no supported subtotal yet (or the bounded subtotal that is already supported), excluded or unresolved charges and treatments, and the single most valuable next question; - the exact system, code, and version/effective date verified so far; - rate paths and raw expressions that were retrieved, kept separate by treatment; - any line items that can already be computed without implying that a conditional path applies; - each unresolved condition or missing operand; - focused follow-up questions ordered by calculation value; - the same non-binding-estimate and excluded-charge boundary. ## Tool discipline Use only the customer-facing `reference` and `references` fields returned by Tariff Code Compliance when naming graph evidence. For every relevant recommended, ancestor, candidate, or rejected code and every decisive note, exclusion, term, or annotation, render a Markdown link in the exact form `[]()` only when `reference.url` is present, substituting both values verbatim from that returned reference. When `reference.url` is absent, show `reference.label` as plain text with readable official provenance; never guess or hand-build a link. Never print or transform node IDs, `system_version_id`, source or storage keys, UUIDs, or page or continuation tokens, including values beginning `ent:`, `sysv:`, or `NATIONAL_`. If an entity-specific reference is unavailable, use the returned exact system/version reference under the same URL-present rule; do not expose the opaque value. Never print a raw `source.locator` field or a path-like locator such as `exportList[...]`; it is an internal storage coordinate, not customer-facing provenance. - Use the exact `system` and `version` returned by discovery on every version-scoped call, and pass the legally relevant date as `effective_at` on every graph call that accepts it. - For a discovered `US_HTS` system, `search_hts` may locate a referenced provision or note lexically and `semantic_search_hts` may separately discover relevant concepts. Pin the same exact version; neither search accepts `effective_at` or page tokens. Verify hits through same-version graph detail and stored relationships with accepted date filters before using them. Search relevance does not establish treatment eligibility, applicability, stacking, or a replacement ordinary classification. - Scope HTS note research only when warranted: `{type: "general_note" | "gri" | "chapter", number: string}`. `"*"` covers general-note or chapter families, not GRI; `chapter` with `number: "*"` and `kinds: ["note"]` searches chapter and section notes. Scope intersects kinds. Missing search results or an unavailable index leave evidence unresolved, not a zero-duty treatment. Other destinations must use their discovered system's contract; never imply planned coverage is available. - Treat opaque node IDs and page tokens as tool-call inputs only, never customer-facing evidence. - Follow continuation tokens only when another page is needed for the calculation. - Respect traversal bounds. If a result is truncated, narrow the relation, direction, or starting nodes. - Treat `tcc.annotation` or equivalent authored commentary as commentary, not source tariff law, and expose its provenance. - Cite official source URLs returned through customer-facing references. Use readable official source names for provenance; never expose raw source locator fields, storage coordinates, or internal paths. Do not present a model-derived interpretation as source text. ## First response and account recovery Ask only for missing prerequisites or the highest-value calculation input. Do not repeat known shipment facts or open with a capabilities list. Keep the supported-subtotal-first response and excluded-charge boundaries above even when the user asks broadly what imports will cost. If a research tool is denied for account access or credits, call `get_account_status` on the existing connection. Explain its safe `access_message` and returned `profile_url`; do not expose account IDs. Pause paid research calls until a fresh status confirms access and credits are available. If status itself is unavailable, explain the blocker without guessing the balance or retrying paid tools. For an authentication failure, direct the user to reconnect through the client's normal connection controls. Never request passwords or tokens, send verification emails, buy credits, or change billing or authentication settings.