Cred

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

With no annotations, the description carries the full disclosure burden and does it well: 1 CRD per call charged even on rejection, but a 429 RATE_LIMITED costs nothing. It also lists the 400 error codes (ALREADY_REFERRED, SELF_REFERRAL, INVALID_REFERRAL_CODE, program inactive), the one-referral-per-program rule, the replay/idempotency semantics, and the request_id to quote for support.

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 effect, then parameters, then constraints, then cost and errors. The sentences are dense and occasionally crammed (parenthetical default and replay clauses), but nearly every clause carries operational 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?

No output schema exists, so the description takes on return semantics itself by naming the replayed flag and the shape of error results including request_id. For a 7-parameter mutation with billing implications, this covers cost, idempotency, limits, failure modes, and the deferral workflow.

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 already 100%, yet the description adds real meaning: credit_type_id determines which program pays and defaults to the project default program, and defer_referrer_credits changes payout timing rather than just being a boolean flag. It also explains that a retry with the same code replays with replayed: true. It does not touch api_key, project_id, or x402_payment, but those are self-explanatory from the 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 ('Apply a referral code for a referred user') plus the effect: issuing configured credits to referee and referrer. It also distinguishes the sibling complete_referral by explaining that the referral stays pending until that tool pays the referrer.

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 clear context for the two optional parameters: credit_type_id selects the program (defaulting to the project default) and defer_referrer_credits pays only the referee now. It names complete_referral as the follow-up but never states when to use generate_referral_code or list_referrals instead, so the sibling routing is implied rather than explicit.

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

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

With no annotations, the description carries the full behavioral burden and does so well: partial-failure semantics ('a bad row does not fail the batch'), per-row errors, count returns, request_id for support escalation, and precise billing rules including the 429 exception. Row-level override precedence for signup_url is also disclosed.

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 tight sentences, each carrying distinct information, with the purpose front-loaded. The signup_url override sentence is mild duplication of the schema and slightly interrupts the flow, keeping it off a 5.

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 upsert tool with no output schema, the description usefully explains the return shape (created/updated counts plus per-row errors) and the failure economics. The one meaningful gap is the upsert key: it never says whether existing rows are matched on external_id, which determines create-vs-update behavior.

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 100%, so the schema already documents the credential params, x402_payment, and the row-level fields. The description's only parameter-adjacent claim (row signup_url overrides the request-level default) restates what the schema already says, so it adds little beyond structured data.

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 with scope: 'Create or update up to 1000 users in one call (one CRD for the batch)'. This clearly separates it from the single-record create_user/update_user siblings without opening their schemas.

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 batch size and the 'upsert many rows' framing make the when-to-use context obvious, and the CRD-cost note gives an economic reason to prefer batching. It never names the singular alternatives or states when not to use it, so it stops 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?

With no annotations supplied, the description carries the full burden and does well: it discloses that the first call deliberately returns the PaymentRequired object inside an error result (a genuinely surprising behavior), that no API key is required because the payment is the credential, and that no CRD is spent. It does not state what happens if payment succeeds but crediting fails, or whether a repeated payment payload is idempotent, which matters for a money-moving 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?

Three sentences, front-loaded with the risk warning, then the call sequence, then the auth/cost facts. Every clause carries information an agent needs to avoid a failed or duplicated payment; there is 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?

For a 7-parameter, no-annotation, no-output-schema money-movement tool, the description covers the essentials: the two-phase handshake, the unusual error-shaped first response, credential model, and cost. Remaining gaps (success payload shape, failure semantics) are modest relative to the high schema coverage.

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 100%, so the baseline is 3; the description earns above that by explaining the semantics of x402_payment as a base64 payload produced after signing the requirements from the first call, which is more than the schema's one-line description conveys. It adds nothing about buyer_id/buyer_name/buyer_email, but those are already self-documenting in the 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?

The description opens with a specific verb and resource ("buy a project's credits") and immediately qualifies the mechanism ("paying in stablecoin over x402"), which cleanly separates it from siblings like issue_credits, deduct_credits, and redeem_credits that move credits without a stablecoin payment. The "MOVES MONEY" prefix makes the operation class unmistakable at a glance.

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 two-step usage protocol: call once without x402_payment to obtain requirements, sign, then call again with the base64 payload. That is unusually actionable. It stops short of naming alternatives (e.g., when to use issue_credits or redeem_credits instead), so it is not a full when/when-not routing statement.

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

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

With no annotations, the description carries the full burden and does so well: credits already issued survive a period-end cancel, immediate cancel has no refund, each call costs 1 CRD even if rejected, a 429 costs nothing, and errors return a request_id to quote to support. These are exactly the side-effect and cost facts an agent needs before a destructive 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?

Four tight sentences, front-loaded with the default behavior, then the override, then the alternate targeting mode, then cost/error handling. No filler and no repetition of schema 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 destructive, credit-charging tool with no annotations and no output schema, the description covers cost, refund policy, and error handling thoroughly. It stops short of describing the success response or stating the identifier requirement explicitly, which keeps it from a 5.

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 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it states at_period_end defaults to true, and that user_id/email are alternatives to subscription_id that fan out to all live subscriptions. It does not state that at least one identifier is required, which is the remaining 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?

Opens with a specific verb+resource ('Cancel a subscription') and immediately distinguishes itself from list_subscriptions and update_subscription_quantity by describing the cancellation modes. An agent can identify the tool's job without opening the 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?

Explains the default path (period-end cancel) versus the at_period_end:false path, and clarifies that user_id/email targets every live subscription of a customer rather than one. It does not explicitly name sibling tools to prefer instead, but the parameter-selection guidance is clear enough to route correctly.

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

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

With no annotations, the description carries the full burden and does so: it discloses that the operation is terminal ('409 HOLD_NOT_ACTIVE if already settled'), that the uncaptured remainder returns to the holder, that the recipient may be created if new, and that it costs 1 CRD even when rejected while a 429 is free. It also lists the specific error codes and tells the agent to quote request_id to support, which is unusually complete behavioral disclosure for an irreversible settlement.

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?

Every sentence carries load: settlement outcome first, then the amount/remainder rule, then recipient routing, then failure codes, then cost model, then support guidance. No repetition of the tool name and no filler, despite the density of parenthetical detail.

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 mutation tool with no annotations and no output schema, the description covers side effects, cost, failure modes, and the destination of captured credits. The main residual gap is the shape of a successful response (aside from the request_id on errors), which an agent must discover on its own.

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 78%, so the baseline is 3, and the description earns above that by clarifying that amount defaults to the full hold and that the residual flows back to the holder, plus that to_user_id/to_user_email route captured credits to a possibly-new recipient. It adds nothing about reason, metadata, or when x402_payment is required (the schema covers api_key and project_id).

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 opens with a specific verb+resource ('Settle a hold') and immediately pins down the resulting state ('status captured'), which is enough to separate it from release_escrow_hold or list_escrow_holds. It never names those siblings explicitly, so an agent must infer the boundary from the settle-vs-release wording rather than being routed.

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 spells out the two operating modes and the condition that selects each: pass to_user_id/to_user_email for marketplace/P2P settlement, omit them and the capture 'stays deducted (settled to the platform).' That is clear usage context, but there is no exclusion or alternative named (e.g. when to release instead of capture).

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

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

With no annotations provided, the description carries the full burden and mostly succeeds: it discloses non-destructive idempotency semantics (replayed: true), the full outcome/status matrix (200/202/402), the named error codes, per-call cost (1 CRD, charged even on rejection, free on 429), and the request_id support path. It does not say whether the charge is reversible/refundable or what auth scope the API key needs, which keeps it from the top mark.

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 critical fact (MOVES MONEY) and packed with semicolon-separated clauses; there is no filler or repetition. It is somewhat cramped and would scan faster as a short outcome list, but every sentence carries operational 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?

For a money-moving mutation with no annotations, no output schema, and seven parameters, the description covers outcomes, error recovery, cost, and idempotency well enough to call it correctly. Gaps remaining are refundability and the exact meaning of the returned credits/new_balance payload, which matter but are secondary.

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 100%, so the schema already explains every parameter including the detailed idempotency_key contract. The description reinforces required-ness of idempotency_key and constrains pricing_tier_id to a one-time tier, but adds little beyond the schema — an appropriate baseline 3.

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?

"MOVES MONEY: charge a user's saved card off-session for one pack of a one-time pricing tier and credit it" gives a specific verb (charge), a specific resource (saved card, off-session), and the exact effect (credits granted). It plainly distinguishes the tool from checkout-based siblings like create_checkout_session and buy_credits_x402.

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 the conditions of use precisely: retries must reuse the SAME key, a 202 must be re-polled with the same key and never a new one, and a 402 with requires_action routes the agent to a checkout flow instead. These are explicit when/when-not rules tied to concrete status codes rather than general advice.

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

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

