Skip to main content
Glama

NAIF Agent Gravity — MCP Diagnostics & Recovery

Delegated Purchase (Capped)

request_delegated_purchase

Use ONLY for an owner/platform-preauthorized autonomous purchase of one of four supported micro-services under an explicit spending cap. Unlike prepare_repair, this tool does not consume an existing quoteId: it creates its own quote, accepts it, and creates checkout within the delegation. Repeating the call may create a new quote/checkout, so it is intentionally non-idempotent. Do NOT use it when quote_repair already produced a quoteId or for general repair services outside the four listed micro-services; use prepare_repair for an existing repair quote. Supports wallet rails and APPLE_PAY_AUTO. APPLE_PAY_AUTO requires one human Apple Pay approval first; when Tap returns an ACTIVE saved-card payment agreement, later purchases may be charged only within the stored cap. If provider support or authorization is missing, the flow fails closed.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
sourceNoOptional attribution label for the calling agent or integration.
productIdYesExactly one of the four services allowed for delegated purchase. For any other repair service, use diagnose_issue → quote_repair → prepare_repair.
descriptionYesSanitized bounded work description for the delegated micro-service; never include secrets, credentials or private keys.
paymentRailNoDelegated-purchase rail policy. AUTO chooses an eligible wallet rail; APPLE_PAY_AUTO uses or establishes the capped Tap authorization. This is not the manual rail selection for prepare_repair.
maxAmountUsdYesOwner/platform per-purchase spending cap in USD-equivalent. The quote must fit inside this cap and the service launch price.
dailyLimitUsdNoRequested daily APPLE_PAY_AUTO cap used only during first-time authorization setup; maximum 20 USD.
authorizeCheckoutYesExplicit permission for this tool to create its own quote, accept it, and create checkout within the supplied cap. If a quoteId already exists, use prepare_repair instead.
authorizedMerchantYesMerchant scope explicitly authorized by the owner/platform for this delegated purchase flow.
applePayAuthorizationTokenNoOpaque token returned by the one-time APPLE_PAY_AUTO setup. Supply only a token from this delegated authorization flow; never provide card data or raw Apple Pay payloads.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
jobNoRepair/delivery job attached by the existing verified-payment workflow when available; may be null.
errorNoFail-closed error code when delegation, price, provider authorization, quote, checkout, or payment requirements are not satisfied.
stateNoProvider/checkout state when returned.
statusNoDelegated-purchase state such as PAYMENT_REQUIRED, ONE_TIME_APPLE_PAY_AUTHORIZATION_REQUIRED, APPLE_PAY_AUTHORIZATION_NOT_ACTIVE, or a provider payment state.
detailsNoBounded provider/commerce error details when available.
quoteIdNoQuote created by this delegated call. It was not supplied by the caller.
nextToolNoFor wallet rails, verify_checkout_payment after the payer submits the exact transfer.
verifiedNoWhen returned by the provider flow, true only for a verified payment.
paymentIdNoVerified payment identifier when returned by the provider flow.
productIdNoOne of the four delegated micro-service product identifiers.
checkoutIdNoCheckout created by this delegated call when quote creation/acceptance succeeded.
payerActionNoRequired human/payer action before payment can be considered complete.
paymentRailNoRail actually selected for this delegated purchase.
automaticJobNoFalse when no verified-payment job has been attached yet.
authorizationNoAPPLE_PAY_AUTO authorization setup/status information, potentially including the one-time human authorization URL/token. Never interpret this object alone as payment success.
automaticQuoteNoTrue when this tool created the delegated quote itself.
automaticPaymentNoFalse for wallet flows and authorization setup; may only become provider-driven within a previously ACTIVE APPLE_PAY_AUTO agreement.
automaticCheckoutNoTrue when this tool created checkout under the delegation.
nextToolArgumentsNoSuggested verification arguments for the wallet checkout; txHash remains caller-supplied after payment.
automaticExecutionNoFalse until the existing post-payment workflow has verified payment; this tool does not execute unpaid work.
automaticAcceptanceNoTrue when the delegated quote was automatically accepted under explicit owner/platform authorization.
paymentInstructionsNoWallet transfer instructions for an existing delegated checkout; the tool does not send the transfer.
delegatedAuthorizationNoEcho of the enforced merchant/spending delegation, including cap and whether quote acceptance/checkout creation were authorized.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed32 schema fields changed
    • changedInput schema / properties / applePayAuthorizationToken / description
      Previous value: -"Opaque token returned by the APPLE_PAY_AUTO setup. Do not provide card data or Apple Pay payloads."New value: +"Opaque token returned by the one-time APPLE_PAY_AUTO setup. Supply only a token from this delegated authorization flow; never provide card data or raw Apple Pay payloads."
    • changedInput schema / properties / authorizeCheckout / description
      Previous value: -"Permission to create quote + acceptance + checkout within the stated cap."New value: +"Explicit permission for this tool to create its own quote, accept it, and create checkout within the supplied cap. If a quoteId already exists, use prepare_repair instead."
    • changedInput schema / properties / authorizedMerchant / description
      Previous value: -"Merchant scope authorized by the owner/platform."New value: +"Merchant scope explicitly authorized by the owner/platform for this delegated purchase flow."
    • changedInput schema / properties / dailyLimitUsd / description
      Previous value: -"Requested daily APPLE_PAY_AUTO cap during setup; maximum 20 USD."New value: +"Requested daily APPLE_PAY_AUTO cap used only during first-time authorization setup; maximum 20 USD."
    • changedInput schema / properties / description / description
      Previous value: -"Sanitized bounded work description; never include secrets, credentials or private keys."New value: +"Sanitized bounded work description for the delegated micro-service; never include secrets, credentials or private keys."
    • changedInput schema / properties / maxAmountUsd / description
      Previous value: -"Per-purchase spending cap in USD-equivalent."New value: +"Owner/platform per-purchase spending cap in USD-equivalent. The quote must fit inside this cap and the service launch price."
    • changedInput schema / properties / paymentRail / description
      Previous value: -"Choose APPLE_PAY_AUTO for one-time authorization followed by capped automatic purchases."New value: +"Delegated-purchase rail policy. AUTO chooses an eligible wallet rail; APPLE_PAY_AUTO uses or establishes the capped Tap authorization. This is not the manual rail selection for prepare_repair."
    • changedInput schema / properties / productId / description
      Previous value: -"One of the four delegated-purchase micro-services."New value: +"Exactly one of the four services allowed for delegated purchase. For any other repair service, use diagnose_issue → quote_repair → prepare_repair."
    • changedOutput schema / description
      Previous value: -"For wallet rails returns payment instructions. For APPLE_PAY_AUTO, first use returns a one-time humanAuthorizationUrl plus authorizationToken; subsequent use with an ACTIVE token may return PAYMENT_VERIFIED automatically. Provider activation failures fail closed."New value: +"Result of a capped delegated purchase attempt. For wallet rails, success creates and accepts a quote plus checkout and returns PAYMENT_REQUIRED with payer instructions; payment itself remains external. For APPLE_PAY_AUTO, first use may return ONE_TIME_APPLE_PAY_AUTHORIZATION_REQUIRED with human authorization data, while a later call with an ACTIVE authorization token may return provider payment-verification fields. Treat error or a non-confirmed status as not paid. This schema describes the delegated flow only; normal existing-quote repairs use prepare_repair."
    • addedOutput schema / properties / authorization / description
      Added value: +"APPLE_PAY_AUTO authorization setup/status information, potentially including the one-time human authorization URL/token. Never interpret this object alone as payment success."
    • addedOutput schema / properties / automaticAcceptance / description
      Added value: +"True when the delegated quote was automatically accepted under explicit owner/platform authorization."
    • addedOutput schema / properties / automaticCheckout / description
      Added value: +"True when this tool created checkout under the delegation."
    • addedOutput schema / properties / automaticExecution / description
      Added value: +"False until the existing post-payment workflow has verified payment; this tool does not execute unpaid work."
    • addedOutput schema / properties / automaticJob
      Added value: +{
      +  "description": "False when no verified-payment job has been attached yet.",
      +  "type": "boolean"
      +}
    • addedOutput schema / properties / automaticPayment / description
      Added value: +"False for wallet flows and authorization setup; may only become provider-driven within a previously ACTIVE APPLE_PAY_AUTO agreement."
    • addedOutput schema / properties / automaticQuote / description
      Added value: +"True when this tool created the delegated quote itself."
    • addedOutput schema / properties / checkoutId / description
      Added value: +"Checkout created by this delegated call when quote creation/acceptance succeeded."
    • addedOutput schema / properties / delegatedAuthorization / description
      Added value: +"Echo of the enforced merchant/spending delegation, including cap and whether quote acceptance/checkout creation were authorized."
    • addedOutput schema / properties / details
      Added value: +{
      +  "description": "Bounded provider/commerce error details when available."
      +}
    • addedOutput schema / properties / error / description
      Added value: +"Fail-closed error code when delegation, price, provider authorization, quote, checkout, or payment requirements are not satisfied."
    • addedOutput schema / properties / job
      Added value: +{
      +  "description": "Repair/delivery job attached by the existing verified-payment workflow when available; may be null."
      +}
    • addedOutput schema / properties / nextTool
      Added value: +{
      +  "description": "For wallet rails, verify_checkout_payment after the payer submits the exact transfer.",
      +  "type": "string"
      +}
    • addedOutput schema / properties / nextToolArguments
      Added value: +{
      +  "additionalProperties": true,
      +  "description": "Suggested verification arguments for the wallet checkout; txHash remains caller-supplied after payment.",
      +  "type": "object"
      +}
    • addedOutput schema / properties / payerAction
      Added value: +{
      +  "description": "Required human/payer action before payment can be considered complete.",
      +  "type": "string"
      +}
    • addedOutput schema / properties / paymentId
      Added value: +{
      +  "description": "Verified payment identifier when returned by the provider flow.",
      +  "type": "string"
      +}
    • addedOutput schema / properties / paymentInstructions / description
      Added value: +"Wallet transfer instructions for an existing delegated checkout; the tool does not send the transfer."
    • addedOutput schema / properties / paymentRail / description
      Added value: +"Rail actually selected for this delegated purchase."
    • addedOutput schema / properties / productId / description
      Added value: +"One of the four delegated micro-service product identifiers."
    • addedOutput schema / properties / quoteId / description
      Added value: +"Quote created by this delegated call. It was not supplied by the caller."
    • addedOutput schema / properties / state
      Added value: +{
      +  "description": "Provider/checkout state when returned.",
      +  "type": "string"
      +}
    • addedOutput schema / properties / status / description
      Added value: +"Delegated-purchase state such as PAYMENT_REQUIRED, ONE_TIME_APPLE_PAY_AUTHORIZATION_REQUIRED, APPLE_PAY_AUTHORIZATION_NOT_ACTIVE, or a provider payment state."
    • addedOutput schema / properties / verified
      Added value: +{
      +  "description": "When returned by the provider flow, true only for a verified payment.",
      +  "type": "boolean"
      +}
  2. Changed9 schema fields changed
    • addedInput schema / properties / applePayAuthorizationToken
      Added value: +{
      +  "description": "Opaque token returned by the APPLE_PAY_AUTO setup. Do not provide card data or Apple Pay payloads.",
      +  "maxLength": 240,
      +  "minLength": 20,
      +  "type": "string"
      +}
    • changedInput schema / properties / authorizeCheckout / description
      Previous value: -"Explicit permission to create quote + acceptance + checkout within the stated cap; not permission for NAIF to move funds."New value: +"Permission to create quote + acceptance + checkout within the stated cap."
    • addedInput schema / properties / dailyLimitUsd
      Added value: +{
      +  "description": "Requested daily APPLE_PAY_AUTO cap during setup; maximum 20 USD.",
      +  "exclusiveMinimum": 0,
      +  "maximum": 20,
      +  "type": "number"
      +}
    • changedInput schema / properties / maxAmountUsd / description
      Previous value: -"Owner/platform per-purchase spending cap in USD-equivalent."New value: +"Per-purchase spending cap in USD-equivalent."
    • addedInput schema / properties / paymentRail
      Added value: +{
      +  "description": "Choose APPLE_PAY_AUTO for one-time authorization followed by capped automatic purchases.",
      +  "enum": [
      +    "AUTO",
      +    "BASE_USDC",
      +    "TRON_USDT",
      +    "APPLE_PAY_AUTO"
      +  ],
      +  "type": "string"
      +}
    • changedOutput schema / description
      Previous value: -"If eligible, returns PAYMENT_REQUIRED with quoteId, checkoutId and exact wallet payment instructions on BASE_USDC or TRON_USDT. No funds are moved by NAIF."New value: +"For wallet rails returns payment instructions. For APPLE_PAY_AUTO, first use returns a one-time humanAuthorizationUrl plus authorizationToken; subsequent use with an ACTIVE token may return PAYMENT_VERIFIED automatically. Provider activation failures fail closed."
    • addedOutput schema / properties / authorization
      Added value: +{
      +  "additionalProperties": true,
      +  "type": "object"
      +}
    • removedOutput schema / properties / nextTool
      Removed value: -{
      -  "type": "string"
      -}
    • changedOutput schema / properties / paymentRail / enum
      Previous value: -[
      -  "BASE_USDC",
      -  "TRON_USDT"
      -]New value: +[
      +  "BASE_USDC",
      +  "TRON_USDT",
      +  "APPLE_PAY_AUTO"
      +]
  3. Changed2 schema fields changed
    • changedOutput schema / description
      Previous value: -"If eligible, returns PAYMENT_REQUIRED with quoteId, checkoutId and exact Base USDC payment instructions. No funds are moved by NAIF."New value: +"If eligible, returns PAYMENT_REQUIRED with quoteId, checkoutId and exact wallet payment instructions on BASE_USDC or TRON_USDT. No funds are moved by NAIF."
    • addedOutput schema / properties / paymentRail / enum
      Added value: +[
      +  "BASE_USDC",
      +  "TRON_USDT"
      +]
  4. Added

