Checkout Page

create_tax_rate

Destructive

Create a fixed tax rate for use on checkout pages.

Use this tool when a merchant wants to charge a fixed percentage tax (VAT, GST, Sales Tax, etc.) on their checkout pages. Fixed tax rates are used with pages that have tax.mode: "fixed".

Inclusive vs exclusive:

Exclusive (inclusive: false) — tax is added on top of the price. A $100 product with 20% tax costs the customer $120.
Inclusive (inclusive: true) — tax is already included in the price. A $100 product with 20% inclusive tax means $83.33 + $16.67 tax.

Default rate:

Set default: true to make this the account's default tax rate. Pages with tax.mode: "fixed" and no explicit fixedTaxRateIds will use the default rate automatically.
Only one tax rate can be the default at a time. Setting a new default replaces the previous one.

This is not Stripe Tax. Fixed tax rates apply a flat percentage regardless of customer location. To calculate tax dynamically by address, use tax.mode: "stripe" on the page instead (no tax rate needed).

Input Schema

TableJSON Schema

Name	Required	Description
`default`	No	Whether this should be the default tax rate. When `true`, this rate is pre-selected for pages using fixed tax mode and no explicit `fixedTaxRateIds`.
`inclusive`	Yes	Whether the tax is inclusive (`true`, meaning it is already included in the price) or exclusive (`false`, meaning it is added on top of the price).
`percentage`	Yes	Tax rate percentage out of 100. Maximum 2 decimal places.
`displayName`	Yes	Short name describing the type of tax, for example VAT, GST, or Sales Tax. Displayed in the checkout and invoices. Maximum 50 characters.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`data`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedOct 15, 2026

TDQS

A4.7/5.0

Behavior4/5

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

Annotations already declare destructiveHint=true, openWorldHint=false and readOnlyHint=false. The description adds real behavioral context beyond that: the default-replacement side effect ('Only one tax rate can be the default at a time. Setting a new default replaces the previous one'), which explains WHY a create tool is flagged destructive. It does not discuss response shape, but the output schema covers that.

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

Conciseness5/5

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

Front-loaded one-line purpose immediately followed by routing guidance, then bolded sub-sections for inclusive/exclusive, default, and the Stripe Tax distinction. Every section earns its place with no redundancy.

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

Completeness5/5

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

An output schema exists so return values need no explanation, and annotations carry the safety profile. The description covers usage, the inclusive/exclusive semantics, and the default-replacement side effect, so an agent has everything needed to call it correctly.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema with a worked example ($100 with 20% inclusive tax = $83.33 + $16.67) and the default-rate selection behavior, extending the terse schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Create a fixed tax rate for use on checkout pages') and the effect on the account. An agent can immediately tell this apart from read-only siblings like list_tax_rates.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use it (merchant wants a fixed percentage VAT/GST/Sales Tax on fixed-mode pages) and when NOT to, routing the agent to `tax.mode: "stripe"` for dynamic/address-based tax instead. Clear positive and negative guidance.

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

All Checkout Page tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?