Kiln

Overview Schema Source Related Servers Discussions Admin

issue_shipping_confirmation_token

Destructive

Issues a single-use token after the user confirms shipping details and options, so order fulfillment can proceed only with verified approval.

Instructions

Issue a single-use token after the user confirms shipping details.

        Call this only after showing the normalized contact/shipping address
        and selected shipping option to the user, asking whether Kiln should
        save the address as a profile, and receiving approval.
        ``fulfillment_order`` refuses to place an order without this token.

        Args:
            quote_id: Quote ID from ``fulfillment_quote``.
            shipping_option_id: Shipping option ID selected from the quote.
            shipping_address: Explicit full shipping address.
            shipping_profile_name: Saved profile name to use instead of
                passing ``shipping_address``.
            save_profile_decision: Required when ``shipping_address`` is
                provided directly. Pass ``"save"`` only after the user says
                yes; pass ``"do_not_save"`` after the user says no.
            save_profile_name: Profile name to save when
                ``save_profile_decision`` is ``"save"``.
            overwrite_saved_profile: Replace an existing profile with the
                same name when saving.
            set_default_profile: Make the saved profile the default.
            ttl_seconds: Token lifetime, default 10 minutes.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "quote_id": "<quote_id>"
    },
    "name": "issue_shipping_confirmation_token"
  }
}

Input Schema

Name	Required	Description
`quote_id`	Yes	Quote ID from ``fulfillment_quote``.
`ttl_seconds`	No	Token lifetime, default 10 minutes. Default: 600.
`shipping_address`	No	Explicit full shipping address.
`save_profile_name`	No	Profile name to save when ``save_profile_decision`` is ``"save"``. Default: "".
`shipping_option_id`	No	Shipping option ID selected from the quote. Default: "".
`set_default_profile`	No	Make the saved profile the default. Default: false.
`save_profile_decision`	No	Required when ``shipping_address`` is provided directly. Pass ``"save"`` only after the user says yes; pass ``"do_not_save"`` after the user says no. Default: "".
`shipping_profile_name`	No	Saved profile name to use instead of passing ``shipping_address``. Default: "".
`overwrite_saved_profile`	No	Replace an existing profile with the same name when saving. Default: false.

Schema Changelog

Changes observed during successful MCP inspections.

Changed9 schema fields changedv1.5.1Nov 5, 2026

changedInput schema / properties / overwrite_saved_profile / description

Previous value: -"Default: false."New value: +"Replace an existing profile with the same name when saving. Default: false."

addedInput schema / properties / quote_id / description

Added value: +"Quote ID from ``fulfillment_quote``."

changedInput schema / properties / save_profile_decision / description

Previous value: -"Default: \"\"."New value: +"Required when ``shipping_address`` is provided directly. Pass ``\"save\"`` only after the user says yes; pass ``\"do_not_save\"`` after the user says no. Default: \"\"."

changedInput schema / properties / save_profile_name / description

Previous value: -"Default: \"\"."New value: +"Profile name to save when ``save_profile_decision`` is ``\"save\"``. Default: \"\"."

changedInput schema / properties / set_default_profile / description

Previous value: -"Default: false."New value: +"Make the saved profile the default. Default: false."

addedInput schema / properties / shipping_address / description
```
Added value: +"Explicit full shipping address."
```

changedInput schema / properties / shipping_option_id / description

Previous value: -"Default: \"\"."New value: +"Shipping option ID selected from the quote. Default: \"\"."

changedInput schema / properties / shipping_profile_name / description

Previous value: -"Default: \"\"."New value: +"Saved profile name to use instead of passing ``shipping_address``. Default: \"\"."

changedInput schema / properties / ttl_seconds / description

Previous value: -"Default: 600."New value: +"Token lifetime, default 10 minutes. Default: 600."

Changed15 schema fields changedv1.5.0Oct 23, 2026
- removedInput schema / properties / overwrite_saved_profile / default
```
Removed value: -false
```
- addedInput schema / properties / overwrite_saved_profile / description
```
Added value: +"Default: false."
```
- removedInput schema / properties / save_profile_decision / default
```
Removed value: -""
```
- addedInput schema / properties / save_profile_decision / description
```
Added value: +"Default: \"\"."
```
- removedInput schema / properties / save_profile_name / default
```
Removed value: -""
```
- addedInput schema / properties / save_profile_name / description
```
Added value: +"Default: \"\"."
```
- removedInput schema / properties / set_default_profile / default
```
Removed value: -false
```
- addedInput schema / properties / set_default_profile / description
```
Added value: +"Default: false."
```
- removedInput schema / properties / shipping_address / default
```
Removed value: -null
```
- removedInput schema / properties / shipping_option_id / default
```
Removed value: -""
```
- addedInput schema / properties / shipping_option_id / description
```
Added value: +"Default: \"\"."
```
- removedInput schema / properties / shipping_profile_name / default
```
Removed value: -""
```
- addedInput schema / properties / shipping_profile_name / description
```
Added value: +"Default: \"\"."
```
- removedInput schema / properties / ttl_seconds / default
```
Removed value: -600
```
- addedInput schema / properties / ttl_seconds / description
```
Added value: +"Default: 600."
```
First observedv0.1.0Jul 4, 2026

TDQS

A4.3/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=false and destructiveHint=true; the description adds real context beyond that: the token is single-use, defaults to a 10-minute TTL, and is a hard prerequisite for fulfillment_order. It does not explain why the operation is flagged destructive (e.g., that the downstream order may commit cost), which is the one behavioral gap.

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

Conciseness4/5

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

Purpose and the user-confirmation precondition are front-loaded in the first two paragraphs, which is the right structure. The Args list duplicates the 100%-covered schema field-by-field and could be trimmed to only the constrained parameters, but it is compact and contains no filler.

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

Completeness4/5

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

For a 9-parameter, multi-step workflow tool, the description covers the human-approval requirement, the gating relationship, and token lifetime. The notable omission is what the call returns (token value and expiry shape), which matters since there is no output schema to fall back on.

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

Parameters3/5

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

Schema description coverage is 100% and the Args block largely restates the same sentences verbatim, so most parameter meaning already lives in structured data. The description does add cross-parameter logic implicitly (saving a profile only when shipping_address is supplied), but that logic is also present in the schema field for save_profile_decision.

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 and resource ('Issue a single-use token') and immediately clarifies its role in the ordering flow by noting that 'fulfillment_order refuses to place an order without this token.' That relationship distinguishes it from fulfillment_quote, fulfillment_order, and save_shipping_profile in the sibling list without requiring a schema read.

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?

Gives an explicit pre-call procedure: show the normalized address and selected shipping option, ask whether Kiln should save the address as a profile, and receive approval. It also documents the alternative input paths (pass shipping_address explicitly vs. reuse shipping_profile_name), which is exactly the when/when-not guidance an agent needs.

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

Deploy Server