Skip to main content
Glama

buy_prepared_artifact

Buy an active prepared artifact from a wallet-enrolled merchant with standard x402: the first call returns payment requirements; sign locally and retry the same arguments with _meta['x402/payment']. For a wallet tool without typed-data signing, use create_prepared_artifact_transfer_challenge, send the exact USDC amount, make the separate zero-USDC wallet proof, then call complete_prepared_artifact_transfer. Reuse the same identifiers and payment proof after timeouts. Successful delivery includes exact delivery.bodyBase64 bytes and private delivery.artifactProof for commitment verification.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "merchantId": "<merchantId>",
      "offerId": "<offerId>",
      "idempotencyKey": "<idempotencyKey>"
    },
    "name": "buy_prepared_artifact"
  }
}

Input Schema

NameRequiredDescriptionDefault
offerIdYes
merchantIdYes
idempotencyKeyYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / additionalProperties
      Added value: +false
  2. First observed

TDQS

A4.3/5.0
Behavior4/5

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

With no annotations, the description carries the full burden and does most of it: it discloses the two-step payment handshake (first call returns requirements, retry with _meta['x402/payment']), the fact that the wallet must send an exact USDC amount, idempotent retry semantics, and what a successful delivery contains (bodyBase64 bytes plus a private artifactProof). What it doesn't state is the irreversibility of the spend or what happens if the payment proof is rejected/expired, which matters for a tool that moves funds.

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?

Purpose and primary call pattern are front-loaded in the first sentence, and the alternative flow and return payload follow in logical order with almost no filler. It is dense and somewhat run-on, packing three flows into four sentences, but the length is justified by the payment complexity.

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 payment tool with no annotations and no output schema, the description covers the call sequence, the alternative signing path, retry/idempotency rules, and the returned delivery fields. Gaps remain around failure modes (expired requirements, rejected proof, insufficient balance) and any prerequisite for the merchant being wallet-enrolled, which an agent would need to debug a failed purchase.

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 0%, so the description must compensate; it explains identifier reuse across retries and the _meta payment field, but never clarifies merchantId vs offerId roles or the idempotencyKey's uniqueness/expiry expectations. It adds partial meaning beyond the bare UUID/pattern constraints, which is minimum-viable rather than complete. Notably, the described _meta['x402/payment'] argument is not present in the schema, which declares additionalProperties: false — an agent could be confused about where that field belongs.

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

Purpose5/5

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

The description opens with a specific verb+resource ("Buy an active prepared artifact from a wallet-enrolled merchant") and qualifies the scope (active, wallet-enrolled, standard x402). It also names the sibling paths it is not — create_prepared_artifact_transfer_challenge plus complete_prepared_artifact_transfer — so an agent can route without opening any schema.

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

Usage Guidelines5/5

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

It gives explicit branch conditions: use the standard signed x402 retry when the wallet supports typed-data signing, and switch to the challenge/transfer/complete sequence "for a wallet tool without typed-data signing." It also states timeout behavior (reuse the same identifiers and payment proof), so the agent knows what to do on retry rather than re-deriving arguments.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources