Skip to main content
Glama

Validate internet order

validate_order
Idempotent

Start: {"lookup_id":"","offer_id":""}. Poll: {"checkout_id":""}. Edit: {"checkout_id":"","expected_revision":,"details":{}}. Use exactly one shape. Customer, installation, consents and internet_addons belong inside details, never at the root. Start a checkout only when the customer asks to order. Each call waits for progress; while checking, poll with checkout_id only. Edits restart validation. On stale expected_revision, retrieve with checkout_id only before editing at the current revision. required_fields defines the contract; field_errors identifies actual missing/invalid fields relative to details. Refreshes the offer and returns an exact review without submitting an order. When preferred installation dates are required, provide both first and second choices using a time_window value allowed by the input schema. Installation type must be self or professional. Record the customer's explicit true or false choices for auto-pay and paperless billing; never enable them silently. Match the customer's equipment preference using returned equipment_options and catalog facts. Customer-owned equipment, included provider equipment and optional paid equipment are different choices. A free provider gateway does not satisfy an own-equipment request. Price or included status alone does not establish ownership. If an offer lacks the requested option, inspect another qualified offer or explain the limitation and ask the customer to choose; never fabricate an option. Send the complete selection in details.internet_addons using returned option_id and quantity values. Omit it to preserve current/default selections; [] declines optional items. Select at most one radio option and retain dependent parents. Ready means technically valid, not necessarily correct for the customer. Compare the entire review with the customer's budget, speed, equipment, billing and installation choices. Resolve mismatches before requesting authorization. Present every returned charge, discount, condition and unknown; do not invent a price adjustment for declined auto-pay or paperless billing. Never repeat the service PIN or full date of birth, even if supplied earlier. Keep capability IDs, terms_hash and validation_token out of customer-facing prose. Obtain explicit authorization for this exact current review before create_order; shopping intent or validation alone is not authorization.

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

Input Schema

NameRequiredDescriptionDefault
detailsNo
offer_idNo
lookup_idNo
checkout_idNo
expected_revisionNo

Output Schema

