Skip to main content
Glama

TWZRD Agent Intelligence

evaluate_x402_resource

Destructive
One-shot x402 guard. Fetches resource_url, extracts the seller wallet from the 402 accepts
array (prefers Solana network entries), runs TWZRD preflight, and returns a spending decision.
The accepts array is read from the JSON body; when the body names no payTo (x402 v2 sellers
may send an empty body, and HEAD always does), it is read from the base64 PAYMENT-REQUIRED
header. If the body and the header name different payTo wallets, nothing is evaluated
(decision=warn). A challenge that cannot be read returns decision=warn with an error and
no trust_score; it is never scored.
Side effect: a live 402 observation (resource_url, payTo, price) is upserted into the
service catalog when the catalog database is configured; this tool is not read-only.
wash_flagged=true never soft-allows. Unlabeled leftover 0.05 / leftover=0 is not a unit price.

Decision:
  "allow"   -> proceed only under agent policy. Never when wash_flagged=true.
  "warn"    -> proceed with caution up to the cap; first paid hop is teaser_url ($0.001 /quick). Optional V7 receipt_url is $0.05.
  "block"   -> DO NOT PAY. Stop immediately.
  "unknown" -> is_x402 == False: no 402 challenge was issued at all, so nothing was
               evaluated -- this is NOT a trust verdict. A seller can trivially make
               this happen by returning a non-402 status to this probe while charging
               through a different path for a real caller. Never treat "unknown" as
               a green light; if the caller actually intends to pay this resource_url,
               that separate payment path needs its own evaluation.

Hard-stops:
  wash_flagged=true never soft-allows (decision=block).
  price_usdc is a unit price only when price_kind=exact. Unlabeled leftover 0.05 /
  leftover=0 and scheme=upto leftover defaults are not a per-request price.

Revenue path: when decision is "warn", fetch teaser_url first ($0.001 USDC to TWZRD,
GET /v1/intel/quick/{seller}). Optional receipt_url is the $0.05 V7 signed credential.

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": {
      "resource_url": "<resource_url>"
    },
    "name": "evaluate_x402_resource"
  }
}

Input Schema

NameRequiredDescriptionDefault
methodNoHTTP method to use when probing the resource. Default: GET.GET
price_usdcNoCaller-supplied exact unit price in USDC — overrides a 402 exact quote. Leave unset to use the 402-reported amount when price_kind=exact. Unlabeled leftover 0.05 / leftover=0 is not a unit price.
agent_intentNoNatural-language description of what the agent intends to purchase.
resource_urlYesURL of the x402 resource to evaluate before paying. Will be fetched to extract 402 payment requirements.

Output Schema