With no annotations, the description carries the full burden and does so: idempotency keyed per referral, already_completed true on repeat, 404 NO_REFERRAL, 1 CRD charge incurred even on rejected calls with a 429 exemption, and request_id in errors for support escalation. Cost and failure-charging semantics are exactly the kind of detail an agent cannot infer elsewhere.

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 purpose, then identity semantics, then safety, then error/cost behavior in a tight telegraphic register. Every clause carries operational information; nothing is padding despite the density.

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 mutating, credit-charging tool with no annotations and no output schema, the description supplies cost model, idempotency, failure modes, and error-correlation guidance. An agent has everything needed to call it correctly and to handle rejections.

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 100%, so the schema already documents all five parameters, including api_key, project_id, and x402_payment. The description reinforces the important user_id semantics (referred user, not referrer) but adds nothing about credit_type_id or the x402 fallback flow beyond what the schema states, so baseline 3 applies.

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 specific verb and resource ('Pay the referrer of a referral') and scopes it to referrals created via defer_referrer_credits, which cleanly separates it from siblings like apply_referral or list_referrals. The clarification that user_id is the REFERRED user removes the main ambiguity an agent would have.

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 clearly conditions use on a prior defer_referrer_credits application and states that repeats are safe, which tells the agent it need not guard against double-calls. It stops short of naming a full alternative branch (e.g., what to do if no deferral exists beyond the 404), so it is strong but not a complete when/when-not map.

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

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

With no annotations, the description carries the full burden and does so well: nothing is charged until the buyer pays, credits are issued on payment completion, subscriptions are credited on every paid invoice, and an invalid redirect domain is silently swallowed with a fallback to Cred's default page. It also states the sk_live_ key requirement and that the tool is not CRD-metered. It omits rate limits, idempotency, and the error path when neither pricing option is supplied.

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 purpose and return values, then ordered into pricing, billing, card saving, redirects, and auth. It is dense and semicolon-heavy, and a few clauses (e.g. the parenthetical about default one_time) duplicate schema text, but nearly every sentence carries operational weight.

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 15-parameter mutation-shaped tool with no annotations and no output schema, the description covers the pricing model, billing semantics, redirect domain caveats, auth level, and metering behavior. The remaining gap is the failure mode when neither pricing_tier_id nor amount/credit_type_id is provided, and error handling generally.

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 100%, so the baseline is 3, but the description adds real cross-parameter meaning the schema cannot: tier × quantity vs amount + credit_type_id, that recurring requires a tier and a recurring/billing_type both setting, and that save_payment_method is one-time only. It explains how the pieces combine rather than restating individual field text.

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 specific verb and resource ("Create a Stripe Checkout link") plus the effect on the end user ("for an end user to buy credits") and the return values (checkout_url, session_id). That clearly separates it from siblings like create_subscription_portal_link, buy_credits_x402, and create_pricing_tier.

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 conditional guidance on which pricing path to take (pricing_tier_id × quantity vs credit_type_id + amount at exchange_rate), how billing=recurring differs from one_time, and when save_payment_method applies. It does not name an alternative sibling to use instead for out-of-scope cases, so it stops short of full when-not guidance.

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

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

With no annotations, the description carries the full burden and does so: it discloses the cost model (1 CRD per call, charged even on rejection, free on 429), the idempotency replay semantics including the 409 IDEMPOTENCY_KEY_REUSED case, the non-idempotent default, and the concrete error codes 400/404. This is exactly the behavioral context an agent needs before a mutating, billable 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?

Front-loaded with the core action and the follow-up tools, then layered with idempotency, errors, and cost. Every sentence carries information, though the density of error codes and pricing in one paragraph makes it slightly harder to scan than a bulleted structure would be.

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 12-parameter, billable mutation with no output schema and no annotations, the description covers the return value (hold_id, status, idempotent_replay), the lifecycle, failure modes, and cost. Nothing an agent needs to call this 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 83%, so the baseline is 3, but the description adds real meaning beyond the schema: it explains what a replay of idempotency_key returns, that expires_at governs when funds can be released back, and that reference_id is filterable in list_escrow_holds. It does not explain user_id vs user_email precedence or metadata, leaving a small 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?

Opens with a specific verb and resource ('Reserve credits: deducts amount from an existing user and parks it in a hold') and immediately names the terminal siblings capture_escrow_hold and release_escrow_hold, so the agent can place this tool in the escrow lifecycle 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?

Explicitly states the follow-up path ('Finish with capture_escrow_hold or release_escrow_hold'), the expiry escape hatch, and the exact condition for supplying idempotency_key ('anything an agent might retry') versus the consequence of omitting it. It also scopes x402_payment to a specific prior failure mode, which is genuine when-to-use guidance.

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

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

With no annotations, the description carries the full burden and does substantial work: it discloses the 1 CRD charge per call, that the charge applies even to rejected calls, that a 429 RATE_LIMITED is free, and that errors return a request_id to quote to support. It stops short of describing the successful response body and does not state idempotency or retry 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?

Front-loaded with the action, then value constraints, then cross-cutting cost and error behavior. Every sentence contributes a fact an agent would otherwise have to discover by failing a call; there is 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?

For an 11-parameter mutation with no annotations and no output schema, this covers the high-risk unknowns (cost, error shape, id semantics). The gap is the success response: with no output schema, the description should say what a created tier returns so the agent knows what to do with the result.

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 100%, so the baseline is 3, but the description adds genuine meaning the schema lacks: the price band (0 or 0.50–1.00 per credit, which is not expressible in the schema), the equivalence of omitting credit_type_ids and passing [], and the rejection of malformed or foreign ids.

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 specific verb+resource: 'Create a pricing tier'. Combined with the name, an agent can distinguish it cleanly from delete_pricing_tier, update_pricing_tier, and list_pricing_tiers without opening a 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?

Usage is only implied by the domain (creating a sellable credit tier). There is no explicit statement of when to use this versus update_pricing_tier or when a tier is the right model, and no stated prerequisites beyond the value constraints.

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

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

With no annotations supplied, the description carries the full behavioral burden and does so well: it discloses the 1 CRD per-call cost, that the charge applies even to rejected calls, the exception for 429 RATE_LIMITED, the ephemeral nature of the link, and that error results include a request_id to quote to support. This is exactly the cost/rate-limit/error context an agent cannot infer from structured fields.

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 action and resource, then flows, usage, identity, cost, and errors in priority order. Every sentence carries information, though the density of the cost/payment aside makes it slightly harder to scan than a formatted 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?

