Skip to main content
Glama

Quantum Atlas Stripe X402 Agent Payment Hub

Request Spend Escalation Approval

x402_request_approval

Create a pending single-use human escalation ticket (sba_*) when a delegated subagent needs one-time permission to exceed its standing per-call cap, budget, or route allowlist. Use this after x402_quote_plan returns human_approval_required=true on a delegated key; do not use this to approve/deny tickets (use x402_decide_approval) or permanently raise standing caps (use x402_update_delegate_key). Free and non-charging; requires a valid sbk_* spend key. Once approved by the master operator via x402_decide_approval, pass the returned approval_id to x402_execute_capability within 15 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": {
      "capability_id": "<capability_id>",
      "justification": "<justification>"
    },
    "name": "x402_request_approval"
  }
}

Input Schema

NameRequiredDescriptionDefault
centsNoExact USD cent amount requested for approval (optional for fixed-SKU capabilities where the hub auto-resolves the exact price).
spend_keyNoStripe-funded master or delegated subagent spend key (format: sbk_<43+ chars>). Optional when the caller supplies the x-atlas-spend-key HTTP header.
ttl_minutesNoMinutes the pending ticket remains open awaiting operator decision (1 to 1440; defaults to 60 minutes).
capability_idYesTarget capability_id or route key requiring one-time over-cap execution (e.g. "audio_visual_isolate" or "POST /audio/visual-isolate").
justificationYesConcise human-readable reason explaining why this one-time spend exception is required (shown to the operator in the /x402/ approval queue).

Output Schema

NameRequiredDescriptionDefault
okYesTrue when the pending escalation ticket was recorded.
approvalNo
approval_idNoCreated single-use escalation ticket identifier (sba_*).

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.7/5.0
Behavior5/5

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

Annotations only say the tool is non-read-only, non-destructive, non-idempotent, and closed-world; the description goes well beyond that by disclosing that the ticket is single-use, free and non-charging, requires a valid sbk_* spend key, and expires 15 minutes after operator approval. The 15-minute post-approval window is behavioral context found nowhere in the schema or annotations.

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?

Three sentences, each carrying distinct load: what is created, when to use it versus alternatives, and the post-approval handoff. The core action and its scope are front-loaded, and no sentence is padding.

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 five-parameter mutation tool with annotations and an output schema, the description covers trigger, prerequisites (sbk_* key), cost profile (free), ticket lifecycle, and the downstream call that consumes approval_id. Return-value detail can be left to the output schema, so nothing an agent needs to call this correctly is missing.

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%, so the schema already explains capability_id, justification, cents, spend_key, and ttl_minutes, including the fixed-SKU auto-resolution and the header fallback. The description adds only the general spend-key requirement and the approval_id handoff, not new meaning for individual parameters, so 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?

States a specific verb and resource — 'Create a pending single-use human escalation ticket (sba_*)' — and immediately bounds the scope to delegated subagents exceeding a per-call cap, budget, or route allowlist. It explicitly distinguishes itself from x402_decide_approval and x402_update_delegate_key, so an agent can pick correctly without opening the schema.

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 trigger ('after x402_quote_plan returns human_approval_required=true on a delegated key'), two explicit exclusions with named alternatives, and the follow-up step that makes the ticket useful (pass approval_id to x402_execute_capability within 15 minutes). Nothing about when to select this tool is left to inference.

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