Tools

These are the tools available to AI agents connected to Axiom via MCP. Each tool requires specific scopes to be granted during authorization.

Axiom runs the entire merchant checkout server-side. An agent starts a purchase and polls for its status; it never sees card details or drives the merchant site itself. See How It Works for the full flow.

The purchase-finality contract

Purchase responses carry explicit finality fields so an agent never over-reports success:

• isFinal (boolean): whether the purchase has reached a terminal state.
• safeToTellUserComplete (boolean): an agent must not tell the user a purchase succeeded unless status is completed and this is true. Intermediate transaction states, payment authorization, card issuance, audit-trail entries, and progress labels are not completion signals.
• nextAction: what the agent should do next: poll_get_purchase_status, open_approval_link_then_wait_for_user, submit_purchase_clarification, tell_user_complete, tell_user_failed, or none.
• finalityMessage: a human-readable summary of the current state.

Account Tools

get_payment_method

Returns the user's linked payment method. Only the card brand and last 4 digits are returned. Use it to confirm a card is on file before starting a purchase.

• Scope: account:read
• Parameters: None
• Returns: Card brand and last 4 digits, or a message if no payment method is linked

Purchase Tools

make_purchase

The single entry point for a purchase. Axiom validates the request against an LLM intent mandate (purchase intent + prohibited-merchant screening), then starts a server-managed browser checkout. Returns immediately: it never waits on the browser pipeline. Poll get_purchase_status for progress and the final receipt.

• Scope: payments:write
• Parameters:
  • userCommand (string, required): The user's original instruction, near-verbatim. This is the audit/intent record; don't paraphrase or fold resolved specifics into it.
  • merchant (object, required):
    • merchantName (string): Resolved brand name (e.g. Chewy), not a category.
    • merchantURL (string): Merchant URL the browser session starts from. Prefer the product detail page; fall back to the merchant homepage.
  • itemName (string, required): The specific resolved product (include variants like size/color/quantity when known), not a category.
  • intentContext (object, optional): Context for terse or elliptical commands ("same one", "buy that", "try again") when the purchase is justified by conversation context rather than the literal userCommand:
    • resolvedUserIntent (string): Concise, audit-safe interpretation of the intended purchase.
    • evidence (string[], 1–5 entries): Concrete supporting evidence: short prior-message summaries, visible app state, or a remembered preference. Without evidence, Axiom may ask for clarification instead of starting checkout.
    • resolutionSummary (string, optional): Concise rationale mapping the evidence to this purchase.
  • itemSubtotal (number, optional): Line-item subtotal in dollars the user approved (pre-shipping/tax/fees). Caps the line-item total at payment time.
  • preferences (object, optional): fulfillment (shipping | pickup | delivery), substitutionsAllowed (boolean), maxTipCents (number), notes (string).
• Returns: A status and, when started, a browserPurchaseSessionID. Status is one of running, needs_clarification, unavailable, mandate_denied, failed, cancelled, or human_needed. Responses also carry the finality fields (isFinal, safeToTellUserComplete, nextAction).

get_purchase_status

Polls a purchase started by make_purchase. Each call waits up to 30 seconds for the next parked or terminal status change, then returns it. If the purchase is still running when the wait elapses, the response says so; call it again in a loop with the same browserPurchaseSessionID. End-to-end purchases often take around 10–15 minutes, so expect several polling rounds.

• Scope: payments:read
• Parameters:
  • browserPurchaseSessionID (string, required): Returned by make_purchase.
• Returns: status (running, awaiting_approval, awaiting_user_input, completed, human_needed, failed, cancelled), public progressStage / progressLabel, the finality fields, an approvalLink when approval is required, a userInputRequest when clarification is needed, and the receipt (including any applied discounts), finalTotal, cart, and transactionUrl on completion.

The transactionUrl links to the transaction page in the Axiom dashboard; it's the canonical link agents should surface to users. The merchant's own order-confirmation URL is intentionally omitted; users reach it through the Axiom app.

Polling etiquette: while status is running, keep calling in a loop. On awaiting_approval, stop polling, send the approvalLink to the user, and resume polling only after they say they've approved. On awaiting_user_input, ask the userInputRequest question and resume with submit_purchase_clarification.

submit_purchase_clarification

Submits the user's answer when get_purchase_status returns awaiting_user_input, and resumes the checkout on the same session.

• Scope: payments:write

• Parameters:

  • browserPurchaseSessionID (string, required)
  • requestID (string, required): From userInputRequest.requestID.
  • selectedOptionID (string, optional): An option from userInputRequest.options[].
  • userInput (string, optional): Free-text answer when allowed.

  Provide selectedOptionID, userInput, or both.

Transaction Tools

list_transactions

Returns the user's recent transactions, most recent first.

• Scope: transactions:read
• Parameters:
  • limit (number, optional): Maximum number of transactions to return (1–100, default 20)
• Returns: transactions (array of transaction summaries with amount, merchant, status, timestamps, and finality), plus count (returned) and total (available)

get_transaction

Returns a single transaction with its full detail, including the receipt and audit trail. Do not treat transaction status, audit-trail entries, payment authorization, or card issuance as purchase success unless purchaseFinality.safeToTellUserComplete is true.

• Scope: transactions:read
• Parameters:
  • transactionId (string, required): The transaction ID to retrieve
• Returns: Transaction status, transactionUrl (the canonical Axiom dashboard link), merchant and merchantImageUrl, amount, approval state, purchaseFinality, receipt (items, taxes and fees, discounts, shipping, total, order number), and audit trail