Podyx MCP

podyx_packages_subscription_management

Read-onlyIdempotent

Retrieve management options for a package subscription by ID, including rights, effective session lengths, quote details, delivery status, and available billing portal access for authorized keys.

Instructions

Subscription management GET /api/v2/subscriptions/{id}/management-options. Package kind is fixed by the route. Purchased snapshots and current ledger allowance determine rights and effective session lengths. Quotes are advisory. Redemption atomically creates all sessions and required delivery intents, or writes nothing. Paid extras use the existing separate session add-on purchase flow. Current authority is checked on replay. Cancellation uses the existing subscription cancellation routes. Native provider work is deferred; management GET exposes pending, ready or failed delivery. A ready billing portal URL is disclosed only to a key with current subscriptions:manage authority; read-only keys retain state and capability visibility without the live instruction. Plan changes, pause and resume are unsupported. Paid external decline retains an actionable refund obligation without executing a refund. 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_packages_subscription_management"
  }
}

Input Schema

Name	Required	Description	Default
`path`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.4.0Nov 7, 2026

TDQS

A3.8/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, yet the description adds real behavioral value: authority is re-checked on replay, the billing portal URL is disclosed only to keys with current subscriptions:manage authority, read-only keys see state but not the live instruction, and management GET reports pending/ready/failed provider delivery. Some sentences describe sibling behavior (atomic redemption, refund obligations on decline) rather than this tool's own semantics, which dilutes focus, but the authority-dependent disclosure is genuinely useful context.

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

Conciseness3/5

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

The route is front-loaded, which is good, but the rest is a dense run-on block that packs roughly ten unrelated policies (atomicity, extras, cancellation, provider deferral, portal disclosure, refunds, pagination, quote non-reservation) into prose without structure. Several sentences serve sibling tools rather than this one, so not every line earns its place.

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 one-parameter read with no output schema, the description covers the operational essentials: it declares itself read-only, specifies pagination behavior, warns that a quote does not reserve a slot or lock a price, and enumerates what the response can convey (state, capability visibility, delivery status). It stops short of describing the actual management-option fields returned, but the capability picture is otherwise complete.

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 load; the route template 'subscriptions/{id}/management-options' does effectively identify the single nested parameter as a subscription UUID, which is meaningful compensation. However, it never explicitly states where the id comes from or how to obtain it, and no additional semantics are given for the nested object shape.

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 clause names the concrete endpoint ('Subscription management GET /api/v2/subscriptions/{id}/management-options'), which is a specific verb+resource and tells an agent this is a read of management options for one subscription. It also implicitly distinguishes itself from the redemption, quote and cancellation siblings by saying those go through separate flows. The opening phrase 'Subscription management' is slightly abstract, but the route disambiguates immediately.

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

Usage Guidelines4/5

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

'Read/preview only' plus the repeated notes that redemption, cancellation, paid extras and add-on purchases use 'existing separate routes' effectively tell the agent when NOT to use this tool. It lacks an explicit 'use this to determine what actions are available before calling quote/redemption' statement, but the routing context is clear enough to select correctly.

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

Deploy Server