subscriptions

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

Discloses critical behavioral details: the full account key is returned only once, and only its SHA-256 and last four characters are retained. With no annotations, this adds substantial transparency about data handling and one-time key exposure.

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?

Two sentences, front-loaded with the core purpose, and no filler. Every word adds value, making it highly concise and well structured.

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?

The description covers the main purpose and a key behavioral nuance, but leaves the sole parameter undefined. Given the low complexity and presence of an output schema, this is a notable gap preventing full completeness.

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?

The only parameter, account_ref, is completely unexplained in the description. Schema coverage is 0%, and the description does not compensate by clarifying what this reference is, its format, or how it relates to the account creation.

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?

The description uses a specific verb ('create') and identifies the exact resource ('a free account') with its purpose ('for bearer attribution'). This clearly distinguishes it from siblings focused on billing, subscriptions, and usage.

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?

It provides clear context: this tool creates a free account specifically for bearer attribution, implying when to use it. However, it does not explicitly name alternatives or state when not to use it, so it misses the top tier.

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

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

With no annotations, the description carries full responsibility for behavioral disclosure. It explicitly states the tool 'never charges a card' and 'fails closed without creating a session' under certain conditions. This is valuable beyond schema and provides critical safety/behavioral information for the agent.

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?

The description is concise, with two sentences that deliver essential information without redundancy. The first sentence states the primary function, and the second provides key behavioral caveats. It is well-structured and front-loaded.

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?

For a simple 2-parameter tool with an output schema, the description is largely complete. It explains the core function, safety guarantees, and failure modes. It does not mention authentication or permissions, but that is often implicit in MCP servers. The only minor gap is the lack of parameter-specific context, already penalized in parameter_semantics.

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%, and the description does not elaborate on the two parameters (plan_id and account_ref). It mentions 'Draft plans' and 'recurring Price IDs' but does not connect them to the actual parameter names or explain their formats or required values. The description fails to compensate for the lack of schema documentation.

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?

The description clearly states the tool's function: 'Prepare a Stripe-hosted subscription Checkout URL.' This specifies the verb (prepare), resource (Stripe-hosted subscription Checkout URL), and scope (subscription). It distinguishes itself from sibling tools like customer_portal_link (portal access) and record_subscription (recording), making the purpose unmistakable.

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?

The description provides clear context for when the tool is appropriate (creating a subscription checkout link) and specifies failure conditions ('Draft plans, missing owner approval, unavailable covered agents, or missing recurring Price IDs fail closed'). It does not explicitly name alternatives, but the context implies usage for new subscription checkouts, which is sufficient for a distinct tool.

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

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

With no annotations, the description adds behavioral context: 'bearer-owned' and 'never moves money' disclose that it's tied to the authenticated user and has no financial side effects. However, it does not disclose other behaviors such as session creation, expiration, or error conditions, leaving gaps.

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?

Two sentences, front-loaded with the primary action, and no filler. Each sentence adds distinct value: purpose and usage note.

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?

The tool is simple, has an output schema, and the description covers the core purpose, use case, and a safety guarantee. It lacks explicit parameter documentation, but the overall context is sufficient for an agent to select and call it correctly in most scenarios.

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?

The schema has zero parameter descriptions, but the description's phrase 'bearer-owned' implies that account_id refers to the authenticated user's account. This adds meaning beyond the raw schema, though it does not explicitly define the parameter or its constraints.

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?

The description clearly states the tool's function with a specific verb ('Return') and resource ('bearer-owned Stripe-hosted billing-portal URL'). It distinguishes from sibling create_checkout_link by specifying 'billing-portal' rather than checkout.

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?

It provides a clear use case: 'The human manages or cancels there' – indicating when to use this tool. However, it does not explicitly name alternatives or state when not to use it, only implies via the 'never moves money' clause.

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

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

With no annotations, the description must carry the transparency burden. The verb 'Return' implies a read-only operation, but the description does not explicitly state safety, error conditions, or any side effects. It adds minimal behavioral context beyond the name.

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?

The description is a single, dense sentence with no filler. It front-loads the action ('Return') and then lists the specific output attributes, making it concise and well-structured.

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?

