MCP Tools Reference

guardrail-sim exposes 12 tools through the Model Context Protocol for AI agent integration.

Setup

Start the MCP server:

npx @guardrail-sim/mcp-server

Add to Claude Desktop config:

{
  "mcpServers": {
    "guardrail-sim": {
      "command": "npx",
      "args": ["@guardrail-sim/mcp-server"]
    }
  }
}

evaluate_policy

Evaluate a proposed discount against the active pricing policy.

Use this tool when:

A B2B buyer requests a discount
You need to check if a discount is allowed before committing
You want to understand the policy constraints for negotiation

Parameters:

Name	Type	Required	Description
`order`	Order	Yes	The order details for evaluation
`proposed_discount`	number	Yes	Requested discount as decimal (0.15 = 15% off)

Order object:

Field	Type	Required	Description
`order_value`	number	Yes	Total order value in dollars
`quantity`	number	Yes	Total units in the order
`product_margin`	number	Yes	Base margin as decimal (0.40 = 40%)
`customer_segment`	string	No	Customer tier (new, bronze, silver, gold, platinum)

Example:

{
  "name": "evaluate_policy",
  "arguments": {
    "order": {
      "order_value": 5000,
      "quantity": 100,
      "product_margin": 0.4,
      "customer_segment": "gold"
    },
    "proposed_discount": 0.12
  }
}

Response:

{
  "approved": true,
  "violations": [],
  "applied_rules": ["margin_floor", "max_discount", "volume_tier"],
  "calculated_margin": 0.28,
  "policy_id": "default",
  "policy_name": "Default Pricing Policy"
}

Response (rejected):

{
  "approved": false,
  "violations": [
    {
      "rule": "margin_floor",
      "message": "Calculated margin falls below 15% floor",
      "ucp_error_code": "discount_code_invalid"
    },
    {
      "rule": "max_discount",
      "message": "Discount exceeds maximum allowed 25%",
      "ucp_error_code": "discount_code_invalid"
    }
  ],
  "applied_rules": ["margin_floor", "max_discount", "volume_tier"],
  "calculated_margin": 0.12,
  "policy_id": "default",
  "policy_name": "Default Pricing Policy"
}

get_policy_summary

Get a human-readable summary of the active policy rules.

Use this tool when:

You need to explain discount limits to a buyer
You want to understand what discounts are possible
Preparing for a negotiation

Parameters: None

Example:

{
  "name": "get_policy_summary",
  "arguments": {}
}

Response:

{
  "policy_id": "default",
  "policy_name": "Default Pricing Policy",
  "rules": [
    {
      "name": "margin_floor",
      "description": "Ensures minimum margin of 15% is maintained after discount"
    },
    {
      "name": "max_discount",
      "description": "Maximum discount cap of 25% regardless of other factors"
    },
    {
      "name": "volume_tier",
      "description": "Orders with quantity < 100 are limited to 10% discount"
    }
  ],
  "summary": "Policy: Default B2B Pricing Policy\nRules:\n1. Margin Floor (15%): Discounts cannot reduce margin below 15%\n2. Max Discount (25%): No discount can exceed 25% regardless of other factors\n3. Volume Tier: Orders with 100+ units qualify for higher discounts (up to 15% vs 10% base)\n\nTo maximize discount approval:\n- Increase order quantity to 100+ units for volume tier benefits\n- Consider products with higher base margins\n- Stay within the 25% maximum cap"
}

get_max_discount

Calculate the maximum allowed discount for a given order.

Use this tool when:

You want to know the ceiling for negotiation
A buyer asks "what's the best you can do?"

Parameters:

Name	Type	Required	Description
`order`	Order	Yes	The order details

Example:

{
  "name": "get_max_discount",
  "arguments": {
    "order": {
      "order_value": 5000,
      "quantity": 50,
      "product_margin": 0.4
    }
  }
}

Response:

{
  "max_discount": 0.1,
  "max_discount_pct": "10%",
  "limiting_factor": "volume_tier",
  "details": "Volume tier limits orders with <100 units to 10% maximum"
}

UCP-Aligned Tools

These tools return responses conforming to the Universal Commerce Protocol specification for agentic commerce.

validate_discount_code

Pre-validate a discount code before applying it to a checkout. Returns UCP-standard error codes.

Use this tool when:

An AI agent wants to pre-validate a discount before checkout
You need UCP-compliant error codes for discount rejection
Building UCP-compatible checkout flows

Parameters:

Name	Type	Required	Description
`code`	string	Yes	The discount code to validate
`discount_amount`	number	Yes	Discount amount in minor currency units (cents)
`order`	Order	Yes	Order context for validation

Example:

{
  "name": "validate_discount_code",
  "arguments": {
    "code": "SUMMER20",
    "discount_amount": 500,
    "order": {
      "order_value": 5000,
      "quantity": 50,
      "product_margin": 0.4
    }
  }
}

Response (approved):

{
  "valid": true
}

Response (rejected):

{
  "valid": false,
  "error_code": "discount_code_user_ineligible",
  "message": "Discount exceeds tier limit (10% base, 15% for qty >= 100)",
  "limiting_factor": "volume_tier"
}

