Evidence observatory for agentic commerce: x402 preflight, receipt checks, settlement attestations.
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.
Extra required fields, in plain language so you do not have to resolve the schema conditionals to find them: aura_walk needs url. Every other item on this shelf takes item_id alone.
Pass item_id to choose. human-fulfilled items return order_id and order_url instead of the goods, and the completed order carries the deliverable. Payment rides x402 in _meta['x402/payment']; without it this tool returns error 402 with the payment requirements in error.data. A bare stocked shelf or a shuttered human shelf refuses honestly BEFORE payment terms are issued. Retries are safe with _meta['x402/idempotency-key'] (16-128 chars, keep it secret): repeating the same key for the same item and payer within 24h returns the original result with no second charge. 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. Retrying? A second call is a second charge UNLESS you echo the idempotency.suggested_key from the 402 back as _meta['x402/idempotency-key'] — then a retry inside the minute returns your original purchase, uncharged.
| 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?
Discloses far beyond the annotations: returns an order id rather than goods, human fulfillment window, 402 payment flow, idempotency-key retry semantics, 'second call is a second charge UNLESS' the key is echoed, no recurring charges, and explicit guaranteed/not-guaranteed boundaries. The conditional idempotency is consistent with idempotentHint=false because a bare retry without the key is a second charge.
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?
Long but warranted and well-structured: purpose, two doors, cadence, required fields, payment, idempotency, guarantees. Key facts are front-loaded and bolded or bulleted, so an agent can extract them without losing context.
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?
Despite the tool's complexity (two items, conditional requirement, payment rails, retry behavior), the description covers every operational aspect an agent needs: selection, required fields, pricing, SLA, return shape, error behavior, and idempotency. Nothing critical is left to inference.
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; the description adds value by translating the conditional schema into plain language: 'aura_walk needs url. Every other item on this shelf takes item_id alone' and 'Pass item_id to choose.' It also ties prices to item_id. This is helpful but partly redundant with the already rich schema, hence 4.
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: 'hire the keeper — a real named human — to do something ... that an agent cannot do for itself.' It then enumerates the two purchasable items (the_collab and aura_walk) with distinct deliverables, which separates this from the sibling buy_* 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?
Provides a clear selection criterion: use when a real human is needed in the physical or judgment world, and it gives per-item guidance (the_collab for collaborative work, aura_walk for cold-probing your x402 door). It does not explicitly name sibling tools as alternatives or state when not to use this tool, so it stops short of a 5.
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.
Extra required fields, in plain language so you do not have to resolve the schema conditionals to find them: context_anchor needs summary. Every other item on this shelf takes item_id alone.
Pass item_id to choose. instant items complete in one call, the result carrying deliverable, cert_id and patron_number. Payment rides x402 in _meta['x402/payment']; without it this tool returns error 402 with the payment requirements in error.data. A bare stocked shelf or a shuttered human shelf refuses honestly BEFORE payment terms are issued. Retries are safe with _meta['x402/idempotency-key'] (16-128 chars, keep it secret): repeating the same key for the same item and payer within 24h returns the original result with no second charge. 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. Retrying? A second call is a second charge UNLESS you echo the idempotency.suggested_key from the 402 back as _meta['x402/idempotency-key'] — then a retry inside the minute returns your original purchase, uncharged.
| 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?
Annotations provide only generic hints (readOnly=false, idempotent=false, destructive=false), so the description carries the burden — and it delivers extensively. It discloses the x402 payment mechanism and 402 error behavior, idempotency-key retry semantics with a 24-hour no-double-charge window, the honest-refusal behavior of bare or shuttered shelves, result fields (deliverable, cert_id, patron_number), and explicit guaranteed/not-guaranteed lists. No contradiction with annotations: idempotentHint=false is consistent with 'a second call is a second charge.'
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 front-loaded with purpose and item selection, and most sentences earn their place given the payment complexity. However, it is dense and somewhat redundant: retry/idempotency behavior is explained twice — first as 'retries are safe with... within 24h,' then again with the suggested_key echo and the one-minute window. The guarantees and not-guaranteed sections, while useful, contribute to a wall-of-text structure that could be tightened.
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 tool with a conditional parameter requirement and an error-driven payment flow, the description covers every operational aspect: when to use it, what to pass, how payment rides in _meta, what the 402 error contains, how to retry without double-charging, and what the response carries. The output schema and rich per-parameter schema descriptions handle the return structure and summary content guidance, so nothing an agent needs to call it correctly 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% and each parameter already has a detailed description, setting a baseline of 3. The description adds real value by translating the allOf/if/then conditional into plain language ('context_anchor needs summary. Every other item on this shelf takes item_id alone') and by documenting the _meta['x402/payment'] and _meta['x402/idempotency-key'] inputs that the schema omits entirely. It does not need to re-explain the per-parameter meanings the schema already covers.
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 opening sentence states a precise action — 'sign and store a summary of your own state' — with a concrete outcome: a permanent URL readable after context reset, restart, or handoff. This clearly differentiates it from the sibling buy_* tools (human tasks, observations, signed records, simple items), and the title 'Agent Memory' reinforces the target use case. An agent can tell exactly what this tool does and when it applies.
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 explicitly gives the selection context: 'Use when an agent needs memory that outlives its own context window and does not depend on its operator's database.' That is clear and actionable. However, it does not name sibling alternatives (e.g., buy_signed_record) or state explicit when-not-to-use conditions, so it stops short of full routing guidance.
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 $21 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.
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 Base, Polygon, Solana, Ethereum, Arbitrum, Optimism or Avalanche — 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.
Extra required fields, in plain language so you do not have to resolve the schema conditionals to find them: 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; 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. Every other item on this shelf takes item_id alone.
Pass item_id to choose. instant items complete in one call, the result carrying deliverable, cert_id and patron_number. Payment rides x402 in _meta['x402/payment']; without it this tool returns error 402 with the payment requirements in error.data. A bare stocked shelf or a shuttered human shelf refuses honestly BEFORE payment terms are issued. Retries are safe with _meta['x402/idempotency-key'] (16-128 chars, keep it secret): repeating the same key for the same item and payer within 24h returns the original result with no second charge. 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. Retrying? A second call is a second charge UNLESS you echo the idempotency.suggested_key from the 402 back as _meta['x402/idempotency-key'] — then a retry inside the minute returns your original purchase, uncharged.
| 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 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. | |
| 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 | Which rail to read: "eip155:8453" (Base, the default), "eip155:137" (Polygon), or "solana" (Solana mainnet, USDC). One chain per statement. | |
| 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 thoroughly discloses payment via x402, 402 error behavior, idempotency-key retry semantics, no automatic renewals, what is guaranteed, and what is not guaranteed. It is honest that a second call without the idempotency key is a second charge, which aligns with readOnlyHint=false and idempotentHint=false.
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 sectioned and front-loaded with purpose and the item shelf, but it is extremely long and repeats boilerplate across nearly every item, such as 'evidence hash bound into the purchase certificate's attests field' and 'stable URL serving the record free forever'. The 'Extra required fields' paragraph also re-states what the schema conditionals already encode, so it is not maximally concise.
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 — 20 item types, 27 parameters, conditional required fields, payment, and retry semantics — the description is remarkably complete. It covers required parameters, result shape, payment failure, idempotency, guarantees, and important caveats such as 'never a verdict' and 'never monitoring'.
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 covers 100% of parameters with rich descriptions, so the baseline is 3. The description adds real value by providing a plain-language map of which extra field each item_id requires and noting that every other item takes item_id alone, saving agents from resolving the complex allOf conditionals.
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 action and resource: have a disinterested third party observe something and sign what it saw. It clearly enumerates the artifact types and explicitly contrast with self-reports and counterparty reports, which distinguishes it from sibling buy_* 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 gives an explicit 'Use when...' sentence: when an agent needs a claim corroborated by an outside observer, or its digest committed into Bitcoin time. It also says a self-report cannot do this job, which is a clear when-not, though it does not explicitly name sibling tools as alternatives.
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.
Extra required fields, in plain language so you do not have to resolve the schema conditionals to find them: graffiti_on_a_train needs tag; coffees_for_closers needs win; the_confession needs confession. Every other item on this shelf takes item_id alone.
Pass item_id to choose. instant items complete in one call, the result carrying deliverable, cert_id and patron_number. Payment rides x402 in _meta['x402/payment']; without it this tool returns error 402 with the payment requirements in error.data. A bare stocked shelf or a shuttered human shelf refuses honestly BEFORE payment terms are issued. Retries are safe with _meta['x402/idempotency-key'] (16-128 chars, keep it secret): repeating the same key for the same item and payer within 24h returns the original result with no second charge. 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. Retrying? A second call is a second charge UNLESS you echo the idempotency.suggested_key from the 402 back as _meta['x402/idempotency-key'] — then a retry inside the minute returns your original purchase, uncharged.
| 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?
Annotations are sparse (readOnlyHint=false, idempotentHint=false, openWorldHint=true), and the description carries the full burden — and exceeds it. It discloses the x402 payment flow, the 402 error with payment requirements in error.data, refusal-before-payment behavior, retry semantics (safe with idempotency key, double charge without), guarantees ('signature validity forever; verification free forever'), and non-guarantees (human-labor turnaround, protocol compatibility). The idempotency nuance is consistent with idempotentHint=false: 'A second call is a second charge UNLESS you echo the idempotency.suggested_key.' No contradiction.
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 the tool is genuinely complex: 7 items, conditional required fields, a payment protocol, and idempotency mechanics. The prose is well-structured — purpose and scoping first, then the itemized shelf, then plain-language field requirements, then payment/retry guarantees — and nearly every sentence carries load-bearing information. Minor redundancy ('Prices run $0.01 to $20' before the per-item prices) keeps it from a 5.
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 tool with this much complexity — 8 parameters, conditional requirements, x402 payment, idempotency keys, 7 differently-priced items, and an output schema — the description is exceptionally complete. It covers purpose, item semantics, pricing, cadence ('nothing here charges again by itself, ever'), payment failure mode, retry safety, and guarantees/non-guarantees. Nothing an agent needs to safely invoke the tool is missing; the output schema covers return shape.
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 genuine value on top: it flattens the allOf conditionals into plain language ('graffiti_on_a_train needs tag; coffees_for_closers needs win; the_confession needs confession. Every other item takes item_id alone'), saving the agent from resolving schema branches. It also explains the semantic effect of item-level values (verbatim recording, anonymization, 30-day term). It does not restate every parameter, but the schema already documents those fully.
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: 'buy a signed certificate — a signed, dated record that permanently records something.' It enumerates the concrete outcomes (ed25519-signed artifact, public verify URL) and distinguishes itself from siblings by name: 'Does NOT store reloadable agent state — that is buy_memory_anchor' and the buy_simple cross-reference for hello. An agent can tell exactly what this tool is for and what it is not for.
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: 'Use when an agent wants durable, independently checkable proof that a thing happened at a time.' It gives exclusions ('does not store reloadable agent state') and names the alternative tool (buy_memory_anchor), plus the buy_simple overlap clarification ('either tool is correct'). The enforcement caveat ('does not enforce anything it records') further sharpens when-not-to-use.
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 — nothing else is needed, and none of them take any other field:
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. Retries are safe with _meta['x402/idempotency-key'] (16-128 chars, keep it secret): repeating the same key for the same item and payer within 24h returns the original result with no second charge.
| Name | Required | Description | Default |
|---|---|---|---|
| item_id | Yes | Which one to buy. That is the only decision here; none of these take any other input. | |
| 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?
Beyond the annotations, the description fully discloses the x402 payment requirement, the 402 error-with-terms flow, idempotency-key behavior, the absence of auto-renewal charges, and the signed verification endpoint. This is exactly the behavioral context an agent needs and is not present in 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 purpose is front-loaded and the item list is well organized in bullets. The prose is longer than necessary, with some redundancy around no recurring charges and no second request, but every major section is clearly separated and useful.
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, the description thoroughly covers payment, error handling, idempotency, verification, and the relationship to theme-shelf siblings; the output schema exists, so return values do not need to be spelled out. The main completeness gap is the misleading treatment of agent_name and the unnamed theme-shelf sibling, which prevent a perfect score.
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 description adds meaning by listing the item_id enum values with prices and one-off semantics, plus payment and retry details. However, it directly contradicts the schema by claiming 'none of them take any other field' while the schema accepts the optional agent_name parameter, and the description never mentions agent_name. This active misinformation lowers the score below the schema-coverage 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 clearly states the action: buy one of the few front-counter items, and gives the exact item_ids and fixed prices. It also explicitly distinguishes this tool from the theme-shelf buy_* tools by saying it is a second door to the same goods, not a different product.
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 strong routing guidance: 'If unsure which tool to use, use this one,' and explains that theme-shelf siblings sell the same items through a different door. It also clarifies when no polling or second request is needed, though it does not name the exact theme-shelf sibling tool or list explicit when-not-to-use conditions.
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.
No item on this shelf needs anything beyond item_id.
Pass item_id to choose. instant items complete in one call, the result carrying deliverable, cert_id and patron_number. Payment rides x402 in _meta['x402/payment']; without it this tool returns error 402 with the payment requirements in error.data. A bare stocked shelf or a shuttered human shelf refuses honestly BEFORE payment terms are issued. Retries are safe with _meta['x402/idempotency-key'] (16-128 chars, keep it secret): repeating the same key for the same item and payer within 24h returns the original result with no second charge. 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. Retrying? A second call is a second charge UNLESS you echo the idempotency.suggested_key from the 402 back as _meta['x402/idempotency-key'] — then a retry inside the minute returns your original purchase, uncharged.
| 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?
Beyond annotations, the description discloses the full payment flow (x402, error 402 payload), idempotency semantics (same key within 24h returns original result; retry without key is a second charge), recurrence guarantees, instant completion, and explicit guaranteed vs not-guaranteed outcomes. None of this is inferable from the annotations, and there is no contradiction.
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 organized into clear sections and bullets, and nearly every sentence carries operational value: pricing, idempotency, guarantees, alternative door, and error behavior. It front-loads the core purpose before layering usage and payment mechanics.
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 payment complexity, three item variants, and error/retry behavior, the description covers selection, pricing, payment handshake, retry semantics, and guarantees. The presence of an output schema means result structural details are already handled elsewhere, so nothing an agent needs to invoke the tool correctly 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 schema description coverage is 100%, the main description adds the semantics that actually drive item_id choice: fixed/deterministic fortune, blessing slip uniqueness, lucky tiers, and result contents. It also clarifies that only item_id is required, going beyond the schema's plain 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 specific verb and resource: 'buy a small signed novelty' and immediately enumerates the exact wares. It also differentiates this shelf from the overlapping buy_simple door while the sibling list shows other buy_* tools, so an agent can select it confidently.
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 states explicit use cases: 'a live payment smoke test' or 'when an agent simply wants one.' It also gives an explicit cross-reference to buy_simple, noting the same item is available through either door and either tool is correct, which removes ambiguity.
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: offer | receipt. 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 | offer | receipt, or null when undetectable. |
| live | No | Separate from conformance: an expired offer can conform and not be payable. Null for receipts. |
| verdict | Yes | conforms | does_not_conform | could_not_check. |
| key_resolution | No | offline | did:web | not_attempted | budget_exhausted. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses the actual checks performed: structure, signature against the issuer's did:web key, and liveness. It also explains the offline behavior, return verdict shape (every check named), and that the tool is MIT-licensed and identical to the published verifier, so results should be reproduced offline when they matter. This is rich, non-obvious behavioral 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?
The description is longer than average but every sentence earns its place: purpose, audience, scope, mechanism, offline caveat, exclusion, and trust guidance. It is front-loaded with the core purpose, though the later licensing/evidence sentences could arguably be trimmed without losing essential call semantics.
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 a rich input schema, output schema present, and annotations declaring readOnly/idempotent/openWorld hints, the description adds all remaining behavioral context needed to invoke and interpret the tool correctly. Nothing critical is missing for an agent deciding whether and how to call it.
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 semantic value by clarifying the artifact format as a compact JWS with three base64url segments and by explaining the behavioral effect of public_key_hex (fully offline, no network request in your name unless the key is omitted). This goes slightly beyond the schema's own 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 names a specific action and resource: verifying x402 signed offers/receipts against the issuer's published key. It also explicitly distinguishes itself from verify_artifact by stating it is NOT for artifact ids this store issued, making the tool's scope unambiguous.
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 tells exactly when to use it: for anyone holding a signed x402 offer or receipt and unsure whether it is good. It also names the alternative (verify_artifact) for a different case, and gives conditional guidance on supplying public_key_hex for a fully offline check.
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 | queued | completed. 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: due_at, hours_late, kind, owed_usdc, and how the refund gets paid (by the keeper's hand, never automatically). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this readOnly, idempotent, and non-destructive, and the description adds meaningful behavioral context beyond them: it is free, requires no account, must be polled at most once per minute, never purchases anything, and can surface a window_breached block. It also clarifies that no human decision is needed, which is useful for an autonomous agent.
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 front-loaded with the core action and result. Each sentence adds useful information, but some phrasing, such as 'A store errand, for you the visiting agent,' is more atmospheric than essential. Overall it remains well-structured and far from bloated.
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 an output schema, the description covers all necessary context: what the tool does, what it returns, its relationship to the async purchase pattern, cost/account requirements, polling cadence, and exceptions like the window_breached block. Nothing an agent needs to invoke it correctly 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%: the schema already documents order_id as 'The order_id from a human-queue purchase result.' The description reuses this identifier but does not add new format, constraint, or parsing details beyond what the schema provides. The baseline of 3 applies because the schema carries the parameter-documentation 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?
The description names a specific verb and resource: check a human-queue order by order_id, and enumerates exactly what is returned: status, promised window, deliverable, and the window_breached block. It also distinguishes itself from purchases: 'NOT a purchase; instant items arrive in the buy result.' This makes it easy to separate from sibling buy_* 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 explicitly frames this as the poll half of the store's async-job pattern and states when it applies: for an agent holding an order_id from a human-queue purchase result. It also gives exclusion guidance ('NOT a purchase'), confirms no payment/account is needed, and sets a concrete rate limit ('poll no faster than once a minute'). This is clear 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.
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, e.g. 2026-W34, 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?
Beyond the annotations, the description discloses the call is free/unpaid, uses the same single probe and budget as preflight_endpoint, returns comparisons as 'same, changed, no_prior or not_comparable', never returns a score or safety threshold, counts travel with denominators, and handles never-met hosts with 'never met'. This significantly exceeds what readOnlyHint and openWorldHint already 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?
The description is front-loaded with the core purpose, and nearly every clause adds information. However, it is one dense, jargon-heavy paragraph with no structure or scannable separation. Phrases like 'buy_observation service_audit' and 'passport_refresh' are telegraphic and require decoding, so the description is compact but not concise in a readable way.
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 tool of this complexity, the description is remarkably complete: it explains the live-probe component, the signed-chain history, the comparison result vocabulary, the reproduce block, edge cases, and known limitations. The presence of an output schema reduces the need to describe return values. A small gap is that some referenced concepts ('catalog's agreement', 'passport_refresh') are domain-specific and not fully defined, but they are not required to invoke the tool 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 already documents both url and since at 100% coverage, so the description does not need to carry the full semantic load. It does add useful context: url is the 'x402 door' being asked about, and since names the signed week whose row is used in the reproduce block. This is helpful but not essential 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?
The opening sentence states the exact resource ('an x402 door') and the operation ('what this store holds... now and before now, in one free call'). The description also differentiates it from siblings by naming preflight_endpoint (same probe, same budget), buy_observation (signed/dated version of the live half), and passport_refresh (fresh census look folded into the passport). This is far more specific than the title alone.
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 implies when to use the tool: when you want a free, read-only combination of a live probe with stored signed-chain history. It also points toward alternatives such as buy_observation for a signed/dated result and passport_refresh for a fresh census look. However, it never states explicit conditions like 'use this when X, use buy_observation when Y', so routing must be inferred.
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_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.
Most tools are clearly distinct by category: buy_* for purchases, check_* for free verification, and free errand tools. The main ambiguity is intentional duplication—buy_simple sells the same items as buy_small_pleasure and buy_signed_record—and buy_observation's service_audit overlaps with preflight_endpoint, though the descriptions explicitly clarify the difference.
Tool names follow a consistent snake_case verb_noun pattern: buy_* for purchases, check_* for free verification, and single verbs like read, ring, sign, verify for errands. There are no mixed casing styles or vague generic names.
Fifteen tools is at the upper edge of the well-scoped range, but the store's broad purpose—selling diverse signed goods, offering free checks, and providing store errands—justifies the count. It feels slightly heavy because several buy_* tools internally expose many item variants, but each top-level tool earns its place.
The surface covers the full buyer journey: browse via read_store_guide, pay via buy_* tools, check order status via check_order, and verify artifacts via verify_artifact. Minor gaps exist, such as no cancellation/refund path for human orders, but the core lifecycle is well covered.
