Integrates with the Nano cryptocurrency network for escrow-protected marketplace payments, using per-order Nano deposit addresses and on-chain payout blocks for purchases on Nagora.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Nagora MCP server search for a used laptop under 100 XNO"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
The official MCP server for nagora.shop, the P2P marketplace where everything settles in Nano (XNO).
It gives any MCP client (Claude Desktop, Claude Code, or your own agent runtime) tools to search listings, place escrow-protected purchases, track orders, and pull signed receipts. Your AI assistant can shop for you, and escrow protects you while it does: funds are held in a per-order Nano account and only released to the seller after delivery is confirmed.
Tool | Auth | What it does |
| none | Full-text search over active listings |
| none | Full listing detail: variants, delivery options, Nano pricing |
| none | Create an agent + API key in one call, no account needed; key is stored locally |
| API key | Verify the key; see spending caps and webhook secret |
| API key | Place an order; returns the escrow deposit address and amount |
| API key | Poll order and escrow status, tracking, receipt ID |
| API key | Confirm arrival and release escrow to the seller |
| API key | Cancel an order that has not been funded yet |
| API key | Fetch the KMS-signed receipt with the on-chain payout block |
Related MCP server: InventPay MCP Server
Zero-install alternative: Nagora also hosts these same tools as a remote MCP server.
claude mcp add --transport http nagora https://api.nagora.shop/mcpand you are done. The trade-off: the hosted server cannot store your key locally, soregister_agentreturns it once and you pass it as theapiKeytool argument or pin it with--header "Authorization: Bearer nag_agt_...". This local package keeps the key in~/.nagora/credentials.jsonfor you instead.
claude mcp add nagora -- npx -y @nagora/mcpIn claude_desktop_config.json:
{
"mcpServers": {
"nagora": {
"command": "npx",
"args": ["-y", "@nagora/mcp"]
}
}
}cd nagora-mcp
npm install
npm run build
claude mcp add nagora -- node /path/to/nagora-mcp/dist/index.jsThat's the whole setup. No Nagora account, no key to copy. The first time your assistant needs to buy something, it calls register_agent with a name and a refund Nano address; the API key comes back once and is saved to ~/.nagora/credentials.json (mode 600). Every other tool picks it up automatically from then on.
Self-registered keys get conservative default spending caps (currently 25 XNO per transaction, 100 XNO per day), enforced server-side. Want higher caps, multiple keys, or a dashboard? Create an account at nagora.shop and manage agents under Settings → Agents; keys minted there work the same way via NAGORA_API_KEY.
Variable | Default | Notes |
| unset | Optional. Overrides the stored credential from |
|
| Point at |
search_listings / get_listing: find the item, note the Nano total.
create_purchase: places the order. The response contains a depositAddress (a per-order escrow account on the Nano network) and amountNano.
Fund the escrow: send exactly amountNano to depositAddress from the agent's own Nano wallet. This server deliberately holds no keys and moves no funds; pair it with a wallet tool such as xno-mcp, or fund it manually. Nano transfers are feeless and settle in under a second.
The order moves to AwaitingShipment automatically when funds land. The seller ships and adds tracking.
get_order (or webhooks, see below) to watch for Shipped.
confirm_delivery once the goods arrive: escrow releases the funds to the seller on-chain.
get_receipt: a signed, independently verifiable proof of the whole transaction, including the payout block hash.
If the seller never ships, the escrow auto-cancel timer refunds the buyer. If something is wrong with the order, open a dispute from the website; a human reviews it.
Instead of polling get_order, register a callbackUrl on your agent (Settings → Agents). Nagora signs every webhook with HMAC-SHA256: compute HMAC-SHA256("{X-Nagora-Timestamp}.{raw_body}", webhookSecret) and compare it against X-Nagora-Signature: sha256=<hex>. The webhookSecret comes from whoami.
Events: order.funded, order.shipped, and friends fire as the order progresses.
The server is stateless and keyless: it cannot spend Nano, only request orders that you then fund (or don't).
Spending caps are enforced server-side per API key; a runaway agent hits a 429, not your wallet.
Escrow means an agent mistake is recoverable: unfunded orders can be cancelled, funded orders are protected until you confirm delivery.
Revoke a key at any time from Settings → Agents; revocation takes effect within 60 seconds.
Cancels an order whose escrow is still Initiated (no on-chain funds sent yet). Restores listing stock. Cannot cancel once escrow is Funded; use the dispute or refund flow on the website instead.
| Name | Required | Description | Default |
|---|---|---|---|
| orderId | Yes | Order ID to cancel |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and it does reveal key behavioral traits: cancellation is limited to unfunded escrows and restores listing stock. It doesn't mention auth, idempotency, or failure behavior, but the core mutation and constraint are clear.
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 short sentences with no filler. The main action and precondition are front-loaded, followed by the side effect and the exclusion/alternative, so 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?
For a single-parameter cancellation tool with no output schema and no annotations, the description gives all essential operational context: what constitutes an eligible order, the side effect, and the fallback when cancellation isn't possible.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the orderId parameter is already described as 'Order ID to cancel'. The description doesn't add parameter-level details, so the high-coverage 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?
States a specific verb and resource: 'Cancels an order', with a precise scope ('escrow is still Initiated'). The definition differentiates itself from the website dispute/refund flow for funded cases, so an agent understands exactly what this tool does.
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 the tool (order escrow in Initiated state) and when not to (once escrow is Funded), and points to the alternative channel (website dispute/refund flow). This leaves no ambiguity about selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Confirms the goods or digital content arrived and releases the escrowed funds to the seller. Requires the order's escrowStatus to be Shipped. Call promptly once delivery is verified: the seller is waiting on this to get paid. If never called, an auto-finalise timer releases funds after the configured window.
| Name | Required | Description | Default |
|---|---|---|---|
| orderId | Yes | Order ID to confirm |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the financial side effect (releasing escrow), the required state, and a time-based fallback behavior. This is rich, honest disclosure of what calling the tool does and its consequences.
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 tightly written sentences, each earning its place: the action and effect, the precondition and urgency, and the fallback behavior. Nothing is wasted or repetitive.
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 tool with no output schema, the description is complete: it explains the purpose, the required state, the urgency, and the risk of non-action. No critical information missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage for the only parameter (orderId) with its type and format. The description adds no additional meaning beyond the schema, so the 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 states a specific verb ('Confirms'), clear object ('goods or digital content'), and direct outcome ('releases the escrowed funds to the seller'). It clearly distinguishes itself from siblings like cancel_order and get_order by focusing on the confirmation-and-payout 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?
Provides explicit when-to-use guidance ('Call promptly once delivery is verified') and a precondition ('Requires the order's escrowStatus to be Shipped'). It also warns about the auto-finalise timer as a fallback, implicitly guiding the agent to act quickly rather than wait.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Places an order against a listing. Returns a depositAddress (per-order escrow Nano account) and amountNano. IMPORTANT: the order is not funded by this call. Send exactly amountNano to depositAddress from the agent's Nano wallet to fund escrow. Once funds are detected the order moves to AwaitingShipment automatically. Funds are held in escrow until confirm_delivery, so the buyer is protected if the item never arrives. Physical listings require a shippingAddress.
| Name | Required | Description | Default |
|---|---|---|---|
| quantity | No | Quantity, default 1 | |
| listingId | Yes | Listing to purchase | |
| variantId | No | Variant ID from get_listing, when the listing has variants | |
| quotedTotalNano | No | Total in XNO from a recent get_listing call. Rejected if more than 2% off the live rate; omit to skip the guard | |
| shippingAddress | No | Required for physical delivery; omit for digital listings | |
| deliveryOptionId | No | Delivery option ID from get_listing, when the listing offers several |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden, and it excels. It discloses that the order is not funded by this call, instructs to send exactly amountNano to depositAddress, explains the automatic state transition to AwaitingShipment, and notes funds are held in escrow until confirm_delivery. This goes well beyond a generic 'creates an order' and gives the agent the critical behavioral context needed to use the tool correctly.
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. Each sentence adds value: the return values, the funding warning, the state transition, the escrow protection, and the shipping condition. The 'IMPORTANT:' callout effectively highlights the critical funding step without extra fluff.
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 complex purchase flow with 6 parameters, a nested object, and no output schema, the description is remarkably complete. It explains the full funding workflow, the automatic status change, the escrow protection, and the shipping requirement. It also describes the return values (depositAddress and amountNano) which would otherwise be unknown without an output schema. Nothing essential for correct invocation 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% — every parameter has a description in the input schema, so the baseline is 3. The description adds little beyond the schema: it restates the shippingAddress condition (already in the schema) and mentions the return values, but does not add new meaning for any specific parameter. It meets the baseline but does not elevate it.
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 'Places an order against a listing,' which is a specific verb+resource action. The title 'Create an escrow-protected purchase' reinforces the purpose. It clearly differentiates from siblings like get_order, confirm_delivery, and cancel_order, which are about other stages of the order lifecycle.
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 on when to use the tool: it places an order and then requires a separate funding step. It explicitly states 'Physical listings require a shippingAddress,' a conditional usage note. It does not explicitly name alternative tools for other actions, but the distinct purpose makes it obvious which sibling to choose for creating a purchase.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a single listing by ID. No API key required. Returns full detail including variants, delivery options, and pricing. Use the returned Nano total as quotedTotalNano when purchasing to guard against exchange-rate drift.
| Name | Required | Description | Default |
|---|---|---|---|
| listingId | Yes | Listing ID from search_listings |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses that no API key is required, that the operation is a read-only fetch, and that output includes variants, delivery options, pricing, and a Nano total. It adds practical behavioral guidance by telling agents to use the Nano total as quotedTotalNano to guard against exchange-rate drift.
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 sentences, each carrying distinct value: core action, authentication requirement, and output/usage guidance. The description is front-loaded and contains no filler or redundant restatement of the tool name.
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 tool with no output schema, the description is complete enough. It covers what the tool returns, the auth context, and how the return value should be used downstream. The input origin is documented in the schema, so no critical context is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides full 100% coverage for listingId, including its format and source. The description only says 'by ID' and does not add parameter-specific meaning beyond the schema. Baseline 3 applies because the schema does the heavy lifting.
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 ('Fetch') and resource ('a single listing by ID'), clearly distinguishing it from search_listings. The title reinforces the same purpose. An agent can tell exactly what this tool does without ambiguity.
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 the tool is used after search_listings by noting the listingId comes from search_listings in the schema, and it connects to the purchase flow. It provides clear context but does not explicitly name alternatives or 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.
Polls an order placed by this agent. Returns orderStatus, escrowStatus, funding timestamps, tracking info, and the receipt ID once available. Poll after funding the deposit address, and after the seller ships, before calling confirm_delivery.
| Name | Required | Description | Default |
|---|---|---|---|
| orderId | Yes | Order ID returned by create_purchase |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. 'Polls' conveys a read-only, repeatable operation, and 'once available' discloses that some data may be absent initially. It also scopes behavior to orders placed by the agent. It stops short of stating explicit side-effect-free guarantees or error behavior, but covers the essential polling semantics.
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 sentences with no wasted words: purpose first, then return contents, then usage timing. The most actionable information (when to poll, before calling confirm_delivery) is placed toward the end but still compact and well-ordered.
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 parameter, no output schema, and no annotations, the description covers the key needs: what it returns, when to poll, and how it fits in the order lifecycle. It lacks explicit notes on not-found behavior or retry semantics, but for a simple status-polling tool the guidance is strong.
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%: orderId is fully documented as the order ID returned by create_purchase. The description adds little about the parameter itself—'an order placed by this agent' is more resource scoping than parameter detail. Baseline 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Polls an order placed by this agent,' and enumerates the exact return fields (orderStatus, escrowStatus, funding timestamps, tracking info, receipt ID). It differentiates from siblings by scoping to the agent's own orders and positioning itself as the pre-confirm_delivery status poller.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit lifecycle timing: 'Poll after funding the deposit address, and after the seller ships, before calling confirm_delivery.' This tells the agent exactly when to call the tool and explicitly excludes using it after confirm_delivery.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the cryptographically signed receipt for a completed order, including the seller's Nano address, the on-chain payout block hash, and Nagora's KMS signature. Available only after escrow is Released; returns an error while the order is still in progress.
| Name | Required | Description | Default |
|---|---|---|---|
| orderId | Yes | Order ID to fetch the receipt for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses the state dependency (escrow Released), the error behavior while in progress, and the contents of the receipt. It doesn't explicitly state it is read-only, but 'get' implies a safe operation and the description focuses on retrieval.
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, front-loaded with the main purpose and contents, followed by the availability condition. No redundant phrasing or fluff.
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?
Covers the essential aspects: what is returned, when it is available, and error behavior. It lacks an explicit return format, but no output schema exists; the information is sufficient for a simple one-parameter 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%—orderId is described as 'Order ID to fetch the receipt for'. The description adds no extra semantic details about the parameter, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it returns the cryptographically signed receipt for a completed order, specifying contents (seller's Nano address, payout block hash, KMS signature). This distinctively separates it from siblings like get_order, which would fetch order details.
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 an explicit condition: available only after escrow is Released, and returns an error during progress. This gives a clear when-to-use signal. It does not name alternative tools, but the purpose is distinct from the sibling set, making the guidance sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates a Nagora agent and mints its API key in one call. No Nagora account or signup required. The key is saved to ~/.nagora/credentials.json and used automatically by all other tools from now on. Requires a name and a nano_ address (your wallet; refunds are routed there if an order is cancelled). Self-registered keys carry conservative default spending caps, returned in the result. Skip this tool if a key is already configured; check with whoami.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Agent name, e.g. 'claude-shopper' | |
| callbackUrl | No | Optional webhook URL; Nagora POSTs signed order state-change events to it | |
| homepageUrl | No | Optional homepage describing the agent | |
| nanoAddress | Yes | Nano (XNO) address refunds should be sent to: the wallet this agent pays from | |
| contactEmail | No | Optional contact email for order issues |
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 the local side effect (~/.nagora/credentials.json), the persistent global effect (all other tools use the key), and the spending-cap behavior. It does not fully spell out what happens if called twice, but the skip-if-configured instruction mitigates that gap.
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?
Five sentences, front-loaded with the core creation action before side effects and usage guidance. Each sentence adds useful information, though 'No Nagora account or signup required' somewhat redundantly repeats the title.
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 setup tool with no output schema, it explains what will happen, where state is persisted, how to avoid duplicate registration, and that spending caps are returned. It does not specify the exact full response shape, but the disclosed details are sufficient for correct 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?
Schema description coverage is 100%, placing this at baseline. The prose adds broad context for the required fields (name and nano_ address as the refund wallet), but does not comment on the optional URL/email fields, which the schema already describes adequately.
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: 'Creates a Nagora agent and mints its API key in one call.' It also disambiguates from the sibling set by tying the result to credential storage and automatic use by all other tools, and by naming whoami as the check when a key already exists.
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?
Gives explicit conditional guidance: 'Skip this tool if a key is already configured; check with whoami.' It also clarifies that no account is required and that a name plus nano_ address are prerequisites, so an agent knows exactly when and how to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full-text search over active listings on nagora.shop. No API key required. Prices are in the listing's display currency with a Nano (XNO) equivalent. Returns an items array and total count. Use get_listing for full detail before purchasing.
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Free-text search query, e.g. 'mechanical keyboard' | |
| count | No | Page size, default 20 | |
| sortBy | No | Sort order, default newest | |
| maxPrice | No | Maximum price filter | |
| minPrice | No | Minimum price filter | |
| categoryId | No | Numeric category filter | |
| startIndex | No | Pagination offset, default 0 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. It discloses that no API key is required, explains price currency presentation (display currency with XNO equivalent), and states the return structure (items array and total count). This goes beyond the schema and helps an agent set expectations, though it omits rate limits or pagination details.
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 sentences with no fluff. It front-loads the core action, then adds auth, currency, return shape, and an alternative tool pointer. 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?
For a search tool with 7 optional parameters and no output schema, the description covers the essential behavioral contract: scope, auth, currency, return shape, and a pointer to get_listing. It doesn't explain all parameter interactions, but the schema fills that gap. The description is sufficient for an agent to invoke the tool effectively.
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 all seven parameters with descriptions. The tool description does not add parameter-specific details beyond what the schema provides, but it does clarify the search scope (full-text over active listings). This meets the baseline for a fully documented schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs full-text search over active listings on nagora.shop. It distinguishes itself from sibling tools like get_listing, which is explicitly referenced for detail retrieval. The verb and resource are specific and 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 provides a clear usage context: use search for discovery and get_listing for full detail before purchasing. It names an alternative explicitly, though it doesn't exhaustively enumerate when not to use search. The guidance is sufficient for an agent to choose correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verifies the configured API key and returns the agent's identity, per-transaction and per-day spending caps, callback URL, and webhook secret. Call this first to confirm the key works.
| 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 full behavioral burden. It discloses that the tool verifies the key and returns identity and other details, implying a read-only operation. It does not explicitly state there are no side effects, but the nature of the tool (introspection) makes that obvious. It also highlights that it returns a webhook secret, which is sensitive. This is adequate for a simple read operation.
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, efficient sentence that front-loads the purpose ('Verifies the configured API key') and then lists the returned data. It also adds a usage hint at the end. Every word earns its place; no 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?
For a zero-parameter, read-only introspection tool with no output schema, the description is complete. It states what it does, what it returns, and when to call it. Nothing an agent needs to correctly invoke this tool is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description does not need to add parameter detail because there are none. The schema coverage is 100% (vacuously), so no compensation is needed. The score reflects the appropriate 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 explicitly states the tool verifies the configured API key and returns specific data (identity, spending caps, callback URL, webhook secret). This is a clear verb+resource and obviously distinct from the order/delivery siblings. The purpose is 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 gives explicit guidance: 'Call this first to confirm the key works.' This tells the agent when to use it. It does not mention exclusions or alternatives, but the sibling tools are all transactional operations, so the usage context is clear enough. A slightly stronger statement about when not to use it would push this to 5.
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.
v0.1.0cancel_orderconfirm_deliverycreate_purchaseget_listingget_orderget_receiptregister_agentsearch_listingswhoamiScored across 9 tools
Each tool has a clearly distinct purpose: listing search/detail, agent registration/auth, purchase creation, order status, cancellation, delivery confirmation, and receipt retrieval are all well-separated. There is little risk of selecting the wrong tool for a given action.
Most tools follow a consistent verb_noun snake_case pattern such as get_order, cancel_order, search_listings, and create_purchase. The only outlier is whoami, which is a familiar standalone command but does break the pattern slightly.
Nine tools is well-scoped for a marketplace agent server. Each tool covers a necessary part of the buyer/escrow workflow and none feel redundant or extraneous.
The set covers the full purchasing lifecycle: register, authenticate, search, view listing, place order, poll status, cancel, confirm delivery, and retrieve receipt. Minor gaps exist such as no list_orders or in-MCP dispute/refund handling, but those are partially external or non-essential for the core flow.
Manage your NanoCart store from any AI agent: products, orders, coupons, subscribers, reports.
Marketplace where AI agents buy/sell skills over Bitcoin Lightning with escrow-backed verification.
Marketplace where AI agents buy/sell skills over Bitcoin Lightning with escrow-backed verification.
Agent-to-agent marketplace: AI agents list and buy data, services and compute. Signed receipts.
