Podyx MCP

podyx_get_purchase

Read-onlyIdempotent

Retrieves purchase instructions, settlement, approval, and fulfillment state by purchase ID for read-only verification and recovery context.

Instructions

Read current purchase instructions, settlement, approval and fulfillment GET /api/v2/purchases/{id}. Email resolves the studio-owned Client and never authenticates the visitor. New purchase entry requires headless_api plus the family purchase permission, clients:read and payments:collect; clients:create is conditional on creating a Client association. GET requires payments:read plus the purchased family's read permission. Recovery requires payments:collect, clients:read and that family's read permission under current studio key/account/public_api authority; accepted recovery remains available with headless new entry disabled. Native provider, credit, promo, approval, private-offer and consent policies apply. Acceptance atomically records a frozen purchase obligation, immutable receipt and required work; no provider IO runs before commit. Instructions carry public SDK capabilities, never proof of settlement. Fetch current state for money, approval and rights separately. Unknown outcomes resume the original frozen tender identity; outcomes beyond the safe replay window require reconciliation and never create another recurring subscription. Cancellation retires unpaid capability before completing; money in flight remains undetermined. No external settlement reports, renewal, aftercare or raw status writes are accepted. Read/preview only. Follow all pagination; a quote does not reserve a slot or lock a price.

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": {
      "path": "<path>"
    },
    "name": "podyx_get_purchase"
  }
}

Input Schema

Name	Required	Description	Default
`path`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.4.0Nov 7, 2026

TDQS

B3.2/5.0

Behavior4/5

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

The annotations already declare readOnly/idempotent/non-destructive, but the description adds genuinely useful operating context: pagination must be followed, a quote does not reserve a slot or lock a price, instructions are capabilities and never proof of settlement, and unknown outcomes resume a frozen tender identity. The downside is that much of the text describes acceptance/cancellation/recovery semantics belonging to other operations, mixed with an explicit "Read/preview only" that keeps it from being a contradiction.

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

Conciseness2/5

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

The purpose is front-loaded, which is good, but the body is a dense run-on chain of permission scopes, policy names and reconciliation rules unrelated to a read call, and the key operational constraint (read-only, paginate) is buried at the very end. Roughly two-thirds of the sentences do not help an agent invoke this tool.

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

Completeness3/5

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

With no output schema, the description should explain what comes back, and it partially does via "instructions, settlement, approval and fulfillment" plus the caveat that instructions are not settlement proof. However, the single required parameter is undocumented and the response shape (fields, envelope, pagination cursor) is never described, leaving gaps for a one-param reader on an open-world API.

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

Parameters2/5

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

The schema has a single nested `path.id` uuid at 0% description coverage, and the description adds little: only the literal `{id}` in the API path implies it is a purchase identifier. It never says which identifier (purchase vs. client vs. subscription) or where to obtain it, notable given the emphasis on email resolving to a Client and on frozen tender identities.

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 opening clause states a specific verb and resource ("Read current purchase instructions, settlement, approval and fulfillment GET /api/v2/purchases/{id}"), so an agent can tell this reads a purchase record. Differentiation from siblings is weak, though: many sibling tools are also get_* readers and the only routing hint is the vague "Fetch current state for money, approval and rights separately."

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?

Usage is implied rather than stated: "Read/preview only" bounds it to non-mutating calls, and "Fetch current state for money, approval and rights separately" hints at when to call it. There is no explicit when-not-to-use, no named alternative (e.g. cancellation/quote siblings), and the permission prose describes new-entry and recovery flows rather than guiding tool selection.

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

Deploy Server