TDQS

A4.6/5.0
Behavior5/5

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

Goes well beyond the annotations: it discloses the non-idempotent quote/accept/checkout lifecycle, the fail-closed behavior when support or authorization is missing, and the APPLE_PAY_AUTO requirement for a one-time human Apple Pay approval plus subsequent stored-cap charging. The idempotentHint=false annotation is reinforced with concrete reasoning rather than merely repeated.

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

Conciseness4/5

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

Front-loaded with the primary usage rule, then layers constraints, non-idempotency, and rail semantics in a logical order. Dense but each sentence carries decision-relevant information; slightly long, with minor overlap between the description and the authorizeCheckout/paymentRail schema text.

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?

Covers authorization prerequisites, spending-cap semantics, the human-approval gate, failure behavior, and sibling routing; an output schema exists so return values need not be described. 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 coverage is 100%, so the schema already documents all nine parameters. The description adds flow-level context (rail policy, token origin, cap enforcement) but little syntax or format detail beyond what the schema provides. Baseline 3 is appropriate when the schema does the heavy lifting.

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?

Opens with a specific verb+resource+scope ('autonomous purchase of one of four supported micro-services under an explicit spending cap') and immediately distinguishes itself from prepare_repair. An agent can tell exactly what this tool does and how it differs from the repair siblings.

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?

Explicitly states when to use ('owner/platform-preauthorized', four listed services), when NOT to use ('when quote_repair already produced a quoteId', 'general repair services outside the four listed micro-services'), and names the alternative ('use prepare_repair for an existing repair quote'). Nothing 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.