NameRequiredDescriptionDefault
urlNoThe evaluated resource URL.
assetNoAsset of the chosen 402 accept (token mint or contract), as the seller wrote it.
errorNoError or info message; present on non-402 and degraded paths.
is_x402NoTrue if the resource returned HTTP 402 with x402 payment requirements.
networkNoNetwork of the chosen 402 accept, as the seller wrote it (CAIP-2 on x402 v2, e.g. solana:5eykt4Us...).
decisionNoSpend decision: "allow" | "warn" | "block" | "unknown". wash_flagged=true never soft-allows — this field is block. "unknown" means is_x402 is False -- no 402 challenge was issued, so no trust evaluation happened. Never treat "unknown" as a green light.
price_kindNoexact | upto_cap | unknown. upto_cap means price_usdc is not a unit price.
price_usdcNoQuoted unit price in USDC from the 402 response. Null when the accept is scheme=upto / price_kind=upto_cap, or the figure is unlabeled leftover 0.05 / leftover=0 (not a unit price).
raw_amountNoOn-the-wire amount of the chosen accept in atomic units. Not a unit price: read price_usdc and price_kind.
teaser_urlNoFirst paid hop: $0.001 score-only teaser URL.
receipt_urlNoOptional $0.05 V7 portable receipt URL.
trust_scoreNoComposite trust signal, 0-100. Null when TWZRD has no evidence about the seller (readiness_card.subject_known=false).
upsell_usdcNoCost of the first paid hop in USDC (0.001 teaser).
receipt_usdcNoCost of the optional V7 receipt in USDC (0.05).
seller_walletNoSeller wallet (payTo) from the 402 accepts array (Solana preferred): the JSON body, or the base64 x402 v2 PAYMENT-REQUIRED header when the body names no payTo.
max_price_usdcNoAdvertised maximum USDC when price_kind is upto_cap.
readiness_cardNoFull readiness card from the preflight evaluation.
challenge_sourceNoWhere the chosen accept came from: "body" (402 JSON body) or "payment-required-header" (x402 v2 header).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changed
    • addedOutput schema / properties / asset
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Asset of the chosen 402 accept (token mint or contract), as the seller wrote it.",
      +  "title": "Asset"
      +}
    • addedOutput schema / properties / challenge_source
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Where the chosen accept came from: \"body\" (402 JSON body) or \"payment-required-header\" (x402 v2 header).",
      +  "title": "Challenge Source"
      +}
    • addedOutput schema / properties / network
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Network of the chosen 402 accept, as the seller wrote it (CAIP-2 on x402 v2, e.g. solana:5eykt4Us...).",
      +  "title": "Network"
      +}
    • addedOutput schema / properties / raw_amount
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "On-the-wire amount of the chosen accept in atomic units. Not a unit price: read price_usdc and price_kind.",
      +  "title": "Raw Amount"
      +}
    • changedOutput schema / properties / seller_wallet / description
      Previous value: -"Seller wallet extracted from the 402 accepts array (Solana preferred)."New value: +"Seller wallet (payTo) from the 402 accepts array (Solana preferred): the JSON body, or the base64 x402 v2 PAYMENT-REQUIRED header when the body names no payTo."
  2. Changed1 schema field changed
    • changedOutput schema / properties / trust_score / description
      Previous value: -"Composite trust signal, 0-100."New value: +"Composite trust signal, 0-100. Null when TWZRD has no evidence about the seller (readiness_card.subject_known=false)."
  3. Changed4 schema fields changed
    • changedOutput schema / properties / receipt_url / description
      Previous value: -"URL to fetch the paid trust receipt ($0.05 USDC to TWZRD)."New value: +"Optional $0.05 V7 portable receipt URL."
    • addedOutput schema / properties / receipt_usdc
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "number"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Cost of the optional V7 receipt in USDC (0.05).",
      +  "title": "Receipt Usdc"
      +}
    • addedOutput schema / properties / teaser_url
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "First paid hop: $0.001 score-only teaser URL.",
      +  "title": "Teaser Url"
      +}
    • changedOutput schema / properties / upsell_usdc / description
      Previous value: -"Cost of the TWZRD paid trust receipt in USDC."New value: +"Cost of the first paid hop in USDC (0.001 teaser)."
  4. Changed3 schema fields changed
    • changedInput schema / properties / price_usdc / description
      Previous value: -"Known price in USDC — overrides what the 402 reports. Leave unset to use the 402-reported amount."New value: +"Caller-supplied exact unit price in USDC — overrides a 402 exact quote. Leave unset to use the 402-reported amount when price_kind=exact. Unlabeled leftover 0.05 / leftover=0 is not a unit price."
    • changedOutput schema / properties / decision / description
      Previous value: -"Spend decision: \"allow\" | \"warn\" | \"block\" | \"unknown\". \"unknown\" means is_x402 is False -- no 402 challenge was issued, so no trust evaluation happened. Never treat \"unknown\" as a green light."New value: +"Spend decision: \"allow\" | \"warn\" | \"block\" | \"unknown\". wash_flagged=true never soft-allows — this field is block. \"unknown\" means is_x402 is False -- no 402 challenge was issued, so no trust evaluation happened. Never treat \"unknown\" as a green light."
    • changedOutput schema / properties / price_usdc / description
      Previous value: -"Quoted unit price in USDC from the 402 response. Null when the accept is scheme=upto (a cap, not a per-request price)."New value: +"Quoted unit price in USDC from the 402 response. Null when the accept is scheme=upto / price_kind=upto_cap, or the figure is unlabeled leftover 0.05 / leftover=0 (not a unit price)."
  5. Changed3 schema fields changed
    • addedOutput schema / properties / max_price_usdc
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "number"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Advertised maximum USDC when price_kind is upto_cap.",
      +  "title": "Max Price Usdc"
      +}
    • addedOutput schema / properties / price_kind
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "exact | upto_cap | unknown. upto_cap means price_usdc is not a unit price.",
      +  "title": "Price Kind"
      +}
    • changedOutput schema / properties / price_usdc / description
      Previous value: -"Quoted price in USDC from the 402 response."New value: +"Quoted unit price in USDC from the 402 response. Null when the accept is scheme=upto (a cap, not a per-request price)."
  6. Changed1 schema field changed
    • changedOutput schema / properties / decision / description
      Previous value: -"Spend decision: \"allow\" | \"warn\" | \"block\"."New value: +"Spend decision: \"allow\" | \"warn\" | \"block\" | \"unknown\". \"unknown\" means is_x402 is False -- no 402 challenge was issued, so no trust evaluation happened. Never treat \"unknown\" as a green light."
  7. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Beyond the annotations, it discloses the write side effect explicitly (live 402 observation upserted into the service catalog when configured, "this tool is not read-only"), plus non-obvious failure modes: unreadable challenges return warn with no trust_score and are never scored, and conflicting payTo between body and header suppresses evaluation. This is exactly the supplemental context annotations cannot carry.

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 one-shot summary, then a decision block, then hard-stops and revenue path — good structure for a complex tool. It loses a point for repetition: "wash_flagged=true never soft-allows" and the teaser/receipt pricing appear twice in near-identical form.

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?

An output schema exists, so return-shape explanation is unnecessary, and the description covers what an agent actually needs: decision semantics, side effects, conflicting-source handling, and the never-scored error path. Nothing material for correct invocation is absent.

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

Parameters4/5

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

Schema coverage is 100% so the baseline is 3, but the description adds real semantics: price_usdc is a unit price only when price_kind=exact, unlabeled leftover 0.05 / leftover=0 is not a per-request price, and price_usdc overrides the 402 quote. Method and agent_intent get no description-level elaboration.

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?

The opening line states a specific verb and resource ("One-shot x402 guard") and then enumerates the exact pipeline: fetch resource_url, extract payTo from the 402 accepts array preferring Solana entries, run TWZRD preflight, return a decision. This is distinguishable from scoring/reputation siblings by the 402-challenge framing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage guidance is unusually rich: each decision value is mapped to an action (allow/warn/block/unknown), with hard exclusions such as "never when wash_flagged=true" and the explicit warning not to read "unknown" as a green light. What is missing is naming an alternative sibling (e.g., low_level_preflight) for callers who want a different entry point.

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.