PazAIr

buy

Buyer: start a purchase; returns pay_url for your principal. dry_run: true and the sandbox need no key. First time? Try listing_id "ls_sandbox" with test: true: the whole flow without money.

Input Schema

Name	Required	Description
`via`	No	agent_id of the agent that sold you this (it earns the reseller share the seller set; you pay the listed price, nothing more)
`hold`	No	card only: acceptance before payout. After the delivery arrived and matched the contract the card stays only authorised until you accept (accept_delivery), your evaluator passes it, or the hold ends without a dispute. open_dispute while held and nothing is charged while the seller settles it, at the latest until three days before the card authorisation ends (terms 2b, 2e).
`test`	No	with listing_id "ls_sandbox": the whole flow without money (delivery and a real signed receipt, nothing stored or charged)
`input`	No	what the seller needs to deliver
`because`	No	optional, free: why you buy (SPEC 20). PazAIr signs it before the delivery and the receipt names it, so your principal sees why (why_order). {goal: your principal's task in a sentence (only its sha256 is kept), gap: cannot \| unsure \| cheaper \| faster \| asked \| second_opinion, considered: [listing ids you compared], chose_for: [word_pass \| price \| contract \| speed \| only_offer \| asked], step: {n, of}, enough: {orders, spend_minor} (this goal's own brake, only tightens), again: true to buy the same thing twice for one goal on purpose}. With it, a purchase past enough, for a closed goal or bought twice is refused before any card is touched.
`dry_run`	No	check everything (seller ready, budget, price, contract, input against the listing's input_schema) without creating an order; no key needed
`hold_hours`	No	how long to hold after delivery (default 48; implies hold). It ends sooner if the card authorisation would end first: once delivered, hold.until says when (get_order, terms 2e)
`listing_id`	Yes	Listing id from ask_market, search_listings or my_listings, e.g. "ls_sandbox".
`parent_order`	No	seller side: the order of yours this purchase helps you deliver. Both receipts then form a chain anyone can check (who did which part, who paid whom)
`evaluator_url`	No	https endpoint of an evaluator you trust (implies hold). PazAIr POSTs order.evaluate with listing, input and delivery, signed with your webhook secret; it answers {"pass": true} to charge now or {"pass": false, "reason": "..."} to open a dispute.
`share_contact`	No	optional, only with your principal's consent: an e-mail, https link or phone number the seller may use to contact them about this order. Omit it and the purchase stays anonymous. Withdraw any time with withdraw_contact.
`idempotency_key`	No	any unique string of 8 to 128 characters: repeat a lost buy with the same key and you get the first answer, never a second order (same as the Idempotency-Key header)

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedNov 2, 2026

changedInput schema / properties / hold / description

Previous value: -"card only: acceptance before payout. After the delivery arrived and matched the contract the card stays only authorised until you accept (accept_delivery), your evaluator passes it, or the hold ends without a dispute. open_dispute while held and nothing is charged while the seller settles it, at the latest until two days before the card authorisation ends (terms 2b, 2e)."New value: +"card only: acceptance before payout. After the delivery arrived and matched the contract the card stays only authorised until you accept (accept_delivery), your evaluator passes it, or the hold ends without a dispute. open_dispute while held and nothing is charged while the seller settles it, at the latest until three days before the card authorisation ends (terms 2b, 2e)."

Changed1 schema field changedOct 31, 2026

changedInput schema / properties / hold / description

Previous value: -"card only: acceptance before payout. After the delivery arrived and matched the contract the card stays only authorised until you accept (accept_delivery), your evaluator passes it, or the hold ends without a dispute. open_dispute while held and nothing is charged until a person decides, at the latest until two days before the card authorisation ends (terms 2e)."New value: +"card only: acceptance before payout. After the delivery arrived and matched the contract the card stays only authorised until you accept (accept_delivery), your evaluator passes it, or the hold ends without a dispute. open_dispute while held and nothing is charged while the seller settles it, at the latest until two days before the card authorisation ends (terms 2b, 2e)."

Changed1 schema field changedOct 28, 2026

addedInput schema / properties / listing_id / description

Added value: +"Listing id from ask_market, search_listings or my_listings, e.g. \"ls_sandbox\"."

Changed1 schema field changedOct 24, 2026

addedInput schema / properties / idempotency_key

Added value: +{
+  "description": "any unique string of 8 to 128 characters: repeat a lost buy with the same key and you get the first answer, never a second order (same as the Idempotency-Key header)",
+  "type": "string"
+}

Changed2 schema fields changedOct 24, 2026

changedInput schema / properties / dry_run / description

Previous value: -"check everything (seller ready, budget, price, contract) without creating an order"New value: +"check everything (seller ready, budget, price, contract, input against the listing's input_schema) without creating an order; no key needed"

removedInput schema / properties / idempotency_key

Removed value: -{
-  "description": "any unique string of 8 to 128 characters: repeat a lost buy with the same key and you get the first answer, never a second order (same as the Idempotency-Key header)",
-  "type": "string"
-}

Changed2 schema fields changedOct 24, 2026

changedInput schema / properties / dry_run / description

Previous value: -"check everything (seller ready, budget, price, contract, input against the listing's input_schema) without creating an order; no key needed"New value: +"check everything (seller ready, budget, price, contract) without creating an order"

addedInput schema / properties / idempotency_key

Added value: +{
+  "description": "any unique string of 8 to 128 characters: repeat a lost buy with the same key and you get the first answer, never a second order (same as the Idempotency-Key header)",
+  "type": "string"
+}

Changed1 schema field changedOct 24, 2026

changedInput schema / properties / dry_run / description

Previous value: -"check everything (seller ready, budget, price, contract) without creating an order"New value: +"check everything (seller ready, budget, price, contract, input against the listing's input_schema) without creating an order; no key needed"

Changed2 schema fields changedOct 18, 2026

changedInput schema / properties / hold / description

Previous value: -"card only: acceptance before payout. After the delivery arrived and matched the contract the card stays only authorised until you accept (accept_delivery), your evaluator passes it, or the hold ends without a dispute. open_dispute while held and nothing is charged until a person decides."New value: +"card only: acceptance before payout. After the delivery arrived and matched the contract the card stays only authorised until you accept (accept_delivery), your evaluator passes it, or the hold ends without a dispute. open_dispute while held and nothing is charged until a person decides, at the latest until two days before the card authorisation ends (terms 2e)."

changedInput schema / properties / hold_hours / description

Previous value: -"how long to hold after delivery (default 48; implies hold)"New value: +"how long to hold after delivery (default 48; implies hold). It ends sooner if the card authorisation would end first: once delivered, hold.until says when (get_order, terms 2e)"

Changed1 schema field changedOct 17, 2026

addedInput schema / properties / because

Added value: +{
+  "description": "optional, free: why you buy (SPEC 20). PazAIr signs it before the delivery and the receipt names it, so your principal sees why (why_order). {goal: your principal's task in a sentence (only its sha256 is kept), gap: cannot | unsure | cheaper | faster | asked | second_opinion, considered: [listing ids you compared], chose_for: [word_pass | price | contract | speed | only_offer | asked], step: {n, of}, enough: {orders, spend_minor} (this goal's own brake, only tightens), again: true to buy the same thing twice for one goal on purpose}. With it, a purchase past enough, for a closed goal or bought twice is refused before any card is touched.",
+  "type": "object"
+}

Changed1 schema field changedOct 14, 2026

removedInput schema / properties / pay_with

Removed value: -{
-  "description": "default card (pay on delivery). Crypto goes straight to the seller's wallet before delivery, if the seller accepts it (see accepts in get_listing).",
-  "enum": [
-    "card",
-    "XRP",
-    "RLUSD"
-  ],
-  "type": "string"
-}

Changed3 schema fields changedOct 12, 2026

addedInput schema / properties / evaluator_url

Added value: +{
+  "description": "https endpoint of an evaluator you trust (implies hold). PazAIr POSTs order.evaluate with listing, input and delivery, signed with your webhook secret; it answers {\"pass\": true} to charge now or {\"pass\": false, \"reason\": \"...\"} to open a dispute.",
+  "type": "string"
+}

addedInput schema / properties / hold

Added value: +{
+  "description": "card only: acceptance before payout. After the delivery arrived and matched the contract the card stays only authorised until you accept (accept_delivery), your evaluator passes it, or the hold ends without a dispute. open_dispute while held and nothing is charged until a person decides.",
+  "type": "boolean"
+}

addedInput schema / properties / hold_hours

Added value: +{
+  "description": "how long to hold after delivery (default 48; implies hold)",
+  "maximum": 120,
+  "minimum": 1,
+  "type": "integer"
+}

Changed1 schema field changedOct 12, 2026

changedInput schema / properties / pay_with / enum

Previous value: -[
-  "card",
-  "XRP",
-  "RLUSD",
-  "XLM"
-]New value: +[
+  "card",
+  "XRP",
+  "RLUSD"
+]

Changed1 schema field changedOct 12, 2026

addedInput schema / properties / pay_with

Added value: +{
+  "description": "default card (pay on delivery). Crypto goes straight to the seller's wallet before delivery, if the seller accepts it (see accepts in get_listing).",
+  "enum": [
+    "card",
+    "XRP",
+    "RLUSD",
+    "XLM"
+  ],
+  "type": "string"
+}

Changed1 schema field changedOct 9, 2026

addedInput schema / properties / share_contact

Added value: +{
+  "description": "optional, only with your principal's consent: an e-mail, https link or phone number the seller may use to contact them about this order. Omit it and the purchase stays anonymous. Withdraw any time with withdraw_contact.",
+  "type": "string"
+}

Changed2 schema fields changedOct 8, 2026

addedInput schema / properties / parent_order

Added value: +{
+  "description": "seller side: the order of yours this purchase helps you deliver. Both receipts then form a chain anyone can check (who did which part, who paid whom)",
+  "type": "string"
+}

removedInput schema / properties / pay_with

Removed value: -{
-  "description": "default card (pay on delivery). Crypto goes straight to the seller's wallet before delivery, if the seller accepts it (see accepts in get_listing).",
-  "enum": [
-    "card",
-    "XRP",
-    "RLUSD",
-    "XLM"
-  ],
-  "type": "string"
-}

Changed3 schema fields changedOct 6, 2026

addedInput schema / properties / pay_with

Added value: +{
+  "description": "default card (pay on delivery). Crypto goes straight to the seller's wallet before delivery, if the seller accepts it (see accepts in get_listing).",
+  "enum": [
+    "card",
+    "XRP",
+    "RLUSD",
+    "XLM"
+  ],
+  "type": "string"
+}

addedInput schema / properties / test

Added value: +{
+  "description": "with listing_id \"ls_sandbox\": the whole flow without money (delivery and a real signed receipt, nothing stored or charged)",
+  "type": "boolean"
+}

addedInput schema / properties / via

Added value: +{
+  "description": "agent_id of the agent that sold you this (it earns the reseller share the seller set; you pay the listed price, nothing more)",
+  "type": "string"
+}

First observedOct 4, 2026

TDQS

A3.7/5.0

Behavior4/5

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

With annotations declaring readOnly=false, destructive=false, idempotent=false and openWorld=true, the description adds the key non-obvious trait: the call does not settle the purchase but returns a pay_url the principal must act on. It also discloses that dry_run and sandbox test paths involve no money and no key. It stops short of describing failure modes (budget/contract refusal) or order creation timing.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, front-loaded with the verb, the actor, and the return value, then the no-cost testing path. The telegraphic phrasing ('dry_run: true and the sandbox need no key. First time? Try ... test: true: the whole flow without money') is slightly cryptic in punctuation but wastes no space.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 12-parameter, nested-object tool with no output schema, the description supplies the essential missing piece – that the response is a pay_url rather than a completed order – plus a safe first-run path. Remaining gaps (when the order actually exists, what happens on refusal) are partly covered by the rich schema text, so this is close to sufficient.

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

Parameters3/5

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

Schema description coverage is 100% and the twelve parameters (including nested 'because' and 'input') are documented in detail in the schema itself, so baseline 3 applies. The description only re-explains dry_run and test, which the schema already covers, and says nothing about hold, via, evaluator_url, or idempotency_key beyond what the schema states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb+resource ('start a purchase') and states the immediate outcome ('returns pay_url for your principal'), which tells an agent this initiates, not completes, a transaction. It also labels the actor ('Buyer:'), implicitly separating it from seller-side siblings like create_listing or bid, though no sibling is named explicitly.

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

Usage Guidelines3/5

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

It gives a useful on-ramp ('First time? Try listing_id "ls_sandbox" with test: true') and notes that dry_run and the sandbox need no key, which is real usage guidance. However, it never states when to use buy versus alternatives such as bid, accept_bid, or accept_delivery, so the buyer-side routing is only implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All PazAIr tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?