subscriptions

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description does add genuinely useful behavior: the full account key is returned exactly once and only a hash plus last four characters are persisted, warning the agent that the key is unrecoverable. It stops short of describing auth requirements or idempotency for a creation 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?

Two short sentences, no filler, and the one-time key disclosure is front-loaded where it will be read. Nothing could be removed without losing information.

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?

An output schema exists, so return shape need not be spelled out, and the key-once caveat is a valuable addition. However, for a creation tool with a single undocumented required parameter, the definition leaves the caller guessing about the input's meaning and any preconditions.

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 sole parameter, account_ref, has 0% schema description coverage and the description never explains what it is (an email, an external identifier, a slug?). With a schema that leaves the only input completely undefined, the description needed to compensate and does not.

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 names a specific verb and resource ('Create a free account') plus a qualifying purpose ('for bearer attribution'), which is enough to distinguish it from read-oriented siblings like get_plan or mrr_summary. The phrase 'bearer attribution' is somewhat opaque but still narrows the scope beyond the title.

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?

There is no statement of when to call this rather than record_subscription, create_checkout_link, or subscription_status. The word 'free' hints at a non-paid path, but the agent must infer the boundary on its own.

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?

Annotations already establish non-read-only, non-destructive, open-world behavior; the description goes further by stating no card is charged and enumerating the exact fail-closed conditions under which no session is created. That is genuine behavioral context beyond the annotations, though it doesn't explain idempotency or what the returned URL looks like.

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 short sentences, front-loaded with what the tool produces and immediately followed by the important non-charging guarantee. Slightly dense jargon ('unavailable covered agents') costs a bit of clarity but nothing is wasted.

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?

An output schema exists, so return values need not be explained, and the failure modes are well covered. The significant remaining gap is parameter meaning: with 0% schema coverage on two required params, the agent has no guidance on how to construct account_ref or which plans are eligible.

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 neither plan_id nor account_ref is described anywhere. The mention of 'Draft plans' and 'recurring Price IDs' hints that plan_id refers to a plan record, but account_ref is entirely unexplained, leaving the agent to guess its format and 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 names a specific verb and artifact – prepare a Stripe-hosted subscription Checkout URL – and adds the key disambiguator 'It never charges a card', which separates it from charge/record tools like record_subscription. It does not explicitly name a sibling alternative, so it stops short of a 5.

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?

Usage is implied (produce a hosted checkout URL for a subscription plan) and the fail-closed preconditions – draft plan, missing owner approval, unavailable covered agents, missing recurring Price ID – effectively tell the agent what state must hold first. However, there is no explicit statement of when to prefer this over customer_portal_link or record_subscription.

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?

Beyond the annotations, it discloses two things an agent could not infer: the URL is bearer-owned (a credential that grants access to whoever holds it), and the tool itself never moves money, with the mutation happening in the human's browser session. This usefully reconciles the read-shaped behavior with readOnlyHint=false, though it says nothing about expiry or whether a new portal session is minted per call.

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 short sentences, front-loaded with the returned artifact, then the safety scoping. Nothing is padded and nothing needs to be re-read.

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?

An output schema exists, so return values need no explanation, and the one-parameter surface keeps complexity low. However, the sole parameter is undocumented in both schema and description, and the absence of any routing cue against create_checkout_link leaves a real 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 single parameter account_id has 0% schema description coverage and the description does not mention it at all, leaving ambiguous whose account it is and what form the identifier takes. The word "bearer-owned" gestures at ownership but does not pin down the parameter's 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?

"Return a bearer-owned Stripe-hosted billing-portal URL" gives a concrete verb (return) and resource (billing-portal URL) with an important qualifier (Stripe-hosted). It is adequately distinct from create_checkout_link by resource name, though it never names that sibling to draw the line 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?

"The human manages or cancels there" implies the use case: hand the URL off for self-service billing management. But there is no explicit when-to-use versus create_checkout_link, no prerequisites stated, and no conditions under which an agent should prefer subscription_status or get_plan.

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?

The annotations already declare that this is a read-only, non-destructive, closed-world operation, so the safety profile is covered. The description adds useful context about the categories of metadata returned but does not go beyond that to describe authorization needs, rate limits, or other operational behavior.

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 front-loaded sentence that lists the returned metadata categories with no filler. Every phrase contributes to identifying what the tool returns.

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 read-only introspection tool with a full output schema and clear safety annotations, the description is largely complete. It lists the key returned metadata categories, though it could more explicitly identify 'this service' as the target resource.

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?

This tool has zero parameters, so there are no parameter semantics to explain. The baseline for a parameterless tool is a 4, and nothing in the description creates ambiguity about inputs.

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 concrete verb, 'Return', and lists specific service metadata fields: version, catalog digest, security posture, lifecycle policy, and capabilities. This makes the tool's purpose clear, though the resource is only implied as 'this service' from the title rather than explicitly restated in the description.

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?

Usage is implied by the returned fields: an agent should call this when it needs service-level metadata. However, the description does not explicitly say when to use it, when not to use it, or name any alternative sibling 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds only that the result carries "versioned catalog lineage," some hint of return content, but with an output schema present this adds little beyond structure.

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?

A single front-loaded sentence with no filler. The phrase "versioned catalog lineage" is jargon-heavy for the amount of information it actually conveys, but it costs only one clause.

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?

An output schema is present and annotations cover the read-only safety profile, so the main remaining gap is the undocumented plan_id. The description does not fill that gap, leaving the definition minimally adequate for a simple one-parameter lookup.

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% for the single required plan_id, so the description must compensate and largely does not. "One exact" weakly implies an exact-match identifier, but neither the expected format nor whether it is an ID versus a name is clarified.

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 names a specific verb and resource ("Get one exact monthly plan") and signals single-item retrieval, which implicitly separates it from the sibling list_plans. The trailing phrase "and its versioned catalog lineage" is vague about what lineage actually means, keeping it short of a 5.

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?

Use is implied rather than stated: "one exact" suggests it is for a known single plan, in contrast to listing. However, it never names list_plans as the alternative or states when-not to use this tool, so the agent must infer the routing.

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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds that the catalog is versioned and carries a readiness flag and pending owner-confirmation notice, which hints at state the agent should check. However, it spends most of its words on return fields that the output schema already documents.

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?

A single front-loaded sentence with the resource stated first and qualifiers after; there is no filler or boilerplate. The list of return fields is somewhat redundant against the output schema, but it is compact and readable.

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 no parameters, an output schema, and annotations covering the safety profile, the remaining burden is small. The description tells the agent what the call yields and that versioning and readiness matter. The only real gap is routing relative to get_plan.

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 takes zero parameters, so there is nothing for the description to disambiguate. Baseline for a no-parameter tool applies, and no misleading parameter hints are given.

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?

Specific verb plus resource: 'List the versioned monthly-seat catalog,' with the returned content enumerated (prices/coverage, SHA-256, readiness flags, owner-confirmation notice). An agent can tell this is a catalog read rather than a single-plan lookup. It does not name the closest sibling, get_plan, so plan-vs-catalog selection still requires inference.

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?

There is no when-to-use or when-not-to-use guidance and no mention of alternatives such as get_plan or the checkout/record tools. The word 'List' only weakly implies a browsing/selection-time context. An agent must guess whether to call this or get_plan first.

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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered structurally. The description adds genuinely new behavioral context: results are scoped to live mode only (test-mode data excluded), values are aggregates rather than per-customer rows, MRR is denominated in minor units, and no account or Stripe identifiers are exposed. What it omits is whether the snapshot is point-in-time or windowed, and whether any filtering is possible.

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 tight sentences, front-loaded with the return payload and followed by the privacy/scope constraint. No filler, no restatement of the title, and every clause carries information.

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?

An output schema exists, so the description is not obliged to explain return values, and the safety profile is covered by annotations. It covers scope, units, and privacy adequately for a zero-argument read tool; the only real gap is that the temporal basis of the MRR figure (current snapshot vs. period) is left implicit.

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 takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. The mention of 'minor units' and 'live-mode' describes output semantics rather than inputs, which is appropriate here.

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-plus-resource (returns an aggregate MRR summary) and enumerates exactly what comes back: active live-mode subscription count, MRR in minor units, and plan mix. An agent knows precisely what this produces, though it never distinguishes itself from the similar-sounding sibling usage_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?

There is no when-to-use statement, no prerequisites, and no named alternative. The phrase 'active live-mode subscription' hints at scope, but nothing tells an agent whether to reach for this versus usage_summary or subscription_status when it needs billing metrics.

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?

Annotations already declare a non-read-only, non-destructive, open-world operation. The description adds useful behavioral context: idempotent activation, exact subscription period handling, and one-time key issuance for newly created accounts, though it omits auth/prerequisite and error behavior.

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 core action, and contains no obvious repetition. The phrasing is slightly compressed and jargon-heavy, but efficient.

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 an open-world billing mutation with an output schema, the description covers the core action, idempotency, and key issuance. It still lacks prerequisites, guidance on when to call it versus subscription_status, and what happens for invalid or already-recorded Stripe sessions.

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% for the single required parameter. The description implies the identifier is a Stripe session or subscription and will be pull-verified, adding some meaning beyond the bare parameter name, but it gives no format or validation details.

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 action: pull-verify a Stripe session/subscription and activate its exact subscription period. The billing/subscription domain is clear, but it does not explicitly distinguish itself from siblings like subscription_status or create_account.

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?

There is no explicit when-to-use or when-not-to-use guidance, and no alternative sibling is named. The only implied usage is post-checkout activation via the sentence about a newly created account receiving its key once.

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?

The annotations already establish readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds two things annotations cannot: the result is scoped to the bearer's own subscription, and the account key is always masked in output – a meaningful privacy disclosure for an agent relaying results.

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 short sentences with the scope stated first and the output-masking caveat second. Nothing is padded, though the second sentence could have been spent resolving the account_id ambiguity instead of only the masking 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?

An output schema exists, so return-value detail is legitimately out of scope. However, for a tool with a single undocumented required parameter and several adjacent siblings (usage_summary, get_plan, mrr_summary), the description leaves the account_id meaning and the routing decision under-explained.

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 sole required parameter account_id has no title or description beyond its name, so the description must compensate and does not. It never explains what account_id should be or why a required identifier is needed when the result is described as bearer-owned, leaving a real ambiguity.

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 names a specific verb and resource: returning the bearer's subscription lifecycle and current-period quota. That is concrete enough to separate it from list_plans or get_plan, though it does not explicitly name a sibling to contrast against.

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?

Usage is only implied – the agent can infer this is the tool for checking its own subscription state and quota. There is no explicit guidance on when to prefer usage_summary or get_plan instead, and no prerequisites are stated.

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?

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so safety is fully covered. The description does add value beyond them by disclosing that results are scoped to the bearer token rather than an arbitrary account and that usage is resolved per period. What "conservation totals" and "exact catalog lineage" operationally mean is never explained, leaving the behavioral picture partially opaque.

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?

It is a single sentence with no filler, which is structurally efficient. But the density of undefined terms means brevity comes at the cost of comprehensibility, and the most actionable detail (bearer scoping) is not 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?

An output schema and annotations cover return shape and safety, lowering the bar. Still, for a tool whose selection hinges on being distinguishable from mrr_summary, the description supplies neither usage routing nor parameter meaning, so key gaps remain.

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?

There is one required parameter, account_id, with 0% schema description coverage, so the description carries the entire burden. It never mentions account_id or clarifies how an explicit account identifier interacts with the "bearer-owned" scoping claim, which is exactly the ambiguity an agent would trip on.

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 ("Return ... usage") and gestures at scope via "bearer-owned" and "period-resolved." However, the core framing is buried under unexplained jargon ("catalog lineage," "conservation totals"), so an agent cannot immediately tell what the payload actually contains or how it differs from the nearby mrr_summary tool.

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?

There is no when-to-use statement, no preconditions, and no mention of the closest alternative, mrr_summary, which also summarizes billing-period data. The agent must infer selection 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.