For a zero-parameter retrieval tool, the description adequately states the output fields, and an output schema exists to detail their structure. It does not mention error scenarios or prerequisites, but given the low complexity, this is a minor gap.

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?

The tool has zero parameters, so parameter semantics are trivially satisfied. The baseline score of 4 applies per the rubric, and the description does not need to elaborate on any parameters.

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?

The description uses the specific verb 'Return' and enumerates the exact output attributes (fleet-standard version, catalog digest, security posture, lifecycle policy, capabilities), making it clear this is a retrieval operation for agent metadata. It distinguishes itself from sibling tools like list_plans or mrr_summary, which deal with plans and revenue.

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 explicit guidance is provided on when to use describe_agent versus alternatives. The tool name and output fields imply its use case, but the description does not state conditions, exclusions, or alternative scenarios.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the action ('Get') and adds a minor contextual detail ('versioned catalog lineage'), but does not disclose side effects, authentication needs, error behavior, or the read-only nature beyond what the verb implies. This is minimal disclosure.

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?

The description is a single, concise sentence that delivers essential information without redundancy. Every word contributes to understanding the tool's function.

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?

The tool is simple with one parameter and an output schema, so the description does not need to detail return values. However, it lacks explicit usage guidance and parameter semantics, making it only partially complete for an agent choosing and invoking the tool. The 'versioned catalog lineage' is a useful context but is not elaborated.

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 for the lack of parameter documentation. The description does not explain 'plan_id', its format, or how to obtain it (e.g., via 'list_plans'). The parameter name is self-evident, but the description adds no semantic value.

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?

The description states a specific verb ('Get'), a clear resource ('one exact monthly plan'), and distinguishes itself from the sibling tool 'list_plans' by emphasizing 'one exact' and 'versioned catalog lineage'. This clearly communicates the tool's unique purpose.

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?

The description implies usage for retrieving a single plan with lineage, but it does not explicitly say when to use this tool versus alternatives like 'list_plans' or mention any exclusions. The differentiation is implicit rather than explicit.

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

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

With no annotations, the description carries the full burden. It discloses several behavioral aspects: it returns exact prices, coverage, SHA-256, readiness flags, and a pending owner-confirmation notice. This goes beyond a generic 'list' statement and gives the agent a clear picture of the tool's output, though it does not explicitly describe side effects (likely none for a list operation).

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?

The description is a single, well-structured sentence that front-loads the verb and resource ('List the versioned monthly-seat catalog') and then lists the key data points. Every part adds value with no wasted words.

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?

Given the tool has zero parameters and an output schema exists, the description provides ample context. It names the specific catalog elements (prices, coverage, SHA-256, flags, notice), which fully covers what an agent needs to understand the tool's purpose and output. No critical information is missing.

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?

The tool has zero parameters, so the baseline is 4. The description adds no parameter-specific semantics because none are needed. It sufficiently communicates what the tool returns without requiring parameter explanations.

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?

The description clearly states the tool lists the 'versioned monthly-seat catalog' with specific details (prices, coverage, SHA-256, readiness flags, owner-confirmation notice). The verb 'List' plus the specific resource distinguishes it from siblings like get_plan or mrr_summary, which serve different purposes.

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?

The description implies this tool is for retrieving the full plan catalog, but there is no explicit guidance on when to use it versus alternatives like get_plan. No when-to-use or exclusion criteria are stated, only an implied scope.

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

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

With no annotations, the description carries the behavioral disclosure burden. It states the scope (active live-mode) and the privacy guardrail (no identifiers exposed), adding useful context beyond the empty schema. It doesn't cover data freshness or the exact definition of 'active', but it's reasonably transparent for a read-only aggregate.

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?

Two sentences, first stating the function and second stating a key constraint. No redundancy, no fluff. Every word earns its place.

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?

Given zero parameters, an existing output schema, and a simple aggregate scope, the description fully covers what the tool returns and what it explicitly avoids. There are no gaps for this level of complexity.

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?

The tool has zero parameters and schema coverage is 100%, so the description need not explain parameters. The baseline for 0 params is 4, and the description implicitly confirms no inputs are needed.

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?