NameRequiredDescriptionDefault
errorNo
reviewNo
statusYes
revisionNo
expires_atNo
terms_hashNo
checkout_idNo
next_actionNo
field_errorsNo
schema_versionYes
required_fieldsNo
validation_tokenNo
equipment_optionsNo
retry_after_secondsNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changed
    • addedOutput schema / $defs / CartReview / properties / due_at_activation
      Added value: +{
      +  "anyOf": [
      +    {
      +      "$ref": "#/$defs/OrderAmount"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null
      +}
    • addedOutput schema / $defs / CartReview / properties / monthly_total
      Added value: +{
      +  "anyOf": [
      +    {
      +      "$ref": "#/$defs/OrderAmount"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null
      +}
    • addedOutput schema / $defs / EquipmentOption / properties / required
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "boolean"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "title": "Required"
      +}
    • addedOutput schema / $defs / ReadyOrderReview / properties / due_at_activation
      Added value: +{
      +  "anyOf": [
      +    {
      +      "$ref": "#/$defs/OrderAmount"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null
      +}
    • addedOutput schema / $defs / ReadyOrderReview / properties / monthly_total
      Added value: +{
      +  "anyOf": [
      +    {
      +      "$ref": "#/$defs/OrderAmount"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null
      +}
  2. Changed1 schema field changed
    • changedOutput schema / $defs / ErrorDetail / properties / retry_after_seconds / anyOf
      Previous value: -[
      -  {
      -    "maximum": 300,
      -    "minimum": 1,
      -    "type": "integer"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "maximum": 86400,
      +    "minimum": 1,
      +    "type": "integer"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
  3. Changed3 schema fields changed
    • addedInput schema / $defs / OrderDetails / description
      Added value: +"Edit payload nested inside validate_order.details, never root tool arguments."
    • addedInput schema / $defs / OrderDetails / properties / consents / description
      Added value: +"Customer consent choices at details.consents, using returned consent names."
    • changedInput schema / $defs / OrderDetails / properties / internet_addons / description
      Previous value: -"Complete equipment selection using returned option IDs. Omit to keep the current selection or defaults; send [] to decline optional equipment."New value: +"Complete equipment selection at details.internet_addons using returned option IDs and quantities; retain dependent parents. Omit to keep current selections/defaults; send [] to decline optional equipment. A free provider gateway is not owned equipment."
  4. Changed8 schema fields changed
    • addedInput schema / $defs / EquipmentSelection
      Added value: +{
      +  "additionalProperties": false,
      +  "properties": {
      +    "option_id": {
      +      "maxLength": 256,
      +      "minLength": 1,
      +      "title": "Option Id",
      +      "type": "string"
      +    },
      +    "quantity": {
      +      "minimum": 1,
      +      "title": "Quantity",
      +      "type": "integer"
      +    }
      +  },
      +  "required": [
      +    "option_id",
      +    "quantity"
      +  ],
      +  "title": "EquipmentSelection",
      +  "type": "object"
      +}
    • addedInput schema / $defs / OrderDetails / properties / internet_addons
      Added value: +{
      +  "anyOf": [
      +    {
      +      "items": {
      +        "$ref": "#/$defs/EquipmentSelection"
      +      },
      +      "maxItems": 100,
      +      "type": "array"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Complete equipment selection using returned option IDs. Omit to keep the current selection or defaults; send [] to decline optional equipment.",
      +  "title": "Internet Addons"
      +}
    • addedOutput schema / $defs / CartReview
      Added value: +{
      +  "additionalProperties": false,
      +  "properties": {
      +    "bundle_discount": {
      +      "anyOf": [
      +        {
      +          "$ref": "#/$defs/OrderAmount"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "default": null
      +    },
      +    "included_products": {
      +      "$ref": "#/$defs/IncludedProducts"
      +    },
      +    "one_time_fees": {
      +      "items": {
      +        "$ref": "#/$defs/OneTimeFee"
      +      },
      +      "maxItems": 100,
      +      "title": "One Time Fees",
      +      "type": "array"
      +    },
      +    "selected_plan": {
      +      "$ref": "#/$defs/IncludedProduct"
      +    },
      +    "total_amount": {
      +      "$ref": "#/$defs/OrderAmount"
      +    }
      +  },
      +  "required": [
      +    "selected_plan",
      +    "included_products",
      +    "one_time_fees",
      +    "total_amount"
      +  ],
      +  "title": "CartReview",
      +  "type": "object"
      +}
    • addedOutput schema / $defs / EquipmentOption
      Added value: +{
      +  "additionalProperties": false,
      +  "properties": {
      +    "included": {
      +      "title": "Included",
      +      "type": "boolean"
      +    },
      +    "max_quantity": {
      +      "minimum": 1,
      +      "title": "Max Quantity",
      +      "type": "integer"
      +    },
      +    "name": {
      +      "maxLength": 300,
      +      "minLength": 1,
      +      "title": "Name",
      +      "type": "string"
      +    },
      +    "option_id": {
      +      "maxLength": 256,
      +      "minLength": 1,
      +      "title": "Option Id",
      +      "type": "string"
      +    },
      +    "selected_quantity": {
      +      "minimum": 0,
      +      "title": "Selected Quantity",
      +      "type": "integer"
      +    },
      +    "selection_type": {
      +      "enum": [
      +        "radio",
      +        "checkbox"
      +      ],
      +      "title": "Selection Type",
      +      "type": "string"
      +    },
      +    "unit_pricing": {
      +      "$ref": "#/$defs/OrderAmount"
      +    }
      +  },
      +  "required": [
      +    "option_id",
      +    "name",
      +    "selection_type",
      +    "included",
      +    "unit_pricing",
      +    "max_quantity",
      +    "selected_quantity"
      +  ],
      +  "title": "EquipmentOption",
      +  "type": "object"
      +}
    • addedOutput schema / $defs / OfferChangedReview / properties / current_cart
      Added value: +{
      +  "anyOf": [
      +    {
      +      "$ref": "#/$defs/CartReview"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null
      +}
    • addedOutput schema / $defs / OfferChangedReview / properties / previous_cart
      Added value: +{
      +  "anyOf": [
      +    {
      +      "$ref": "#/$defs/CartReview"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null
      +}
    • addedOutput schema / $defs / ReadyOrderReview / properties / bundle_discount
      Added value: +{
      +  "anyOf": [
      +    {
      +      "$ref": "#/$defs/OrderAmount"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null
      +}
    • addedOutput schema / properties / equipment_options
      Added value: +{
      +  "items": {
      +    "$ref": "#/$defs/EquipmentOption"
      +  },
      +  "maxItems": 100,
      +  "title": "Equipment Options",
      +  "type": "array"
      +}
  5. Changed4 schema fields changed
    • changedInput schema / $defs / BillingPreferences / properties / auto_pay / anyOf
      Previous value: -[
      -  {
      -    "const": true,
      -    "type": "boolean"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "type": "boolean"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedInput schema / $defs / BillingPreferences / properties / paperless_billing / anyOf
      Previous value: -[
      -  {
      -    "const": true,
      -    "type": "boolean"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "type": "boolean"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedOutput schema / $defs / BillingPreferences / properties / auto_pay / anyOf
      Previous value: -[
      -  {
      -    "const": true,
      -    "type": "boolean"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "type": "boolean"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedOutput schema / $defs / BillingPreferences / properties / paperless_billing / anyOf
      Previous value: -[
      -  {
      -    "const": true,
      -    "type": "boolean"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "type": "boolean"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
  6. Changed6 schema fields changed
    • changedInput schema / $defs / BillingPreferences / properties / auto_pay / anyOf
      Previous value: -[
      -  {
      -    "type": "boolean"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "const": true,
      +    "type": "boolean"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedInput schema / $defs / BillingPreferences / properties / paperless_billing / anyOf
      Previous value: -[
      -  {
      -    "type": "boolean"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "const": true,
      +    "type": "boolean"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedInput schema / $defs / InstallationDetails / properties / type / anyOf
      Previous value: -[
      -  {
      -    "enum": [
      -      "self",
      -      "professional",
      -      "no_preference"
      -    ],
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "enum": [
      +      "self",
      +      "professional"
      +    ],
      +    "type": "string"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedOutput schema / $defs / BillingPreferences / properties / auto_pay / anyOf
      Previous value: -[
      -  {
      -    "type": "boolean"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "const": true,
      +    "type": "boolean"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedOutput schema / $defs / BillingPreferences / properties / paperless_billing / anyOf
      Previous value: -[
      -  {
      -    "type": "boolean"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "const": true,
      +    "type": "boolean"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedOutput schema / $defs / InstallationDetails / properties / type / anyOf
      Previous value: -[
      -  {
      -    "enum": [
      -      "self",
      -      "professional",
      -      "no_preference"
      -    ],
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "enum": [
      +      "self",
      +      "professional"
      +    ],
      +    "type": "string"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
  7. Changed8 schema fields changed
    • addedOutput schema / $defs / IncludedProduct
      Added value: +{
      +  "additionalProperties": false,
      +  "properties": {
      +    "name": {
      +      "maxLength": 300,
      +      "minLength": 1,
      +      "title": "Name",
      +      "type": "string"
      +    },
      +    "quantity": {
      +      "minimum": 1,
      +      "title": "Quantity",
      +      "type": "integer"
      +    },
      +    "total_pricing": {
      +      "$ref": "#/$defs/OrderAmount"
      +    },
      +    "unit_pricing": {
      +      "$ref": "#/$defs/OrderAmount"
      +    }
      +  },
      +  "required": [
      +    "name",
      +    "quantity",
      +    "unit_pricing",
      +    "total_pricing"
      +  ],
      +  "title": "IncludedProduct",
      +  "type": "object"
      +}
    • addedOutput schema / $defs / IncludedProducts
      Added value: +{
      +  "additionalProperties": false,
      +  "properties": {
      +    "internet": {
      +      "items": {
      +        "$ref": "#/$defs/IncludedProduct"
      +      },
      +      "maxItems": 100,
      +      "title": "Internet",
      +      "type": "array"
      +    },
      +    "television": {
      +      "items": {
      +        "$ref": "#/$defs/IncludedProduct"
      +      },
      +      "maxItems": 100,
      +      "title": "Television",
      +      "type": "array"
      +    },
      +    "television_add_ons": {
      +      "items": {
      +        "$ref": "#/$defs/IncludedProduct"
      +      },
      +      "maxItems": 100,
      +      "title": "Television Add Ons",
      +      "type": "array"
      +    }
      +  },
      +  "title": "IncludedProducts",
      +  "type": "object"
      +}
    • addedOutput schema / $defs / OneTimeFee
      Added value: +{
      +  "additionalProperties": false,
      +  "properties": {
      +    "description": {
      +      "maxLength": 1000,
      +      "minLength": 1,
      +      "title": "Description",
      +      "type": "string"
      +    },
      +    "fee_type": {
      +      "maxLength": 100,
      +      "minLength": 1,
      +      "title": "Fee Type",
      +      "type": "string"
      +    },
      +    "name": {
      +      "maxLength": 300,
      +      "minLength": 1,
      +      "title": "Name",
      +      "type": "string"
      +    },
      +    "pricing": {
      +      "$ref": "#/$defs/OrderAmount"
      +    }
      +  },
      +  "required": [
      +    "name",
      +    "description",
      +    "pricing",
      +    "fee_type"
      +  ],
      +  "title": "OneTimeFee",
      +  "type": "object"
      +}
    • addedOutput schema / $defs / OrderAmount
      Added value: +{
      +  "additionalProperties": false,
      +  "properties": {
      +    "amount_cents": {
      +      "minimum": 0,
      +      "title": "Amount Cents",
      +      "type": "integer"
      +    },
      +    "amount_currency": {
      +      "pattern": "^[A-Z]{3}$",
      +      "title": "Amount Currency",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "amount_cents",
      +    "amount_currency"
      +  ],
      +  "title": "OrderAmount",
      +  "type": "object"
      +}
    • addedOutput schema / $defs / ReadyOrderReview / properties / included_products
      Added value: +{
      +  "$ref": "#/$defs/IncludedProducts"
      +}
    • addedOutput schema / $defs / ReadyOrderReview / properties / one_time_fees
      Added value: +{
      +  "items": {
      +    "$ref": "#/$defs/OneTimeFee"
      +  },
      +  "maxItems": 100,
      +  "title": "One Time Fees",
      +  "type": "array"
      +}
    • addedOutput schema / $defs / ReadyOrderReview / properties / total_amount
      Added value: +{
      +  "$ref": "#/$defs/OrderAmount"
      +}
    • changedOutput schema / $defs / ReadyOrderReview / required
      Previous value: -[
      -  "provider_name",
      -  "selected_offer",
      -  "service_address",
      -  "unknown_charges_remain_unknown"
      -]New value: +[
      +  "provider_name",
      +  "selected_offer",
      +  "included_products",
      +  "one_time_fees",
      +  "total_amount",
      +  "service_address",
      +  "unknown_charges_remain_unknown"
      +]
  8. Changed2 schema fields changed
    • changedInput schema / $defs / InstallationChoice / properties / time_window / anyOf
      Previous value: -[
      -  {
      -    "maxLength": 100,
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "enum": [
      +      "8:00 AM - 12:00 PM (Local Time)",
      +      "12:00 PM - 5:00 PM (Local Time)"
      +    ],
      +    "type": "string"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedOutput schema / $defs / InstallationChoice / properties / time_window / anyOf
      Previous value: -[
      -  {
      -    "maxLength": 100,
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "enum": [
      +      "8:00 AM - 12:00 PM (Local Time)",
      +      "12:00 PM - 5:00 PM (Local Time)"
      +    ],
      +    "type": "string"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
  9. Changed1 schema field changed
    • addedInput schema / $defs / MailingAddress / properties / same_as_service
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "boolean"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "title": "Same As Service"
      +}
  10. Added

TDQS

A4.6/5.0
Behavior5/5

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

Adds a lot beyond the annotations: each call blocks/waits for progress, edits restart validation, the call refreshes the offer, it returns an exact review but never submits an order, and it is subject to optimistic concurrency via expected_revision. It also discloses side effects and handling rules the annotations cannot express, such as never enabling auto-pay/paperless silently, omitting internet_addons to preserve defaults, and [] declining optional items.

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 content mostly earns its place given the multi-mode contract and business rules, but it is delivered as a dense, run-on wall of text with no headings or bullet separation, and the most important scoping rules sit far from the top. Several statements duplicate what the schema already says (details nesting, addons omit-vs-empty-array), which adds length without new information.

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?

For a complex, multi-mode, open-world tool with five optional root parameters, an output schema, and optimistic concurrency, the description covers everything an agent needs: mode selection, field placement, error semantics, the required_fields vs field_errors contract, ready meaning 'technically valid, not necessarily correct', and the authorization gate before create_order. Return values are correctly left to the output schema, and PII handling (never repeat service PIN or full DOB) is stated.

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

Parameters5/5

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

With 0% schema description coverage, the description carries the full burden and does so: it defines the three legal argument shapes, states that exactly one must be used, and insists customer, installation, consents and internet_addons live inside details and never at the root. It further constrains values the schema leaves opaque, such as installation type self/professional, time_window values allowed by the schema, option_id and quantity for addons, and at most one radio option with dependent parents retained.

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

Purpose4/5

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

The description conveys a specific resource and action: it starts/polls/edits a checkout for an internet order and returns an exact review without submitting. It also names its sibling boundary ('before create_order; shopping intent or validation alone is not authorization'). The one weakness is front-loading: the opening is a set of JSON call-shape templates rather than a plain statement of purpose, so the actual definition ('Refreshes the offer and returns an exact review') has to be excavated from the middle.

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?

Explicit when-to-use and when-not guidance across all three modes: start a checkout only when the customer asks to order, poll with checkout_id only while checking, edit only with checkout_id plus current revision, and never treat validation as authorization to create_order. It also handles error routing (on stale expected_revision, retrieve with checkout_id only before editing) and the alternative path when an offer lacks an option ('inspect another qualified offer or explain the limitation').

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources