tax_estimate
Read-only
Preview the full order price breakdown, including tax on the orchestration fee, before placing an order so buyers see exact line items with no hidden fees.
Instructions
Preview the complete price breakdown — including tax — before placing an order.
Terms §7 contract: "Preview the tax for any order with the
``tax_estimate`` tool before placing it. We display the full
fee + tax breakdown before charging. No hidden fees."
This tool fulfills that contract by returning the same line
items the order will commit to at charge time. Per Terms §7
tax is computed on the orchestration fee ONLY — never on
the manufacturer's quoted total. The manufacturer is
responsible for any taxes on their own charges.
Two calling shapes are supported:
1. **Canonical preview** (recommended): pass
``manufacturer_quote_usd`` and the tool returns the
full breakdown — ``manufacturer_quote``,
``orchestration_fee``, ``tax_on_fee``, ``total`` — so
the agent can show the user the exact line items that
match the eventual charge. This is the shape Terms §7
commits to.
2. **Tax-only legacy** (compatibility): pass ``fee_amount``
with no ``manufacturer_quote_usd`` and the tool returns
the older ``{tax: {...}}`` shape, useful for callers
that already know the fee and only want the tax line.
Args:
fee_amount: Legacy — the platform fee amount (from the
quote's ``kiln_fee``). Used only when
``manufacturer_quote_usd`` is omitted.
jurisdiction: Where the buyer is located (e.g.
``"US-CA"``, ``"DE"``, ``"AU"``). Use
``tax_jurisdictions`` to see all supported codes.
When empty in canonical-preview mode, no tax is
applied (preview shows manuf + fee only).
business_tax_id: If the buyer is a business, their tax
ID (e.g. EU VAT number). In the EU, UK, Australia,
and Japan, businesses are exempt — the tax line
shows $0.00 with a note that reverse charge
applies.
manufacturer_quote_usd: Provider's quoted price (e.g.
from ``fulfillment_quote``). When non-zero,
triggers canonical-preview mode.
currency: Currency of the manufacturer quote (default
USD). Tax rates are applied at the standard
jurisdiction rate regardless.
user_email: Buyer's email, so the preview can apply any
fee waiver the buyer's plan carries this month. Read
in canonical-preview mode only.
Returns:
Canonical mode (``manufacturer_quote_usd > 0``):
``{success, manufacturer_quote, orchestration_fee,
tax_on_fee, total, currency, fee_waived,
fee_waiver_reason, tax_jurisdiction,
tax_rate_percent, tax_reverse_charge, note}``.
Legacy mode (``manufacturer_quote_usd == 0``):
``{success, tax: {...}}``.
Read-only — charges no card, contacts no provider.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "tax_estimate"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| currency | No | Currency of the manufacturer quote (default USD). Tax rates are applied at the standard jurisdiction rate regardless. Default: "USD". | |
| fee_amount | No | Legacy — the platform fee amount (from the quote's ``kiln_fee``). Used only when ``manufacturer_quote_usd`` is omitted. Default: 0.0. | |
| user_email | No | Buyer's email, so the preview can apply any fee waiver the buyer's plan carries this month. Read in canonical-preview mode only. Default: "". | |
| jurisdiction | No | Where the buyer is located (e.g. ``"US-CA"``, ``"DE"``, ``"AU"``). Use ``tax_jurisdictions`` to see all supported codes. When empty in canonical-preview mode, no tax is applied (preview shows manuf + fee only). Default: "". | |
| business_tax_id | No | If the buyer is a business, their tax ID (e.g. EU VAT number). In the EU, UK, Australia, and Japan, businesses are exempt — the tax line shows $0.00 with a note that reverse charge applies. Default: "". | |
| manufacturer_quote_usd | No | Provider's quoted price (e.g. from ``fulfillment_quote``). When non-zero, triggers canonical-preview mode. Default: 0.0. |