Skip to main content
Glama

fulfillment_order

Destructive

Place a manufacturing order from an existing quote and charge the orchestration fee before ordering, with an automatic refund if order placement fails.

Instructions

Place a manufacturing order based on a previous quote.

        Charges the orchestration fee BEFORE placing the order to prevent
        unpaid orders.  If order placement fails after payment, the
        charge is automatically refunded.  On an install that orders
        through Kiln's servers, the servers charge the fee when they
        place the order and the reply says what they charged.

        Args:
            quote_id: Quote ID from ``fulfillment_quote``.
            quote_token: The ``quote_token`` a quote through Kiln's
                servers returned.  Optional: Kiln keeps it beside the
                quote, so ``quote_id`` alone works; when passed it must
                be that token.  An order is placed only from a quote
                taken on this computer.
            shipping_option_id: Shipping option ID from the quote's
                ``shipping_options`` list.
            shipping_address: Optional shipping contact/address dict for
                provider checkout. Keys: ``first_name``, ``last_name``,
                ``email``, ``phone``, ``street``, ``city``,
                ``postal_code``, ``country``; include ``state`` for US.
            shipping_profile_name: Saved shipping profile name to use
                instead of passing ``shipping_address``.
            preview_token: Token from ``issue_preview_token`` after the
                rendered model preview was shown to and approved by the user.
            preview_file_path: Exact model file path that was previewed.
                The preview token is validated against this file's bytes.
            shipping_confirmation_token: Token from
                ``issue_shipping_confirmation_token`` after the contact and
                shipping address were shown to and approved by the user.
            payment_hold_id: PaymentIntent ID from the quote's
                ``payment_hold`` field.  If provided, the previously
                authorized hold is captured before placing the order.
                This is the preferred payment flow.
            quoted_price: Total price returned by ``fulfillment_quote``
                (used to calculate the fee when no ``payment_hold_id``
                is provided).  Required when ``payment_hold_id`` is
                empty and a payment rail is configured.
            quoted_currency: Currency of ``quoted_price`` (default USD).
            jurisdiction: Buyer's region (e.g. ``"US-CA"``, ``"DE"``, ``"AU"``).
                When provided, the response includes an accurate total with
                tax so the user sees exactly what they'll pay — no hidden
                fees.  Use ``tax_jurisdictions`` to see all supported codes.
                On an install that orders through Kiln's servers, pass it
                to ``fulfillment_quote`` instead: the servers pin it to the
                quote and the order is taxed as the quote said.
            business_tax_id: If the buyer is a registered business, their
                tax ID (EU VAT number, AU ABN, etc.).  Businesses in the
                EU, UK, Australia, and Japan are tax-exempt via reverse
                charge — the tax line shows $0.00.

        Use ``fulfillment_order_status`` to track progress after placing.

        Nothing is made until the person pays on the print service's
        checkout, so the reply opens with ``tell_the_person``: the link to
        pay first, then the checkout total with any tax, the print
        service's order terms and a link to them. Pass every line on to
        the person word for word.

        If the person asks whether they can pay with a particular method,
        answer from ``provider_pay_methods`` in the reply: yes for one it
        lists; for any other, say Kiln doesn't know and that the checkout
        page shows every option for their country. Never claim a method
        that isn't listed.
        

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": "fulfillment_order"
  }
}

Input Schema