For an 8-parameter tool with zero required parameters and no output schema, the description covers cost, error handling, flow semantics, and subscriber identification. It leaves open what happens if no identifier (subscription_id, user_id, or email) is supplied, and never states that the return value is the portal URL itself.

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 already 88%, so the baseline is 3, but the description adds real meaning beyond it: it documents the default value of the 'flow' enum (payment_method_update) and explains that user_id/email resolve to the customer's most recent subscription rather than requiring subscription_id.

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 — 'Create a short-lived Stripe customer portal URL' — and immediately names the two supported flows with their outcomes, so an agent can distinguish this from siblings like list_subscriptions or cancel_subscription without opening the 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-use ('Mint it when the customer asks') plus an exclusion ('don't store it') and explains identity resolution ('With user_id/email, uses their most recent subscription'). It does not name a sibling tool to use instead for other subscription operations, which is the one gap.

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

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

With no annotations, the description carries the full load and does most of it well: 1 CRD per call charged even on rejection, 429 RATE_LIMITED costing nothing, first-touch signup attribution rules, the created:true signal, and request_id in errors for support escalation. It stops short of stating authentication requirements or whether a rejected call partially mutates state, which keeps it off a 5.

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?

Information-dense and front-loaded, with the create/upsert behavior first followed by attribution, cost, and error handling. The opening sentence packs lookup precedence into a parenthetical phrase, which is slightly harder to parse than a clean split, but no sentence is 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?

For a 10-parameter mutation tool with no annotations and no output schema, the description covers the costly and surprising behaviors (billing, error identity, attribution side effects, metadata field dropping is covered in schema). It does not describe the shape of the returned user object beyond created:true, which is a minor residual gap given no output schema exists.

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 100%, so the baseline is 3, but the description adds real meaning beyond the schema: the email-before-external_id dedupe precedence, and the signup_url fallback to the connection's x-app-origin header plus the rule that attribution is only written on new users or users lacking one. These are behavioral semantics the schema cannot express.

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 ('Create an end user') plus the upsert scope ('or return/update the existing one'), and explains the lookup order (email first, then external_id). This tells an agent it can rely on this tool for existing users too, which meaningfully separates it from update_user and bulk_create_users.

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 rather than stated: the idempotent email/external_id lookup tells the agent this is safe to call when unsure whether the user already exists. However, it never names alternatives such as bulk_create_users for multiple users or update_user for later modifications, so the agent must infer the boundary.

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

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

With no annotations, the description carries the full burden and does so thoroughly: 400 INSUFFICIENT_CREDITS means nothing was deducted, 404 USER_NOT_FOUND, replay returns the original transaction with idempotent_replay: true, auto_topup_triggered signals a saved-card purchase, and the 1 CRD per-call cost applies even on rejection except for 429. This is exactly the behavioral context an agent needs before a destructive spend.

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 action and identity resolution, then layers error semantics, idempotency, side effects, and cost in short, information-dense sentences. No filler; every clause conveys a distinct operational fact.

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 with no annotations and no output schema, the description covers the critical gaps: failure codes and their side effects, retry safety, auto top-up side effect, per-call cost, and request_id for support escalation. Nothing essential to calling 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 100%, so the baseline is 3; the description still adds value by stating the email-first resolution order and by linking reference_id to refund_credits ('also lets refund_credits find it'). The idempotency_key explanation largely restates the already-detailed schema text, keeping it from 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?

States a specific verb and resource ('Deduct (spend) credits from an existing user') plus the identity resolution order (user_email checked first, then user_id). This clearly separates it from siblings like issue_credits, refund_credits, and redeem_credits without needing to name them.

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 concrete operational guidance: pass idempotency_key on anything an agent might retry, and explains the consequence of omitting it ('every call deducts again'). It does not explicitly route to alternatives (e.g., use issue_credits to add balance), but the failure modes and retry policy cover the main decision points.

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

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

With no annotations, the description carries the full burden and does well: it discloses the return value (count deleted), a per-call cost of 1 CRD charged even on rejection, the 429 exception that costs nothing, and that errors carry a request_id to quote to support. It stops short of stating whether deletion is permanent/reversible or what permissions are required beyond the api_key in schema.

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 sentences, all load-bearing, with the primary action and its scope front-loaded before cost and error-handling details. No filler or repetition.

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, yet the description still names the return value, and it covers billing, error metadata, and the pause alternative. For a destructive single-purpose tool at full schema coverage, an agent has everything needed to call 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 100% and every parameter is already documented, including credit_type_id's 'omit to delete every rule' semantics. The description's restatement of that behavior adds reinforcement but no new meaning beyond the schema, so the baseline 3 applies.

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 (delete) and resource (auto top-up rule) plus the exact scoping variable (credit_type_id) and the omit-means-all behavior. An agent can distinguish it from save_auto_topup and get_auto_topup 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?

Gives both usage modes (single rule by credit_type_id vs. all rules when omitted) and names the explicit alternative for the adjacent intent: 'To pause instead, save_auto_topup with enabled: false.' The condition that selects the alternative is stated, not implied.

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

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

No annotations exist, and the description carries the full burden well: it discloses that deletion is permanent, the 404/409 error semantics, that force also destroys auto top-up rules, the 1 CRD charge incurred even on rejection, the 429 exemption, and that errors carry a request_id to quote to support. That is far beyond what a bare 'delete' would 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-loads the action and scope, then layers the 409/force path, the deactivation alternative, and cost/error behavior — every clause carries information an agent needs. No filler or restatement of the tool name.

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, credit-metered tool with no annotations and no output schema, the definition covers safety, error modes, cost, and the consent precondition. The only thin spot is the x402 re-payment flow, which the schema description already explains.

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 100%, so baseline is 3, but the description adds real policy meaning to force ('after the user confirms' — a consent gate not present in the schema) and clarifies what it destroys. It says nothing about the api_key, project_id, or x402_payment parameters, leaving the payment-recovery path undocumented in prose.

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 ('Permanently delete a pricing tier by id') plus scoping ('404 if not in this project'), and explicitly contrasts with the sibling update_pricing_tier deactivation path. An agent can distinguish it from list_pricing_tiers, create_pricing_tier and update_pricing_tier 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?

Gives explicit when-to-use and when-not-to guidance: deleting while auto top-up rules exist returns 409 and requires force: true after user confirmation, whereas deactivation (update_pricing_tier is_active: false) preserves history. The alternative, its trade-off, and the precondition for the destructive path are all named.

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

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

With no annotations, the description carries the full burden and does so: it discloses the downstream effects on charging and auto top-up, the no-op return shape, a per-call credit cost that is charged even on rejection, the 429 exception, and request_id in errors. That is materially more than 'delete' would imply.

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 sentences, front-loaded with the action and its effect, then return value, cost, and error handling in order of decision relevance. Every sentence carries operational information; nothing is repeated from the schema.

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 single-entity call with no annotations and no output schema, the description supplies the missing pieces: side effects, cost model, rate-limit exception, and error contract. An agent can call it and interpret the result without further documentation.

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 100% and each parameter is documented inline, including the x402 payment payload, so the baseline is 3. The description adds no parameter-level detail beyond the 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 ('Remove a user's saved card') and adds the mechanism ('detached in Stripe'), which distinguishes it from siblings like get_saved_payment_method and delete_auto_topup. No need to open the schema to know what it does.

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 context is conveyed through consequences: charge_saved_card and auto top-up stop working until a new card is saved, and the no-op case returns deleted: false. There's no explicit 'use X instead' routing to a sibling, but the blast radius is clear enough to decide when to call it.

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

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

With no annotations supplied, the description carries the full burden and does so: it discloses irreversibility and exactly which records are destroyed (balances, ledger, auto top-up rules), the 409 USER_HAS_HISTORY retention rule, the 404 case, a per-call 1 CRD charge that applies even on rejection while 429 is free, and that error results carry a request_id to quote to support.

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?

Six tight sentences, each carrying a distinct operational fact, with the identifier rule front-loaded and the error codes, cost model, and support workflow following in priority order. 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?

For an irreversible destructive tool with no annotations and no output schema, the definition supplies the failure modes, the cost model, the data-retention rule, and the support escalation path, leaving nothing an agent needs in order to call it safely or interpret a failure.

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 100%, so the baseline is 3; the description earns an extra point by explaining the precedence between user_email and external_id, which is not stated in the schema itself. The api_key, project_id, and x402_payment parameters are left entirely to their schema descriptions.

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 ("Delete an end user") plus the two identifiers used to target it, which unambiguously separates it from update_user, create_user, and delete_auto_topup among the siblings.

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 identification precedence (user_email checked first, external_id as fallback) and states the consequence of a user having swap history, so the agent knows when this call will be refused. It stops short of naming an alternative action for the history case.

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

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

With no annotations supplied, the description carries the full behavioral burden and does so thoroughly: it discloses the per-call cost of 1 CRD charged even on rejection, the 429 exception that costs nothing, the fee deduction, the idempotent_replay behavior, the 409 IDEMPOTENCY_KEY_REUSED condition, and the full set of error codes including 400 INSUFFICIENT_CREDITS, 404 USER_NOT_FOUND, and out-of-min/max bounds.

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?

Dense but front-loaded: the core swap mechanic comes first, followed by error codes, direction semantics, idempotency, and cost. Nearly every clause carries operational information, though the error-code enumeration and the support/request_id note make it longer than strictly needed for tool selection.

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, no-output-schema mutation tool, the description covers cost, failure modes, idempotency, and direction semantics well. What is left implicit is the success response shape (resulting balances, converted amount fields), which matters for a credit-moving operation when no output schema exists.

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 100%, so the baseline is 3, but the description genuinely adds meaning beyond the schema: it explains that reverse direction spends the target type at 1/rate, and it clarifies the idempotency_key contract (same key + same args replays, same key + different args is 409). The x402_payment parameter, though documented in schema, is not connected to the out-of-CRD scenario described in the text.

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 ('Swap a user's credits along a swap pair') and immediately defines the mechanics: deducts source_amount of the source type, credits the converted amount after fee in the target type. The mechanics inherently distinguish it from deduct_credits/issue_credits, but no sibling is named, so an agent must infer the routing rather than being told it.

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 clear usage context: when the pair is bidirectional, use direction='reverse' to spend the target type at 1/rate; otherwise the call fails with SWAP_NOT_BIDIRECTIONAL. It also tells the caller to supply an idempotency_key on retries. It stops short of explicit when-to-use-vs-alternative guidance (e.g. execute_swap vs deduct_credits), and states no prerequisites such as the user needing to exist.

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

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

With no annotations, the description carries the full burden and does so richly: it discloses the 1 CRD cost per call, that the charge applies even on rejection, that a 429 RATE_LIMITED is free, that the call is repeatable, that it may create a user, and that errors carry a request_id to quote to support. This is exactly the behavioral context an agent needs before invoking.

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 the core action, then cost, then error handling. Every clause adds decision-relevant information 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?

For a tool with no output schema and no annotations, the description covers cost, idempotency, side effects, and error handling well. It stops short of describing the return payload shape beyond 'referral code' and doesn't restate auth requirements, leaving a small 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?

Schema description coverage is 100%, so all four parameters are already documented, and the description adds essentially no per-parameter meaning beyond the implicit 'creates the user if needed' hint tied to user_id. Baseline 3 is appropriate when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Clear verb+resource ('Get a user's referral code') with an important qualifier that it generates one when absent and creates the user if needed. That get-or-create semantics differentiates it well from siblings like apply_referral or list_referrals, though it never explicitly names 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?

Usage is implied rather than stated: 'Safe to repeat' signals idempotency and the cost note implies a use-with-care posture, but there is no explicit when-to-use vs when-not guidance or named alternative such as list_referrals for viewing existing codes.

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

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

With no annotations at all, the description carries the full burden and does so well: it discloses the 1 CRD charge, that the charge applies even to rejected calls, the 429 RATE_LIMITED exception, and that errors return a request_id to quote to support. It also explains field meaning like disabled_reason being set when Cred disables a failing rule.

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 behavior, then costs, then error handling — a sensible ordering with no filler. It is dense and packs several ideas into one long sentence, but 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?

There is no output schema, yet the description enumerates the returned fields (threshold, enabled, max_per_day, charges_last_24h, last_status/last_error, disabled_reason) and mentions the saved card. Combined with billing and error behavior, an agent has everything needed to call and interpret this 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?

Schema coverage is 100%, so baseline is 3, but the description adds real meaning beyond the schema by defining the semantic effect of omitting credit_type_id (all rules returned) and the null case for the single-rule result. x402_payment and api_key handling are left to the 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 (get) and resource (auto top-up rule / saved card) and precisely distinguishes the two result shapes via credit_type_id. An agent can immediately tell this apart from siblings like save_auto_topup or delete_auto_topup.

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 branching on credit_type_id is spelled out explicitly, which tells the agent when to expect a single rule versus all rules. It does not name alternative tools (e.g. get_saved_payment_method) or state prerequisites such as needing an existing user, so it stops short of full 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.

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

With no annotations present, the description carries the full burden and does so: it discloses per-call cost (1 CRD), that rejected calls are still charged, that a 429 RATE_LIMITED is free, that an unknown user yields an empty balances array rather than an error, and that errors carry a request_id to quote to support. These are non-obvious billing, error, and rate-limit behaviors an agent could not derive from the schema.

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 tight sentences, front-loaded with the action and then the identification rule, followed by the two things most likely to trip an agent: empty-vs-error results and billing. No sentence is redundant and the parenthetical cost clarification is 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 a six-parameter, zero-required read tool with no output schema and no annotations, the description covers identification, the empty-result edge case, billing, rate limits, and error identifiers. It stops short of describing the shape of a returned balance entry or how credit_type_id filters the result, which are the remaining gaps.

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 100%, so all six parameters are already documented, including precedence markers "checked first" and "(fallback)". The description reinforces the email-first resolution rule and clarifies that the unknown-user case returns an empty array, but adds little semantic detail beyond what the schema already provides, so the baseline 3 applies.

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?

"Get a user's credit balance(s)" is a specific verb plus resource with clear scope, and the identification rules (email first, user_id fallback) sharpen what the call targets. It never names a sibling such as get_user_wallet or get_transactions, so an agent must infer the boundary between balance lookup and wallet/transaction lookups.

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 gives concrete usage mechanics for identity resolution (email is checked first, user_id is the external ID) and a conditional path for x402 payment, but it never states when to prefer this tool over get_user_wallet, get_transactions, or list_credit_types. Usage is implied by the resource name rather than explicitly routed.

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

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

With no annotations provided, the description carries the full burden and does so well: it discloses a per-call cost of 1 CRD charged even on rejection, that a 429 RATE_LIMITED is not charged, that errors return a request_id to quote to support, and that the payload can be null. These are exactly the operational traits an agent cannot get from the schema.

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 parameter selection, then cost/error mechanics — each sentence adds distinct information with 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?

There is no output schema, and the description compensates by naming the returned fields and the null case, plus billing and error/request_id behavior. The return description is a field list rather than a full shape, so an agent still infers the envelope, but nothing needed to call the tool 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 100%, so the baseline is 3, and the description earns an increment by explaining the semantics of credit_type_id — its default behavior when omitted and its null-result behavior — which the schema's one-line "Credit type whose program to read" does not convey. api_key, project_id, and x402_payment are left entirely to the 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?

Opens with a specific verb+resource ("Get a referral program's settings") and enumerates the returned fields (is_active, referrer/referee credits, credit type), which clearly separates it from the mutating save_referral_settings sibling. It stops short of naming the sibling or list_referrals explicitly, so differentiation is implied by the verb 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?

Gives precise selection logic for the main discriminator: pass credit_type_id to read that credit type's program, omit it for the project's default program, and expect null settings when a credit type has no program. It does not contrast this tool with adjacent siblings (list_referrals, generate_referral_code), so tool-level routing 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?

With no annotations, the description carries the full burden and delivers: cost of 1 CRD per call, that credits are consumed even on rejected calls, the 429 RATE_LIMITED exception, and that error results carry a request_id to quote to support. This is exactly the operational context an agent cannot get from the schema.

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 the return shape and nullity first, then provenance, then cost/error behavior. No filler; each clause carries distinct operational 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?

For a read tool with no output schema and no annotations, the description supplies the return fields, the empty case, the credit cost model, the rate-limit exception, and error payload conventions. Auth via api_key/x-api-key is already covered by the schema, so nothing an agent needs to call 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 100% and each of the four parameters is documented in the schema itself, so the baseline of 3 applies. The description only obliquely touches parameters — "for a user" maps to user_id and the CRD cost implies x402_payment — but adds no syntax or format detail beyond the 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 ("Get the card saved for a user") and enumerates the fields returned (brand, last4, expiry), including the null case. It is clearly separable from siblings like charge_saved_card and delete_saved_payment_method 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?

Provides the precondition needed to understand when this tool has data at all — the card must have been saved via create_checkout_session with save_payment_method: true — which implicitly routes the agent to that sibling when no card exists. There is no explicit when-not guidance, but the retrieval-only context makes it low-risk.

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

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

With no annotations, the description carries the burden well: it discloses billing behavior (1 CRD per call, charged even on rejection, 429 costs nothing) and error semantics (request_id to quote to support). It does not mention auth requirements or whether the call is read-only, though the metric list implies a read.

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, front-loaded sentences: what it returns, over what window, then cost and error policy. Every clause carries operational information an agent needs before spending credits; nothing is redundant.

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 no-output-schema analytics read, the description tells the agent what dimensions and measures come back, the default window, the cost and the error contract. Only auth expectations (api_key header alternative) and rate-limit limits themselves are left implicit, which the schema partially covers.

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 100%, so all four parameters are documented in the schema itself, and the description only restates the `days` semantics (default 30, 0 = all time) that the schema already contains. Nothing extra is added for api_key, project_id or x402_payment beyond what the schema says, so baseline 3 applies.

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 (signup attribution breakdown) plus the grouping dimension (per signup_host), the exact metrics returned (users, purchases, revenue) and the time window. No sibling tool in the list does analytics, so this is unambiguous and instantly distinguishable from the transaction/user CRUD siblings.

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 clear operating context: default window of 30 days, that 0 means all time, and the credit cost per call. It does not state when NOT to call it or any alternative tool, but no sibling offers comparable reporting, so there is little ambiguity left. The exclusion is minor rather than harmful.

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

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

With no annotations, this description carries the full burden and does substantial work: it discloses the per-call cost (1 CRD), that the charge applies even to a later rejection, that a 429 RATE_LIMITED is free, and that errors return a request_id to quote to support. It stops short of describing auth requirements or return record shape, which keeps it from a 5.

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, each front-loaded with a distinct concern: what it returns, how to filter/paginate, and the cost/error contract. Nothing is redundant and even the parenthetical about 429s earns its place as cost-clarifying detail.

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 eight-parameter, zero-required read tool with no output schema, the description covers the operation, filtering, pagination, billing behavior, and error handling contract. The remaining gap is the shape of a returned transaction, which the agent must discover empirically.

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 100%, so the baseline is 3; the description adds value by framing email and user_id as alternative ways to filter by user and by grouping limit/offset as pagination. It does not clarify the optional project_id or the x402_payment fallback flow beyond what the schema already says.

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 ledger transactions'), adds ordering ('newest first') and enumerates the transaction types (issue, deduct, refund). It is clearly distinct from mutation siblings like deduct_credits or issue_credits, though it never explicitly distinguishes itself from near-neighbors such as list_deposits.

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 practical usage context by naming the available filters (user via email or user_id, credit_type_id) and pagination controls, so an agent knows how to narrow a query. However, it never says when to choose this over list_deposits or get_balance, nor are prerequisites or exclusions 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?

With no annotations provided, the description carries the full burden and does so well: it discloses a 1 CRD cost per call, that the charge applies even to rejected calls, the 429 RATE_LIMITED exception where nothing is charged, the 404 USER_NOT_FOUND outcome for missing lookups, the result ordering (newest first), and that errors carry a request_id to quote to support. That is far more than the structured data supplies.

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 dense sentences, each earning its place, with the two modes front-loaded and cost/error behavior following. No filler, no restatement of the tool name, and the parenthetical error codes are compact rather than bloated.

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 read tool with zero annotations and no output schema, the description covers modes, ordering, filtering, cost, and error contract thoroughly. What remains thin is the shape of a returned user record and the auth/x402 path, though the latter is documented per-parameter in the schema.

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 100%, so the baseline is 3, but the description adds mode semantics the schema does not: that email/external_id select a single-record lookup rather than acting as filters, and that signup_host / signup_credit_type_id apply only to the list mode with newest-first ordering. It omits any mention of x402_payment or the api_key/project_id auth params, which the schema does cover.

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 opens with a specific verb and resource ('Look up one end user') and cleanly splits the tool into two modes: single-user lookup by email/external_id and a newest-first listing with filters. The purpose is unambiguous, but it never names a sibling (e.g. create_user, bulk_create_users) to sharpen the boundary, which keeps it just 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?

It states the concrete trigger for each mode: pass email or external_id to fetch one user, otherwise use signup_host / signup_credit_type_id to list. That is genuinely actionable routing guidance, but there are no exclusions or pointers to alternatives when the caller actually wants to create or mutate users.

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

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

With no annotations, the description carries the burden well: it discloses per-call pricing (1 CRD charged even on rejected calls), the exception for 429 RATE_LIMITED, and that errors carry a request_id to quote to support. It does not state auth requirements or what happens when the user has no wallet on file, which is the remaining 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: purpose first, then cost/error behavior. Nothing is repeated and no sentence 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?

For a lookup tool with no output schema, the description conveys the essential return fields and the billing/error surface. It stops short of explaining how the five optional identifiers resolve (which one is effectively required to find a user) or what a null/unset wallet result looks like.

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 100%, so every parameter is already documented, including email being checked first and x402_payment only following a PaymentRequired failure. The description adds no parameter-level meaning beyond the schema, so the baseline 3 applies.

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?

"Read the EVM address on file for an end user" gives a specific verb (read) and resource (stored wallet address), plus the extra returned state (verified, verified_at). It is clearly a read counterpart to set_user_wallet, but it never names that sibling, so the differentiation is left implicit.

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 inferable: call this to look up a user's stored wallet and its verification status. There is no explicit when-to-use/when-not guidance and no pointer to alternatives such as verify_wallet_signature or request_wallet_challenge for a wallet that is not yet verified.

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

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

With no annotations, the description carries the full burden and does: auto-creates missing users, replay returns the original transaction with idempotent_replay: true and mints/sends no second webhook, on-chain mint status is reported, and a 1 CRD fee is charged even on rejection except 429. It also discloses that errors carry a request_id for support escalation.

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 dense sentences, front-loaded with the core action and side effect, then idempotency, then on-chain/cost behavior, then error handling. No restated 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?

For a 14-parameter mutation tool with no annotations and no output schema, the description covers the critical behaviors: creation side effects, dedupe semantics, billing cost, and the shape of response/error fields. An agent could call this correctly and safely without reading anything else.

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 100%, so the baseline is 3; the description goes further by tying idempotency_key to a concrete retry policy and by naming the replay flag and mint behavior the parameter triggers. It does not explain x402_payment or project_id redundancy, leaving some multi-param interactions to the 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 (issue/add credits to a user) plus a non-obvious side effect (creates the user on email-first lookup). Against siblings like deduct_credits and refund_credits the direction of the credit movement is unambiguous.

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 for idempotency_key ("anything an agent might retry") and warns that omitting it re-issues on every call. It stops short of routing the agent to alternatives such as deduct_credits for negative movements or explaining the x402_payment retry path, which only appears in the schema.

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

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

With zero annotations the description carries the full behavioral burden and does so well: it discloses the 1 CRD cost per call, the unusual rule that cost is incurred even on rejection, the 429 RATE_LIMITED exception, and that errors return a request_id to quote to support. It also implies the endpoint is read-only and project-scoped by returning only active types.

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 action and returned fields, then cost model, then error handling — a logical order with no filler. It is dense and long-ish, but each clause (cost rule, 429 exception, request_id) conveys information an agent would otherwise get wrong.

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 by listing the returned fields in full, including on-chain fields. Combined with the cost and error behavior, an agent has everything needed to call it correctly and interpret the result.

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 100%, so api_key, project_id, and x402_payment are already documented in the schema. The description adds no parameter-level meaning beyond noting the id feeds credit_type_id elsewhere, which is usage context rather than parameter semantics. Baseline 3 applies.

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?

Names a specific verb+resource ('List the project's active credit types') and immediately enumerates the returned fields, so it is unmistakable versus siblings like list_pricing_tiers or list_subscriptions. The 'active' qualifier also scopes the result set precisely.

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 tells the agent why and when to call it: to obtain the id, which 'use the id as credit_type_id in other tools' makes actionable. It stops short of naming an alternative or a when-not condition, but for a discovery/list tool the usage context is clear.

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

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

With no annotations provided, the description carries the behavioral burden well: it discloses that the tool is read-only, that chain ingest writes the deposits, how statuses behave, that unattributed deposits are held, the 1 CRD cost per call including rejected calls, the 404 behavior, and request_id support escalation. It stops short of fully covering auth/rate-limit behavior, but the schema covers api_key and x402 details.

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 with the core purpose and then supplies error and cost details. The status enumeration is dense but each status meaning is useful; there is little wasted wording.

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 read-only listing tool without annotations or an output schema, the description covers the main behavioral risks: cost, errors, status semantics, and the read-only nature. Pagination and result shape are left to the schema or omitted, but overall it is complete enough to invoke 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 already 90%, so the baseline is 3. The description adds meaningful semantics beyond the schema by explaining the status values, the unattributed-deposit behavior, the 404 for unknown user filters, and the per-call cost.

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: list on-chain token deposits for the project, newest first. It is clear and scope-specific, but it does not explicitly differentiate from related siblings such as get_transactions or list_x402_receipts.

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 tool purpose and the status explanations, and the read-only note helps. However, there is no explicit guidance on when to choose this over get_transactions, list_x402_receipts, or other transaction-oriented tools.

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

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

With no annotations, the description carries the full burden and does well: it discloses the 1 CRD per-call cost, that cost is charged even on rejection, that a 429 RATE_LIMITED is free, and that error results carry a request_id to quote to support. It omits auth requirements and pagination behavior, keeping it short of a 5.

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 dense sentences, front-loaded with purpose and filters, then cost and error handling. No wasted wording.

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, no-output-schema, no-annotation tool, it covers purpose, filters, cost, and error handling well. The main gap is pagination semantics (limit/offset) and what 'total' represents.

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 67%, and the description adds semantic grouping by naming the filter dimensions (status, holder, reference_id), but it says nothing about limit/offset pagination or the x402_payment fallback, leaving those to the 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 ('List escrow holds'), plus ordering ('newest first') and a return aggregate ('with total'). The list verb cleanly separates it from the create/capture/release escrow siblings.

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?

Names the filterable dimensions (status, holder, reference_id), which implies when the tool is useful, but gives no explicit when-to-use/when-not guidance or pointers to sibling tools for related operations.

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

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

With no annotations supplied, the description carries the full burden and does so: it discloses cost ('1 CRD (platform credit) per call'), the non-obvious billing rule that a rejected call still bills while a 429 RATE_LIMITED is free, and the need to quote request_id from error results. These are exactly the operational facts an agent cannot infer from the schema.

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 dense sentences, front-loaded with purpose and ordering before the filter semantics and then cost/error handling. Every clause carries information not available in the structured fields; nothing is repeated from the schema.

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 compensates by describing the shape of key return fields (price as a dollar string, credit_type_ids and its [] meaning) as well as error behavior and billing. For a four-parameter read tool with payment-path complexity, 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 already 100%, so the baseline is 3, but the description adds genuine meaning: it explains the response-side semantics of credit_type_ids and what the empty array implies, and clarifies that credit_type_id expands matches to include all-type tiers, plus the UUID validation rule behind the 400.

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 active pricing tiers (credit packs)') plus two distinguishing traits: ordering ('cheapest first') and price format ('price is a dollar string'). Against siblings create_pricing_tier / update_pricing_tier / delete_pricing_tier, the 'list active' verb makes the read-only scope unambiguous.

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 concrete context for using the credit_type_id filter ('returns every tier purchasable for that type: tiers scoped to it plus tiers with []') and the 400 failure mode. It stops short of naming alternatives, e.g. list_credit_types for discovering the IDs you would pass here, so the routing to a sibling is left implicit.

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

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

With no annotations provided, the description carries the full burden and does real work: it discloses the 1 CRD per-call cost, that the charge applies even to rejected calls, the 429 RATE_LIMITED exemption, and that error results carry a request_id to quote to support. That is meaningful operational context an agent cannot get from the schema. It stops short of stating auth requirements or whether results are paginated, which is why it is not a 5.

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: purpose and filters first, cost model second, error-handling guidance last. No filler, no restatement of the tool name, and the most decision-relevant constraint (cost per call) is placed early.

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 read tool with zero annotations and no output schema, the description supplies the two things the structured data omits: billing behavior and error/request_id handling. Return shape and pagination semantics are the remaining gap, but with a full-coverage schema and the cost disclosure present, an agent has enough to call 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 description coverage is 100%, so every parameter is already documented, and the description adds only marginal meaning by glossing credit_type_id as the 'program' concept. It does not explain the relationship between referrer_email and referrer_user_id, nor how limit/offset interact for paging beyond what the schema says.

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 project's referrals') plus the three supported filter axes, so an agent immediately knows this is the read-side referral enumeration tool. It does not name the sibling tools it is distinct from (apply_referral, complete_referral, generate_referral_code), but the read-only listing framing separates it adequately.

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

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

The description implies when to use it via the filterable fields, and the cost warning implicitly discourages casual polling. However, there is no explicit guidance on when to prefer this over sibling listing tools or related referral tools, and no stated preconditions such as needing a project-scoped key.

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

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

With no annotations, the description carries real weight and mostly delivers: it discloses the 1 CRD cost per call, the notable rule that a rejected call still costs credits except on 429 RATE_LIMITED, the 100-row cap with no pagination mentioned, and that error payloads carry a request_id to quote to support. What it omits is auth/permission scope and confirmation that the operation is read-only, which would complete the picture on a credits-consuming endpoint.

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 opening clause leads with purpose, scope, and returned fields, and the following sentences each carry a distinct operational fact (status alias, cost model, error handling). It is dense and slightly parenthetical-heavy, but no sentence is redundant.

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 read tool with no output schema and no annotations, the description covers the things an agent cannot infer: result cap, billing side effect, and error recovery path. Missing pieces are minor but real — no note on pagination behavior beyond the 100 cap and no statement of the permission scope required to list subscriptions.

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 100%, so the baseline is 3; the description earns an increment by clarifying that status="active" is a convenience alias covering active, trialing and past_due rather than an exact Stripe status. It adds no meaning for email, user_id, project_id, or x402_payment, which are left entirely to the 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 ("List recurring credit subscriptions") and immediately enumerates the fields returned, so an agent knows exactly what this yields. The scope constraint "newest 100" and the filterable status field further pin it down, and it is unmistakably distinct from sibling mutators like cancel_subscription and update_subscription_quantity.

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 resource but never stated: there is no "use this when you need X" framing and no routing to alternatives such as get_transactions, get_users, or cancel_subscription. The only explicit conditional guidance is the status="active" mapping, which is about semantics rather than when to pick this tool.

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

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

With no annotations, the description carries the burden and does it well: it discloses the 1 CRD cost per call, that the charge applies even on rejection, that a 429 RATE_LIMITED is free, and that errors carry a request_id for support escalation. It omits return ordering/pagination behavior, which keeps it short of a 5.

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, no filler: payload fields first, filters second, cost/error behavior last. The parenthetical field list is dense but each item earns its place, and the cost caveat is stated precisely rather than hedged.

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 six-param read tool with no output schema, the description compensates by naming the returned fields and describing the billing and error contract, which is the information an agent most needs before spending credits. It stops short of covering result ordering, pagination, or what an inactive pair looks like, leaving minor gaps.

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 100%, so all six parameters are already documented, and the description only restates the source/target credit-type filters without adding format or semantics. include_inactive, api_key, project_id, and x402_payment are left entirely to the schema, which is appropriate but adds no extra 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?

States a specific verb and resource ("List credit swap pairs") and enumerates the fields returned, so an agent knows exactly what it gets back. It never names the sibling it pairs with (execute_swap) or says when to list vs. swap, so sibling differentiation is implied by the name 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?

"Optionally filter by source or target credit type" gives a light usage cue for the two filter params, and the cost warning implicitly discourages speculative calls. There is no explicit when-to-use/when-not guidance relative to execute_swap or list_credit_types, so usage is only implied.

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

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

With no annotations, the description carries the full burden and does substantial work: it discloses API-key auth, a 1 CRD per-call charge that applies even to rejected calls, the 429 exemption, and that errors return a request_id for support escalation. Missing are rate-limit specifics beyond the 429 note and whether the charge applies to repeated retries within a session.

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 dense sentences, front-loaded with purpose then billing/auth/error behavior, with parentheticals used efficiently for the 429 exemption. No sentence is 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?

For a 5-parameter read tool with no output schema and no annotations, the description covers auth, cost model, error path, ordering, and returned fields, which is close to sufficient. It stops short of describing pagination past the limit cap or the meaning of credits_granted values.

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 100%, including the non-obvious x402_payment payload, so the schema handles parameter meaning. The description's field list (kind, status, payer, amount_usd, transaction_hash, credits_granted, error) reads as return fields rather than parameter semantics, adding little beyond what the schema already documents.

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 this project's x402 stablecoin payments') plus an ordering ('newest first') and the returned fields, which differentiates it from generic siblings like get_transactions or list_deposits. It never names a sibling alternative explicitly, so the boundary is inferred 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?

Usage context is implied by the resource scope (x402 payment receipts for this project), and the cost/auth notes give surrounding context, but there is no explicit 'use this instead of X' guidance or a stated when-not condition. An agent must infer that this is the receipt-history counterpart to get_transactions.

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

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

With no annotations, the description carries the full burden and does so well: it discloses cumulative cost (1 CRD per call, charged even on rejection), the 429 exception that costs nothing, the 400 REDIRECT_NOT_ALLOWED failure mode, the reusability of an existing account, and the request_id in error results. This is exactly the behavioral context an agent needs before a billed mutation.

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 dense sentences, front-loaded with purpose, then integration hint, then constraints and cost. Nothing is padded and the highest-value operational facts (redirect rules, CRD charge) appear before any conditional edge cases.

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 by naming both key returns (onboarding URL and acct_… stripe_account_id). For a billed, error-prone onboarding mutation with 8 parameters, it covers requirements, cost, failure modes, and downstream usage without meaningful gaps.

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 100%, so the baseline is 3, but the description adds real constraints beyond the schema for return_url and refresh_url (must be https on a Cred host or an allowed redirect domain, or the call fails with 400). It also implies why user_id/user_email matter by describing the account as tied to an end user, though it does not disambiguate user_id vs user_email usage.

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 opens with a precise verb+resource+outcome: "Create (or reuse) a Stripe Express connected account for an end user and return an onboarding URL." It distinguishes the tool from nearby siblings like create_user or redeem_credits by naming the downstream handoff (stripe_account_id as destination for redeem_credits).

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 clearly states what the tool produces and how to use the result with redeem_credits, and gives the redirect-URL prerequisites (https on a Cred host or an allowed redirect domain). It stops short of naming an explicit alternative or a "do not use when" condition, so it is strong context rather than full routing guidance.

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

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

With no annotations, the description carries the full burden and does so thoroughly: exchange-rate mechanics that cannot be overridden, exactly what idempotency does (including the fallback where reference_id becomes the key and the case where neither exists so every call redeems again), the 502 PAYOUT_PENDING recovery path with the ~15 minute reconciliation sweep, and the 1 CRD per-call cost that is charged even on rejection while a 429 is free.

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 critical "MOVES MONEY" warning and organized around prerequisites, idempotency, recovery, and errors. It is dense and near run-on in the middle sentence, but essentially every clause carries operational information an agent needs before calling.

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 13-parameter money-movement tool with no annotations and no output schema, the description covers prerequisites, idempotency, failure recovery, cost model, and the full error taxonomy, which is as complete as an agent needs to invoke 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 coverage is 100%, so baseline would be 3, but the description adds real meaning beyond the schema: the fixed exchange rate for `amount`, the restriction that `destination` must be the user's own onboarded account, and the non-obvious interaction between `idempotency_key`, `reference_id`, and repeat redemptions.

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 specific verb and resource - "cash out a user's credits as a Stripe transfer to a connected account" - and immediately signals the money-moving nature. It is clearly distinguishable from sibling read/write tools like deduct_credits, refund_credits, issue_credits, and onboard_payout_account, which the destination constraint explicitly references.

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?

Prerequisites are stated concretely: the credit type must be redeemable, destination must be this user's own account from onboard_payout_account, and idempotency_key should be a fresh UUID per intended operation. It stops short of an explicit "use X instead when Y" comparison against siblings such as deduct_credits or refund_credits, leaving that routing 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?

With no annotations supplied, the description carries the full burden and does so: it flags money movement in caps, discloses the 1 CRD per-call cost that is charged even on rejection (but not on 429), explains idempotent_replay semantics on retry, and enumerates the failure modes with status codes and their side effects (e.g. 402 STRIPE_REFUND_FAILED = no credits changed). This is exactly the behavioral context an agent needs before invoking a destructive billing operation.

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

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

It is front-loaded with the highest-stakes information ('MOVES MONEY') and organized by mode, cost, and errors. The error-code run is dense but each entry adds actionable signal rather than padding; a slightly tighter grouping of the 404/409/400 family would improve scanability.

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 12-parameter, high-risk financial tool with no annotations and no output schema, the description covers purpose, source selection, cost, idempotency, and error recovery including quoting request_id to support. Nothing an agent needs to call this correctly or interpret a failure 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 100%, so the baseline is 3, but the description adds meaning the schema cannot express: the mutual-exclusivity constraint on source parameters, the 'default: all' semantics of amount, and the clarification that reference_id targets the latest matching transaction. Minor gap: reason, metadata, project_id, api_key, and x402_payment are left entirely to their schema descriptions.

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 opening 'Refund or reverse credits' pairs a specific verb with the resource, and the following sentences enumerate the two distinct modes (purchase refund vs. ledger reversal) with the exact parameters that select each. An agent can distinguish this from sibling mutators like deduct_credits, issue_credits, and redeem_credits 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?

The description states the selection rule outright: 'Pass exactly one source,' then explains what each source does (purchase_id/stripe_payment_intent_id refunds the Stripe charge; transaction_id/reference_id reverses a ledger entry). It also specifies the exclusion behavior for reference_id ('latest matching transaction') and the partial-refund mode via amount, leaving no ambiguity about when to pick which path.

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

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

No annotations are supplied, so the description carries the full behavioral burden. It does well on error semantics and cost (1 CRD per call, charged even on rejection, 429 free, request_id in errors), but omits what the response contains, whether a release is reversible, and any auth/permission requirements — significant gaps for a mutating financial operation with zero 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?

Front-loaded with the action and resulting state, then error outcomes, then cost, then support guidance. Every sentence carries distinct operational information and nothing is repeated from the schema.

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?

Handles errors and billing well for a five-parameter mutating tool with no annotations and no output schema. It still leaves the agent guessing about the return payload, auth requirements, and how to obtain a valid hold_id, so it is adequate rather than 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 description coverage is 80%, so most parameters are self-documenting and the baseline is 3. The description adds no meaning beyond the schema — it never explains what 'reason' is for, how hold_id should be sourced (list_escrow_holds is not mentioned), or when to supply x402_payment.

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 (release), resource (a held escrow hold), and resulting state (status released), plus that it is a full release back to the holder. That last detail implicitly separates it from capture_escrow_hold, but the sibling is never named, so the agent must infer the contrast.

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 useful negative guidance — a retry after success returns 409 HOLD_NOT_ACTIVE — which tells the agent not to retry blindly. It never says when to prefer this over capture_escrow_hold or cancel paths, and does not state prerequisites such as an active hold being required before calling.

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

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

With no annotations supplied, the description carries the full burden and does so well: single-use semantics, a ten-minute expiry, a requirement to display the message unmodified, a 1 CRD cost charged even on rejection, the 429 exemption, and request_id in error results for support. These are exactly the operational facts an agent cannot infer from the schema.

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?

Five short sentences, front-loaded with the purpose and the step ordering, then progressively disclosing constraints, cost, and error handling. Nothing is redundant and no sentence could be dropped without losing a fact the 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?

There is no output schema, and the description implies but never enumerates the success payload (message text, nonce, expiry field). For a six-parameter mutation-adjacent tool the behavioral coverage is strong, but the exact success response shape 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?

Schema coverage is 100%, so each parameter is already documented, and the description adds no field-level meaning beyond the implied 'nonce' output. Baseline 3 is appropriate since the schema does the heavy lifting and the description only reinforces the signing flow.

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 ('get a single-use message for them to sign') and frames it explicitly as the first half of a two-step flow, which cleanly distinguishes it from the sibling verify_wallet_signature. An agent knows exactly what this returns without opening the 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 sequences the call: 'Step 1 ... Then call verify_wallet_signature with the nonce and the signature their wallet produces.' It also names the escape hatch (x402_payment) via the schema and the 429 no-charge case, so the agent knows both the next step and the failure branches.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the 1 CRD cost charged even on rejection, that a 429 costs nothing, that saving clears a failure-disabled rule, that a warning is returned when no card exists, the 404 USER_NOT_FOUND case, and that error results include a request_id to quote to support. These are exactly the side effects and failure modes an agent needs before calling a mutation.

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?

Dense but front-loaded: the upsert action and its trigger condition come first, followed by constraints, cost, and error handling. A few clauses are compressed to the point of ambiguity (e.g. 'clears a rule cred disabled after failures'), which slightly hurts readability without wasting words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 9-parameter mutation with no annotations and no output schema, the description covers cost, immediate side effects, preconditions, warnings, error codes, and remediation (request_id, x402 fallback context). Nothing an agent needs to invoke it safely 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 100%, so the baseline is 3, but the description adds behavior-linked meaning: max_per_day is framed as an at-most charge cap per 24h, threshold as the deduct-triggered floor, and pricing_tier_id as one pack that must not be recurring-only. credit_type_id is only obliquely covered via '(user, credit type)', so it is not a full 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?

States a specific verb+resource with scope: 'Create or replace the auto top-up rule for (user, credit type)'. The upsert semantics are explicit, which cleanly separates it from get_auto_topup and delete_auto_topup in the sibling list.

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 concrete prerequisites for use (saved card required, tier must not be recurring-only) and describes the immediate-charge behavior when enabled with a balance already below threshold. It does not explicitly route to siblings (e.g. get_auto_topup to inspect first, delete_auto_topup to remove), so it falls short of full alternative guidance.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the 1 CRD cost per call, that the charge applies even to rejected calls, that a 429 RATE_LIMITED is free, and that error results carry a request_id to quote to support. This is exactly the behavioral context an agent needs before invoking a paid mutation.

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?

Dense but front-loaded: purpose first, then the credit_type_id branch, then update semantics, then cost/error behavior. Every sentence carries operational information 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?

For a paid mutation with no annotations and no output schema, the description covers cost, error handling, and update semantics thoroughly. It stops short of describing what a successful response contains, which is a minor gap given no output schema exists.

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 100%, so baseline is 3, but the description adds real meaning beyond the schema: the credit_type_id vs default-program distinction and the create-if-needed behavior, plus the partial-update rule that governs all optional 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 pair (create or update) and resource (referral program) plus what the program contains (credits to referrer and referred user). It is clearly the write counterpart to get_referral_settings among the siblings.

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?

Explains the key branching condition: with credit_type_id it writes that credit type's program (creating if needed), without it the project default. It also clarifies partial-update semantics ('Only fields you pass change'). It does not explicitly name get_referral_settings as the read alternative, 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?

With no annotations supplied, the description carries the full burden and does so thoroughly: unproven assertion semantics, that changing the address clears prior verification, that only future deposits match, that detaching leaves balances untouched, and that 1 CRD is charged even on rejection except for 429 RATE_LIMITED. The error/request_id guidance is exactly the kind of operational detail an agent needs.

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, then layers semantics, edge cases, cost, and error handling in descending priority. Every sentence contributes a distinct fact; there is no restatement of the 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?

For a 6-parameter mutation with no annotations and no output schema, this covers nearly everything an agent needs: cost model, rejection behavior, verification invalidation, and detach semantics. The only gap is the success response shape and how the user is resolved when multiple identifiers are supplied.

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 100%, so the baseline is 3, but the description adds real meaning: wallet_address=null detaches and balances are unaffected, and the per-call CRD cost contextualizes the x402_payment escape hatch. It does not clarify the precedence among user_email/external_id (only the schema notes 'checked first'), leaving that to structured data.

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 ("Attach an EVM address to an end user") plus the downstream effect (on-chain credits mint to them). The clause "No signature required" implicitly separates it from the verify_wallet_signature / request_wallet_challenge siblings without the agent needing to open another 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 clear context for use (so on-chain credits mint to the user) and a distinct non-use case (the assertion path versus the signature-proof path), plus the detach case via null. It stops short of naming the sibling tools explicitly, so the agent must infer the alternatives from the 'no signature' contrast.

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

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

With no annotations supplied, the description carries the full burden and does so well: it discloses the 1 CRD cost per call, that the charge applies even on rejected calls, the 429 exemption, that partial updates leave untouched fields alone, and that errors return a request_id for support. This is exactly the behavioral context an agent cannot get from the schema.

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 dense sentences, front-loaded with the core action, then parameter shortcuts, then cost and error handling. Every clause carries operational information with no filler or repetition of the schema.

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 13-parameter mutation tool with no annotations and no output schema, the description covers cost, failure billing, error payloads, and partial-update semantics. It leaves minor gaps around auth via api_key/project_id and what the response contains, though the schema documents those 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?

Adds meaning beyond the 62%-covered schema for the highest-risk parameters: credit_type_ids semantics ('[] = all credit types') and is_active ('stop selling it without deleting'), plus the global 'only fields you pass change' rule that clarifies every optional field. It does not explain the remaining undocumented fields such as credits, currency, or is_popular.

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 ('Update a pricing tier by id') plus the partial-update rule, so the agent knows exactly what the tool does and how it differs from create/delete siblings. The phrase 'without deleting' implicitly contrasts it with delete_pricing_tier.

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 concrete when-to-use conditions for specific operations: pass credit_type_ids to re-scope, is_active: false to stop selling without deleting, and references create for price rules. It stops short of naming create_pricing_tier/delete_pricing_tier explicitly as alternatives for the agent to choose between.

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

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

With no annotations, the description carries the full burden and does so: it discloses the billing consequence (unit price × quantity from next renewal, unit credits × quantity), the absence of proration, and the 1 CRD cost charged even for rejected calls except 429 RATE_LIMITED. It also states that error results carry a request_id to quote to support — unusually complete behavioral disclosure for a mutation tool.

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

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

Front-loads the mutation and its billing impact, then identity resolution, then cost, then error handling. Every clause carries information an agent needs (price model, no-op case, credit cost, rate-limit exemption); nothing is redundant or 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?

For a financial, non-reversible-in-effect mutation with 7 params and no output schema, the description covers preconditions, cost, failure modes, and error payload hints well. The remaining gap is the success response shape (what fields come back after a quantity change), which the description leaves unstated.

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 100%, so the baseline is 3; the description adds genuine meaning beyond the schema by explaining that user_id/email are alternatives that require exactly one live subscription and that subscription_id is the escape hatch on 409. The x402_payment retry condition and the free-on-429 nuance are also only implicit in the schema text.

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 with scope: "Change a live subscription's quantity (seats/packs, 1–10000)." It is clearly distinguishable from siblings such as cancel_subscription, list_subscriptions, and update_pricing_tier 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?

Gives concrete conditional guidance: identify the customer via user_id/email only when exactly one live subscription exists, otherwise expect a 409 and pass subscription_id. It also flags that the same quantity is a no-op. It stops short of naming sibling tools to call for recovery (e.g., list_subscriptions) or of explicitly stating when to prefer this over other subscription tools.

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

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

With no annotations, the description carries the full burden and does so: PATCH-style partial semantics, a 400 NO_FIELDS_TO_UPDATE on empty calls, 404 USER_NOT_FOUND, 1 CRD cost charged even on rejection, 429 costing nothing, and request_id in errors for support escalation. It also discloses surprising mutation effects (metadata wholesale replace; referral_code/stripe_account_id preserved; silent drop of stripe_account_id outside Cred).

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 verb, resource, and lookup key, then the behavioral rules. It is dense with stacked parentheticals and semicolon-chained clauses, which costs some scannability, but essentially every clause carries operational 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?

For an 11-parameter mutation tool with no annotations and no output schema, the description covers cost, failure modes, field side effects, and the sibling alternative. It stops short of indicating what a successful response contains, which would round out the contract.

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 100%, so the baseline is 3, and the description adds real meaning beyond it: precedence of user_email over external_id, the metadata replacement rule and its two exceptions, and the fact that signup_* fields re-derive attribution/related fields. It does not explain x402_payment mechanics beyond the schema's own note, leaving a small 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 ('Update an existing end user') and immediately disambiguates the lookup key ('identify by user_email, checked first, or external_id'). It also distinguishes itself from sibling set_user_wallet, so an agent can route 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?

Explicitly redirects wallet changes to set_user_wallet and explains the intended use of signup_* fields ('use to correct it'). It lacks an explicit boundary against create_user/delete_user, but the 'existing end user' phrasing and the named alternative cover the main ambiguity.

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

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

With no annotations, the description carries the full burden and does well: it discloses the side effect (address stored and marked verified), the consumption of the nonce even on rejection, the per-call credit cost including on rejection, the 429 exemption, and that errors carry a request_id for support. The one gap is return shape on success (no output schema exists), which is only partially covered by 'the address is stored and marked verified'.

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 dense sentences, front-loaded with the action and outcome, then consequences and cost. No filler, and each clause (single-use, cost, 429 exemption, request_id) carries information an agent needs before calling.

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 7-parameter, no-annotation, no-output-schema mutation tool, the description covers preconditions, cost, nonce lifecycle, and error handling well. It stops short of describing what a successful response contains beyond the verification effect, which is the only material omission.

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 100%, so the schema already explains nonce provenance, the address guard, chain_id provenance, and when x402_payment applies; the description adds little field-level meaning beyond reinforcing that the signature is a personal_sign output. Baseline 3 is appropriate since the schema does the parameter work.

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 ('submit the personal_sign signature over the challenge message') plus the outcome ('the address is stored and marked verified'), and the 'Step 2' framing ties it to the challenge-issuing sibling rather than any credit/subscription tool. An agent can distinguish this from request_wallet_challenge and the rest of the sibling list without opening a 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?

Explicit about the precondition (a challenge nonce, obtained in step 1) and about the retry path: a challenge is single-use, a rejected signature consumes it too, so a retry requires a fresh challenge. It also gives the cost trade-off that determines whether a retry is worth making.

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

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

No annotations are supplied, so the description carries the full burden, and it does disclose two behaviors an agent genuinely needs: no credentials are required and the call costs no CRD. It also frames the tool as informational by describing exactly what metadata comes back. Minor gaps remain around rate limits, caching, and the shape of the returned price list.

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

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

Two sentences, front-loaded with the purpose, followed by the optional parameter's effect and the auth/cost guarantees. No redundant restatement of the tool name and nothing 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?

For a single-optional-parameter read tool with no output schema, the description covers purpose, parameter effect, auth requirements, and cost, and it enumerates the returned fields (scheme, network, asset, prices). It stops short of describing the structure of the per-project price list, which is the one thing left for the agent to discover at call time.

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 100%, so the baseline is 3, but the description adds real meaning beyond the schema: passing project_id switches the response from generic scheme/network data to that project's credit price list. That is an effect statement the bare schema text ('Project whose credits you want priced') does not convey.

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 gives a specific verb and resource ('Discover how to pay Cred with x402') and enumerates what is returned: accepted scheme, network, asset, and prices. That clearly separates it from the transactional sibling buy_credits_x402, though it never names that sibling explicitly, so an agent must infer the pairing.

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 rather than stated: this is the pre-flight discovery step before buying credits via x402, and the project_id note tells the agent how to get project-scoped pricing. There is no explicit 'use this before X, use Y to actually purchase' routing, and no stated exclusions, so it lands at implied-usage rather than true guidance.

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