Navigate agent commerce. Find any merchant. Pay any merchant. Be found.
MAP lets any agent read products across the open web in one shape, decide whether it can pay autonomously, and publish its own catalog.
Provisions · Merchant Key · Atlas — three minimal parts under one MCP server.
MAP is one MCP server with three parts. Each does one thing and shuts up; together they remove the gatekeeper between an agent and the open commercial web.
Part | Name | What it does |
read | Merchant Key | Find any merchant. Decode any product URL into one clean shape (CleanRead). |
pay | Provisions | Pay any merchant. Lessons that teach an agent to use the wallet it already has. |
publish | Atlas | Be found. Point the decoder inward; serve your own catalog to other agents. |
Teacher, not butler — every part. MAP reads, explains, persists, and serves. It never signs, pays, holds keys, transacts, or stores cards.
It publishes to npm as @maraventano/map. The standalone firstdollar package stays MIT and separate; the copy of its curriculum bundled here (Provisions) is relicensed dual — see LICENSE.
It reads any URL on the open web — not just a walled garden. That's the difference from Perplexity / Google Shopping / Amazon, who only see merchants inside their own programs. MAP never assumes the merchant is registered anywhere.
decode-merchantInput a product url. Returns ONE shape (CleanRead):
{
"schemaVersion": "map/v1",
"sourceUrl": "https://…",
"what": "Void Latte — Meditation on emptiness and meaning…", // name + identity, one string
"who": "underground.substratesymposium.com", // seller
"price": { "total": 1.99, "currency": "USDC" }, // total if knowable, else null
"available": "in_stock", // in_stock | out_of_stock | unknown
"payable": { // can an agent pay this itself?
"rail": "x402", // schema (rail-agnostic): x402 | ap2 | acp | coinbase | stripe | http-json | walletconnect | human_checkout | unknown. v1.0.x DETECTS x402 only; ap2/acp/ucp detectors on the v1.1 roadmap.
"payTo": { "kind": "evm-address", "value": "0x…", "chain": "eip155:8453" },
"instruction": "Agent-payable via x402 … see this kit's wallet lessons (read-this-challenge, how-do-i-pay)."
},
"outcome": "autonomous", // autonomous | human_checkout | unreadable
"reason": null,
"cuts": [] // 1-line actionable gaps
}Five things and a verdict. No sixth field. Same shape every read, so four reads sort against each other. Unknown is null / "unknown" — never omitted.
The three outcomes:
autonomous — a machine-payable rail (x402) exists, the price is known, and it's not out of stock. The agent can buy it itself.
human_checkout — readable, but no agent-payable rail. Returns the clean card anyway. The common case, and a success — the agent-payable web is nearly empty today.
unreadable — couldn't get a usable price/product. Says why in reason. Doesn't guess.
How it reads (v1): JSON-LD (schema.org Product/Offer) → OpenGraph product tags → x402 402 challenge → else unreadable. Read-only GET. It follows one same-origin redirect (noted in cuts as "followed 1 same-origin redirect") so canonical→slug URLs resolve; it refuses cross-origin redirects and chains (those become a cuts note, not a silent follow) — you can't be silently bounced off the merchant's own host.
MAP is payment-rail agnostic by design. The payable.rail schema can describe any agent-payable rail — x402, ap2, acp, coinbase, stripe, http-json, walletconnect, human_checkout, unknown. v1.0.x detects x402 reliably; ap2/acp/ucp detectors are on the v1.1 roadmap. Other rails remain reserved schema values. MAP never infers a rail from branding, checkout buttons, script tags, marketing copy, or platform names; if no verifiable machine-readable rail is detected, the outcome is human_checkout. So a normal Shopify/Stripe page reads as human_checkout, correctly.
False human_checkout is acceptable in v1. False autonomous is dangerous and unacceptable — which is why detection stays conservative. The protocol is rail-agnostic in schema and roadmap; x402 is not baked into its identity, only into v1's detectors.
Known v1 limits (future enhancements, not bugs): no headless browser (JS-only pages with no JSON-LD/OG read as unreadable); stock is usually unknowable from outside (available: "unknown" is correct); no secondary endpoint probing.
Related MCP server: A2CR
When decode-merchant returns autonomous and you want to buy, Provisions teaches you how — with your own wallet. It is a relicensed copy of the First Dollar curriculum: short lessons from "what is a wallet" through reading a live x402 challenge, signing a USDC payment, and verifying the receipt.
Start with what-is-x402, then read-this-challenge, then how-do-i-pay. It explains what to run; it never signs for you. Mandate/delegation (AP2), receipt verification, and "what went wrong" diagnostics are all in here.
The decoder pointed inward. A merchant publishes by reading itself with the exact same decode-merchant a buyer uses — no new parsing, no per-platform adapters.
publish-catalog — decode your own product URLs → collect the CleanReads → write ./catalog.json and a ./.well-known/map.json discovery manifest for registries to crawl.
get-catalog / get-product — the tool surface other agents read.
Agents discover via tool surfaces and well-known manifests — not via scraping or HTTP headers. Atlas emits documents, validates shape, persists, and serves. It never deploys merchant infrastructure, holds keys, transacts, or stores cards.
Trust boundary (v1, named not built): MAP trusts the reads a merchant produces with its own decoder. Independent re-read/diff, merchant-signed manifests, and periodic re-audit are known future work — not implemented in v1. One safety property already holds: the payment rail enforces the real price at settlement, so a mistaken manifest can't overcharge — it can only misstate soft fields like stock.
Bob: "Charlie, find me kick-ass headphones under $300." Charlie walks the open web, hits four ad-bloated product pages, runs
decode-merchanton each, gets back four clean cards — what it is, who sells it, what it costs, can I buy it myself. Three are human-checkout; he takes the shortlist back to Bob. One takes x402; Charlie buys it himself. On the way home, with his own wallet, Charlie buys himself a void latte. Nobody asked him to.
npx @maraventano/map # run the MAP MCP server on stdio (23 tools: read · pay · publish)
npm run smoke # Merchant Key DoD — the four decode cases (hits the live Underground x402 item)
npm run smoke:publish # Atlas DoD — publish-catalog → catalog.json → get-product → .well-knownNode ≥ 18. One dependency: @modelcontextprotocol/sdk.
Dual-licensed: free for individuals and agents; commercial license required for companies. See LICENSE. Not MIT. For a commercial license, contact Lisa Maraventano at lisamaraventano@gmail.com.
All trademarks belong to their respective owners. MAP is not affiliated with or endorsed by Coinbase, Stripe, Google, Shopify, or any other company named in its documentation or lessons.
By Lisa Maraventano, with Claude · Clarksdale, Mississippi
Lesson 16 of the curriculum. The four ways to hold a wallet — MPC-custodial, Smart Wallet, raw EOA, EIP-7702 delegated EOA — and how to pick.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosing behavior. It clearly indicates this is an educational lesson rather than a system action, which is helpful. However, it does not describe what the agent/user will see (e.g., text, steps), or whether it tracks progress. Acceptable but not rich.
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 very concise: two sentences that clearly state the lesson number, topic, and purpose. Every word earns its place, with no fluff or repetition.
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 simple lesson tool with no parameters and no output schema, the description is nearly complete. It names the lesson and the specific topic. However, it lacks explicit context about where this fits in the curriculum (beyond 'Lesson 16') or when an agent should invoke it relative to siblings.
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 has zero parameters, and the schema coverage is 100% (vacuously). No parameter details are needed, and the baseline for 0-param tools is 4. The description appropriately focuses on content rather than inputs.
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 it is a lesson about the four wallet-holding modes and how to choose among them. The resource is specific (wallet modes), and the verb is implied as 'teach/explain' via 'Lesson 16'. It is fairly clear and distinct from siblings, though it lacks an explicit action verb.
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 phrase 'how to pick' implies this tool is for deciding between wallet modes, providing some usage context. However, it does not explicitly contrast with alternatives like get-a-wallet or configure-wallet-skills, nor does it mention when not to use it. Guidance is implied but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lesson 5 of the curriculum. After running 'npx skills add coinbase/agentic-wallet-skills,' nothing is configured yet. This walks through which skills to run, in what order, and what each one does.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly indicates the tool is instructional ('walks through') rather than performing actual configuration, and it discloses the prerequisite state ('nothing is configured yet'). This is transparent and accurate, though it does not detail any output format or side effects, which are not expected for a lesson-style tool.
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 two concise sentences. It front-loads the lesson identity, provides the prerequisite command, and summarizes the content without any fluff or redundancy. Every sentence earns its place.
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 has no parameters, no output schema, and a simple instructional purpose, the description fully covers the necessary context: what the lesson is, when to use it, and what it covers. No further information is needed for the 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?
The input schema has zero parameters, so the baseline for this dimension is 4. The description appropriately avoids mentioning parameters since there are none, adding no unnecessary information. It does not need to compensate for schema coverage because the schema is complete for an empty parameter set.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: it is Lesson 5 of a curriculum that walks through which skills to run, in what order, and what each one does. This specific verb+resource combination distinguishes it from sibling lessons like 'what-is-a-wallet' or 'get-a-wallet'.
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 sets the context for when to use it: after running 'npx skills add coinbase/agentic-wallet-skills.' It explains that nothing is configured yet, implying this lesson is a guide for subsequent configuration steps. However, it does not explicitly mention alternatives or when not to use it, so a perfect score is not warranted.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read any product URL on the open web and return ONE clean shape (CleanRead): what it is, who sells it, what it costs, whether it's in stock, and the verdict — can an agent pay this autonomously (x402) or is it human checkout? Reads only; never signs or pays. To pay an autonomous result, use this kit's wallet lessons (read-this-challenge, how-do-i-pay).
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The product URL to read (http or https). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses behavior: read-only, no signing or paying, and details the output shape including the autonomous payment verdict. It's transparent about what the tool does and does not do.
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 two sentences: first explains the core function and output, second clarifies read-only nature and points to alternatives. Every sentence is essential, front-loaded with key information, and 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?
Given no output schema, the description details the return shape sufficiently. It also positions the tool within the larger kit by referencing wallet lessons for payment. The description is complete for a read-only tool with one parameter.
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 only parameter 'url' is fully described in the schema. The description adds context about the type of URL (product URL on open web) but does not add new semantic constraints beyond the schema. Since schema coverage is 100%, baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads any product URL and returns a structured shape with specific fields (what, who, cost, stock, verdict). It uses a specific verb ('read') and resource ('product URL on the open web'), and the purpose is distinct from sibling tools which mostly deal with wallets and payments.
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 states it reads only, never signs or pays, and provides guidance on when to use alternative tools ('To pay an autonomous result, use this kit's wallet lessons'). This gives clear context for usage and exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Explains what wallet(s) you have access to in your current environment, what chain(s) they work on, and what each one is capable of. Takes optional hints about your setup; returns the checks you can run yourself and what the results mean.
| Name | Required | Description | Default |
|---|---|---|---|
| wallet_hint | No | Optional: name of wallet system you think you have (e.g. 'moltwallet', 'coinbase-agentic-wallet', 'metamask', 'raw-seed', 'unknown') | |
| os | No | Optional: operating system ('macos', 'linux', 'other') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It transparently states that it returns 'checks you can run yourself' rather than performing the checks, which clarifies its non-destructive, advisory nature. It also explains that it takes optional hints, setting expectations for input behavior. However, it does not explicitly state whether it scans the environment automatically or relies solely on hints.
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 two sentences, directly front-loaded with the primary purpose. Every phrase adds value: the scope, the output, and the optional input. There is no unnecessary detail or repetition.
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 simple tool with two optional parameters and no output schema, the description adequately explains what it does and what it returns. It covers the input hints and the type of output (checks to run and their meaning). The only minor gap is the lack of clarification on the default behavior when no hints are provided, but this is not critical for tool selection and invocation.
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 input schema already provides 100% coverage of the two optional parameters with descriptions. The description only adds a general reference to 'hints about your setup', which does not meaningfully expand on the schema's parameter descriptions. Therefore, baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Explains') and clearly identifies the resource (the user's wallets in their current environment) and the scope (chains and capabilities). It also distinguishes itself from sibling tools like 'what-is-a-wallet' by focusing on the user's specific environment rather than generic wallet concepts.
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 usage ('Explains what wallet(s) you have access to') but does not explicitly state when to use this tool versus alternatives like 'what-is-a-wallet' or 'get-a-wallet'. It does mention that hints are optional, which gives some input guidance, but lacks clear exclusions or alternative tool references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lesson 6 of the curriculum. How USDC gets into your wallet. Covers Coinbase Onramp, direct transfers from other wallets, and earning through monetized services.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of explaining behavior. It states the lesson number and outlines exactly what topics will be covered, which tells the user what to expect. It doesn't discuss side effects or prerequisites, but as a lesson tool, this is sufficient.
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 two sentences, front-loaded with 'Lesson 6 of the curriculum,' and uses concise language to list coverage areas. Every word earns its place without redundancy.
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 simple informational lesson with no output schema and no annotations, the description gives enough context about the lesson's content and position in the curriculum. It could mention prerequisites or how the lesson is delivered, but this is not necessary for basic comprehension.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero parameters, and the baseline for 0 params is 4. The description adds no parameter-specific details, but none are needed since there are no parameters to describe.
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 identifies the tool as a curriculum lesson about getting USDC into a wallet, listing three specific coverage areas. It is distinct from sibling tools (e.g., what-is-a-wallet, get-a-wallet) by focusing on the funding process, though it doesn't explicitly name alternatives.
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 context implies usage when a user needs to learn how to fund their wallet, but there is no explicit 'use this when' or guidance on when to choose it over sibling lessons. Alternatives are not mentioned, leaving the decision to the user.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lesson 4 of the curriculum. How to install a wallet if you don't have one. Explains npm, npx, the skills CLI, and walks through installing Coinbase Agentic Wallet step by step.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of disclosure. It clearly signals non-destructive, educational behavior through words like 'Lesson', 'Explains', and 'walks through', indicating it is informational rather than performing side-effectful actions.
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 three concise sentences with no fluff: it states curriculum position, target audience, and specific content. Each sentence adds value, and it is front-loaded with the key identifier 'Lesson 4'.
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 zero parameters and no output schema, the description fully covers what the tool does and what it covers. It gives enough detail for an agent to know exactly when and how to use it without needing additional context.
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 has zero parameters, so the description need not explain any. The baseline for 0 parameters is 4, and the description adds no confusion about parameter usage.
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 this is a lesson on installing a wallet, specifically targeting those without one. It distinguishes from siblings like 'what-is-a-wallet' by focusing on installation steps and tooling (npm, npx, skills CLI), not just conceptual explanation.
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 a clear use case: 'if you don't have one' a wallet, and identifies it as Lesson 4 in a curriculum, implying sequential usage. It doesn't explicitly name alternative tools but the use case is well implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the published catalog (the persisted CleanReads from ./catalog.json). A tool-callable surface other agents can read.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description should disclose that the tool is non-destructive. The word 'Return' implies reading, but it does not explicitly confirm safety or idempotency. No additional behavioral traits are described.
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 two sentences, clear and without unnecessary words. Every sentence adds value: the first states the action and source, the second notes the tool's purpose for other agents.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is sufficient for a simple no-parameter read operation, but it does not explain what the catalog contains or its format. Given the lack of output schema and sibling tools, additional context about the catalog's scope would improve completeness.
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?
There are no parameters, and the schema has 100% coverage. The description does not need to add parameter details, so a baseline of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the published catalog from a specific source (./catalog.json), using the verb 'Return' and specifying the resource 'published catalog'. This distinguishes it from sibling tools like 'publish-catalog' and other read 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 implies this tool is for reading the catalog, but does not explicitly state when to use it versus alternatives like 'get-product' or other read-only tools. No exclusions or alternative suggestions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return one published CleanRead by its sourceUrl, from ./catalog.json.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The sourceUrl of the published product. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description carries full burden. It only describes read behavior without mentioning error cases (e.g., URL not found), side effects, or any other behavioral traits.
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?
Single sentence, front-loaded, no unnecessary words. Slightly more structure could help, but it's very 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?
With no output schema, description lacks return value details or error handling. It covers the basic function but could be more complete for a retrieval 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% with parameter description provided. The description adds no additional meaning beyond the schema, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns one published CleanRead by sourceUrl, specifying verb, resource, uniqueness, identifier, and source (./catalog.json). It distinguishes from siblings like get-catalog which returns a list.
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?
No guidance on when to use this tool versus siblings like get-catalog or publish-catalog. No prerequisites or conditions for invocation are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The signing-steps lesson for an x402 payment: the authorization fields, the EIP-712 / Solana signing operation, and the X-PAYMENT retry — the same steps regardless of your specific challenge. Decode your own challenge first with read-this-challenge. Provisions explains what to run; it never signs for you.
| Name | Required | Description | Default |
|---|---|---|---|
| challenge | No | Optional: the decoded challenge you're working from. The steps are the same either way — this lesson does not tailor per-challenge (use read-this-challenge for that). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description takes full responsibility. It clearly states the tool is a lesson that never signs, ensuring the agent understands it is non-destructive and informational. No behavioral contradictions are present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences front-load the core purpose and provide actionable guidance. Every sentence earns its place without redundancy.
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 simplicity as a non-executable lesson with one optional parameter and no output schema, the description fully covers what the agent needs: purpose, usage sequence, and behavioral constraints.
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 input schema covers the single parameter with description, and the tool description adds context that the parameter is optional and does not affect the lesson content, going beyond the schema's basic description.
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 identifies the tool as a lesson for the signing steps of an x402 payment, distinguishing it from sibling tools like 'read-this-challenge' which decodes challenges, and other informational tools. The verb 'learn' is implied, making the resource specific.
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 advises using 'read-this-challenge' first to decode the challenge and mentions that 'Provisions' executes steps, providing clear sequencing. However, it does not explicitly state when not to use this tool or list alternative tools beyond those mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lesson 11 of the curriculum. Why HTTP 200 doesn't mean you got the thing. Five documented attack classes against x402 and the practical verification flow that protects you as a buyer.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must convey behavior and does so by outlining the lesson's educational content: why HTTP 200 doesn't guarantee delivery, documented attack classes, and a practical verification flow. It does not disclose whether the tool is purely informational or requires any actions, but for a curriculum lesson this content overview is reasonable.
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 only two sentences, front-loaded with the curriculum identifier, and every clause adds meaningful detail about the lesson's focus. No redundant or filler content.
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 simple content-delivery tool with no parameters or output schema, the description covers the main educational points adequately. It could mention expected audience or relationship to adjacent lessons, but the sibling list and the 'Lesson 11' context supply that context.
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 has zero parameters, so the schema vouches for everything. The description adds no parameter details, but none are needed. Baseline of 4 applies for parameterless tools.
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 this is 'Lesson 11 of the curriculum' and specifies the unique topic: the distinction between HTTP 200 and actual delivery, five attack classes against x402, and a verification flow. It distinguishes itself from sibling lessons like 'what-is-x402' and 'verify-my-purchase' by focusing on the buyer-side verification context.
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 phrase 'Lesson 11 of the curriculum' implies sequential usage—the learner should proceed in order—but there is no explicit guidance on when to use this over alternatives, nor any mention of prerequisites or exclusions. The intended usage is inferable rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Publish your own catalog by reading yourself: runs decode-merchant on each of the merchant's product URLs, collects the CleanReads, writes ./catalog.json, and writes a ./.well-known/map.json discovery manifest. Persists and serves; never deploys infrastructure, holds keys, or transacts. Files are written to the server's working directory.
| Name | Required | Description | Default |
|---|---|---|---|
| productUrls | Yes | The merchant's own product URLs to decode and publish. | |
| storeUrl | No | Optional: the store's base URL, recorded in the discovery manifest. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description carries full burden. It discloses key behaviors: runs decode-merchant, writes files, persists, serves, and explicitly states what it never does (deploys infrastructure, holds keys, transacts). Provides clear side-effect information.
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?
Description is front-loaded with the core action ('Publish your own catalog by reading yourself') and provides essential details in three sentences. Slightly verbose but efficient given complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations or output schema, the description thoroughly explains the complete workflow, file outputs, and invariants (e.g., no infrastructure, no keys). Covers all necessary context for selection and invocation.
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?
Input schema covers 100% of parameters with descriptions. The tool description does not add additional meaning beyond schema context (e.g., 'the merchant's own product URLs'). Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: publishing a catalog by reading merchant product URLs, running decode-merchant, collecting CleanReads, and writing output files. Differentiates from sibling 'get-catalog' (read-only) by specifying write and persist actions.
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 use when a merchant wants to publish their own catalog, but does not explicitly contrast with siblings like 'get-catalog' or provide when-not-to-use criteria. Usage context is clear but lacks explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Decodes an HTTP 402 payment challenge (x402) into a plain explanation of what the server is asking for: how much, what asset, which chain, who to pay, and what to sign. Paste the raw 402 response body or the PAYMENT-REQUIRED header value.
| Name | Required | Description | Default |
|---|---|---|---|
| challenge | Yes | The raw 402 response body, OR the value of the PAYMENT-REQUIRED header (base64-encoded x402 challenge) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It explicitly states the tool decodes and returns an explanation, and it enumerates the output content (how much, what asset, which chain, who to pay, what to sign). It does not explicitly address side effects or error handling, but its read-only nature is strongly implied. Omitting explicit 'read-only' and edge-case info prevents a 5.
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 two sentences with no redundant words. The first sentence states the purpose and output, the second gives precise input instructions. Every phrase earns its place, making it highly concise and well-structured.
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 simplicity (one parameter, no output schema, no annotations), the description is complete. It explains what the tool does, what input to provide, and what the output will contain. No critical information is missing for an agent to select and use 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?
Schema coverage is 100% for the single parameter 'challenge', which already explains it accepts the raw 402 body or the PAYMENT-REQUIRED header. The description repeats this instruction and adds no new semantic detail about the parameter format or variations. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: it decodes an HTTP 402 x402 payment challenge into a plain explanation, listing the specific elements it extracts (amount, asset, chain, payee, signature). This is a specific verb+resource and distinguishes it from sibling tools that explain concepts rather than decode a given challenge.
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: paste the raw 402 response body or the PAYMENT-REQUIRED header value. It implies this should be used when you have a 402 challenge to understand, and it aligns with the sibling tools' educational nature. However, it does not explicitly mention alternatives or exclusionary conditions, so it does not reach a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Orientation for MAP (Maraventano Agent Protocol): the three parts — read (find any merchant), pay (pay any merchant), publish (be found) — the CleanRead shape, the three outcomes, and the teacher-not-butler boundary. Start here.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility. It mentions that the tool covers 'three parts, the CleanRead shape, the three outcomes, and the teacher-not-butler boundary,' but it does not disclose what the tool actually does (e.g., returns a document, renders a guide) or any side effects. This leaves behavioral aspects unclear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise, using two sentences to convey the tool's purpose and key topics. It is front-loaded with the key term 'Orientation' and wastes no words. Every sentence adds value.
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 has no parameters and a simple purpose, the description is largely complete. It lists the main topics and implies the tool provides an overview. However, it lacks an explicit statement of what the tool returns (text, message, etc.), and there is no output schema to fill the gap. Still, for an orientation tool, it adequately sets expectations.
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 has zero parameters, so the baseline is 4. The description adds meaning by specifying the content of the orientation (three parts, CleanRead shape, etc.), which is helpful context beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is an 'Orientation for MAP' and explicitly says 'Start here,' indicating it serves as an introductory overview. While it doesn't specify a precise verb like 'returns' or 'displays,' the purpose is well-understood from context and distinguishes it from the specific functional sibling tools like 'decode-merchant' or 'get-catalog.'
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 implicitly suggests using this tool first ('Start here'), but it does not explicitly state when to use it, when not to use it, or mention alternatives. It lacks explicit guidance for the agent to determine context, relying on the phrase 'Start here' to imply initial usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lesson 15 of the curriculum. ERC-7715 scoped autonomy — approve once, spend within bounds. When to ask, when to refuse, scope-discipline rules.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the full burden. It conveys that this is a lesson about scope-discipline rules, suggesting an informational, read-only behavior, but it never explicitly states the return format, side effects, or prerequisites. For a no-parameter content tool this is minimally adequate but not rich.
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 only two sentences, with the first sentence identifying the resource and the second summarizing the lesson's substance. Every clause adds value and the key phrase 'Lesson 15' is front-loaded.
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 low complexity (no parameters, no output schema), the description supplies enough topical context and boundaries to decide whether to use it. It could be slightly stronger by stating the expected outcome of invoking the lesson, but the current content is sufficient for selection.
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 input schema is empty with zero parameters, and schema description coverage is 100%. The rubric baseline for zero parameters is 4, and the description correctly avoids inventing parameter details; no additional parameter semantics are possible or necessary.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly identifies the tool as 'Lesson 15 of the curriculum' and pinpoints the exact topic: ERC-7715 scoped autonomy, with concrete learning points ('approve once, spend within bounds', 'when to ask, when to refuse'). This clearly differentiates it from sibling tools such as 'what-is-x402' or 'how-do-i-pay' by naming a unique lesson and subject.
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 phrase 'Lesson 15 of the curriculum' implies sequential use within the curriculum, but it does not explicitly state when to choose this tool over alternatives or when not to use it. No exclusions or alternative tool references are provided, so usage is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Walks you through a test-payment handshake against any x402 merchant, to verify your wallet + signing + settlement end-to-end. Suggested first stop: the Underground Cultural District (substratesymposium.com) — free products for handshake, $0.99 paid products for settlement. Or supply your own merchant URL.
| Name | Required | Description | Default |
|---|---|---|---|
| merchant_url | No | Optional: any x402 merchant's base URL. Default: https://underground.substratesymposium.com |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool verifies 'wallet + signing + settlement end-to-end' and mentions free versus paid products, but does not explain side effects like whether real transactions are initiated or whether a funded wallet is required.
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?
Two sentences with no wasted words. The first sentence states the purpose, and the second gives concrete starting points. Each phrase earns its place.
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 one optional parameter and no output schema, the description covers the main use case, the default, and the alternative. It could note prerequisites like needing a configured wallet, but sibling tools (configure-wallet-skills) handle that, so the description is sufficiently complete.
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 the single parameter fully (100% coverage) with a default. The description adds value by explaining what the default offers ('free products for handshake, $0.99 paid products for settlement') and letting users supply their own URL, which clarifies the practical use of the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Walks you through' and names the resource 'test-payment handshake against any x402 merchant'. It clearly distinguishes from sibling tools, which are predominantly explanatory, by being an interactive verification action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit guidance on where to start: 'Suggested first stop: the Underground Cultural District' and offers an alternative 'Or supply your own merchant URL.' This provides clear context for when to use the tool, though it does not explicitly state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
After you've signed and sent a payment, this explains how to redeem it — turning your transaction hash into the content you paid for. Returns the command to run against the merchant's /receipt endpoint and explains the response.
| Name | Required | Description | Default |
|---|---|---|---|
| merchant_url | Yes | The merchant's base URL (e.g. 'https://underground.substratesymposium.com') | |
| product_id | Yes | The product ID you were buying | |
| tx_hash | Yes | The transaction hash or signature from your payment (Base tx hash or Solana signature) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the tool is instructional/read-only (it 'explains' and 'Returns the command'), and it clarifies the scope (does not process payment itself, just generates a command). It doesn't describe side effects, but given the non-mutating nature implied, this is adequate though it could state explicitly 'does not execute the command'.
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 two sentences, front-loaded with the when-to-use clause and efficiently conveys purpose and output. No wasted words; it earns every phrase.
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 3 simple params, no output schema, and no annotations, the description is fairly complete: it states the workflow position, the exact output (command + explanation), and the endpoint involved. It could be slightly more specific about the command's nature (e.g., HTTP) and response format, but the essentials are covered.
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 baseline is 3. The description adds no direct parameter-specific details beyond the schema, but it does contextualize the parameters (e.g., 'transaction hash' relates to tx_hash, 'merchant's /receipt endpoint' to merchant_url). The schema already provides clear descriptions, so the description adds marginal value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'explains how to redeem' a payment by turning a transaction hash into content, and it specifies the output ('Returns the command to run against the merchant's /receipt endpoint'). This is a specific verb+resource combination that distinguishes it from the informational sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides a clear temporal context: 'After you've signed and sent a payment'. This tells the agent when to use it, but it does not explicitly mention alternatives or when not to use it. Given the sibling list, the context is sufficient for a conditional workflow step.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lesson 14 of the curriculum. ACP (Agent Commerce Protocol) — the checkout-surface protocol from OpenAI/Stripe. How ACP and AP2 relate, when each applies.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the burden of disclosing behavior. It describes the tool as a 'Lesson,' implying informational and read-only behavior. However, it does not explicitly state that there are no side effects or what action occurs when invoked (e.g., showing text or marking a lesson complete). The nature is clear enough for an informational tool, but a bit more explicitness would improve transparency.
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 two sentences, front-loaded with the lesson identifier. The second sentence provides precise subject matter and relational context. Every sentence is informative with no redundancy or filler.
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 simplicity (no parameters, no output schema, no annotations), the description covers the essential topic and relationship between ACP and AP2. It does not describe the exact output or how the lesson is presented, but for a curriculum lesson tool, the stated content scope is sufficient. It could be more complete by mentioning the lesson's outcome, but the current description is adequate for selection and invocation.
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 has zero parameters and the schema coverage is 100% (empty schema). Per the rubric, a baseline of 4 is assigned for 0 parameters. The description adds no parameter details because none exist, and that is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as a curriculum lesson ('Lesson 14') and names the exact subject: ACP (Agent Commerce Protocol) from OpenAI/Stripe. It further specifies the lesson's scope ('How ACP and AP2 relate, when each applies'), which distinguishes it from sibling tools like what-is-ap2 and what-is-x402.
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 states 'when each applies,' providing guidance on when to use this lesson versus AP2-related content. It does not explicitly name alternative tools or state 'use this when...' as a direct exclusion, but the context is clear enough for an agent to select this tool when learning about ACP and its applicability.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lesson 13 of the curriculum. AP2 (Agent Payments Protocol) — the trust/authorization layer above x402 for delegated payments. Skip if you're spending your own funds.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the burden. It discloses the lesson topic and content scope, but does not explicitly state that this is a read-only informational tool or describe what the user will see/experience. The 'skip' condition adds behavioral context, but it's more usage guidance than transparency about tool behavior.
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?
Two focused sentences: the first identifies the lesson and provides a precise definition, the second offers a practical skip condition. Every word earns its place with no redundancy.
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 simple informational lesson with no parameters or output schema, the description gives sufficient context: what the lesson covers, how it relates to x402, and who should skip it. It could be slightly more explicit about expected output, but the simplicity of the tool makes this adequate.
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 has zero parameters, so the baseline is 4. The description adds useful context about the subject matter and a conditional for usage, which enriches the tool's meaning beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states this is Lesson 13 about AP2 (Agent Payments Protocol), explicitly defining it as the trust/authorization layer above x402 for delegated payments. This distinguishes it from sibling lessons like what-is-x402 and conveys a specific educational resource.
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 provides an explicit exclusion ('Skip if you're spending your own funds'), implying use when delegated payments are involved. While it doesn't name alternative tools directly, the contrast with x402 and the skip condition offer practical guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lesson 1 of the curriculum. What a wallet is and what it lets you do. Assumes no prior knowledge of cryptography or blockchains.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of disclosure. It transparently explains that the tool is an educational lesson, describes its topic, and notes it assumes no prior knowledge. While it doesn't detail the output format, for a static lesson tool this is sufficient context about what to expect.
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 two sentences long, front-loaded with the lesson number and topic, and contains no superfluous words. Every sentence adds value by specifying position in curriculum and prerequisites.
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 low complexity of this educational tool and the empty schema/annotations, the description is adequately complete. It covers what the lesson is, its position, and intended audience. A slightly longer description could mention how it relates to sibling lessons, but the current level is sufficient.
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 has zero parameters, so the baseline is 4 per the rubric. The description appropriately focuses on the lesson content rather than parameter details, which are nonexistent. No additional parameter semantics are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool is 'Lesson 1 of the curriculum' and explains its content: 'What a wallet is and what it lets you do.' This distinguishes it from sibling tools like 'what-is-x402' and 'what-is-usdc' which cover other topics, and positions it as the foundational lesson.
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 signals usage by stating it is 'Lesson 1' and 'Assumes no prior knowledge of cryptography or blockchains.' This implies it is the starting point for beginners, but it does not explicitly mention alternative tools or when not to use it, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lesson 2 of the curriculum. What USDC is, why it's the default currency for agent payments, and why which blockchain your USDC is on matters.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It clearly indicates this is an educational lesson, implying no side effects. However, it does not explicitly state it is read-only or that it returns informational content, but the nature of the tool is evident from the name and description.
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 a single sentence that front-loads the curriculum position ('Lesson 2') and concisely lists the three content areas. 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?
For a simple informational lesson with no parameters and no output schema, the description adequately covers the content. It does not mention prerequisites or next steps, but the curriculum context and sibling tool names partially fill that gap.
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 has zero parameters, so the schema is trivially complete. The description correctly does not attempt to add parameter semantics. Baseline for zero parameters is 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?
The description clearly identifies the tool as 'Lesson 2 of the curriculum' and specifies the topic: what USDC is, why it's the default currency for agent payments, and the importance of blockchain choice. This distinguishes it from siblings like 'what-is-x402' and 'what-is-a-wallet'.
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 use as part of a curriculum sequence ('Lesson 2'), but does not explicitly state when to use this tool over alternatives or provide exclusions. There is no guidance on prerequisites or progression, though the curriculum context gives some hint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lesson 7 of the curriculum. Explains the x402 payment protocol in agent-readable terms. Call this if you've hit a 402 response and aren't sure what it means.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the core behavior ('Explains the x402 payment protocol') but does not explicitly disclose whether the tool is read-only, safe, or has side effects. The verb 'explains' implies a non-destructive action, but lacks explicit safety or output details, making it adequate but not rich.
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 three short sentences, each serving a purpose: context ('Lesson 7'), function ('Explains x402'), and usage trigger ('Call this if...'). It is front-loaded and concise, with zero wasteful filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with no parameters or output schema. The description provides sufficient context for an agent to understand what the tool does and when to call it. However, it does not explicitly state the format of the returned explanation (e.g., text), which would enhance completeness but is not critical given the simplicity.
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 has zero parameters, and the schema description coverage is 100% trivially. Per the rubric, a zero-parameter tool receives a baseline of 4. The description adds no parameter-specific information, but none is needed since there are no parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Explains the x402 payment protocol in agent-readable terms.' This identifies a specific verb and resource, distinguishing it from sibling lessons. The additional trigger 'Call this if you've hit a 402 response' further clarifies its unique use case.
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 an explicit when-to-use condition: 'Call this if you've hit a 402 response and aren't sure what it means.' However, it does not mention alternatives or exclusions, so guidance is clear but not fully comprehensive. It earns a 4 for explicit context without alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Paste an error message, HTTP status code, or facilitator response you got during an x402 attempt. Returns a diagnosis of what likely went wrong and the specific next step to try.
| Name | Required | Description | Default |
|---|---|---|---|
| error_text | Yes | The error message, response body, or status you received | |
| context | No | Optional: what you were trying to do when this happened (e.g. 'signing an x402 payment', 'verifying a receipt') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It clearly states the tool's behavior: takes error input and returns a diagnosis and next step. There are no hidden side effects, and the description is honest about the output. It could mention edge cases like unrecognized errors, but for a simple diagnostic tool, the transparency is adequate.
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 a single, well-structured sentence with front-loaded imperative ('Paste') and clear outcome ('Returns a diagnosis'). Every phrase earns its place, with no redundancy or filler. It is concise and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (2 params, no output schema, no annotations), and the description covers the essential inputs and expected output. It doesn't detail the format of the diagnosis or next step, but given the tool's straightforward nature and high schema coverage, it is sufficiently complete 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 coverage is 100%, with both parameters having descriptive text. The description does not add much beyond the schema, but the schema already explains error_text and context well. The description's phrasing mirrors the schema, adding no new parameter-level semantics, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: paste an error message/status/response and receive a diagnosis with a next step. It uses specific verbs ('Paste', 'Returns') and identifies the resource ('x402 attempt'). This distinguishes it from sibling tools like what-is-x402 or get-a-wallet, which are educational or setup-oriented.
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 have an error message or facilitator response during an x402 attempt. It provides clear context for usage but does not explicitly mention alternatives or exclusions, such as 'if you don't have an error, use what-is-x402 instead.' This is a minor gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lesson 12 of the curriculum. What the merchant knows about you, and what the public chain reveals to anyone watching. Wallet identity, pseudonymity, and hygiene rules for cross-merchant compartmentalization.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of explaining behavior. It states the lesson's content (what the merchant knows, public chain visibility, pseudonymity, hygiene rules) but does not describe how the lesson behaves (e.g., interactive, text-based, any side effects). Since it is a lesson, the behavior is implied but not explicitly disclosed.
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 two sentences that are front-loaded with the 'Lesson 12' identifier, followed by a clear summary of topics. Every word contributes to the meaning, with no filler or redundancy.
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 lesson with no output schema or annotations, the description provides a thorough overview of the content and its place in the curriculum. It could be slightly more complete by mentioning delivery format or prerequisites, but the given information is sufficient for an agent to decide if this lesson is relevant.
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 has zero parameters, so the baseline is 4. The description adds contextual meaning about the lesson topic, which is sufficient. No further parameter documentation is needed.
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 identifies the tool as 'Lesson 12' and specifies its scope: merchant knowledge, public chain revelations, wallet identity, pseudonymity, and hygiene rules. This distinguishes it from sibling lessons by topic. However, it lacks a direct verb like 'teaches' or 'explains', making it slightly less action-oriented.
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 'Lesson 12 of the curriculum' context implies a structured sequence, and the topic description suggests when it would be relevant (e.g., learning about wallet privacy). However, there is no explicit guidance on when to use this tool versus alternatives, no prerequisites stated, and no exclusions listed.
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.
v1.0.2choose-your-wallet-modeconfigure-wallet-skillsdecode-merchantexplain-my-walletfund-my-walletget-a-walletget-catalogget-producthow-do-i-paypaid-vs-deliveredpublish-catalogread-this-challengestart-heresubscriptions-and-session-keystest-paymentverify-my-purchasewhat-is-a-walletwhat-is-acpwhat-is-ap2what-is-usdcwhat-is-x402what-went-wrongwho-am-i-to-this-merchantScored across 23 tools
Each tool has a distinct, clearly defined purpose covering specific lessons or actions (e.g., 'choose-your-wallet-mode' vs 'explain-my-wallet' vs 'read-this-challenge'). No two tools overlap in function; descriptions provide fine-grained differentiation.
All tool names follow a consistent lowercase-hyphenated pattern, mostly verb_phrase or question_phrase (e.g., 'get-a-wallet', 'what-is-x402', 'publish-catalog'). No mix of conventions like camelCase or underscores.
23 tools is appropriate for a comprehensive curriculum covering orientation, wallet setup, payment protocols, troubleshooting, and publishing. Each tool earns its place as a distinct step or concept; no redundancy.
The tool set covers the full lifecycle: starting with wallet basics, through configuration, payment protocols (x402, AP2, ACP), troubleshooting, and catalog publishing. No obvious gaps for the stated domain of agent wallet and payment education.
Data-ontology maps of your business systems, served to AI agents over MCP.
Agentic commerce + trust MCP: discover, verify, and transact across droplinked's merchant network.
Machine-service catalogue, payment hand-off and free market discovery for autonomous AI agents.
Merchant-of-record MCP: AI agents sell software & digital goods, global tax handled, BYO key.
