Creates a new subscription for the customer and generates a new invoice. @param customer_id: The customer's database id @param subscription_type_fk: The database subscription type @return: a json object, in the "values" object
| Name | Required | Description | Default |
|---|---|---|---|
| customer_id | Yes | ||
| subscription_type_fk | Yes |
Changes observed during successful MCP inspections.
Output schema / (root)Previous value: -{
- "type": "object"
-}New value: +nullDoes the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It does disclose one behavioral trait beyond the name: that an invoice is generated as a side effect. But it omits permission/auth requirements, idempotency, whether re-subscribing an already-subscribed customer errors, and error behavior – significant gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the core action in the first clause and keeps the whole definition to a few lines. The @param/@return tag scaffolding is slightly mechanical but not wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
A create tool with invoice side effects, zero annotation coverage, and no output schema should explain auth needs, side-effect scope, and failure modes. It briefly notes the return shape ('json object in the values object'), but that is far short of what an agent needs to call this safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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, and it does partially by documenting both params via @param. However, 'The customer's database id' and 'The database subscription type' are thin – no format, source, or valid-value guidance – so it adds marginal meaning over the integer types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Creates a new subscription for the customer') plus a notable side effect ('generates a new invoice'). An agent can distinguish this from siblings like customer_subscription_status or customer_validate_subscription, though the description never names an alternative explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance, no prerequisites, and no mention of adjacent siblings (e.g., customer_validate_subscription, customer_subscription_status). The agent must infer that this is the creation path from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.