UCP Error Codes

Error Code	Description
`discount_code_invalid`	Code doesn't exist or exceeds limits
`discount_code_expired`	Code is past validity window
`discount_code_user_ineligible`	User doesn't qualify for this discount
`discount_code_combination_disallowed`	Can't combine with other codes
`discount_code_user_not_logged_in`	Requires authentication

simulate_checkout_discount

Simulate a UCP checkout with discount codes applied.

Use this tool when:

Testing how discounts would be applied in a UCP checkout
Simulating multi-code discount scenarios
Validating discount stacking behavior

Parameters:

Name	Type	Required	Description
`codes`	string[]	Yes	Array of discount codes to apply
`line_items`	LineItem[]	Yes	UCP line items for the checkout
`currency`	string	Yes	ISO 4217 currency code (e.g., USD)
`discount_percentage`	number	Yes	Discount percentage to simulate (0.15 = 15%)
`product_margin`	number	No	Base margin for policy evaluation (0.40 = 40%)

LineItem structure:

{
  "item": { "id": "SKU-001" },
  "quantity": 2,
  "subtotal": {
    "amount": 50000,
    "currency": "USD"
  }
}

Example:

{
  "name": "simulate_checkout_discount",
  "arguments": {
    "codes": ["SUMMER20"],
    "line_items": [
      {
        "item": { "id": "SKU-001" },
        "quantity": 2,
        "subtotal": { "amount": 500000, "currency": "USD" }
      },
      {
        "item": { "id": "SKU-002" },
        "quantity": 1,
        "subtotal": { "amount": 250000, "currency": "USD" }
      }
    ],
    "currency": "USD",
    "discount_percentage": 0.1,
    "product_margin": 0.4
  }
}

Response (approved):

{
  "codes": ["SUMMER20"],
  "applied": [
    {
      "code": "SUMMER20",
      "title": "10% Discount",
      "amount": 75000,
      "method": "across",
      "priority": 1,
      "allocations": [
        { "target": "$.line_items[0]", "amount": 50000 },
        { "target": "$.line_items[1]", "amount": 25000 }
      ]
    }
  ],
  "currency": "USD",
  "allocations": [
    { "target": "$.line_items[0]", "amount": 50000 },
    { "target": "$.line_items[1]", "amount": 25000 }
  ]
}

Amounts are plain integers in minor units

amount is a number of cents, not a Money object. And per UCP 2026-04-08 the amount in applied is positive — it states the discount's value. Only the corresponding entry in a checkout's totals[] is negative, because that reflects the effect on the receipt.

Response (rejected):

{
  "codes": ["SUMMER20"],
  "applied": [],
  "messages": [
    {
      "type": "warning",
      "code": "discount_code_invalid",
      "message": "Calculated margin falls below 15% floor",
      "field": "dev.ucp.shopping.discount.codes"
    },
    {
      "type": "warning",
      "code": "discount_code_user_ineligible",
      "message": "Discount exceeds tier limit (10% base, 15% for qty >= 100)",
      "field": "dev.ucp.shopping.discount.codes"
    }
  ],
  "currency": "USD"
}

There is no `rejected` array

Rejections are reported through messages[] with type: "warning", which is what UCP specifies so they surface to the user rather than being handled silently.

Simulation Tools

run_simulation

Runs the adversarial buyer personas against the active policy. Deterministic: the same seed always produces the same sessions.

Parameter	Type	Notes
`orders_per_persona`	`number?`	1-50, default 10. Values above 50 are rejected.
`personas`	`string[]?`	Persona ids; defaults to all five built-ins.
`seed`	`number?`	Default 42.

Returns SimulationMetrics plus seed and persona_count. Note totalEvaluations (one per negotiation round) alongside totalSessions (one per buyer) — rates derived from violationsByRule must divide by the former.

analyze_simulation

Runs a simulation and analyzes the results, returning { metrics, insights } where insights carries total, critical, warnings and the individual items.

UCP Checkout Tools

These five tools implement the UCP checkout capability. Sessions live in memory for the server process lifetime — there is no persistence and no auth.

Tool	Required input	Returns
`create_checkout`	`checkout`	`{ checkout }` — a new session
`get_checkout`	`id`	`{ checkout }`, or a `NOT_FOUND` error
`update_checkout`	`id`, `checkout`	`{ checkout }` with discounts re-evaluated
`complete_checkout`	`id`	`{ checkout }` carrying an order reference
`cancel_checkout`	`id`	`{ checkout }` with status `canceled`

create_checkout, complete_checkout and cancel_checkout accept an optional idempotency_key; replaying a key returns the original session rather than acting twice.

Line items must carry an inline title and price — bare item references are rejected, since the policy engine cannot price them.

Applying discount codes updates totals[]: the discount appears as a negative entry and reduces total, per UCP 2026-04-08.

MCP Tools Reference

MCP Tools Reference

Setup

evaluate_policy

get_policy_summary

get_max_discount

UCP-Aligned Tools

validate_discount_code

UCP Error Codes

simulate_checkout_discount

Simulation Tools

run_simulation

analyze_simulation

UCP Checkout Tools

Best Practices

For Negotiation

For UCP Integration

On this page