NameRequiredDescriptionDefault
quote_idYesQuote ID from ``fulfillment_quote``.
quote_tokenNoThe ``quote_token`` a quote through Kiln's servers returned. Optional: Kiln keeps it beside the quote, so ``quote_id`` alone works; when passed it must be that token. An order is placed only from a quote taken on this computer. Default: "".
jurisdictionNoBuyer's region (e.g. ``"US-CA"``, ``"DE"``, ``"AU"``). When provided, the response includes an accurate total with tax so the user sees exactly what they'll pay — no hidden fees. Use ``tax_jurisdictions`` to see all supported codes. On an install that orders through Kiln's servers, pass it to ``fulfillment_quote`` instead: the servers pin it to the quote and the order is taxed as the quote said. Default: "".
quoted_priceNoTotal price returned by ``fulfillment_quote`` (used to calculate the fee when no ``payment_hold_id`` is provided). Required when ``payment_hold_id`` is empty and a payment rail is configured. Default: 0.0.
preview_tokenNoToken from ``issue_preview_token`` after the rendered model preview was shown to and approved by the user. Default: "".
business_tax_idNoIf the buyer is a registered business, their tax ID (EU VAT number, AU ABN, etc.). Businesses in the EU, UK, Australia, and Japan are tax-exempt via reverse charge — the tax line shows $0.00. Default: "".
payment_hold_idNoPaymentIntent ID from the quote's ``payment_hold`` field. If provided, the previously authorized hold is captured before placing the order. This is the preferred payment flow. Default: "".
quoted_currencyNoCurrency of ``quoted_price`` (default USD). Default: "USD".
shipping_addressNoOptional shipping contact/address dict for provider checkout. Keys: ``first_name``, ``last_name``, ``email``, ``phone``, ``street``, ``city``, ``postal_code``, ``country``; include ``state`` for US.
preview_file_pathNoExact model file path that was previewed. The preview token is validated against this file's bytes. Default: "".
shipping_option_idNoShipping option ID from the quote's ``shipping_options`` list. Default: "".
shipping_profile_nameNoSaved shipping profile name to use instead of passing ``shipping_address``. Default: "".
shipping_confirmation_tokenNoToken from ``issue_shipping_confirmation_token`` after the contact and shipping address were shown to and approved by the user. Default: "".

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed13 schema fields changedv1.5.1
    • changedInput schema / properties / business_tax_id / description
      Previous value: -"Default: \"\"."New value: +"If the buyer is a registered business, their tax ID (EU VAT number, AU ABN, etc.).  Businesses in the EU, UK, Australia, and Japan are tax-exempt via reverse charge — the tax line shows $0.00. Default: \"\"."
    • changedInput schema / properties / jurisdiction / description
      Previous value: -"Default: \"\"."New value: +"Buyer's region (e.g. ``\"US-CA\"``, ``\"DE\"``, ``\"AU\"``). When provided, the response includes an accurate total with tax so the user sees exactly what they'll pay — no hidden fees.  Use ``tax_jurisdictions`` to see all supported codes. On an install that orders through Kiln's servers, pass it to ``fulfillment_quote`` instead: the servers pin it to the quote and the order is taxed as the quote said. Default: \"\"."
    • changedInput schema / properties / payment_hold_id / description
      Previous value: -"Default: \"\"."New value: +"PaymentIntent ID from the quote's ``payment_hold`` field.  If provided, the previously authorized hold is captured before placing the order. This is the preferred payment flow. Default: \"\"."
    • changedInput schema / properties / preview_file_path / description
      Previous value: -"Default: \"\"."New value: +"Exact model file path that was previewed. The preview token is validated against this file's bytes. Default: \"\"."
    • changedInput schema / properties / preview_token / description
      Previous value: -"Default: \"\"."New value: +"Token from ``issue_preview_token`` after the rendered model preview was shown to and approved by the user. Default: \"\"."
    • addedInput schema / properties / quote_id / description
      Added value: +"Quote ID from ``fulfillment_quote``."
    • addedInput schema / properties / quote_token
      Added value: +{
      +  "description": "The ``quote_token`` a quote through Kiln's servers returned.  Optional: Kiln keeps it beside the quote, so ``quote_id`` alone works; when passed it must be that token.  An order is placed only from a quote taken on this computer. Default: \"\".",
      +  "title": "Quote Token",
      +  "type": "string"
      +}
    • changedInput schema / properties / quoted_currency / description
      Previous value: -"Default: \"USD\"."New value: +"Currency of ``quoted_price`` (default USD). Default: \"USD\"."
    • changedInput schema / properties / quoted_price / description
      Previous value: -"Default: 0.0."New value: +"Total price returned by ``fulfillment_quote`` (used to calculate the fee when no ``payment_hold_id`` is provided).  Required when ``payment_hold_id`` is empty and a payment rail is configured. Default: 0.0."
    • addedInput schema / properties / shipping_address / description
      Added value: +"Optional shipping contact/address dict for provider checkout. Keys: ``first_name``, ``last_name``, ``email``, ``phone``, ``street``, ``city``, ``postal_code``, ``country``; include ``state`` for US."
    • changedInput schema / properties / shipping_confirmation_token / description
      Previous value: -"Default: \"\"."New value: +"Token from ``issue_shipping_confirmation_token`` after the contact and shipping address were shown to and approved by the user. Default: \"\"."
    • changedInput schema / properties / shipping_option_id / description
      Previous value: -"Default: \"\"."New value: +"Shipping option ID from the quote's ``shipping_options`` list. Default: \"\"."
    • changedInput schema / properties / shipping_profile_name / description
      Previous value: -"Default: \"\"."New value: +"Saved shipping profile name to use instead of passing ``shipping_address``. Default: \"\"."
  2. Changed21 schema fields changedv1.5.0
    • removedInput schema / properties / business_tax_id / default
      Removed value: -""
    • addedInput schema / properties / business_tax_id / description
      Added value: +"Default: \"\"."
    • removedInput schema / properties / jurisdiction / default
      Removed value: -""
    • addedInput schema / properties / jurisdiction / description
      Added value: +"Default: \"\"."
    • removedInput schema / properties / payment_hold_id / default
      Removed value: -""
    • addedInput schema / properties / payment_hold_id / description
      Added value: +"Default: \"\"."
    • removedInput schema / properties / preview_file_path / default
      Removed value: -""
    • addedInput schema / properties / preview_file_path / description
      Added value: +"Default: \"\"."
    • removedInput schema / properties / preview_token / default
      Removed value: -""
    • addedInput schema / properties / preview_token / description
      Added value: +"Default: \"\"."
    • removedInput schema / properties / quoted_currency / default
      Removed value: -"USD"
    • addedInput schema / properties / quoted_currency / description
      Added value: +"Default: \"USD\"."
    • removedInput schema / properties / quoted_price / default
      Removed value: -0
    • addedInput schema / properties / quoted_price / description
      Added value: +"Default: 0.0."
    • removedInput schema / properties / shipping_address / default
      Removed value: -null
    • removedInput schema / properties / shipping_confirmation_token / default
      Removed value: -""
    • addedInput schema / properties / shipping_confirmation_token / description
      Added value: +"Default: \"\"."
    • 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: \"\"."
  3. First observedv0.1.0

