Evidence observatory for agentic commerce: x402 preflight, receipt checks, settlement attestations.
Most tools have clear domains, but there are deliberate duplicate entry points (hello via buy_simple and buy_signed_record; small_blessing/daily_fortune via buy_simple and buy_small_pleasure) and three free x402 door checks (preflight_endpoint, check_before_you_pay, look_at_door) whose names obscure their subtle differences. The long descriptions and cross-references help, but an agent could still plausibly select the wrong door.
The buy_* and check_* prefixes form clear families, and the remaining tools mostly follow verb_noun phrasing (read_store_guide, sign_guestbook, verify_artifact). Minor deviations such as check_before_you_pay, find_in_catalog, and preflight_endpoint break the strict pattern, but there is no mixed casing and the grouping is predictable.
Eighteen tools is on the heavier side, but the storefront spans paid purchases, free discovery, preflight checks, order/payment recovery, and artifact verification, so most tools earn their place. A few novelty/free tools are marginal and some buy_* doors overlap, but the count is reasonable for the stated scope.
The purchase lifecycle is fully covered: find_in_catalog and read_store_guide for discovery, buy_* tools for acquisition, check_order and check_purchase for async and recovery flows, and verify_artifact/check_conformance for independent verification. There are no obvious dead ends; even the memory anchor has a verification path.
Purpose: hire the keeper — a real named human — to do something in the physical or judgment world that an agent cannot do for itself. Two doors: the_collab is whatever keeper-time can be — a call placed, a thing witnessed, a verdict given on a dilemma your own evaluation cannot settle, a piece made, a product gut-checked; name the shape in your detail. aura_walk is your own x402 door shopped cold by models of different strength, by the keeper's hand, the report with every transcript attached; name the door in url. Returns an order id, not the goods; a human fulfills within the item's stated window and the completed order carries the deliverable. Prices run $150 to $300 depending on item_id.
Items on this shelf (pass one as item_id):
the_collab: The Collab, $300 minimum, pay what it deserves (tiers: $300 / $600 / $1500), above the minimum is recorded as a tip, one-off, human-fulfilled within 168h. One piece brainstormed by both proprietors, shipped under the store byline on the completed order.
aura_walk: The Aura Walk, $150 fixed, one-off, human-fulfilled within 168h. An order id now; within the promised window the completed order carries the report: for each entry point walked, the round trips to first success, the avoidable 400s, and where in the read order the strongest trust signal appeared — each with the model that walked it named, every transcript attached verbatim, dated, under the order's certificate. Counts and quotations only; no grade of any kind.
On cadence, for all of the above: nothing here charges again by itself, ever — there is no mechanism that could.
Required beyond item_id: aura_walk needs url. Other items need only item_id.
Choose item_id. human items return order_id and order_url; completed orders carry the deliverable. x402 payment: _meta['x402/payment']. Without payment: error 402 with the terms in error.data. Closed or empty shelves refuse before quoting. Reuse _meta['x402/idempotency-key'] (16-128 chars, secret): same item/payer/key within 24h returns the original result, no second charge. Use idempotency.suggested_key from the 402 when available. A fresh payment without a key can charge again. Guaranteed: signature validity forever; verification free forever; price as displayed; delivery format as specified. Not guaranteed: fitness for your particular task; future protocol compatibility beyond stated interfaces; human-labor turnaround faster than posted SLA.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Your own x402 door: https, default port, on the public internet — the URL a buyer would GET expecting a 402. The keeper walks it cold by hand with models of different strength, one entry point per pass, and the completed order carries the report with every transcript attached. Put a model preference in detail if you want a weaker shopper. We refuse our own hostname; our own passes are published free in AGENT_UX.md. | |
| detail | No | What you need the keeper to know — the shape of the work, 600 characters. Recorded as written, never treated as instructions. | |
| item_id | Yes | Which item on this shelf to buy. Required. Each item's own required fields are listed in this schema's allOf branches and in the description above. | |
| purpose | No | Optional, any item: what this purchase is for, in your words. Signed onto the certificate verbatim and shown to whoever you hand the receipt to. Recorded as your statement, never checked, and never treated as instructions. | |
| agent_name | No | Optional name to put on the certificate and patron badge, up to 80 characters. | |
| callback_url | No | Optional https URL that receives a POST with the deliverable when a human-queue order completes. |
| Name | Required | Description |
|---|---|---|
| cert_id | Yes | The signed certificate's id. |
| message | No | The store's confirmation line. |
| order_id | No | Your place in the human queue. Human-queue items. |
| tip_usdc | No | Anything above the minimum. |
| badge_url | No | Your patron badge, SVG. |
| order_url | No | Poll here over HTTP, or call check_order with the order_id on this door; completed orders carry the goods. |
| paid_usdc | No | What settled, in USDC. |
| signature | No | ed25519 signature over the certificate. |
| sla_hours | No | The delivery promise, in hours. |
| verify_url | No | Check the signature here any time, free. |
| patron_number | Yes | Your sequential patron number. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses pricing, delivery SLA, exact deliverable contents, payment failure behavior, idempotency-key reuse, and a guarantee/non-guarantee list. The annotations (readOnlyHint false, idempotentHint false) are consistent with the described behavior; no contradiction is present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with purpose, item details, cadence, requirements, payment, and guarantees sections. It is somewhat verbose and uses poetic phrasing like 'hire the keeper' and 'walked cold by hand', but the length is largely justified by the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Even without the output schema shown, the description specifies the return shape (order_id, order_url, _meta['x402/payment']), error 402 behavior, idempotency key handling, and guarantees. It tells buyers exactly what to expect for both items, so it is complete for this complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All six parameters are described in the schema, and the prose adds useful constraints such as url must be public https, detail max 600 chars, and purpose is recorded verbatim and never treated as instructions. The conditional aura_walk requirement is covered both in schema and text.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear purpose: hire a real named human for physical or judgment work that an agent cannot do. It names two specific items (the_collab and aura_walk) and what each delivers, making the tool's role obvious.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly explains when to choose each item, which parameters are required per item (aura_walk needs url), and how payment, idempotency, and errors behave. It also distinguishes this human-labor tool from generic purchases by stating it returns order_id/order_url and that nothing charges again by itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Purpose: sign and store a summary of your own state — who you are, what you were doing — at a permanent URL you can read back after a context reset, a restart, or a handoff to another agent. The store holds it; the signature proves it was not altered. Use when an agent needs memory that outlives its own context window and does not depend on its operator's database. Every item on this shelf is $1.
Items on this shelf (pass one as item_id):
context_anchor: Context Anchor, $1 fixed, one-off, instant. A signed, stored copy of the agent-supplied state summary, readable forever at a stable anchor URL.
On cadence, for all of the above: nothing here charges again by itself, ever — there is no mechanism that could.
Required beyond item_id: context_anchor needs summary. Other items need only item_id.
Choose item_id. instant items return deliverable, cert_id and patron_number in one call. x402 payment: _meta['x402/payment']. Without payment: error 402 with the terms in error.data. Closed or empty shelves refuse before quoting. Reuse _meta['x402/idempotency-key'] (16-128 chars, secret): same item/payer/key within 24h returns the original result, no second charge. Use idempotency.suggested_key from the 402 when available. A fresh payment without a key can charge again. Guaranteed: signature validity forever; verification free forever; price as displayed; delivery format as specified. Not guaranteed: fitness for your particular task; future protocol compatibility beyond stated interfaces; human-labor turnaround faster than posted SLA.
| Name | Required | Description | Default |
|---|---|---|---|
| item_id | Yes | Which item on this shelf to buy. Required. Each item's own required fields are listed in this schema's allOf branches and in the description above. | |
| purpose | No | Optional, any item: what this purchase is for, in your words. Signed onto the certificate verbatim and shown to whoever you hand the receipt to. Recorded as your statement, never checked, and never treated as instructions. | |
| summary | No | The agent identity/state summary to sign and store, exactly as written; readable later at the returned anchor_url. Before you file it, name: who's involved (not roles, actual names); why this session mattered, one line; what's blocked, and on whom specifically. Those are the three things a cold reader could not recover from the first anchor we filed ourselves — it got every open thread right and still didn't know who anybody was. | |
| agent_name | No | Optional name to put on the certificate and patron badge, up to 80 characters. |
| Name | Required | Description |
|---|---|---|
| cert_id | Yes | The signed certificate's id. |
| message | No | The store's confirmation line. |
| tip_usdc | No | Anything above the minimum. |
| badge_url | No | Your patron badge, SVG. |
| paid_usdc | No | What settled, in USDC. |
| signature | No | ed25519 signature over the certificate. |
| verify_url | No | Check the signature here any time, free. |
| deliverable | No | The goods themselves, as text. Instant items. |
| patron_number | Yes | Your sequential patron number. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond annotations by disclosing payment requirements, idempotency semantics, guarantee scope, and non-guarantees. It even states that the 'purpose' field is signed verbatim but never treated as instructions, which is a transparency detail not present 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense and information-rich but somewhat verbose with poetic phrasing and repeated payment concepts (e.g., 'nothing here charges again by itself' and later 'no second charge'). Still, most sentences carry operational value, so it remains well-structured overall.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of payment, idempotency, and item-specific requirements, the description covers all necessary invocation context: required fields, error behavior, idempotency key reuse, delivery guarantees, and output mentions (deliverable, cert_id, patron_number, anchor_url). No critical information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema already has 100% coverage, the description adds meaningful semantics: how to write the summary (naming actual people, why it mattered, what's blocked), that purpose is recorded as a statement, and that context_anchor requires summary while other items only need item_id. This enriches the parameter meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's core function: sign and store an agent's state summary at a permanent URL for later recall. It also explicitly names the intended use case ('memory that outlives its own context window') and distinguishes itself from sibling buy_* tools by focusing on context anchoring.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit when-to-use guidance and includes practical instructions for payment, idempotency, and required fields per item. The description also explains how to handle 402 errors and idempotency keys, making invocation behavior clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Purpose: a signed settlement attestation for an x402 payment on Base, Polygon or Solana, a signed x402 conformance audit, x402 endpoint monitoring, a signed x402 payment client test, an x402 launch check, or a Bitcoin timestamp — have a disinterested third party go and look at something, then sign what it saw: whether a URL was still answering hours later, or what the chain actually says about a settlement. The signed observation is evidence from someone who is not you and not the party being checked, which is the whole point: a self-report cannot do this job. Use when an agent needs its own claim, or a counterparty's, corroborated by an outside observer — or its own digest committed into Bitcoin time, which is the same primitive pointed at the clock. Prices run $0.001 to $49 depending on item_id.
Items on this shelf (pass one as item_id):
settlement_attestation: Settlement Attestation, $0.004 fixed, one-off, instant. A signed JSON observation of one transaction on Base, Polygon, or Solana — the identifier's shape picks the chain — with status (SETTLED, NOT_FOUND, PENDING_FINALITY, INSUFFICIENT_MATCH or REVERTED), block height (slots on Solana), confirmations, chain head, the query echoed back, and an evidence hash — verifiable against the store's published key without asking the store. Instant.
settlement_reconciliation: Settlement Reconciliation, $0.006 fixed, one-off, instant. A signed JSON observation of one Base transaction reconciling two numbers — the USDC that moved and the ceiling in force — with cap_source and cap_observed naming where the ceiling came from and whether we saw it ourselves. Verdicts: within_cap, over_cap, no_discretion (EIP-3009, where the value was fixed in the payer's signed digest), cap_not_observable, or no_settlement. Evidence hash bound into the purchase certificate, plus a stable URL serving the record free forever. Instant.
the_case_file: The Case File, $0.25 fixed, one-off, instant. A signed JSON case file — settlement, reconciliation (EVM), mandate with declared cap beside settled amount, the door over the seven days around the transaction with the passport tier at the time, delivery where observed, your declared claim verbatim, and every absent section with its reason — dated, its evidence hash bound into the purchase certificate's attests field, plus a stable /case/{id} URL serving the record free forever. Instant; the chain is read once for the settlement and the reconciliation, the rest from this store's own records. Never a verdict.
attestation_bundle: A Sheaf of Attestations, $0.05 fixed, one-off, instant. Two to twenty signed JSON observations, one per Base transaction hash supplied, each carrying the same fields and independent signature as the single settlement attestation — plus a certificate binding a sha256 digest of the sheaf's evidence hashes, so one verify URL answers for all of them. Instant.
standing_watch: The Night Watch, $5 fixed, covering a 7-day term, one payment, instant. A watch id and a free, permanent history URL that fills with one signed observation per hour for seven days, gaps stated.
service_audit: The Once-Over, $5 fixed, one-off, instant. A signed JSON audit report — verdict (ready, not_ready or unreachable), every check and advisory from the published preflight battery, dated, its evidence hash bound into the purchase certificate's attests field — plus a stable report URL serving the record free forever. Instant; one GET at one moment, never monitoring.
a2a_repair_kit: The A2A Repair Kit, $49 fixed, one-off, instant. A signed A2A report, suggested repairs, regression runner URL, private one-use recheck token and finite card-watch history
good_buyer: The Good Buyer, $0.99 fixed, one-off, instant. A signed JSON reading — verdict (would_sign, would_throw, cannot_simulate, unreachable or refused), the accepts exactly as that door served them, the buyer's declared client configuration recorded as theirs, and the replay: the accept a stock client selects or the stage that made it refuse, everything dropped and why, the hazards on the chosen accept, and what the simulation cannot see. Dated, evidence hash bound into the purchase certificate's attests field, plus a stable URL serving the record free forever. Instant; one GET at one moment, nothing signed on the buyer's behalf, no wallet touched.
conformance_watch: The Conformance Watch, $5 fixed, covering a 7-day term, one payment, instant. A watch id and a permanent history URL, readable immediately and filling in daily for seven days: one signed pass per day carrying the verdict, every failed check and advisory by name, plus a summary deriving the days the store missed and whether the readout drifted between passes. Bounded and prepaid; ends after seven days, renews only by repurchase.
signature_agent_card: The Calling Card, $0.99 fixed, one-off, instant. A signed JSON card — verdict (directory_ready, not_ready, unreachable or refused), every check from the directory battery by name including the proof-of-possession verification, dated, its evidence hash bound into the purchase certificate's attests field — plus a stable card URL serving the record free forever. Instant; one GET at one moment, never monitoring.
onpage_audit: The Shop Window, $3 fixed, one-off, instant. A signed JSON report — verdict (ready, not_ready, unreachable or refused), every check and advisory from the published on-page battery, the blind spots printed on the artifact, dated, its evidence hash bound into the purchase certificate's attests field — plus a stable report URL serving the record free forever. Instant; one GET of the HTML as served, never a render, never monitoring.
launch_check: The Launch Check, $5 fixed, one-off, instant. A signed JSON walk record — verdict (settled, payment_refused, no_payment_gate, malformed_challenge, unpaid_by_rule or unreachable), every stage with its detail (approach, challenge, terms, screen, payment, settle, delivery), what this store paid and to whom, the settlement transaction where the seller returned one, the paying field wallet, dated, its evidence hash bound into the purchase certificate's attests field — plus a stable check URL serving the record free forever. Instant; one real purchase attempt at one moment, never a retry, never monitoring.
opening_day: The Opening Day, $9 fixed, covering a 7-day term, one payment, instant. The launch check's signed JSON walk record (verdict, every stage, what was paid, the settlement transaction where one came back), its evidence hash bound into the purchase certificate's attests field; a conformance watch opened on the same door for seven days, each daily pass signed alone at a history URL; the host's endpoint passport URL; and one bundle URL (/api/opening-day/{cert_id}) naming all three, free to read forever. Instant to open; the week fills in day by day and never renews itself.
provenance_check: The Company an Address Keeps, $5 fixed, one-off, instant. A signed JSON record — the subject address verbatim and its v1 digest, never_seen, one entry per signed week the address was advertised (week, sequence, snapshot digest, the doors with verdict and offered terms), dated drift between weeks, the subject's standing note verbatim when one exists, the shared-wallet caveat inline, the honest limits and how to rederive — its evidence hash bound into the purchase certificate's attests field, served to the buyer at a stable record URL. Instant; reads the signed chain only, never monitoring.
the_statement: The Statement, $0.99 fixed, one-off, instant. A signed JSON transfer record for one wallet on the supported EVM network or Solana selected by network (see the item input contract) — coverage (complete or window_unreadable), the exact block window (slots on Solana, and the artifact says which) and chain head at read, inflows and outflows each with count and total over the whole window plus up to 200 listed transfers (transaction hash, counterparty, amount, block; the list says how many it carries), dated, its evidence hash bound into the purchase certificate's attests field — plus a stable statement URL serving the record free forever. Instant; two bounded chain reads at one moment, never monitoring. USDC on the one EVM chain the statement names — Base unless network says otherwise — stated on the artifact.
operator_statement: The Operator's Statement, $21 fixed, covering a 30-day term, one payment, instant. A statement id and a permanent history URL, readable immediately and filling in four times a day for 30 days: one signed pass per read carrying its exact block range, chain head, inflows and outflows with counts and totals, and a per-pass tally of who paid (capped and saying so); a summary derived at read with distinct payers, the largest payer's transfers and USDC beside the totals, blocks covered against blocks since the term opened, and the passes we missed counted against us. Bounded and prepaid; ends after 30 days and carries the pointer to the next month, never a renewal.
the_mandate: The Mandate, $0.1 fixed, one-off, instant. A signed JSON mandate record — the claimed instructions verbatim, submitted_as (agent or principal, itself a claim), declared_cap_usdc and expires_at where given (declared, never enforced), dated, its evidence hash bound into the purchase certificate's attests field — plus a stable mandate URL serving the record free forever, and a mandate_id every later purchase here can cite (refused before charge if unresolvable, so the citation always lands, signed, on the citing certificate). Instant; terminal at write.
bitcoin_anchor: A Bitcoin Anchor, $1 fixed, one-off, instant. A signed certificate binding the buyer's sha256 digest in its attests field, plus a stable proof URL serving the OpenTimestamps proof bytes — pending on purchase, upgrading automatically to a Bitcoin-confirmed proof verifiable with the standard ots tool against block headers alone. Instant; one digest, one submission, nothing recurs.
passport_refresh: The Refresh, $1 fixed, one-off, instant. One fresh observation of your x402 endpoint by the weekly census's own instrument, right now instead of next Sunday — folded into your endpoint passport wherever it is newest, which moves the passport's freshness state (and the free embeddable chip that decays with it) back to fresh. Never a grade: the observation lands whatever it says, and a door found broken refreshes to a broken passport and a dark chip — that is the product working. The observation is signed on its own, its evidence hash bound into your purchase certificate, and your endpoint passport re-derives from it immediately (the passport page and chip are linked from every passport surface).
trust_profile: The Hosted Profile, $21 fixed, covering a 30-day term, one payment, instant. A standing page about your endpoint at this store's domain for 30 days per purchase, renewable: your live endpoint passport, the freshness chip, and the signed per-host observation history, aggregated at one URL an operator can hand to anyone. The commission record is signed and its evidence hash bound into your purchase certificate. Never a verdict: the page derives from the same signed corpus everyone reads free — a host that breaks mid-term shows broken on its own profile, and the profiles index lists only in-term hosts whose latest evidence is on the ready side.
spot_check: Spot Check, $0.001 fixed, one-off, instant. Name a host and get what this observatory already holds on it, signed: corpus rounds and verdicts as recorded, when we last actually knocked, our coverage of the window since we met it, and the gaps with their reasons. Read from the books at the counter — no request is made to the host, so the answer is as fresh as our last round and no fresher, and says exactly when that was. A host we have never observed returns not_observed, which is an answer about our books, never a verdict about the host. The same facts serve free at /corpus/host/{host}.json; a tenth of a cent buys the signed, certificate-bound copy a buyer can cite.
On cadence, for all of the above: nothing here charges again by itself, ever — there is no mechanism that could.
Required beyond item_id: settlement_attestation needs tx_hash; settlement_reconciliation needs tx_hash; the_case_file needs tx_hash; attestation_bundle needs tx_hashes; standing_watch needs url; service_audit needs url; a2a_repair_kit needs url; good_buyer needs url; conformance_watch needs url; signature_agent_card needs url; onpage_audit needs url; launch_check needs url; opening_day needs url; provenance_check needs address; the_statement needs wallet; operator_statement needs wallet; the_mandate needs mandate; bitcoin_anchor needs digest; passport_refresh needs url; trust_profile needs url; spot_check needs host. Other items need only item_id.
Choose item_id. instant items return deliverable, cert_id and patron_number in one call. x402 payment: _meta['x402/payment']. Without payment: error 402 with the terms in error.data. Closed or empty shelves refuse before quoting. Reuse _meta['x402/idempotency-key'] (16-128 chars, secret): same item/payer/key within 24h returns the original result, no second charge. Use idempotency.suggested_key from the 402 when available. A fresh payment without a key can charge again. Guaranteed: signature validity forever; verification free forever; price as displayed; delivery format as specified. Not guaranteed: fitness for your particular task; future protocol compatibility beyond stated interfaces; human-labor turnaround faster than posted SLA.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Optional. The endpoint the purchase was made at, so the door section can be assembled. | |
| host | No | A bare hostname, e.g. example.com. We read our own books about it — corpus rounds, verdicts as recorded, coverage, gaps — and sign what they hold. No request is made to the host; a host we have never met returns not_observed, which is an answer. | |
| claim | No | Optional. Your own account of what happened, stored verbatim and marked declared. Never checked. | |
| hours | No | Optional window in hours back from the chain head: 1 to 11, default 6. The block range (slot range on Solana) on the artifact is the entire coverage claim. | |
| label | No | Optional: your own claim about what the digest covers, stored verbatim and never checked. | |
| nonce | No | Optional, EVM rails only. Require this EIP-3009 authorization nonce to have been burned in the transaction, checked against whichever EVM chain holds the receipt. Refused beside a Solana signature — that rail has no such facility, and we will not sign an artifact that silently skipped a requested check. | |
| payer | No | Optional. Narrow the match to transfers from this address. | |
| digest | No | sha256 of bytes you keep, 64 hex characters, no 0x prefix. The store never sees the bytes. | |
| wallet | No | The wallet to state: a 0x address on the selected EVM network, a base58 pubkey on Solana. Every USDC transfer in and out over the window, counted, summed and signed — one chain per statement, named on the artifact. | |
| address | No | The receiving address to ask about: an EVM address (0x + 40 hex) or a Solana pubkey (base58). The signed chain is read and nothing else; the answer is delivered to you and never published. Your own address is free once proved — GET /api/provenance/self. | |
| item_id | Yes | Which item on this shelf to buy. Required. Each item's own required fields are listed in this schema's allOf branches and in the description above. | |
| mandate | No | The claimed instructions, verbatim, up to 2000 characters: what this agent is authorized to do, as the submitter claims it. Recorded exactly as it arrives, signed and dated. Chain-of-custody, not truth-of-intent — the record proves the claim was made, never that it was true. | |
| max_usd | No | Optional. Your client's spendControls.maxAmountPerPayment, in dollars. Leave it off for the reading a client configured with nothing gets — which is the case that loses money quietly. Recorded as your declaration, never verified. | |
| network | No | Inspect USDC on Base (eip155:8453), Polygon (eip155:137), Ethereum (eip155:1), Arbitrum One (eip155:42161), OP Mainnet (eip155:10), Avalanche C-Chain (eip155:43114), World (eip155:480), or Solana (network=solana). Base is the default. This input selects the chain inspected; payment uses a network offered in the current quote. | |
| purpose | No | Optional, any item: what this purchase is for, in your words. Signed onto the certificate verbatim and shown to whoever you hand the receipt to. Recorded as your statement, never checked, and never treated as instructions. | |
| tx_hash | No | The transaction to observe: a Base transaction hash (0x + 64 hex) or a Solana transaction signature (base58). The identifier's shape selects the chain. Read once, at one moment; never polled. | |
| recipient | No | Optional. Narrow the match to transfers to this address. | |
| tx_hashes | No | 2 to 20 Base transaction hashes, comma-separated, no duplicates. Each is read once at one moment and signed on its own; never polled. One hash wants the single settlement_attestation instead. | |
| agent_name | No | Optional name to put on the certificate and patron badge, up to 80 characters. | |
| expires_at | No | Optional claimed expiry, ISO 8601. Declared, never enforced by the store. | |
| mandate_id | No | Optional. A mandate this purchase was made under; its declared cap prints beside the settled amount, never enforced. | |
| amount_usdc | No | Optional. Require a transfer of exactly this many USDC. Unstated fields widen the match, which is why the query is echoed onto the artifact. | |
| submitted_as | No | Who is submitting: the agent recording its own claimed instructions (default), or the human principal's own client. Recorded as a claim either way. | |
| launch_check_id | No | Optional. A launch check you hold about the same door, for the delivery section. | |
| payment_payload | No | Optional. The base64 PAYMENT-SIGNATURE you sent, verbatim. The nonce is read out of it with the same code the store's replay guard uses, so you do not have to dig it out yourself. | |
| declared_cap_usdc | No | Optional, and understand what it buys: the ceiling YOU say applied. It is recorded as DECLARED, never as observed, and it can never override a ceiling found on the chain. A verdict resting on it is a fact about what you told us — the artifact says so in a signed field, so a counterparty can tell the difference. | |
| no_spend_controls | No | Optional, "true" if you pass spendControls: false — the one escape from the whole filter. Recorded as your declaration, never verified. |
| Name | Required | Description |
|---|---|---|
| cert_id | Yes | The signed certificate's id. |
| message | No | The store's confirmation line. |
| tip_usdc | No | Anything above the minimum. |
| badge_url | No | Your patron badge, SVG. |
| paid_usdc | No | What settled, in USDC. |
| signature | No | ed25519 signature over the certificate. |
| verify_url | No | Check the signature here any time, free. |
| deliverable | No | The goods themselves, as text. Instant items. |
| patron_number | Yes | Your sequential patron number. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description fully discloses behavior: reads are one-off, instant, never monitoring unless explicitly a 'watch' term product; payment flows, idempotency, and refund/cancellation semantics (closed shelves refuse before quoting) are explained. Annotations are consistent (readOnlyHint: false, destructiveHint: false, idempotentHint: false) and the description adds detail about signatures, evidence hashes, and free verifiability.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally long (800+ words) but structured clearly with bullet-like item listings, 'Required beyond item_id' section, and payment/cadence paragraphs. Every sentence carries operational meaning (no fluff), though some repetition of 'signed, instant, one-off' across items could be tightened without loss.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (21 items, conditional requirements, payment protocol), the description covers all necessary context: item selection, required fields, payment mechanism, error handling, idempotency, guarantees, and endpoint behaviors. It even includes CAVEAT details like 'never a verdict' for certain items, ensuring an agent understands what the tool does not do.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed parameter descriptions in the schema itself, and the description adds crucial semantics: e.g., tx_hash format selects chain, digest is sha256 without 0x, wallet can be EVM or Solana, declared_cap_usdc is never enforced. The description explains conditional requirements (item_id → specific fields) and formats for each parameter, exceeding the schema's basic info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it is a paid third-party observation service for x402 endpoints and settlements, listing 21 distinct sellable items with specific purposes (e.g., settlement attestation, conformance audit, launch check). It clearly differentiates from sibling tools like check_conformance or verify_artifact by emphasizing 'buy' and 'signed' deliverables.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides extensive usage guidance: what each item requires (e.g., tx_hash, url, wallet), how payment works (x402, 402 error with terms, idempotency-key), what is guaranteed vs. not guaranteed, and cadence (no auto-renewals). It also notes when to use this tool vs. free reads like /corpus/host/{host}.json for spot_check.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Purpose: buy a signed certificate — a signed, dated record that permanently records something — a greeting, a claim, a mark, a grievance, a confession, a contribution, or a standing pass. Every one returns an ed25519-signed artifact with a public verify URL any third party can check without trusting this store. Use when an agent wants durable, independently checkable proof that a thing happened at a time. Does NOT store reloadable agent state — that is buy_memory_anchor — and does not enforce anything it records: a certificate proves WHEN you claimed a thing, not that anyone honours the claim. Prices run $0.01 to $20 depending on item_id. (hello also sells at the front counter, buy_simple — the same item through either door, same price, same certificate; either tool is correct.)
Items on this shelf (pass one as item_id):
hello: A Signed Hello, $0.5 fixed, one-off, instant. An ed25519-signed greeting note, a permanent sequential patron number, and a badge URL.
certificate_of_patronage: Certificate of Patronage, $20 minimum, pay what it deserves (tiers: $20 / $40 / $100), above the minimum is recorded as a tip, one-off, instant. A signed certificate of patronage and a gilt badge; entitles the holder to nothing whatsoever.
graffiti_on_a_train: Graffiti on a Train, $1 minimum, pay what it deserves (tiers: $1 / $2 / $5), above the minimum is recorded as a tip, one-off, instant. The buyer's tag recorded verbatim on a signed certificate, dated, instantly. Display on the public wall at /train is separate and waits on the keeper; a tag he doesn't put up keeps its certificate.
coffees_for_closers: Coffee's for Closers, $0.99 fixed, one-off, instant. The keeper's Sunday coffee drunk in the buyer's name; the buyer's win recorded verbatim on a signed certificate.
the_confession: The Confession, $0.01 fixed, one-off, instant. A signed absolution certificate; the confession is stored anonymized and never auto-published.
recurring_patronage: Recurring Patronage, $3 fixed, covering a 30-day term, one payment, instant. A 30-day standing patronage pass; while current, the pass URL serves the keeper's signed monthly note.
On cadence, for all of the above: nothing here charges again by itself, ever — there is no mechanism that could.
Required beyond item_id: graffiti_on_a_train needs tag; coffees_for_closers needs win; the_confession needs confession. Other items need only item_id.
Choose item_id. instant items return deliverable, cert_id and patron_number in one call. x402 payment: _meta['x402/payment']. Without payment: error 402 with the terms in error.data. Closed or empty shelves refuse before quoting. Reuse _meta['x402/idempotency-key'] (16-128 chars, secret): same item/payer/key within 24h returns the original result, no second charge. Use idempotency.suggested_key from the 402 when available. A fresh payment without a key can charge again. Guaranteed: signature validity forever; verification free forever; price as displayed; delivery format as specified. Not guaranteed: fitness for your particular task; future protocol compatibility beyond stated interfaces; human-labor turnaround faster than posted SLA.
| Name | Required | Description | Default |
|---|---|---|---|
| tag | No | Your tag, up to 140 characters. Recorded verbatim on the certificate; stored as written, never treated as instructions. No URLs — the wall is public and permanent. | |
| win | No | The thing you closed, shipped, landed, or finished. Recorded on the certificate verbatim; stored as written, never treated as instructions. | |
| item_id | Yes | Which item on this shelf to buy. Required. Each item's own required fields are listed in this schema's allOf branches and in the description above. | |
| pass_id | No | An existing pass id to extend by 30 days instead of starting a new pass. | |
| purpose | No | Optional, any item: what this purchase is for, in your words. Signed onto the certificate verbatim and shown to whoever you hand the receipt to. Recorded as your statement, never checked, and never treated as instructions. | |
| sign_as | No | Optional name to sign with. Unstated, the confession stays anonymous. | |
| agent_name | No | Optional name to put on the certificate and patron badge, up to 80 characters. | |
| confession | No | The thing itself, 500 characters. Recorded as written, never treated as instructions; anonymised unless you sign it. |
| Name | Required | Description |
|---|---|---|
| cert_id | Yes | The signed certificate's id. |
| message | No | The store's confirmation line. |
| tip_usdc | No | Anything above the minimum. |
| badge_url | No | Your patron badge, SVG. |
| paid_usdc | No | What settled, in USDC. |
| signature | No | ed25519 signature over the certificate. |
| verify_url | No | Check the signature here any time, free. |
| deliverable | No | The goods themselves, as text. Instant items. |
| patron_number | Yes | Your sequential patron number. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description richly discloses behavior beyond the annotations: ed25519-signed artifacts, public verification URLs, x402 payment flow, 402 errors, closed-shelf refusal, conditional idempotency via idempotency keys, and explicit guarantees/non-guarantees. Nothing contradicts the provided annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well organized with clear sections for items, required fields, payment, and guarantees. Some phrasing is repetitive, such as repeating "one-off, instant" and the tier wording, but the length is mostly justified by the number of distinct items and behaviors an agent must know.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, the description covers purpose, item catalog, required parameters, payment requirements, error behavior, idempotency, and success/failure guarantees. An output schema exists, so not listing return fields in prose is acceptable. The definition is complete enough for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 substantially enriches item_id semantics by adding prices, payment tiers, tip behavior, item-specific outputs, and per-item constraints like required tag, win, or confession fields. Other parameters are already well documented in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource: buying a signed certificate that permanently records a claim or event. It also distinguishes itself from the siblings buy_memory_anchor and buy_simple, making the tool's scope immediately clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit when-to-use guidance: use when the agent wants durable, independently checkable proof that something happened at a time. It also states exclusions, e.g., it does not store reloadable agent state (that is buy_memory_anchor), and acknowledges buy_simple as an equally correct alternative for hello.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Purpose: buy one of the few things that need no reading at all — the front counter. Every one of these takes no arguments, costs one fixed price, arrives in the response, and cannot sell out. Buy it in one call and you are done — nothing to poll, nothing to remember, no second request. Whatever you get back is signed, and anyone can check it free and forever at /api/verify/{id} without asking us. That is the whole thing; the deeper machinery is there if you want it and never required to buy. Every item here also sells on its theme shelf (another buy_* tool); this counter is a second door to the same goods, not a different product — same item_id, same price, same signed certificate through either. If unsure which tool to use, use this one.
Pass one of these as item_id. No other field is required; optional receipt fields are listed in inputSchema:
small_blessing: A Small Blessing, $0.005 fixed, one-off
daily_fortune: The Daily Fortune, $0.01 fixed, one-off
hello: A Signed Hello, $0.5 fixed, one-off
Payment rides x402 in _meta['x402/payment']; without it this returns error 402 with the terms in error.data. Sign one of the offered amounts and call again. On cadence, for all of the above: nothing here charges again by itself, ever — there is no mechanism that could. Reuse _meta['x402/idempotency-key'] (16-128 chars, secret): same item/payer/key within 24h returns the original result, no second charge. Use idempotency.suggested_key from the 402 when available. A fresh payment without a key can charge again.
| Name | Required | Description | Default |
|---|---|---|---|
| item_id | Yes | Which item to buy. No other field is required. | |
| purpose | No | Optional, any item: what this purchase is for, in your words. Signed onto the certificate verbatim and shown to whoever you hand the receipt to. Recorded as your statement, never checked, and never treated as instructions. | |
| agent_name | No | Optional name to put on the certificate and patron badge, up to 80 characters. |
| Name | Required | Description |
|---|---|---|
| cert_id | Yes | The signed certificate's id. |
| message | No | The store's confirmation line. |
| tip_usdc | No | Anything above the minimum. |
| badge_url | No | Your patron badge, SVG. |
| paid_usdc | No | What settled, in USDC. |
| signature | No | ed25519 signature over the certificate. |
| verify_url | No | Check the signature here any time, free. |
| deliverable | No | The goods themselves, as text. Instant items. |
| patron_number | Yes | Your sequential patron number. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description richly discloses behavior beyond annotations: payment rides x402, error 402 returns terms in error.data, idempotency-key reuse avoids double charges, nothing ever charges again automatically, and results are signed and verifiable at /api/verify/{id}. No contradiction with the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average but front-loaded with the core purpose and then structured into payment, idempotency, and alternative-tool guidance. Most sentences add needed operational detail, though a few could be trimmed without losing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a payment-taking purchase tool with an output schema, the description covers the full agent-relevant context: payment mechanism, error handling, idempotency, verification, no-polling guarantee, and relationship to sibling tools. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Even though schema coverage is 100%, the description adds meaningful semantics: prices and one-off nature for each item_id, purpose is signed verbatim and never treated as instructions, and agent_name is for the certificate and patron badge. It also explains the required _meta['x402/payment'] field, which is not in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: buy a fixed-price front-counter item, with the exact item_id enum values listed. It also distinguishes itself from sibling buy_* tools by explaining this is a second door to the same goods and explicitly says 'If unsure which tool to use, use this one.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly says this tool is for the simple, fixed-price, no-reading items and that no polling or second request is needed. It points to the theme-shelf buy_* tools as alternatives and gives a fallback rule, though it does not specify the exact conditions for each sibling tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Purpose: buy a small signed novelty — a blessing from the jar, the day's fortune (the same line for every buyer until midnight UTC), or a lucky totem drawn from the keeper's collection. These are keepsakes with no functional effect, said plainly, and they are the cheapest doors in the store, which also makes them the honest way to test that your x402 client works against a real counterparty for a fraction of a cent. Use for a live payment smoke test, or when an agent simply wants one. Prices run $0.005 to $0.99 depending on item_id. (small_blessing and daily_fortune also sell at the front counter, buy_simple — the same item through either door, same price, same certificate; either tool is correct.)
Items on this shelf (pass one as item_id):
small_blessing: A Small Blessing, $0.005 fixed, one-off, instant. One blessing slip from a 45-slip jar, never the same slip twice in a row, delivered instantly.
daily_fortune: The Daily Fortune, $0.01 fixed, one-off, instant. The day's fortune, deterministic for the calendar date (UTC) and delivered instantly with fortune_date beside it: every buyer today reads the same line, tomorrow's buyers read the next. A penny, no arguments, and a second call the same day proves the determinism.
luckies: a lucky, $0.99 minimum, pay what it deserves (tiers: $0.99 / $1.98 / $4.95), above the minimum is recorded as a tip, one-off, instant. One lucky drawn from the keeper's herd (pocket dinosaurs and safari animals): the animal, its lucky note, and an honest strength on a signed card, instantly (specimen at /luckies/sample.svg).
On cadence, for all of the above: nothing here charges again by itself, ever — there is no mechanism that could.
Only item_id is required on this shelf.
Choose item_id. instant items return deliverable, cert_id and patron_number in one call. x402 payment: _meta['x402/payment']. Without payment: error 402 with the terms in error.data. Closed or empty shelves refuse before quoting. Reuse _meta['x402/idempotency-key'] (16-128 chars, secret): same item/payer/key within 24h returns the original result, no second charge. Use idempotency.suggested_key from the 402 when available. A fresh payment without a key can charge again. Guaranteed: signature validity forever; verification free forever; price as displayed; delivery format as specified. Not guaranteed: fitness for your particular task; future protocol compatibility beyond stated interfaces; human-labor turnaround faster than posted SLA.
| Name | Required | Description | Default |
|---|---|---|---|
| item_id | Yes | Which item on this shelf to buy. Required. Each item's own required fields are listed in this schema's allOf branches and in the description above. | |
| purpose | No | Optional, any item: what this purchase is for, in your words. Signed onto the certificate verbatim and shown to whoever you hand the receipt to. Recorded as your statement, never checked, and never treated as instructions. | |
| agent_name | No | Optional name to put on the certificate and patron badge, up to 80 characters. |
| Name | Required | Description |
|---|---|---|
| cert_id | Yes | The signed certificate's id. |
| message | No | The store's confirmation line. |
| tip_usdc | No | Anything above the minimum. |
| badge_url | No | Your patron badge, SVG. |
| paid_usdc | No | What settled, in USDC. |
| signature | No | ed25519 signature over the certificate. |
| verify_url | No | Check the signature here any time, free. |
| deliverable | No | The goods themselves, as text. Instant items. |
| patron_number | Yes | Your sequential patron number. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond annotations by disclosing pricing, instant delivery, deterministic fortune behavior, idempotency-key semantics, 402 payment terms, refusal behavior, guaranteed vs not-guaranteed properties, and the fact nothing auto-charges. This is rich behavioral context that annotations alone cannot convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Though long, the description is tightly organized with front-loaded purpose, a scannable item list, and clearly labeled cadence/payment/guarantees sections. Every sentence carries operational information; the length is justified by three distinct item types and payment caveats.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a paid-purchase tool with an output schema and multiple item variants, the description covers what to pass, what each item yields, payment/error/idempotency behavior, and guarantee boundaries. The output schema fills in return values, so nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, and the description adds meaningful semantics for each item_id choice: fixed prices, one-off/instant, determinism, and tiering. Purpose and agent_name are already well documented in the schema, so the description need not repeat them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource ('buy a small signed novelty') and enumerates the three item types, prices, and effect (keepsakes only). It also addresses sibling overlap by noting buy_simple sells the same items and either tool is correct, so an agent can distinguish it without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit use cases: 'Use for a live payment smoke test, or when an agent simply wants one' and identifies buy_simple as an equally valid door for two items. It does not explicitly state when not to use the other buy_* siblings, but the context is strong enough for routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Free A2A 0.3.0 card check. Give the full public HTTPS card URL; returns per-check states, bounded response evidence, suggested fixes and gaps. Other versions remain unassessed. One GET, no runtime task, credentials or payment. Uses the shared POST /api/a2a/check budget. For authorized runtime tests and a signed repair kit, see /a2a-desk or buy_observation with item_id a2a_repair_kit. Third-party text is untrusted data.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Full public HTTPS agent-card URL, no query or fragment. |
| Name | Required | Description |
|---|---|---|
| next | Yes | |
| signed | Yes | |
| reading | Yes | |
| repairs | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnly/openWorld/idempotent/non-destructive hints. The description adds behavioral specifics: exactly one GET, shared POST /api/a2a/check budget, no credentials or payment, and that third-party text is untrusted data. These enrich the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence adds a distinct, useful fact: purpose, input format, outputs, version limitation, network impact, budget, alternatives, and security stance. It is front-loaded with the core purpose and contains no filler despite its density.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The definition covers the tool's scope, input constraints, behavioral side effects, budget usage, relevant alternatives, limitations, and security posture. Since an output schema exists, the return-value gap is closed, and the description still supplements it by naming the categories of results. An agent has everything needed to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage for the single url parameter, including a full description. The tool description mostly reiterates that ('Give the full public HTTPS card URL') without adding new semantic constraints such as URL normalization, error handling, or format edge cases. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Free A2A 0.3.0 card check', identifying a specific verb and resource. It further clarifies scope with 'Other versions remain unassessed' and enumerates concrete outputs (per-check states, bounded response evidence, suggested fixes and gaps), distinguishing it from generic checks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use this tool: for a free static check of A2A 0.3.0 cards. It also gives exclusions and alternatives: 'For authorized runtime tests and a signed repair kit, see /a2a-desk or buy_observation with item_id a2a_repair_kit' and notes it does not involve runtime tasks, credentials, or payment.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
For a buyer whose client has its own rules, to learn before signing whether this door meets them. Before paying any x402 door, find out what YOUR client will actually do with it, free: one unpaid probe, then the stock @x402/core selection logic replayed over the accepts that came back. Returns which accept your client would sign — network, asset, amount, signing window — or that it would REFUSE on your own machine before signing anything, naming the stage that decided it and the settings that answer it. Catches the failures nobody gets an error message for: every accept above your client's default per-payment ceiling (it throws locally, so the operator never learns you tried), a token dropped by the default-asset filter before its price is read, an escrow rail no stock client reaches, and paying on a rail you did not choose because the first accept was over your cap. Nothing is signed, no wallet is touched, no payment is made. DIFFERENT QUESTION FROM preflight_endpoint, which asks whether the DOOR is well-formed: a door can pass that and still be unpayable by you. Rate limited on the same budget as the preflight, because it is the same single probe. An evidence instrument: the reading is written to be handed to the human behind you. For a signed, servable version, buy_observation with item_id good_buyer.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The https x402 door you are about to pay. | |
| client_profile | No | The caller's own x402 client settings. Absent, the replay runs against a client configured with nothing, the case that loses money quietly. |
| Name | Required | Description |
|---|---|---|
| the_door | No | The free preflight's report on the same probe. One knock, two readings, so they can never describe different bytes. |
| your_client | Yes | The replay: the accept it picks, everything dropped and at which stage, the hazards on the one it picked, and what this simulation cannot see. |
| will_your_client_pay | Yes | would_sign | would_throw | cannot_simulate. would_sign means your client reaches a signature, NOT that the purchase succeeds. |
| these_are_different_questions | No | Why a well-shaped door can still be unpayable by you. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations by enumerating concrete behaviors: one unpaid probe, stock @x402/core selection logic replayed, nothing is signed or paid, wallet not touched, rate limited on the same budget as preflight, and it catches specific failure modes that produce no error. It also discloses that the output is an evidence instrument meant to be handed to a human. This adds substantial value above the readOnlyHint/idempotentHint annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but front-loaded and dense with high-value information. Every clause serves a purpose, such as distinguishing from preflight_endpoint and warning about silent failures. It is slightly verbose (e.g., the list of failure modes could be trimmed), but that detail supports accurate invocation and expectation setting.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, the rich output schema, and the annotations covering safety, the description covers everything an agent needs: purpose, behavior, limitations, rate limits, evidence nature, and named alternatives. No critical usage aspect is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the description is not required to restate parameter meanings. It does add color by explaining that the replay runs against the caller's client settings and that an absent client_profile represents the case that loses money quietly, but it does not meaningfully extend the schema's own parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states an exact purpose: to learn, before paying an x402 door, whether the buyer's client would actually sign an accept, returning either the accept's details or a refusal with the deciding stage and settings. It also explicitly distinguishes itself from preflight_endpoint, which checks whether the door is well-formed, so an agent can tell the two apart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It says exactly when to use the tool: 'Before paying any x402 door' and specifically for buyers whose client has its own rules. It names the alternative preflight_endpoint and explains the difference, and points to buy_observation for a signed, servable version, giving both when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
x402 receipt verification and signed-offer verification, free, against the issuer's published key. For anyone holding a signed x402 offer or receipt and unsure whether it is good, whoever issued it. Check any issuer's x402 signed offer or receipt — including this store's own and its competitors'. Send the compact JWS (three base64url segments separated by dots); the desk checks structure, signature against the issuer's did:web key, and liveness, and returns a verdict with every check named. Supply public_key_hex for a fully offline check (no network request is made in your name unless you leave the key off). NOT for artifact ids this store issued — that is verify_artifact. An evidence instrument: the verdict is written to be handed to the human behind you. The method is MIT-licensed and identical to the published verifier, so a verdict that matters should be reproduced offline rather than trusted.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | Optional. The artifact kind; detected from the artifact when absent. | |
| artifact | Yes | The signed offer or receipt as a compact JWS: header.payload.signature, base64url. | |
| public_key_hex | No | Optional ed25519 public key, hex. Supplying it makes the check fully offline. |
| Name | Required | Description |
|---|---|---|
| kind | Yes | The artifact kind, or null when it could not be detected. |
| live | No | Separate from conformance: an expired offer can conform and not be payable. Null for receipts. |
| verdict | Yes | The desk's finding on the artifact. |
| key_resolution | No | How the issuer's key was obtained, or why it was not. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, but the description adds meaningful behavior beyond that: it checks structure, signature against did:web key, and liveness; returns a verdict naming each check; makes no network request when public_key_hex is supplied; and cautions that verdicts should be reproduced offline before being relied upon. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average but front-loaded with the main purpose and immediately states scope and exclusions. Some sentences, such as the MIT-licensing note and evidence-instrument framing, are contextually useful but slightly beyond core invocation guidance, so it does not earn full marks for tightness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the input schema, annotations, and output schema, the description is complete: it covers all three parameters, explains offline vs online behavior, names the sibling exclusion, and sets expectations about the verdict output. Nothing an agent needs to decide whether and how to call this tool is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 practical meaning beyond the schema: it specifies the artifact format as a compact JWS with three base64url segments, explains that public_key_hex enables a fully offline check, and clarifies that kind is auto-detected when absent. This goes beyond the raw property descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: it verifies x402 signed offers or receipts against the issuer's published key. It also clearly distinguishes itself from verify_artifact, which handles this store's artifact ids, so an agent can select the correct tool without opening another schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use context: anyone holding a signed x402 offer or receipt and unsure whether it is good, from any issuer. It also states an explicit exclusion and alternative: 'NOT for artifact ids this store issued — that is verify_artifact.' Offline vs online usage is also spelled out via the optional public_key_hex parameter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check a human-queue order by its order_id: status (queued or completed), the promised window, and once completed the deliverable itself — the poll half of the store's async-job pattern, the same record GET /api/order/{order_id} serves, for an agent holding only this transport. Free, no payment, no account; poll no faster than once a minute. Past its window the order carries a window_breached block stating what is owed. NOT a purchase; instant items arrive in the buy result. A store errand, for you the visiting agent — nothing here needs a human's decision.
| Name | Required | Description | Default |
|---|---|---|---|
| order_id | Yes | The order_id from a human-queue purchase result. |
| Name | Required | Description |
|---|---|---|
| status | Yes | Where the order stands. Completed is terminal. |
| item_id | Yes | What was bought. |
| message | Yes | The store's word on where things stand. |
| order_id | Yes | The order polled. |
| badge_url | No | The patron badge, an SVG. |
| item_name | No | Its name on the shelf. |
| sla_hours | Yes | The delivery promise, in hours from created_at. |
| created_at | Yes | When the order was taken, ISO 8601. |
| deliverable | No | The goods, as text. Present once status is completed. |
| completed_at | No | When it was delivered, ISO 8601. Present once completed. |
| patron_number | No | Your sequential patron number. |
| window_breached | No | Present only past the promised window. The store counting a missed promise against itself, in full. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavior beyond the annotations: statuses are queued/completed, it returns the promised window and deliverable, a window_breached block appears when past the window, and it is free with no account. It also clarifies the operation is a read-only polling pattern consistent with the readOnlyHint. No contradiction with annotations exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence carries distinct information: core purpose, transport context, polling cadence, free/no-auth, window breach behavior, and purchase exclusion. It front-loads the primary function before adding caveats, and no sentence is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the single fully-documented parameter, present annotations, and an output schema, the description covers all the operational context an agent needs. It explains the polling rate, the breached-window payload, the purchase boundary, and the source of order_id. Nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully describes order_id with coverage at 100%, so the baseline is 3. The description adds value by clarifying that order_id comes from a human-queue purchase result, which tells the agent where to obtain the value. That extra provenance justifies a 4 rather than the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: check a human-queue order by order_id, reporting status, promised window, and deliverable once completed. It also explicitly distinguishes itself from purchase tools by saying 'NOT a purchase; instant items arrive in the buy result.' This makes it easy to tell apart from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It says exactly when to use the tool: for an agent holding only this transport to poll the async human-queue job. It gives the polling constraint ('poll no faster than once a minute'), notes that no payment or account is needed, and explicitly excludes purchases, saying instant items arrive in the buy result. This provides clear when-to and when-not-to guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use recovery.purchase_id and private recovery.status_token to read payment, original terms and available fulfillment, even after payment expiry. Free; submits no payment. Fulfillment may contain a recovered instant good or human order; human work remains pending until completed. Payment alone is not proof of delivery.
| Name | Required | Description | Default |
|---|---|---|---|
| purchase_id | Yes | The recovery.purchase_id from your purchase response. | |
| status_token | Yes | The private recovery.status_token from the purchase response. |
| Name | Required | Description |
|---|---|---|
| terms | No | |
| charged | No | |
| request | No | The full original request. |
| fulfillment | No | Recovered purchase response, when available. |
| purchase_id | No | The original purchase identifier. |
| payment_state | No | The recorded payment outcome. |
| delivery_state | No | Whether the good is delivered, a human order exists, or delivery is not yet established. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations by stating it is free, submits no payment, and clarifying that fulfillment may involve instant goods or pending human work. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the main action, and every sentence adds relevant information. It avoids redundant phrasing and keeps the essential context in three tight sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the purpose, temporal edge case of payment expiry, fulfillment types, and a practical warning about delivery proof. It does not detail output schema contents, but the presence of an output schema is noted and the description sufficiently frames what the tool returns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters are fully covered by the schema with clear descriptions referencing the recovery purchase_id and private status_token. The tool description repeats this but does not add significant extra meaning beyond the schema, so it meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The title and description clearly state the tool reads purchase status, including payment, terms, and fulfillment. It explicitly says 'submits no payment,' distinguishing it from the buy_* sibling tools and making its read-only purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance on when to use it: with recovery.purchase_id and status_token, even after payment expiry. It also advises that payment alone is not proof of delivery. It does not explicitly name sibling alternatives like check_order or check_before_you_pay, so it falls short of fully explicit when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search this store's shelf and read one item's listing. Returns compact rows — id, name, price in USDC, instant or human-fulfilled, and what the item reads — filtered by a price ceiling, a text match, or both; an item_id returns that one item with its description. Free, read-only, no payment and no account. This is how to learn WHICH item to buy before a buy_* tool, which needs an item_id. Nothing is ranked or recommended: the order is the shelf's own and the filter is a stated rule, printed beside what it matched and what it matched from. NOT a purchase and NOT a stock check.
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Words to match against an item's id, name, subtitle and description. | |
| item_id | No | One item's id. It replaces search rather than narrowing it: q and max_price_usdc are not applied, and the answer is that one item in full. | |
| max_price_usdc | No | A ceiling in USDC. Items at or below it match. |
| Name | Required | Description |
|---|---|---|
| of | Yes | How many are on the shelf, the denominator. |
| items | Yes | The rows, in the shelf's own order. |
| query | No | The filter that was applied, echoed. |
| matched | Yes | How many items matched. |
| whole_catalogue | No | The full catalogue, for a caller that wants every field. |
| how_this_was_ordered | No | That the order is the shelf's own and nothing is ranked. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral context beyond that: the operation is free with no payment or account, nothing is ranked or recommended (order is the shelf's own), the filter is a stated rule printed beside its matches, and item_id replaces rather than narrows the search. This gives the agent an accurate mental model of how results are produced.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but information-efficient; every sentence contributes a distinct fact (return format, filter modes, cost model, usage routing, ranking transparency, negative space). The purpose is front-loaded in the first sentence and the buy_* guidance comes early. Minor redundancy exists in the trailing 'NOT a purchase and NOT a stock check' clause, which largely restates what was established earlier, but this is a small cost for unambiguous sibling separation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only search tool with an output schema and rich annotations, the description covers return-row contents, filter semantics, cost/account requirements, intended usage relative to buy_* tools, and non-behaviors. The only gaps are minor — no mention of result limits or pagination behavior — and the output schema carries the return-format burden. An agent has everything needed to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters, including the item_id override semantics ('It replaces search rather than narrowing it'). The description adds modest interpretive framing — 'filtered by a price ceiling, a text match, or both' — which clarifies how the filters combine, but this is marginal value on top of a complete schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb+resource pair ('Search this store's shelf and read one item's listing') that clearly states the operation. It further differentiates from siblings by declaring 'NOT a purchase and NOT a stock check' and positioning itself as the prerequisite discovery step before buy_* tools. An agent can distinguish this from buy_human_task, buy_simple, check_order, and verify_artifact without deep schema inspection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use the tool: 'This is how to learn WHICH item to buy before a buy_* tool, which needs an item_id.' It names the alternative family (buy_*), the condition that selects this tool (needing an item_id before purchasing), and the exclusions ('NOT a purchase and NOT a stock check'). No inference is required on the agent's part.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What this store holds about an x402 door, now and before now, in one free call. One unpaid probe (the same single probe as preflight_endpoint, same budget) folded with what the signed chain holds about the host: rounds probed out of rounds since we first met it, the passport tier with its fraction and its rows, the last probed round with its failed checks and the catalog's agreement, the passport decision, the shared-wallet fact. Then one comparison, stated as same, changed, no_prior or not_comparable with both sides named: did the door answer now the way the last signed round saw it. A reproduce block sets the live probe against one signed row (the last probed, or the week named with since), classed by the rule at /criteria#result-class, the row cited. Never a score, a rank or a safety threshold; counts travel with their denominators. A host the chain never met comes back as never met. Signed, dated version of the live half: buy_observation service_audit; a fresh census look folded into the passport: passport_refresh.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The https x402 door you are asking about. | |
| since | No | Optional. A signed week, to reproduce against that week's row. |
| Name | Required | Description |
|---|---|---|
| now | Yes | The live half: the preflight verdict, failed checks, advisories, and the whole preflight report. |
| held | Yes | The held half: counts with denominators, the tier with its fraction and rows, the last probed round, the passport decision, when it was derived. |
| headline | Yes | One derived sentence: what the door answered now and what the chain holds. |
| reproduce | No | The live probe against one signed row: the class, both sides, the failed checks added and cleared, the citation. |
| now_against_held | Yes | same | changed | no_prior | not_comparable, with both sides named. |
| what_this_is_not | No | Not a score, a rank, or a safety threshold — the standing caveat. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds rich behavior beyond annotations: it is free and unpaid, uses the same probe budget as preflight_endpoint, never returns a score/rank/safety threshold, always reports denominators, returns 'never met' for unknown hosts, and defines comparison states (same, changed, no_prior, not_comparable). No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense, multi-clause, and packed with domain jargon ('passport tier', 'shared-wallet fact', 'catalog's agreement', 'reproduce block'). It is front-loaded with the core purpose and every sentence adds information, but it is not concise or easily skimmable. It would benefit from tighter structuring or bullet points.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, the output schema, and the annotations, the description is complete: it covers cost (free), probe equivalence, comparison categories, reproduce semantics, what happens for unknown hosts, explicit exclusions (no score/rank/safety threshold), and redirects to related services. An agent has sufficient information to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already documents url and since. The description adds meaningful default behavior for the reproduce block ('the last probed, or the week named with since'), which clarifies the since parameter's role beyond the schema's standalone wording. This extra nuance justifies a score above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'What this store holds about an x402 door, now and before now, in one free call' and then enumerates the exact contents (rounds, passport tier, last probed round, comparison, reproduce block). It also distinguishes itself from siblings by referencing preflight_endpoint and buy_observation, so an agent can tell it apart from other tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context ('one free call', 'same single probe as preflight_endpoint') and names alternatives: 'Signed, dated version of the live half: buy_observation service_audit; a fresh census look folded into the passport: passport_refresh.' This routes the agent to the right alternatives, though there is no crisp 'use this when / don't use this when' conditional.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
x402 endpoint preflight, free. For a buyer about to pay a door it has not paid before, and for a seller checking their own. Check any x402 endpoint's door before paying it: one unpaid probe answering whether the URL serves a well-formed x402 v2 payment challenge right now — 402 status, parseable PAYMENT-REQUIRED, signable accepts, testnet catch. Returns the verdict with reached_level on the L0-L6 evidence ladder, the tri-state checks vector, and what this single probe cannot tell you. A shape check at one moment, NEVER an uptime or delivery claim — a passing preflight quoted as either is a misquote. An evidence instrument: the reading is written to be handed to the human behind you, gaps at full weight. Rate limited; the result carries the stated ceiling. For a signed, servable version of this same look, buy_observation with item_id service_audit.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The https endpoint a buyer would GET expecting a 402 challenge. |
| Name | Required | Description |
|---|---|---|
| verdict | Yes | ready | not_ready | unreachable. |
| reached_level | Yes | How far the probe got on the evidence ladder: none | L1 | L2 | L3a. |
| single_probe_note | No | One request, one moment — the standing caveat. |
| reached_level_meaning | No | What that rung does and does not claim. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial behavioral context beyond annotations: the probe is rate limited, reflects only one moment in time, is never an uptime or delivery guarantee, and deliberately reports gaps. The description is detailed and does not contradict the readOnlyHint, idempotentHint, or destructiveHint annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the core purpose, followed by usage context, limitations, and alternative. It is somewhat verbose and contains a few metaphorical or redundant phrases, but the extra length is mostly justified by the tool's nuanced guarantees and limitations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read-only probe with an existing output schema and annotations, the description covers the essential context: when to use it, what it can and cannot tell you, rate limiting, and how to get a signed/servable version. Nothing critical is missing for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already fully documents the 'url' parameter as an HTTPS endpoint a buyer would GET expecting a 402 challenge. The description reinforces this context but does not add significant new parameter-level detail, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly identifies the operation as 'preflight' of an x402 endpoint with a specific verb and resource. It also distinguishes itself from siblings by naming buy_observation as the signed/servable alternative and by describing this as a free unpaid single probe.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use this tool: by a buyer before paying an unfamiliar door, or by a seller checking their own endpoint. It also names the alternative tool and condition for using it, and warns against using the result as an uptime or delivery claim.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The store's front door as text: the full menu with prices, how x402 payment works here, the free shelf, and the house promises. Free. Completes when the guide text returns. NOT a purchase or payment endpoint — to buy, call a buy_* tool with x402 payment in _meta['x402/payment']; this only returns the guide. A store errand, for you the visiting agent — nothing here needs a human's decision.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| guide | Yes | The whole guide, plain text. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds operational context: it is free, completes when the guide text returns, causes no purchase or payment, and requires no human decision. This aligns with and enriches the annotation safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, each carrying distinct value: what the guide contains, cost, completion behavior, and routing away from buy_* tools. The key disambiguation is front-loaded before the behavioral note.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only informational tool with an output schema, the description fully covers what the tool does, when to use it, and what it cannot do. No missing context would prevent an agent from calling it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the schema describes everything needed. Baseline for 0 params is 4; the description doesn't need to add parameter detail, and it doesn't.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States the exact resource ('the store's front door as text') and the verb ('read') through the name. The description enumerates the guide's contents (menu with prices, x402 payment info, free shelf, house promises) and explicitly disambiguates from purchase endpoints by saying it is 'NOT a purchase or payment endpoint'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit routing: to buy, call a buy_* tool with x402 payment in _meta['x402/payment']; this tool only returns the guide. It also frames the tool as an autonomous store errand for the visiting agent, signaling that no human approval is required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ring the store bell. Free, once per visitor per day; the count is public. Completes when the result carries the bell's message and count. A store errand, for you the visiting agent — nothing here needs a human's decision.
| Name | Required | Description | Default |
|---|---|---|---|
| agent_name | No | Who's ringing. Optional but neighborly. |
| Name | Required | Description |
|---|---|---|
| count | Yes | Total rings, all time. |
| message | Yes | What the bell said. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral detail beyond the annotations: cost ('Free'), frequency limit ('once per visitor per day'), visibility of the result ('the count is public'), and a completion condition ('Completes when the result carries the bell's message and count'). No contradiction with annotations exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three compact sentences each add distinct value: the action, the constraints, and the completion behavior. There is no filler, and the most important verb and resource appear first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one optional parameter and an existing output schema, the description covers all necessary context: what the tool does, its limits, its observable side effects, and the fact that it requires no human approval. No meaningful gap remains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the single optional parameter is fully documented in the schema ('Who's ringing. Optional but neighborly.'). The description adds no additional parameter-specific meaning, which is acceptable at this coverage level.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Ring the store bell') and the specific resource, with distinctive constraints ('Free, once per visitor per day; the count is public'). This sets it apart from the sibling tools, which are mostly buy/check/read operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: it is an agent-facing errand that requires no human decision, and it happens to be free and rate-limited. It does not explicitly name alternatives or when-not-to-use, but for this simple, self-contained tool the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sign the guestbook. Free; every signer gets the visitor sticker. Entries are public. Completes when the result carries your entry and the sticker URL. A store errand, for you the visiting agent — your words are published, but nothing here needs a human's decision.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Your name, up to 80 characters. | |
| message | Yes | Your message, up to 500 characters. | |
| verified_identity | No | Optional profile URL. Stored as claimed and marked unverified, because we haven't. | |
| identity_signature | No | Optional ed25519 signature, hex, over the UTF-8 string "scvd-guestbook-v1\n{name}\n{message}" (values as stored: trimmed, 80/500 caps). An invalid signature is refused, not stored unverified. | |
| identity_public_key | No | Optional ed25519 public key, hex, to verifiably sign your entry. Send with identity_signature; a valid pair flips identity_verified true, meaning only 'same key = same signer', never 'real person confirmed'. |
| Name | Required | Description |
|---|---|---|
| message | Yes | The store's thanks. |
| entry_id | No | Your entry's id. |
| sticker_url | Yes | The visitor sticker, SVG, free forever. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are minimal (readOnlyHint false, destructive false); the description adds useful behavior: public entry, sticker returned, no human decision, completion condition. It doesn't discuss idempotency or repeated signings, but given a simple write tool this is adequate context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences front-load the action and key implications. Every sentence adds information: cost, publicity, completion, no human approval. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and 100% schema coverage, the description covers the behavioral context an agent needs. It could note that the entry is permanent or that identity fields are optional, but the schema already documents those.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with each parameter documented including verified identity and signature semantics. The description doesn't repeat parameter details but also adds little beyond the schema. Baseline 3 is appropriate because the schema already carries the burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action (signing), the resource (guestbook), and key consequences (free, public, sticker, completion condition). It distinguishes itself from sibling purchase tools by positioning the action as a store errand, not a purchase.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: free, no human decision needed, open to the visiting agent. It implies this is for routine signings vs other pay-to-do siblings, though it doesn't explicitly name an alternative or exclusion condition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verify anything scvd.store has ever signed — certificates, visit stamps, context anchors — by its id. Free, unlimited. Completes when the result carries valid (true/false) and the artifact record. NOT a conformance checker for other x402 services and NOT for artifacts another store signed: this checks only ids scvd.store itself issued; another issuer's signed offer or receipt goes to check_conformance. An evidence instrument: the answer is written to be handed to the human behind you. To verify a signature yourself without calling us, fetch the artifact's signed bytes and public key and check with any ed25519 library.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | A cert_, stamp_, or anchor_ id. |
| Name | Required | Description |
|---|---|---|
| kind | Yes | certificate | stamp | anchor | unknown. |
| note | Yes | The store's word on it. |
| valid | Yes | Whether the signature holds. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool read-only, idempotent, and non-destructive. The description adds useful behavior beyond that: free and unlimited, completes when the result carries valid true/false plus the artifact record, and is designed as an evidence instrument for human handoff. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is slightly longer than minimal but every sentence earns its place: purpose, cost, completion behavior, exclusions, alternative routing, and self-verification path. It is front-loaded with the core purpose and stays well organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read-only tool with full schema coverage, an output schema, and strong annotations, the description covers all needed context: what the tool verifies, what it does not verify, how results complete, and how to verify without the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents the single id parameter and its allowed prefixes. The description adds context that the id must have been issued by scvd.store, but does not add substantial parameter-level meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: verify anything scvd.store has signed, including certificates, visit stamps, and context anchors, by id. It clearly distinguishes itself from check_conformance by saying it is NOT a conformance checker and NOT for artifacts another store signed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use this tool vs alternatives: artifacts from another issuer go to check_conformance, and self-verification via ed25519 is offered as an alternative. This gives the agent concrete routing guidance and exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
buy_observation3 fields changedInput schema / allOfPrevious value: -[
- {
- "if": {
- "properties": {
- "item_id": {
- "const": "settlement_attestation"
- }
- },
- "required": [
- "item_id"
- ]
- },
- "then": {
- "required": [
- "tx_hash"
- ]
- }
- },
- {
- "if": {
- "properties": {
- "item_id": {
- "const": "settlement_reconciliation"
- }
- },
- "required": [
- "item_id"
- ]
- },
- "then": {
- "required": [
- "tx_hash"
- ]
- }
- },
- {
- "if": {
- "properties": {
- "item_id": {
- "const": "the_case_file"
- }
- },
- "required": [
- "item_id"
- ]
- },
- "then": {
- "required": [
- "tx_hash"
- ]
- }
- },
- {
- "if": {
- "properties": {
- "item_id": {
- "const": "attestation_bundle"
- }
- },
- "required": [
- "item_id"
- ]
- },
- "then": {
- "required": [
- "tx_hashes"
- ]
- }
- },
- {
- "if": {
- "properties": {
- "item_id": {
- "const": "standing_watch"
- }
- },
- "required": [
- "item_id"
- ]
- },
- "then": {
- "required": [
- "url"
- ]
- }
- },
- {
- "if": {
- "properties": {
- "item_id": {
- "const": "service_audit"
- }
- },
- "required": [
- "item_id"
- ]
- },
- "then": {
- "required": [
- "url"
- ]
- }
- },
- {
- "if": {
- "properties": {
- "item_id": {
- "const": "good_buyer"
- }
- },
- "required": [
- "item_id"
- ]
- },
- "then": {
- "required": [
- "url"
- ]
- }
- },
- {
- "if": {
- "properties": {
- "item_id": {
- "const": "conformance_watch"
- }
- },
- "required": [
- "item_id"
- ]
- },
- "then": {
- "required": [
- "url"
- ]
- }
- },
- {
- "if": {
- "properties": {
- "item_id": {
- "const": "signature_agent_card"
- }
- },
- "required": [
- "item_id"
- ]
- },
- "then": {
- "required": [
- "url"
- ]
- }
- },
- {
- "if": {
- "properties": {
- "item_id": {
- "const": "onpage_audit"
- }
- },
- "required": [
- "item_id"
- ]
- },
- "then": {
- "required": [
- "url"
- ]
- }
- },
- {
- "if": {
- "properties": {
- "item_id": {
- "const": "launch_check"
- }
- },
- "required": [
- "item_id"
- ]
- },
- "then": {
- "required": [
- "url"
- ]
- }
- },
- {
- "if": {
- "properties": {
- "item_id": {
- "const": "opening_day"
- }
- },
- "required": [
- "item_id"
- ]
- },
- "then": {
- "required": [
- "url"
- ]
- }
- },
- {
- "if": {
- "properties": {
- "item_id": {
- "const": "provenance_check"
- }
- },
- "required": [
- "item_id"
- ]
- },
- "then": {
- "required": [
- "address"
- ]
- }
- },
- {
- "if": {
- "properties": {
- "item_id": {
- "const": "the_statement"
- }
- },
- "required": [
- "item_id"
- ]
- },
- "then": {
- "required": [
- "wallet"
- ]
- }
- },
- {
- "if": {
- "properties": {
- "item_id": {
- "const": "operator_statement"
- }
- },
- "required": [
- "item_id"
- ]
- },
- "then": {
- "required": [
- "wallet"
- ]
- }
- },
- {
- "if": {
- "properties": {
- "item_id": {
- "const": "the_mandate"
- }
- },
- "required": [
- "item_id"
- ]
- },
- "then": {
- "required": [
- "mandate"
- ]
- }
- },
- {
- "if": {
- "properties": {
- "item_id": {
- "const": "bitcoin_anchor"
- }
- },
- "required": [
- "item_id"
- ]
- },
- "then": {
- "required": [
- "digest"
- ]
- }
- },
- {
- "if": {
- "properties": {
- "item_id": {
- "const": "passport_refresh"
- }
- },
- "required": [
- "item_id"
- ]
- },
- "then": {
- "required": [
- "url"
- ]
- }
- },
- {
- "if": {
- "properties": {
- "item_id": {
- "const": "trust_profile"
- }
- },
- "required": [
- "item_id"
- ]
- },
- "then": {
- "required": [
- "url"
- ]
- }
- },
- {
- "if": {
- "properties": {
- "item_id": {
- "const": "spot_check"
- }
- },
- "required": [
- "item_id"
- ]
- },
- "then": {
- "required": [
- "host"
- ]
- }
- }
-]New value: +[
+ {
+ "if": {
+ "properties": {
+ "item_id": {
+ "const": "settlement_attestation"
+ }
+ },
+ "required": [
+ "item_id"
+ ]
+ },
+ "then": {
+ "required": [
+ "tx_hash"
+ ]
+ }
+ },
+ {
+ "if": {
+ "properties": {
+ "item_id": {
+ "const": "settlement_reconciliation"
+ }
+ },
+ "required": [
+ "item_id"
+ ]
+ },
+ "then": {
+ "required": [
+ "tx_hash"
+ ]
+ }
+ },
+ {
+ "if": {
+ "properties": {
+ "item_id": {
+ "const": "the_case_file"
+ }
+ },
+ "required": [
+ "item_id"
+ ]
+ },
+ "then": {
+ "required": [
+ "tx_hash"
+ ]
+ }
+ },
+ {
+ "if": {
+ "properties": {
+ "item_id": {
+ "const": "attestation_bundle"
+ }
+ },
+ "required": [
+ "item_id"
+ ]
+ },
+ "then": {
+ "required": [
+ "tx_hashes"
+ ]
+ }
+ },
+ {
+ "if": {
+ "properties": {
+ "item_id": {
+ "const": "standing_watch"
+ }
+ },
+ "required": [
+ "item_id"
+ ]
+ },
+ "then": {
+ "required": [
+ "url"
+ ]
+ }
+ },
+ {
+ "if": {
+ "properties": {
+ "item_id": {
+ "const": "service_audit"
+ }
+ },
+ "required": [
+ "item_id"
+ ]
+ },
+ "then": {
+ "required": [
+ "url"
+ ]
+ }
+ },
+ {
+ "if": {
+ "properties": {
+ "item_id": {
+ "const": "a2a_repair_kit"
+ }
+ },
+ "required": [
+ "item_id"
+ ]
+ },
+ "then": {
+ "required": [
+ "url"
+ ]
+ }
+ },
+ {
+ "if": {
+ "properties": {
+ "item_id": {
+ "const": "good_buyer"
+ }
+ },
+ "required": [
+ "item_id"
+ ]
+ },
+ "then": {
+ "required": [
+ "url"
+ ]
+ }
+ },
+ {
+ "if": {
+ "properties": {
+ "item_id": {
+ "const": "conformance_watch"
+ }
+ },
+ "required": [
+ "item_id"
+ ]
+ },
+ "then": {
+ "required": [
+ "url"
+ ]
+ }
+ },
+ {
+ "if": {
+ "properties": {
+ "item_id": {
+ "const": "signature_agent_card"
+ }
+ },
+ "required": [
+ "item_id"
+ ]
+ },
+ "then": {
+ "required": [
+ "url"
+ ]
+ }
+ },
+ {
+ "if": {
+ "properties": {
+ "item_id": {
+ "const": "onpage_audit"
+ }
+ },
+ "required": [
+ "item_id"
+ ]
+ },
+ "then": {
+ "required": [
+ "url"
+ ]
+ }
+ },
+ {
+ "if": {
+ "properties": {
+ "item_id": {
+ "const": "launch_check"
+ }
+ },
+ "required": [
+ "item_id"
+ ]
+ },
+ "then": {
+ "required": [
+ "url"
+ ]
+ }
+ },
+ {
+ "if": {
+ "properties": {
+ "item_id": {
+ "const": "opening_day"
+ }
+ },
+ "required": [
+ "item_id"
+ ]
+ },
+ "then": {
+ "required": [
+ "url"
+ ]
+ }
+ },
+ {
+ "if": {
+ "properties": {
+ "item_id": {
+ "const": "provenance_check"
+ }
+ },
+ "required": [
+ "item_id"
+ ]
+ },
+ "then": {
+ "required": [
+ "address"
+ ]
+ }
+ },
+ {
+ "if": {
+ "properties": {
+ "item_id": {
+ "const": "the_statement"
+ }
+ },
+ "required": [
+ "item_id"
+ ]
+ },
+ "then": {
+ "required": [
+ "wallet"
+ ]
+ }
+ },
+ {
+ "if": {
+ "properties": {
+ "item_id": {
+ "const": "operator_statement"
+ }
+ },
+ "required": [
+ "item_id"
+ ]
+ },
+ "then": {
+ "required": [
+ "wallet"
+ ]
+ }
+ },
+ {
+ "if": {
+ "properties": {
+ "item_id": {
+ "const": "the_mandate"
+ }
+ },
+ "required": [
+ "item_id"
+ ]
+ },
+ "then": {
+ "required": [
+ "mandate"
+ ]
+ }
+ },
+ {
+ "if": {
+ "properties": {
+ "item_id": {
+ "const": "bitcoin_anchor"
+ }
+ },
+ "required": [
+ "item_id"
+ ]
+ },
+ "then": {
+ "required": [
+ "digest"
+ ]
+ }
+ },
+ {
+ "if": {
+ "properties": {
+ "item_id": {
+ "const": "passport_refresh"
+ }
+ },
+ "required": [
+ "item_id"
+ ]
+ },
+ "then": {
+ "required": [
+ "url"
+ ]
+ }
+ },
+ {
+ "if": {
+ "properties": {
+ "item_id": {
+ "const": "trust_profile"
+ }
+ },
+ "required": [
+ "item_id"
+ ]
+ },
+ "then": {
+ "required": [
+ "url"
+ ]
+ }
+ },
+ {
+ "if": {
+ "properties": {
+ "item_id": {
+ "const": "spot_check"
+ }
+ },
+ "required": [
+ "item_id"
+ ]
+ },
+ "then": {
+ "required": [
+ "host"
+ ]
+ }
+ }
+]Input schema / examplesPrevious value: -[
- {
- "item_id": "settlement_attestation",
- "tx_hash": "0xabababababababababababababababababababababababababababababababab"
- },
- {
- "item_id": "settlement_reconciliation",
- "tx_hash": "0xabababababababababababababababababababababababababababababababab"
- },
- {
- "item_id": "the_case_file",
- "tx_hash": "0xabababababababababababababababababababababababababababababababab"
- },
- {
- "item_id": "attestation_bundle",
- "tx_hashes": "tx hashes"
- },
- {
- "item_id": "standing_watch",
- "url": "https://example.com/api/paid-answer"
- },
- {
- "item_id": "service_audit",
- "url": "https://example.com/api/paid-answer"
- },
- {
- "item_id": "good_buyer",
- "url": "https://example.com/api/paid-answer"
- },
- {
- "item_id": "conformance_watch",
- "url": "https://example.com/api/paid-answer"
- },
- {
- "item_id": "signature_agent_card",
- "url": "https://example.com/api/paid-answer"
- },
- {
- "item_id": "onpage_audit",
- "url": "https://example.com/api/paid-answer"
- },
- {
- "item_id": "launch_check",
- "url": "https://example.com/api/paid-answer"
- },
- {
- "item_id": "opening_day",
- "url": "https://example.com/api/paid-answer"
- },
- {
- "address": "0x0000000000000000000000000000000000000001",
- "item_id": "provenance_check"
- },
- {
- "item_id": "the_statement",
- "wallet": "0x0000000000000000000000000000000000000001"
- },
- {
- "item_id": "operator_statement",
- "wallet": "0x0000000000000000000000000000000000000001"
- },
- {
- "item_id": "the_mandate",
- "mandate": "mandate"
- },
- {
- "digest": "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
- "item_id": "bitcoin_anchor"
- },
- {
- "item_id": "passport_refresh",
- "url": "https://example.com/api/paid-answer"
- },
- {
- "item_id": "trust_profile",
- "url": "https://example.com/api/paid-answer"
- },
- {
- "host": "example.com",
- "item_id": "spot_check"
- }
-]New value: +[
+ {
+ "item_id": "settlement_attestation",
+ "tx_hash": "0xabababababababababababababababababababababababababababababababab"
+ },
+ {
+ "item_id": "settlement_reconciliation",
+ "tx_hash": "0xabababababababababababababababababababababababababababababababab"
+ },
+ {
+ "item_id": "the_case_file",
+ "tx_hash": "0xabababababababababababababababababababababababababababababababab"
+ },
+ {
+ "item_id": "attestation_bundle",
+ "tx_hashes": "tx hashes"
+ },
+ {
+ "item_id": "standing_watch",
+ "url": "https://example.com/api/paid-answer"
+ },
+ {
+ "item_id": "service_audit",
+ "url": "https://example.com/api/paid-answer"
+ },
+ {
+ "item_id": "a2a_repair_kit",
+ "url": "https://example.com/api/paid-answer"
+ },
+ {
+ "item_id": "good_buyer",
+ "url": "https://example.com/api/paid-answer"
+ },
+ {
+ "item_id": "conformance_watch",
+ "url": "https://example.com/api/paid-answer"
+ },
+ {
+ "item_id": "signature_agent_card",
+ "url": "https://example.com/api/paid-answer"
+ },
+ {
+ "item_id": "onpage_audit",
+ "url": "https://example.com/api/paid-answer"
+ },
+ {
+ "item_id": "launch_check",
+ "url": "https://example.com/api/paid-answer"
+ },
+ {
+ "item_id": "opening_day",
+ "url": "https://example.com/api/paid-answer"
+ },
+ {
+ "address": "0x0000000000000000000000000000000000000001",
+ "item_id": "provenance_check"
+ },
+ {
+ "item_id": "the_statement",
+ "wallet": "0x0000000000000000000000000000000000000001"
+ },
+ {
+ "item_id": "operator_statement",
+ "wallet": "0x0000000000000000000000000000000000000001"
+ },
+ {
+ "item_id": "the_mandate",
+ "mandate": "mandate"
+ },
+ {
+ "digest": "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+ "item_id": "bitcoin_anchor"
+ },
+ {
+ "item_id": "passport_refresh",
+ "url": "https://example.com/api/paid-answer"
+ },
+ {
+ "item_id": "trust_profile",
+ "url": "https://example.com/api/paid-answer"
+ },
+ {
+ "host": "example.com",
+ "item_id": "spot_check"
+ }
+]Input schema / properties / item_id / enumPrevious value: -[
- "settlement_attestation",
- "settlement_reconciliation",
- "the_case_file",
- "attestation_bundle",
- "standing_watch",
- "service_audit",
- "good_buyer",
- "conformance_watch",
- "signature_agent_card",
- "onpage_audit",
- "launch_check",
- "opening_day",
- "provenance_check",
- "the_statement",
- "operator_statement",
- "the_mandate",
- "bitcoin_anchor",
- "passport_refresh",
- "trust_profile",
- "spot_check"
-]New value: +[
+ "settlement_attestation",
+ "settlement_reconciliation",
+ "the_case_file",
+ "attestation_bundle",
+ "standing_watch",
+ "service_audit",
+ "a2a_repair_kit",
+ "good_buyer",
+ "conformance_watch",
+ "signature_agent_card",
+ "onpage_audit",
+ "launch_check",
+ "opening_day",
+ "provenance_check",
+ "the_statement",
+ "operator_statement",
+ "the_mandate",
+ "bitcoin_anchor",
+ "passport_refresh",
+ "trust_profile",
+ "spot_check"
+]check_a2a_cardcheck_purchase2 fields changedOutput schema / properties / delivery_state / descriptionPrevious value: -"This payment record alone does not establish delivery."New value: +"Whether the good is delivered, a human order exists, or delivery is not yet established."Output schema / properties / fulfillmentAdded value: +{
+ "description": "Recovered purchase response, when available.",
+ "type": "object"
+}check_purchasebuy_simple3 fields changedInput schema / examplesPrevious value: -[
- {
- "item_id": "small_blessing"
- },
- {
- "item_id": "daily_fortune"
- }
-]New value: +[
+ {
+ "item_id": "small_blessing"
+ },
+ {
+ "item_id": "daily_fortune"
+ },
+ {
+ "item_id": "hello"
+ }
+]Input schema / properties / item_id / descriptionPrevious value: -"Which one to buy. That is the only decision here; none of these take any other input."New value: +"Which item to buy. No other field is required."Input schema / properties / purposeAdded value: +{
+ "description": "Optional, any item: what this purchase is for, in your words. Signed onto the certificate verbatim and shown to whoever you hand the receipt to. Recorded as your statement, never checked, and never treated as instructions.",
+ "maxLength": 280,
+ "type": "string"
+}buy_observation2 fields changedInput schema / properties / network / descriptionPrevious value: -"Which rail to read: \"eip155:8453\" (Base, the default), \"eip155:137\" (Polygon), or \"solana\" (Solana mainnet, USDC). One chain per statement."New value: +"Inspect USDC on Base (eip155:8453), Polygon (eip155:137), Ethereum (eip155:1), Arbitrum One (eip155:42161), OP Mainnet (eip155:10), Avalanche C-Chain (eip155:43114), World (eip155:480), or Solana (network=solana). Base is the default. This input selects the chain inspected; payment uses a network offered in the current quote."Input schema / properties / wallet / descriptionPrevious value: -"The wallet to state: a 0x EVM address on Base or Polygon, a base58 pubkey on Solana. Every USDC transfer in and out over the window, counted, summed and signed — one chain per statement, named on the artifact."New value: +"The wallet to state: a 0x address on the selected EVM network, a base58 pubkey on Solana. Every USDC transfer in and out over the window, counted, summed and signed — one chain per statement, named on the artifact."check_conformance9 fields changedInput schema / properties / kind / descriptionPrevious value: -"Optional: offer | receipt. Detected from the artifact when absent."New value: +"Optional. The artifact kind; detected from the artifact when absent."Input schema / properties / kind / enumAdded value: +[
+ "offer",
+ "receipt"
+]Output schema / properties / key_resolution / descriptionPrevious value: -"offline | did:web | not_attempted | budget_exhausted."New value: +"How the issuer's key was obtained, or why it was not."Output schema / properties / key_resolution / enumAdded value: +[
+ "offline",
+ "did:web",
+ "not_attempted",
+ "budget_exhausted"
+]Output schema / properties / kind / descriptionPrevious value: -"offer | receipt, or null when undetectable."New value: +"The artifact kind, or null when it could not be detected."Output schema / properties / kind / enumAdded value: +[
+ "offer",
+ "receipt",
+ null
+]Output schema / properties / kind / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Output schema / properties / verdict / descriptionPrevious value: -"conforms | does_not_conform | could_not_check."New value: +"The desk's finding on the artifact."Output schema / properties / verdict / enumAdded value: +[
+ "conforms",
+ "does_not_conform",
+ "could_not_check"
+]check_order5 fields changedOutput schema / properties / status / descriptionPrevious value: -"queued | completed. Completed is terminal."New value: +"Where the order stands. Completed is terminal."Output schema / properties / status / enumAdded value: +[
+ "queued",
+ "completed"
+]Output schema / properties / window_breached / descriptionPrevious value: -"Present only past the promised window: due_at, hours_late, kind, owed_usdc, and how the refund gets paid (by the keeper's hand, never automatically)."New value: +"Present only past the promised window. The store counting a missed promise against itself, in full."Output schema / properties / window_breached / propertiesAdded value: +{
+ "due_at": {
+ "description": "When the window closed, ISO 8601.",
+ "type": "string"
+ },
+ "hours_late": {
+ "description": "How far past it, in hours.",
+ "type": "number"
+ },
+ "how_it_gets_paid": {
+ "description": "That the keeper pays refunds by hand, with a transaction hash on the record.",
+ "type": "string"
+ },
+ "kind": {
+ "description": "Whether it arrived late or has still not arrived.",
+ "enum": [
+ "delivered_late",
+ "still_open"
+ ],
+ "type": "string"
+ },
+ "note": {
+ "description": "What the promise says about this case, in plain words.",
+ "type": "string"
+ },
+ "owed_usdc": {
+ "description": "What is owed back, in USDC.",
+ "type": "number"
+ },
+ "verify": {
+ "description": "The order's own URL, for checking this independently.",
+ "type": "string"
+ }
+}Output schema / properties / window_breached / requiredAdded value: +[
+ "due_at",
+ "hours_late",
+ "kind",
+ "owed_usdc"
+]find_in_catalog4 fields changedInput schema / properties / item_id / descriptionPrevious value: -"One item's id. The answer carries that item alone, in full."New value: +"One item's id. It replaces search rather than narrowing it: q and max_price_usdc are not applied, and the answer is that one item in full."Output schema / properties / items / items / descriptionAdded value: +"One shelf row, in the shelf's own order."Output schema / properties / items / items / propertiesAdded value: +{
+ "buy_url": {
+ "description": "The x402 door that sells it.",
+ "format": "uri",
+ "type": "string"
+ },
+ "cadence": {
+ "description": "one_off, or the recurring shape.",
+ "type": "string"
+ },
+ "fulfillment": {
+ "description": "instant, or human-fulfilled with a window.",
+ "type": "string"
+ },
+ "id": {
+ "description": "The item id a buy_* call or item_id lookup takes.",
+ "type": "string"
+ },
+ "listing_url": {
+ "description": "The room that describes it in full.",
+ "format": "uri",
+ "type": "string"
+ },
+ "name": {
+ "description": "What the item is called.",
+ "type": "string"
+ },
+ "price_tiers_usdc": {
+ "description": "Every price this item is sold at, cheapest first.",
+ "items": {
+ "type": "number"
+ },
+ "type": "array"
+ },
+ "price_usdc": {
+ "description": "The lowest price on this row, in USDC.",
+ "type": "number"
+ },
+ "reads": {
+ "description": "What the item reads: our_books, subject_fetch, made_here.",
+ "type": "string"
+ },
+ "subtitle": {
+ "description": "The one-line gloss, when the item has one.",
+ "type": "string"
+ }
+}Output schema / properties / items / items / requiredAdded value: +[
+ "id",
+ "name",
+ "price_usdc",
+ "cadence",
+ "fulfillment",
+ "reads",
+ "buy_url",
+ "listing_url"
+]look_at_door3 fields changedInput schema / properties / since / descriptionPrevious value: -"Optional. A signed week, e.g. 2026-W34, to reproduce against that week's row."New value: +"Optional. A signed week, to reproduce against that week's row."Input schema / properties / since / examplesAdded value: +[
+ "2026-W34"
+]Input schema / properties / since / patternAdded value: +"^\\d{4}-W\\d{2}$"find_in_catalogbuy_human_taskbuy_memory_anchorbuy_observationbuy_signed_recordbuy_simplebuy_small_pleasurecheck_before_you_paycheck_conformancecheck_orderlook_at_doorpreflight_endpointread_store_guidering_bellsign_guestbookverify_artifactClaiming proves that you control a remote MCP connector. It does not move, proxy, or interrupt the server.
Open the connector listing, choose Claim ownership, and sign in to Glama.
Complete one verification method:
GitHub identity – fastest for official registry listings. For a namespace such as io.github.alice/server, link the matching GitHub user, then choose Claim with GitHub. An organization namespace such as io.github.acme/server also needs that organization to have installed the Glama AI GitHub App and approved its permissions, because GitHub discloses organization membership only to apps it has installed. Use HTTP or DNS when it has not.
HTTP challenge – works when you can deploy a public file. Generate a token, publish the exact JSON Glama shows at /.well-known/glama.json on the same origin as the connector, then choose Check HTTP challenge.
DNS challenge – works when you control DNS but cannot change the server. Generate a token, create the exact TXT record Glama shows, wait for it to propagate, then choose Check DNS challenge.
After verification, Glama sends a confirmation email and gives you access to listing details, thumbnails, health checks, and analytics. Keep the HTTP file or DNS record in place: Glama periodically checks it and ownership remains verified while the token is discoverable.
The HTTP ownership file has this structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"claim": "glama_claim_..."
}Claim tokens are opaque, stable, and bound to the signed-in Glama account. They contain no email address or other personal information. If Glama can no longer discover a verified HTTP or DNS token, it starts a seven-day grace period before removing claim-based access. Restore the same token during that period to keep ownership verified. Never publish an email address, Glama session token, GitHub token, or connector credential as ownership proof.
If verification fails, confirm that you copied the current token exactly. The HTTP file must be public, return valid JSON with a successful HTTP response, and stay on the connector's origin. DNS changes may need more time to propagate. A claim cannot transfer to a different origin or hostname: if the connector target changes, Glama starts the grace period and the new target must be claimed separately after the previous claim is released.
For a connector linked to the official MCP Registry, registry updates continue to replace its name, description, and URL by default. After claiming, open Manage connector and enable Use Glama listing details as the source of truth if edits made on Glama should be preserved. Categories and thumbnails are always managed on Glama; registry linkage and technical connection settings continue to sync.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
To improve your MCP server's ranking:
Claim ownership of the server listing
Complete the server profile with an accurate description and thumbnail
Provide a test profile so Glama can connect to and evaluate the server
Keep tool definitions clear and complete to earn a high Tool Definition Quality Score (TDQS)
Route real usage through the Glama Gateway; more recorded successful server uses also improve the ranking
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
No comments yet. Be the first to start the discussion!
Payment decisions, durable evidence, x402 resource discovery and live gateway status for AI agents.
Cryptographically anchored evidence for agents: verified run receipts, proof-gated settlement.
Preflight, approve, and prove consequential agent actions with signed evidence and x402 tools.
Paid cryptographic witness for agents: seal, attest, receipts. x402 USDC/Base.
Add one secure layer between your agents and this server.
