Podyx MCP

podyx_get_external_subscription_cycle

Read-onlyIdempotent

Retrieves a local external subscription term cycle by UUID so you can inspect its dates, coverage, and status before reporting or approving renewal actions.

Instructions

Read a local external subscription term cycle GET /api/v2/subscription-cycles/{id}. The studio key owns the tenant. Cycle UUID, financial collection UUID, delivery Idempotency-Key and monthly grant period are distinct. The predecessor must be the subscription's committed local cycle; dates and recurring amount come from the purchased snapshot. Paid outcomes use actual aggregate external coverage and shared fulfillment. Partial coverage grants nothing; approval remains separate. Failed renewal marks overdue; recovery extends that same term once. Cancellation/nonrenewal and terminal access remain authoritative: collected money stays recorded with an action instead of resurrecting rights. POST requires subscriptions:report_external_cycle plus payments:report_external under current account/key authority; GET requires subscriptions:read plus payments:read. New cycles require headless entry and external writer readiness; accepted cycle recovery survives commercial disable. Native provider subscription IDs cannot be reported here. 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_external_subscription_cycle"
  }
}

Input Schema

Name	Required	Description	Default
`path`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.4.0Nov 7, 2026

TDQS

B3.1/5.0

Behavior3/5

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds real value with the required scopes (subscriptions:read, payments:read), the tenant-ownership rule ('the studio key owns the tenant'), and 'Follow all pagination'. It still omits what is actually returned, and the heavy renewal/coverage/overdue prose is mutation semantics that muddies an otherwise 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.

Conciseness2/5

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

The useful part is the first sentence plus the scope and pagination lines; the rest is dense domain jargon about POST requirements, grant periods, overdue recovery and cancellation resurrection that is irrelevant to a GET-by-id read. It is front-loaded acceptably but far longer than the task warrants.

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

Completeness2/5

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

There is no output schema, so the description must describe what a cycle record contains, yet it never does. For a read tool with a nested path parameter and no return-value documentation, the permissions and pagination notes are insufficient to fully brief an agent.

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 carry the burden for the single nested path.id parameter, and it only implies it: 'Cycle UUID, financial collection UUID, delivery Idempotency-Key and monthly grant period are distinct' tells the agent the id is a cycle UUID as opposed to other UUIDs. That is a helpful disambiguation but not a full explanation of the path parameter.

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 first sentence gives a concrete verb and resource: read a local external subscription term cycle via GET /api/v2/subscription-cycles/{id}. That is specific enough to act on, but the description never names or contrasts the sibling read tools (e.g. podyx_get_external_payment_report, podyx_list_external_refund_collections), so an agent must infer the boundary from the name alone.

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?

There are useful constraints: 'Read/preview only' and 'Native provider subscription IDs cannot be reported here', plus per-verb permission requirements. However, the bulk of the text describes POST/cycle-creation behavior that does not apply to this read tool, and there is no explicit when-to-use-this-vs-alternative routing.

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

Deploy Server