SparkPay

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

Annotations already flag destructiveHint=true and openWorldHint=true, but the description adds substantial context beyond them: human approval gating, the deliberate decision to leave Stripe products/prices untouched so existing subscriptions are never affected, the two refusal conditions and how they are matched, and the required follow-up `bun run plans:sync`. Nothing here conflicts with idempotentHint or the other hints.

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-loading is excellent: purpose first, then the WRITE/human-gate warning, then context, then refusals, then the post-step. It is one dense paragraph whose sentences each carry information, though the middle context sentence is long enough to slow scanning.

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 destructive, human-gated write with no output schema and three parameters, this covers the safety profile, side effects, refusal behavior, subscription impact, and the follow-up sync step. The only minor omission is what dry_run returns, which is inferable from 'previews anywhere.'

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%, so the description has to carry the load. It meaningfully explains `dry_run` ('previews anywhere'), clarifies that `tier` is a slug matched against Stripe price ids, and ties refusal logic to it. `app_id` is only implied by 'an app's plan catalog' and its format is never stated, which keeps this short of a 5.

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 first sentence gives a specific verb and resource ('Remove a tier from an app's plan catalog') and immediately positions the tool against siblings: 'Every other plan tool edits tiers that already exist, so a catalog could grow but never shrink.' An agent can distinguish this from update_plan_meta/update_plan_pricing without reading any schema.

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 states exactly when a real write is possible ('needs an elicitation-capable client and the human must approve') versus when it is not ('dry_run previews anywhere'), and names the gap it fills that the other plan tools leave open. Refusal conditions (non-cancelled subscribers, last remaining tier) tell the agent when not to expect success.

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 non-readOnly, idempotent and non-destructive, but the description adds substantial context beyond them: the human-gated elicitation requirement, that the form overrides the passed arguments, that non-elicitation clients are refused (except dry_run), and that actual create is guarded per-app. It even discloses the batch semantics (already-present codes are `skipped` rather than failing) and the return shape (per-app outcome matrix plus counts).

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 most decision-critical facts (what it does, human-gating, the batch skip behavior) are front-loaded, and every sentence carries information. It is somewhat dense and a couple of the parenthetical asides could be trimmed, but there is little wasted text.

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 mutation bulk tool with no output schema, the description still explains the return value (per-app outcome matrix plus created/skipped/failed counts) and the approval flow. The remaining gap is the undocumented optional parameters, which is captured under parameter semantics; overall it is complete enough for an agent to call it 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% across 10 parameters, so the description carries the burden. It clarifies app_ids provenance (from list_apps), the semantics of dry_run, that code and discount_percent define the coupon, and that 'coupon terms' are entered once via the form overriding the args. But it leaves listed, max_uses, expires_at, description, applies_to_tiers and confirm_high_discount unexplained, so it only partially compensates for the coverage gap.

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 and resource ('Create the SAME discount code across many apps in one call') and immediately distinguishes it from the sibling create_coupon ('Runs each app through the same fully-guarded create as create_coupon'). An agent can tell exactly what this tool does and how it differs from single-create without opening any schema.

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 gives explicit when-to-use ('portfolio-promo shortcut'), a recommended precondition ('Use dry_run:true first to see which apps would create vs skip'), and a hard constraint ('Pass explicit app_ids (from list_apps)'; 'deliberately no all apps shortcut'). It also names the behavioral contrast with the single-call alternative. This is about as complete as usage guidance gets.

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 destructive and idempotent annotations, it discloses the human-gated elicitation flow, per-app approval visibility with redemption counts, refusal for non-elicitation clients, and skipped behavior for apps that never had the code. It also describes the returned outcome matrix and counts.

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 purpose is front-loaded and nearly every sentence adds operational value. The paragraph is dense and has some long clause chains, but the detail is justified for a destructive bulk tool.

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 destructive, human-gated bulk operation with no output schema and undocumented input parameters, the description is complete enough to call correctly. It covers authorization behavior, preview workflow, skipping semantics, and return shape.

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?

With 0% schema description coverage, the description compensates by explaining app_ids as explicit apps from list_apps, dry_run as a preview mechanism, and confirm_used as consulted only for dry_run previews. The code parameter is also contextualized as the same coupon code across apps.

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 and resource: deleting the same coupon code across many apps in one call. It distinguishes the tool from siblings by naming bulk_create_coupon as its inverse and framing the use case as retiring a portfolio-wide promo.

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 explicitly recommends dry_run:true first and instructs passing explicit app_ids from list_apps. It also explains when clients without elicitation are refused and the condition under which confirm_used applies.

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?

Goes well beyond the annotations: discloses real external side effects ('minting real Stripe prices', same helper as /api/apps/sync-plans), the overwrite guard, and a security guarantee that push-mode webhook secrets only appear in post_steps and never in kit files. This is exactly the extra context the destructiveHint/openWorldHint flags can't convey.

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-loaded with the purpose and ordered step, then the side effects and safety rules. It is a dense compound paragraph, but each clause carries distinct information an agent needs; minor tightening would help readability.

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?

Compensates for the missing output schema by describing the return artifact (kit contents: client, plans.json, sync script, INTEGRATION.md) and post_steps. The nested answers object is only partly covered, but the agent has enough to call the tool correctly and 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. It does partially: it explains that plan_catalog is applied/minted into real Stripe prices and that confirm_overwrite controls overwrite behavior, and it ties push_mode to the webhook secret. However, success_url, cancel_url, trial_days, tier, monthly_price/yearly_price and payment_type are left entirely to the raw schema.

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: mints Stripe prices from answers.plan_catalog, registers/updates the app, and returns a downloadable integration kit. It also places itself in a sequence ('Step 2 of onboarding'), which implicitly distinguishes it from plan_app_kit (step 1), but no sibling is named 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 'Step 2 of onboarding' framing gives clear sequencing context, and the overwrite rule ('refuses to overwrite ... unless answers.confirm_overwrite is true') tells the agent exactly when the call will succeed or fail. No explicit when-not or named alternative tools are given, though.

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?

Far exceeds the annotations: it discloses the elicitation/human-in-the-loop gate, that argument values are only a proposal overridden by the human form, the side effects (coupons row + best-effort Stripe mint with checkout backfill), the normalization/unique constraint on code, the free-only-app limitation, and the three non-negotiable house rules (6-month max expiry, 90%+ forced invite_only, 90%+ tier pinning). None of this is recoverable from readOnlyHint/openWorldHint/idempotentHint.

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?

Roughly 200 words but densely packed with non-redundant operational facts, and the most decision-critical items (WRITE, human-gated, dry_run) are front-loaded before the house rules. A few clauses, such as the parenthetical Stripe fallback detail, could be trimmed without losing selection value.

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 10-parameter mutation tool with no output schema, it covers side effects, failure modes, defaults, next-step verification and business constraints well enough to call it correctly. The remaining gap is per-parameter semantics for max_uses/description/listed and confirmation of what confirm_high_discount does versus the automatic house rules.

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%, so the description carries the burden and does substantial work: dry_run semantics, expires_at default (omitting means 6 months, not never), applies_to_tiers default (all paid tiers), code uppercasing/uniqueness, and the discount_percent 90%+ consequences. However max_uses, description, listed, app_id and confirm_high_discount are never explained, leaving roughly half the parameters undocumented anywhere.

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?

Opens with a concrete verb+resource ("Create a percentage discount coupon for an app") and immediately flags it as a WRITE, human-gated operation, so the agent knows exactly what kind of effect to expect. It never names the obvious sibling bulk_create_coupon, so differentiation from that tool is left implicit (singular vs. bulk) rather than stated.

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?

Explicitly prescribes the pre-flight ("Set dry_run:true first to preview the exact row without writing"), the post-flight ("Use list_coupons afterwards to confirm"), and where to find tier slugs ("list_plans"). It also states a hard gating condition — clients without elicitation are refused while dry_run still works anywhere — which tells the agent exactly when the call will and will not succeed.

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 destructive annotation, it discloses the human-gated elicitation flow, that the model cannot self-confirm, that confirm_used only affects dry_run previews, that non-elicitation clients are refused, and that the Stripe object plus database row are removed to avoid orphans. It also states permanence and that the code becomes reusable.

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 front-loaded and mostly earns its sentences, covering safety gates and effects efficiently. It has some repetition around human confirmation/elicitation, but given the destructive nature the length is defensible.

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 destructive, human-gated delete with no output schema, the description is complete: it explains prerequisites, refusal behavior, dry_run preview, exact side effects, permanence, and a recommended prior check. Only app_id semantics 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?

With 0% schema description coverage, the description covers the critical semantics of dry_run and confirm_used well, and implies code is the coupon code. However, app_id is never explained, leaving one of four parameters undocumented.

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 and resource ('Delete one coupon from an app') with clear single-item scope, distinguishing it from the bulk_delete_coupon sibling by saying 'one coupon'.

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 gives strong operational guidance: use list_coupons first, set dry_run for previews, and note that elicitation-capable clients are required for real deletes. It does not explicitly name bulk_delete_coupon as the alternative for multi-coupon deletion, so it falls short of full alternative 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 readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the response is exhaustive across apps, includes verification/plan/billing/usage/refunds, and returns empty for an unknown email — a meaningful edge case an agent must handle.

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?

Three compact sentences: the action first, then return shape and scoping, then the empty-result edge case. Every sentence carries information and nothing is padded.

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?

No output schema exists, so the description must describe the return — and it enumerates the returned detail categories and the empty case. Combined with two well-explained parameters, an agent has everything needed to call and interpret it.

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 carry the parameter meaning — and it does: email is the lookup key and app_id is an optional scope limiter ('within one app if app_id is given'). It does not state email format or app_id sourcing, leaving a small gap, but the semantics are usable.

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 ('Look up a customer by email') plus the exact scope of what is returned (every subscription/registration across apps). This clearly distinguishes it from sibling list_* tools, which enumerate collections rather than resolving one customer by identifier.

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 makes the selection context clear: use it when you have an email and need the full customer picture, and pass app_id to narrow to a single app. It stops short of explicitly naming an alternative tool or stating when not to use it, so it falls just below the top band.

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?

Discloses behavior well beyond the annotations: human-gated elicitation requirement, refusal on non-elicitation clients, lowercasing/de-duplication, malformed addresses reported not dropped, and the crucial idempotency semantics (re-inviting a redeemed or revoked address does nothing). This is consistent with idempotentHint=true and destructiveHint=false, and adds the operational detail the hints cannot express.

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 and its default side effect before the operational caveats, and every sentence carries non-obvious information. It is dense but long for a single paragraph; the elicitation aside could be tightened without losing meaning.

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 6-parameter, non-read-only tool with no output schema and no schema descriptions, the description covers the risky semantics (gating, idempotency, dry run, warnings) thoroughly. The only real omission is what 'source' means and what the result object contains beyond the warning.

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?

With 0% schema description coverage the description does most of the work: it explains emails normalization/reporting behavior, dry_run's preview role, and the exact meaning and default of enforce_invite_only including its warning side effect. The 'source' parameter and the app_id/code pair are never mentioned, leaving a gap.

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 ('Add email addresses to a coupon's invite list') plus the default side effect ('switch the coupon to invite-only'). This cleanly separates it from list_coupon_invites and revoke_coupon_invite in the sibling set without the agent needing to open any schema.

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?

Gives explicit when-to guidance ('Use dry_run:true first') and a precise when-not ('Set enforce_invite_only:false only to stage a list before gating the code'), plus the client-capability prerequisite for elicitation. It stops short of naming sibling alternatives like revoke_coupon_invite, so it is clear context rather than full 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 readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds the genuinely useful behavioral fact that the output is a lookup table of app_id→name pairs intended as a scoping input for other tools. It says nothing about result size or pagination, which is the only meaningful gap.

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, both front-loaded: what it returns first, how to use it second. No restatement of the tool name or filler.

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 and no output schema, the description carries return-value burden and does so by naming the two returned fields and the downstream role of app_id. Only pagination/result-size behavior is unaddressed, which is minor for a small registry listing.

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 applies. The description instead clarifies the semantics of the returned app_id as the scoping key used by other tools, which is bonus 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?

States a specific verb and resource ("List the registered apps") and even declares the returned fields (app_id + name), so an agent knows exactly what comes back. It is trivially distinguishable from the sibling listing tools (list_coupons, list_plans, list_subscriptions) by resource.

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 this first to discover valid app_id values, then pass one to the other tools" gives an explicit workflow ordering and downstream purpose, which is exactly what an agent needs for a discovery tool. It stops short of naming which specific sibling tools consume app_id or any exclusion condition, so not a 5.

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 cover readOnly/idempotent/non-destructive, so the 'Read-only' sentence is redundant; the real value is the disclosure that invite rows are recorded but NOT enforced when invite_only is false. That is a genuine behavioral trait not present in any structured field and prevents a serious misreading of the results. Minor deduction only for the repeated safety claim and the absence of any note on result size or ordering.

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 return payload is front-loaded, followed by the interpretation rule and then sibling routing — a sensible order. It is dense but every sentence does work, except the redundant 'Read-only' clause that repeats the annotation block.

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?

There is no output schema, and the description compensates well by enumerating the returned fields and the invite_only flag. The remaining gap is parameter-level: an agent knows what it will get back but not what `app_id` should be, which matters for a tool requiring both parameters.

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%, so the description carries the full burden, and it only partially does: 'a coupon' implies that `code` identifies the coupon, but the `app_id` parameter is never mentioned or explained. With just two required parameters and no schema documentation, a brief note on whether code is the coupon code and what app_id scopes would have closed the gap.

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 plus the exact payload returned: per-address status (invited / redeemed / revoked), invite source, timestamps, and the coupon's invite_only flag. It explicitly differentiates itself from list_coupons, invite_to_coupon, and revoke_coupon_invite by name, so no sibling ambiguity remains.

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?

Routes the agent precisely: list_coupons for terms, invite_to_coupon to add addresses, revoke_coupon_invite to withdraw one. It also gives the interpretation rule ('read that FIRST' on invite_only) that determines whether the returned rows actually mean anything, which is exactly the kind of conditional guidance an agent needs before acting.

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/idempotentHint, so the safety profile is covered, but the description adds real value by defining what 'active' means (not expired, not maxed out) and enumerating returned fields. No mention of pagination behavior or how limit interacts with the result set.

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?

Three tight sentences, front-loaded with purpose, then optional scoping, then the read-only constraint. The read-only clause partly restates annotations, but it earns a place as a guard against mutation misuse.

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 output schema, the field enumeration substitutes well for return-value documentation, and the active_only semantics are clarified. The main gap is pagination/limit behavior for a list tool, which an agent calling with default limit 50 would want to know.

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%, so the description carries the burden: it defines app_id as scoping and active_only as an expiry/max-uses filter, which is helpful semantics beyond the bare property names. However, the limit parameter (default 50) is never mentioned, leaving one of three parameters undocumented everywhere.

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 (list) and resource (discount coupons), then enumerates the fields returned (code, percent off, expiry, max uses, use count, applicable tiers). This clearly separates it from create_coupon, delete_coupon, and list_coupon_invites without the agent needing to open any schema.

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?

Explicitly frames the two optional scoping modes (app_id scoping and active_only filtering) and notes it cannot create, edit, or delete, implicitly routing mutations to the sibling write tools. It stops short of naming those alternatives or stating exclusions like 'use list_coupon_invites for invites'.

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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds meaningful context beyond them: it is the source of truth that `bun run plans:sync` regenerates plans.json from, and Stripe IDs are conditionally withheld. It doesn't discuss pagination or whether the catalog can be empty for unconfigured apps.

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?

Three sentences, front-loaded with what is returned, then why it's authoritative, then the one flag caveat. No filler, and the most decision-relevant fact (source of truth) is placed high.

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?

No output schema exists, so the description's enumeration of returned fields (tiers, names, prices, trial, limits) does the work of explaining the response. The remaining gap is app_id acquisition — pointing to list_apps would make it fully self-sufficient for a 2-param tool.

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?

With 0% schema description coverage the description must compensate, and it does explain one of the two parameters precisely (Stripe price/product IDs omitted unless include_stripe_ids is set). app_id is only implied as "an app's" — no format or source-of-valid-IDs guidance — leaving the required parameter under-specified.

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 ("Download") and resource ("an app's live plan catalog") and enumerates the payload: tiers, names, prices, trial, and limits. It is clearly a read-only catalog listing, distinguishable from the many mutate-plan siblings (update_plan_*, archive_plan) and from list_apps.

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?

Gives real selection guidance — "diff against this rather than trusting the committed file" tells the agent to prefer this over plans.json, which is a concrete when-to-use rule. It stops short of naming sibling tools (e.g., list_apps for app_id discovery) or stating exclusions, so it is clear but not fully 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 readOnly/idempotent/non-destructive/openWorld, so safety is covered; the description adds real behavioral context on top: free rows are excluded from the result set and ordering is descending by cancellation date. It does not disclose the limit default behavior or what 'include_samples' does to the returned data, which keeps it out of 5 territory.

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, no filler, and the scoping detail (paid only, recency order) is front-loaded before the sibling disambiguation. Every clause carries information an agent needs.

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?

Annotations and the description together cover the read-only listing and its result semantics reasonably well for a tool with no output schema. But with three wholly undocumented parameters and no statement about pagination or default page size, an agent cannot confidently control scope or result volume.

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 all three parameters, so the description carries the full burden and largely drops it. 'limit' and 'app_id' are never mentioned, and 'include_samples' — the least self-explanatory of the three — is not explained at all, despite 'with what each customer was paying' hinting at sample rows.

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 resource (recently canceled paid subscriptions), the filter applied (excludes free rows), and the output shape (most recent first, with what each customer was paying). It explicitly distinguishes itself from the sibling that could be confused with it, list_subscriptions, so an agent can select correctly without opening either schema.

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?

Gives a concrete use case ('churn review') and names the alternative (list_subscriptions) with the axis of differentiation (ordering by signup date vs. cancellation recency). What's missing is an explicit negative condition — e.g., when a churn-review need should instead go to list_recent_payments or revenue_by_app.

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 readOnly, idempotent, non-destructive, so safety is covered. The description adds genuinely new behavioral facts: free-tier rows are excluded, ordering is newest-first by payment date, and amounts are in cents of the transaction currency.

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?

Four short sentences, front-loaded with the core behavior, no filler. Slightly scattered ordering-wise with the currency note last, but every sentence adds 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?

No output schema exists, and two of three parameters go undocumented in both schema and description, plus no hint on how many results 'recent' returns. The core semantics are captured, but an agent cannot fully parameterize the call from this definition.

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%, so the description carries the full burden, yet only app_id is explained ('optionally scope by app_id'). limit and include_samples are never mentioned, leaving the agent to guess pagination size and what samples mean.

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 (list paid transactions), and adds distinguishing scope: excludes free-tier rows, newest first by payment date. This differentiates it from revenue_summary and list_recent_cancellations without naming them 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?

'Use to review recent sales activity' implies the use case but never states when to prefer this over revenue_summary, revenue_by_app, or list_recent_cancellations, nor any preconditions. Adequate but leaves routing to the agent's inference.

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 that this is a read-only, idempotent, non-destructive, open-world operation. The description adds useful context about the returned fields and ordering ("newest first"), but does not explain pagination behavior, how limit interacts with ordering, or what include_samples does.

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 compact sentences with zero filler, and the core purpose and ordering are front-loaded before the optional filtering details.

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 four parameters at 0% schema coverage and no output schema, the description is too thin. An agent can infer the record shape and optional app/status filters, but cannot know how many records are returned by default or what include_samples changes.

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 carry the full parameter burden. It mentions app_id and status (including the pending/rewarded enum values) but completely omits limit, its default of 25, and include_samples, leaving half the parameters undocumented in both places.

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 ("List referral records") and enumerates the record contents (referrer/referee, reward coupon code, status). It clearly distinguishes the tool from coupon- and plan-oriented siblings, though it does not explicitly call out an alternative.

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 states that scoping by app_id and/or status is optional, which implies a basic usage pattern. However, it gives no explicit when-to-use guidance, no exclusions, and no comparison to sibling list tools such as list_coupon_invites.

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 readOnly, idempotent, non-destructive and openWorld, so safety is covered. The description adds the 'newest first' ordering and a sketch of the returned metadata (email, status, plan, amounts), which is genuine context. However, it never explains pagination/limit behavior or what include_samples does, which are non-trivial behavioral traits with no annotation coverage.

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?

Three short sentences, zero waste, with the core behavior and return shape front-loaded before the sibling routing hint.

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 read-only list tool with no output schema, the description gives the ordering, the filterable dimensions, and the returned fields. It falls short only on the limit/include_samples parameters and pagination expectations.

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 bears the full burden. It names app_id, status, and payment_type only as filters, adding no meaning beyond the property names, and it omits limit and include_samples entirely. An agent could not infer the default page size or what sample data inclusion changes.

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 (list) and resource (subscriptions/registrations), plus the implicit sort order 'newest first'. Sibling tools list_plans, list_coupons, and list_recent_cancellations make the resource distinction essential, and the description draws it clearly.

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?

Explicitly routes the agent: use get_customer for a single user or revenue_summary for totals, leaving this tool for enumeration and filtering. The optional-filter sentence makes the intended usage unambiguous.

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, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: it returns automated findings plus a minimum set of human questions covering prices, billing model, redirect URLs, trial length, and push-webhook opt-in.

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 three sentences, front-loads the step-1 context, then explains the output and next action. The parenthetical list of question topics is compact and 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?

No output schema exists, but the description explains the return shape at a useful level: automated findings plus targeted human questions. It also explains the next step. It could say more about what findings look like or what happens if the app name conflicts, but the core information is present.

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 carry parameter meaning. It explains that app_name is reconciled against existing apps and the portfolio's plan catalogs, which adds useful role-level meaning, but it does not specify format, uniqueness expectations, or examples beyond that.

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 action and resource: Step 1 of onboarding a new app onto SparkPay, reconciling the app name against existing apps and plan catalogs. It clearly distinguishes this planning/reconciliation tool from create_app_kit, which is named as the next step.

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 explicitly says this is the first step in onboarding a new app and directs the agent to pass answers to create_app_kit next. That gives both the condition for using this tool and the handoff alternative.

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 cover the safety profile (readOnly, idempotent, non-destructive), but the description adds genuinely non-obvious semantics: latest_payments is a run-rate from the most recent payment per customer, not lifetime turnover, and no lifetime figure exists because accrual is recorded per owner. That prevents a likely misinterpretation of the numbers. It stops short of describing the shape of the returned rollup or how many apps come back.

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 payload comes first (what the rollup contains, then sort order), followed by the run-rate caveat and then the routing sentence. Three dense sentences with no filler.

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 output schema, the description does the work of naming the returned metrics and ordering, and the run-rate caveat is essential context that is included. The only omission is the behavior of include_samples, which leaves one caller-facing decision unexplained.

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 exactly one parameter, include_samples, with 0% schema description coverage, and the description never mentions it or what 'samples' would contain. The otherwise rich description does not compensate for that gap, so an agent must guess the effect of setting it.

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+resource (per-app revenue rollup) and enumerates the metrics returned (latest_payments, refunded, MRR, paid customer count) plus the sort order. An agent can distinguish it from revenue_summary purely from 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?

Explicitly says 'Use to compare products at a glance; use revenue_summary for one app in depth.' This names the alternative sibling and the condition that selects it, so nothing is left to inference.

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 readOnly/idempotent/non-destructive, but the description adds the failure modes an agent actually needs: amount_paid is overwritten on renewal so latest_payments is a run-rate, lifetime_net counts only charges whose Stripe webhook reached this app and silently under-counts on missed renewals, and lifetime_net is null when no accrual record exists. This is exactly the beyond-annotation context the dimension rewards.

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 one dense paragraph that front-loads the returned fields and pushes caveats after, with no filler sentences. The heavy parenthetical nesting makes it longer and harder to scan than necessary, but nearly every clause carries operational meaning.

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?

There is no output schema, so the description carries the full burden of explaining return fields — and it does, including null semantics and why figures may be understated. Only the include_samples parameter is unaddressed, and that gap is already scored under 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%, so the description must carry both parameters. It clarifies app_id ('optionally scope by app_id; omit for platform-wide totals') well, but include_samples is never mentioned anywhere, leaving the second of two parameters undocumented.

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+resource (revenue and subscriber summary) and enumerates exactly what is returned: latest_payments, refunds, approximate MRR, active/trialing/paid counts, and lifetime_net. The two non-obvious metrics are distinguished from each other in-line (run-rate vs. cumulative per-owner net), so an agent understands the scope without opening anything else.

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 gives an explicit exclusion with an alternative: 'For turnover, accounts or tax, read Stripe directly: it is authoritative,' and it tells the agent when a 0 is an absence-of-record rather than an absence of sales. It does not name a sibling tool (e.g., revenue_by_app) as the scoped alternative, which keeps it just short of a 5.

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?

Goes well beyond the annotations (destructive/idempotent/openWorld) by disclosing the human-gated elicitation requirement, that elicitation-incapable clients are refused while dry_run works anywhere, and that a revoked tombstone is written even for never-invited addresses and survives later bulk re-invites. The only gap is what a successful response looks like or how refusal surfaces to 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?

Front-loaded with the core action and scope before the caveats. It is a dense single paragraph — long, but nearly every clause carries operational information (gating, tombstone persistence, irreversibility, sibling routing); minor trimming of the delete_coupon justification would tighten it.

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?

No output schema exists, and the description covers the complex parts an agent needs: write gating, tombstone semantics, irreversibility for redeemed invites, and prerequisite listing. Missing the `reason` field's purpose and any indication of the return/refusal shape keeps it short of 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%, so the description carries the burden; it clarifies that email is the targeted address, code is the coupon, and that dry_run changes the gating behavior. However `reason` is never mentioned and `app_id` is never explained, leaving two of five parameters undocumented in both schema and 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?

States a precise verb and resource — 'Withdraw one address's right to spend a coupon' — and immediately characterizes it as 'the targeted block,' which distinguishes it from whole-coupon deletion. An agent can tell exactly what object is affected and at what granularity.

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?

Gives explicit routing: prefer over delete_coupon when a single recipient misbehaves, because deleting punishes other invitees; call list_coupon_invites first to see status. It also states the boundary condition — it only blocks FUTURE redemptions, and an already-`redeemed` discount must be handled via dashboard cancel/refund.

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 description adds substantial behavior beyond the annotations: writes require an elicitation-capable client, clients without elicitation are refused, dry-run works anywhere, and the human sees the code, discount, direction of movement, and start date. It also discloses side effects and safety boundaries: no Stripe object is touched, the discount does not move, scheduling only affects public listing, expired/maxed listings warn, and already-current states return `noop`.

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 purpose and the write-gating caveat are front-loaded, and most sentences carry operational constraints that matter for correct invocation. The description is nevertheless dense and long, so it is closer to a compact specification than a maximally concise definition.

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 output schema, the description still covers the key return states and outcomes: refusal for missing elicitation, refusal for invite-only coupons, contradiction refusal, warnings for expired/maxed or bad scheduling, and `noop` for already-current state. It also supplies the authorization and side-effect context needed to call a human-gated write 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 coverage is 0%, so the description must compensate, and it strongly explains the central parameters `listed` and `listed_from`, including future staging, schedule clearing, refusal with `listed:false`, and warning conditions. It also explains `dry_run` parenthetically and implies `code` via coupon codes, but it does not explain `app_id` or fully define `code` beyond using `list_coupons` first.

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 and resource: show, hide, or schedule an existing coupon on public pricing pages via `listed` and optional `listed_from`. It also distinguishes the tool from broader coupon mutations by saying these are deliberately the only fields an agent can change on a live coupon.

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 explicitly says to use `list_coupons` first to see codes and current visibility, and it defines operative conditions such as existing coupons, human-gated writes, and dry-run behavior. It also names clear when-not cases: invite-only coupons are refused, and `listed_from` with `listed:false` is refused as contradictory.

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 flag destructive/non-idempotent/openWorld, and the description adds substantial context beyond them: at most one elicitation form per call, human-typed values override args, a declined stage leaves prior committed stages applied, Stripe prices only minted by the plans stage for existing paid tiers, and per-stage reversibility. This is exactly the extra behavioral detail annotations cannot express.

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-loaded with the purpose, then progressively discloses stage mechanics, overrides, failure modes, and prerequisites. It is dense but nearly every clause carries operational meaning; the only slack is the slightly rambling enumeration of configurable items in the opening sentence.

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 9-parameter, multi-stage, destructive wizard with no output schema, the description covers the call-return loop (returns next_call to continue), stage ordering, and human-gating, which is what an agent needs to drive it. The remaining gap is the unexplained `tier`/`domain`/`coupon_code`/`discount_percent` args and no detail on what overview/finish recon returns.

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 carry the load, and it does for the important ones: the `stage` enum values and their purpose, `price_suggestions` ('pass price_suggestions from market research to seed defaults'), `faq_drafts` as seeds, and `dry_run` echoing the form with no writes. However `tier`, `domain`, `coupon_code`, and `discount_percent` are never explained, so a caller still has to guess how those args map to form fields.

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 ('guided, stage-chained wizard that configures an app's hosted pricing page end to end') and enumerates exactly what it configures (plans, coupon, branding, FAQ, theme). It also explicitly carves out what it does NOT do ('Testimonials are NOT configurable here'), which separates it from sibling coupon/plan tools.

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?

Gives explicit routing: 'Use list_apps first for app_id', run stages in order (overview -> plans -> coupon -> branding -> content -> finish), use dry_run to preview, and after plan changes run `bun run plans:sync`. It names alternatives and preconditions (standalone tools for reversing effects, form stages refused on clients without elicitation).

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?

Goes well past the annotations by disclosing a human-gated elicitation requirement, that non-elicitation clients are refused while dry_run still works, that the human reviews a per-tier before->after diff, and that the multi-tier write is atomic. It also documents the -1 unlimited convention and the exact blast radius (limits object only).

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 WRITE/human-gated warning before the mechanics, and nearly every sentence carries a distinct fact (guardrail, atomicity, -1, blast radius, alternative, sync step). It is dense but runs long; the alternatives and post-sync instructions could be tightened without losing meaning.

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?

Appropriately complete for a destructive, nested-object write with no output schema: safety gate, scope, sentinel value, and follow-up step are all covered. The one omission is what merge versus replace actually does to existing limit keys, which matters given destructiveHint=true.

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?

With 0% schema description coverage and a nested `updates` object, the description carries the burden and mostly delivers: tier-keyed structure, key->number shape via the example, -1 semantics, and dry_run behavior. The `mode` enum (merge vs replace) is never explained anywhere, which is a real gap for a destructive write.

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 (change usage limits on an app's existing tiers) and immediately anchors it with a concrete example (set ai_generations_daily to 200 on pro). It also draws a hard boundary against adjacent operations — 'this writes ONLY the limits object: it never touches Stripe, prices, or plan names' — so it is unmistakable versus update_plan_pricing or create_app_kit.

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?

Explicitly routes alternatives: changing prices or adding a tier is 'a different job: use create_app_kit or the dashboard.' It also names a preview path (dry_run), and gives a required post-condition (run `bun run plans:sync` and commit plans.json).

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?

Goes well beyond the annotations: it discloses human gating with a before -> after diff, the no-elicitation pass-through case and why it is safe (never reaches Stripe, no amounts/limits/billing model changes), reversibility, and the non-obvious write behavior that setting a flag false deletes the key rather than storing false. It also mentions the exported plans.json side effect that must be regenerated.

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-loaded with the core action and structured with the write-safety details following. It is on the long side, and the parenthetical about the "gold/carbon BEST VALUE card with the rainbow title and app icon" is more color than an agent needs, but nearly every other sentence carries actionable 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?

Mutation tool with no output schema and an undefined dry_run parameter, but the description compensates with approval flow, side effects, reversibility and the sync follow-up. The omission of dry_run semantics is the one thing an agent might need before calling it correctly.

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%, so the description carries the burden. It meaningfully covers name, tier (as a slug sourced from list_plans), is_elite and recommended, including their values and side effects. But app_id is only implied and dry_run is never mentioned at all, leaving a meaningful gap for a 6-parameter mutation tool.

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 plus the exact fields touched: display name and the two badge flags. It clearly separates itself from the pricing/limits siblings by framing this as display metadata used by the public pricing page, and even explains that the page reads the flag rather than the slug.

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?

Gives explicit when-to-use ("Use this to repair that" when a top tier lacks is_elite), explicit prerequisites ("Use list_plans first for tier slugs and current flags"), and an explicit follow-up (run `bun run plans:sync`). It also warns that the tool does not clear flags from siblings, so a second call is required to move a badge.

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?

Far exceeds what annotations disclose: explains the human-gated elicitation flow, that typed values override arguments so the model cannot move a price alone, that clients without elicitation are refused, Stripe price immutability (mints a new price, old subscribers keep theirs), and that switching to one_time clears recurring price ids. This is rich, non-obvious behavioral context.

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-loaded with the core action, then layered with the gating, immutability, and cleanup consequences. Dense but each clause carries real meaning; only minor tightening possible.

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 destructive, human-gated write with no output schema, it covers the critical unknowns: override semantics, refusals, subscriber impact, side effects, and the post-write plans:sync step. Nothing an agent needs to invoke it correctly 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?

Schema coverage is 0%, so the description must compensate. It clarifies the tier, amount, and billing model concepts and implies dry_run preview, but does not map fields like amount_cents vs monthly_amount_cents or explain the nested updates array, leaving some parameter 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?

States a specific verb and resource ("Change what an app's EXISTING tiers charge") plus the two changeable dimensions (amount, billing model). It implicitly distinguishes itself from siblings like update_plan_limits and update_plan_meta by naming what it does and does not touch.

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?

Explicitly says to run list_plans first for tier slugs and current amounts, and states which tiers are refused (free, contact, payg) with a reason (catalog change, not reprice). It also notes dry_run works everywhere, giving clear when/when-not guidance.

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