TDQS

A4/5.0
Behavior4/5

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

Annotations declare destructiveHint=true and readOnlyHint=false, and the description adds substantial non-obvious behavior beyond them: the orchestration fee is charged BEFORE order placement, automatically refunded if placement fails, and fee-charging differs on Kiln-server installs. It also explains that nothing is manufactured until the end user pays at the provider checkout, and that the reply opens with tell_the_person which must be relayed verbatim. It does not cover idempotency/duplicate-order risk or cancellation windows, so not a 5.

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

Conciseness3/5

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

The opening sentence and the fee/refund paragraph are front-loaded and earn their place, but the description is long and the Args block largely duplicates the schema descriptions word for word. The payment-method guidance in the closing paragraph is useful but sits far from the top and dilutes the core instruction.

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?

This is a high-stakes, money-moving, 13-parameter tool with no output schema, and the description covers the safety-critical elements: fee timing, refund on failure, token prerequisites for preview and shipping confirmation, and what the reply contains. Gaps remain around result shape beyond tell_the_person/provider_pay_methods and what happens on partial failure after the order is placed, but overall it is fit for an agent to call.

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 coverage is 100%, so the description restates the per-parameter docs nearly verbatim rather than adding new meaning. It does add cross-parameter dependency context (quoted_price required when payment_hold_id is empty and a payment rail is configured; preview token validated against preview_file_path bytes), but with the schema already complete, the baseline of 3 applies.

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?

The description opens with a specific verb and resource: "Place a manufacturing order based on a previous quote." It names the upstream tool (fulfillment_quote) that produces the quote_id, and distinguishes itself from fulfillment_order_status (tracking) and fulfillment_cancel, so an agent can route correctly among siblings.

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

Usage Guidelines4/5

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

It states when to use it (fulfill a quote), points to fulfillment_order_status for tracking after placement, and gives explicit conditionals for choosing payment_hold_id over quoted_price and jurisdiction vs. passing jurisdiction to fulfillment_quote on Kiln-server installs. No explicit when-not-to-use exclusion (e.g., don't call twice for the same quote), which keeps it below a 5.

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

Deploy Server

Other Tools