The description uses a specific verb 'Return' plus a precise resource: aggregate active live-mode subscription metrics. It clearly differentiates from siblings like subscription_status (single subscription) and usage_summary (usage) by emphasizing MRR minor units and plan mix, and explicitly excludes identifiers.

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?

It doesn't explicitly name alternative tools, but it clearly frames the tool as an aggregate summary with no account-level identifiers, implying use for high-level revenue reporting rather than per-customer queries. This is clear context, though it lacks explicit when-not-to-use guidance.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It usefully states the operation is idempotent and that a newly created account receives its key once, which are important side-effect semantics. It does not detail permissions, failure modes, or reversibility, but the provided behavior is non-trivial and valuable.

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?

The description is two sentences, front-loaded with the primary action, and contains no redundant wording. Every phrase adds useful context, including idempotency and the one-time key behavior.

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?

Given the simple one-parameter signature and presence of an output schema, the description covers the key operational context: verifying a Stripe identifier, activating the exact period, idempotency, and the key-delivery condition. It lacks explicit when-to-use guidance but is otherwise complete for a tool of this complexity.

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. It clarifies that the single parameter is a Stripe session or subscription identifier used for pull-verify and activation. However, it does not add format, validation, or ownership constraints beyond what the parameter title already suggests.

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?

The description clearly states the action: 'Pull-verify a Stripe session/subscription and idempotently activate its exact subscription period.' It names a specific resource (Stripe session/subscription) and a precise outcome, distinguishing it from sibling read-only tools like subscription_status or creation tools like create_checkout_link.

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?

The description implies usage after a Stripe session or subscription exists (pull-verify then activate), and the phrase 'newly created account' hints at a post-account-creation workflow. However, it does not explicitly name alternatives, prerequisites, or conditions where this tool should be avoided.

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

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

With no annotations, the description carries the transparency burden. It discloses that the account key is always masked in output, which is useful behavioral context. However, it does not explicitly state that this is a read-only operation, nor does it describe error behavior or auth requirements beyond 'bearer-owned', leaving some ambiguity.

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?

The description is two short, front-loaded sentences with no wasted words. Every sentence adds value: the first states the core purpose and scope, the second discloses an important output behavior.

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?

Given the tool's low complexity and presence of an output schema, the description covers the core purpose but leaves gaps in usage guidance and parameter explanation. It is minimally viable but not fully complete for an agent to confidently invoke the tool without additional inference.

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?

The only parameter, account_id, is not described in the tool description. With schema description coverage at 0%, the description should compensate, but it only hints at 'bearer-owned' without clarifying the relationship between account_id and the bearer or expected format/meaning.

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?

The description clearly states the tool returns subscription lifecycle and current-period quota, which is a specific verb+resource combination. It distinguishes itself from sibling plan-focused tools like get_plan and list_plans by focusing on bearer-owned subscription status, though it does not explicitly name alternatives.

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?

The description provides no guidance on when to use this tool versus siblings such as get_plan, mrr_summary, or usage_summary. It simply states what it returns, leaving the agent to infer usage context from the tool name alone.

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

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

No annotations are provided, so the description carries the disclosure burden. It signals a read-only operation via 'Return' and adds useful behavioral context (bearer ownership, period resolution, data lineage), but it does not mention potential side effects, rate limits, error cases, or whether account_id must match the bearer. This is adequate but not exhaustive.

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?

One dense sentence conveys purpose and key qualifiers without filler; front-loaded verb and structured qualifiers make it easy to scan.

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?

With an output schema available and only one required parameter, the description gives a clear high-level contract. It could add usage guidance or clarify period resolution, but for a read-only summary tool it is reasonably complete.

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 coverage is 0% and the description never mentions account_id or its semantics. The single parameter is self-explanatory by name, and 'bearer-owned' hints at ownership scope, but the description does not compensate for the schema's lack of description.

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?

Clear verb 'Return' identifies the read action; specifies resource 'usage' and qualifiers (bearer-owned, period-resolved, included/overage, catalog lineage, conservation totals), distinguishing it from MRR-oriented sibling mrr_summary.

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 explicit when-to-use or alternative comparison is provided, though 'usage' and 'period-resolved' imply it is for usage summaries rather than MRR or subscription status. Sibling tools like mrr_summary suggest alternatives but are not named in the description.

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