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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is structured; the description nevertheless adds that execution is stateless and performs zero external Stripe mutations, which is real context beyond the annotations. It omits error/runtime behavior and any limits on execution time for large arrays, 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 sentences, front-loaded with the verb and scope, then behavior, then routing guidance. The enumerated return fields are long but earn their place since no output schema exists; only the list of scanned/derived counters borders on verbose.

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

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

With no output schema present, the description compensates by naming the structuredContent keys an agent will receive, and the schema already documents all five optional inputs including the omit-to-use-fixtures fallback. Combined with sibling routing, an agent has everything needed to invoke 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% and every parameter carries a detailed description with ranges and defaults (costPerEventCents 1-10000 default 142, dunningGracePeriodDays 0-14 default 3), so the schema does the heavy lifting. The description adds no additional parameter semantics beyond echoing those two field names in the return payload.

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 set ('Run a deterministic 90-day B2B revenue leakage and chargeback readiness audit across Stripe subscriptions, AI/API usage telemetry events, and open disputes'), including the exact data sources scanned. An agent can tell this apart from the single-customer and single-dispute siblings 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 scopes usage ('portfolio-wide multi-customer audits') and names two alternatives with the condition that selects each: revclamp_evaluate_ghost_usage for single-customer entitlement checks and revclamp_stage_stripe_dispute_ce3 for a single dispute's CE 3.0 bundle. Nothing is left to inference.

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

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

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false. The description adds useful behavioral context by stating the calculation is deterministic, uses exact integer USD cents, and returns structuredContent fields including statelessEphemeralAudit and calculation.

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 calculation and plan-fit purpose, then covers inputs and return fields in three efficient sentences. The output field list is justified because no output schema exists.

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

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

The input schema is fully described, annotations cover safety and idempotency, and because there is no output schema the description usefully enumerates the key returned structuredContent fields. Nothing essential for correct invocation appears 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 description coverage is 100%, so the schema already documents ranges, defaults, and tier thresholds for all four parameters. The description repeats the parameter names and their role in recommending a tier, but adds no parameter semantics beyond what the schema provides.

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: calculate monthly and annual B2B margin savings and recommend the optimal RevClamp plan tier. It distinguishes the tool from sibling audit/evaluate tools by focusing on ROI calculation and plan fit rather than leakage auditing or usage evaluation.

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

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

The description provides a clear usage context: replacing a 25%-30% contingency chargeback agency with RevClamp flat-rate plans. It does not explicitly name when-not to use it or name sibling alternatives, so it falls 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description wisely focuses on what annotations cannot express: fail-closed pagination semantics ('has_more must be explicitly false') and the 0-14 day dunning grace window that keeps past_due subscriptions entitled. It also enumerates the structuredContent return keys. Minor deduction because it restates 'stateless, read-only, zero side effects', which the annotations already declare.

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 evaluation purpose, then the fail-closed/dunning behavior, then the return shape and sibling routing. It is dense and jargon-heavy ('Stripe 2025-03-31.basil'), but nearly every clause carries operational meaning and nothing is padded.

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

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

With no output schema, the description compensates by listing the returned structuredContent keys (ok, mode, statelessEphemeralAudit, tenantId, evaluation fields). Combined with 100% schema coverage and rich annotations, an agent has enough to call it correctly; only the failure mode for a truncated page (error vs. ok=false) is left unspecified.

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 every parameter including defaults and ranges, making 3 the baseline. The description does add one cross-parameter constraint (raw arrays require subscriptionsHasMore=false to avoid truncation) and the 0-14 day grace window, but these largely restate what the individual field descriptions say.

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: evaluates whether one customer's AI/API usage event is 'unpaid ghost usage' against multi-subscription Stripe basil state. It also names its scope (per-customer, real-time) explicitly against the batch sibling revclamp_audit_revenue_leakage, so it is distinguishable 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?

The final sentence gives an explicit routing rule: 'use this tool for real-time per-customer entitlement gating; use revclamp_audit_revenue_leakage for batch multi-customer portfolio audits.' This is a direct when-to-use plus named alternative, which is exactly what an agent needs among nine revclamp siblings.

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

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

Annotations already establish read-only, idempotent, closed-world, non-destructive, so the description correctly spends its words elsewhere: it asserts determinism, that linting is non-destructive to merchant notes and markers, and enumerates the structuredContent keys returned. With no output schema present, that return-field disclosure carries real weight.

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 intent is front-loaded in the first clause, but the body is a single sprawling run-on sentence that ends in a 17-item comma-separated return-field list. It is dense rather than wasteful, yet the enumeration should have been a structured clause, hurting scannability.

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

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

Given no output schema and no annotations describing returns, the description supplies the verdict keys an agent needs to interpret results, plus the domain rule set. It stops short of explaining the preset/custom interaction and the relationship to the staging sibling, but nothing essential for 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, but the description adds genuine meaning: it clarifies the ceiling is measured as String.prototype.length (UTF-16 code units, not bytes), names the exact --- BEGIN/END REVCLAMP CE3 EVIDENCE --- delimiters the evidenceLogText must contain, and states the CE 3.0 '>= 2 prior charges + IP/device overlap' rule that governs priorMatchedCount/hasIpMatch/hasDeviceMatch.

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 (lint) and a precisely-scoped resource (Stripe dispute evidence[access_activity_log] payload), and enumerates exactly which checks it runs (UTF-16 ceiling, UTF-8 bytes, delimiters, note preservation, CE 3.0 qualification). It never distinguishes itself from the very similar sibling revclamp_stage_stripe_dispute_ce3, so an agent must open both schemas to know which to pick.

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

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

Usage is only implied: the checks listed make it obvious this is a pre-submission validation step. There is no explicit 'call this before X' guidance and no exclusion telling the agent when to prefer revclamp_stage_stripe_dispute_ce3 over this linter, which is the key routing 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety bar is lower; the description still adds real value by declaring the function pure/stateless with no floating-point drift and by enumerating the structuredContent fields returned. It stops short of describing preconditions (e.g. what inputs produce an error versus an ok=false reconciliation).

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 the arithmetic guarantee before the field enumeration; every sentence is informational. The long parenthetical list of return fields and modes is dense but earns its place given there is no output 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 stateless, read-only calculator with a fully documented 8-param schema, a complete annotation set, and no output schema, the description covers purpose, usage routing, computational semantics, and the shape of the response. An agent has everything needed to invoke it correctly and interpret the result envelope.

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%, with every parameter documented including ranges, defaults, and the singular/plural credit-note alias, so the schema carries the load. The description only reinforces the unit convention (integer cents, no floats) and adds no syntax or interaction rules beyond it. 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+resource: reconcile B2B wholesale Net-15/30/60 invoice deposits, partial payments, and credit notes, and adds the distinguishing trait of exact integer minor-unit arithmetic. It explicitly separates itself from the VAT sibling, so an agent can tell the two apart without opening 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?

States the intended use case ('B2B wholesale order deposit gating and Net-terms balance calculation') and routes the agent away to revclamp_validate_eu_vat_vies for VAT validation. It does not address the other seven siblings (disputes, ROI, ghost usage, webhooks), so the exclusion guidance is partial rather than complete.

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

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

Annotations already declare readOnlyHint/idempotentHint/non-destructive, so the bar is lower, but the description adds real behavioral context: deterministic evaluation, stateless ephemeral audit, and the specific bug classes detected (resurrected canceled subscriptions, stale downgrades, duplicate retry side-effects). It stops short of stating rate limits or cost, so 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?

Front-loaded with the core action and mechanism, and every clause carries substance. It is two very dense, long sentences, however, so it is packed rather than lean — slightly harder to scan than an ideal 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?

Although there is no output schema, the description enumerates the structuredContent fields (ok, mode, steps, finalStatus, naiveFinalStatus, naiveHandlerBug, etc.), so an agent knows both inputs and outputs. For a 4-param, read-only simulation tool this is complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3; the description still contributes by explaining the semantics behind the params — the dedup Set is keyed on eventId, the guard compares event.createdSec against lastAppliedCreatedSec, and it restates the window range/default and 1-10 event bound. That adds interpretive value beyond the field 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 (simulate/replay evaluation) and resource (webhook lifecycle event sequences) plus the exact mechanisms applied: idempotency dedup Set, configurable window, and monotonic timestamp guard. It also names the contrast target (naive overwrite-on-arrival handler), which makes the tool's role unmistakable versus siblings like verify_webhook_signature.

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 conveys the context (evaluating ordered/out-of-order webhook sequences against a dedup window) but never states when to choose this over revclamp_verify_webhook_signature or other siblings, and gives no explicit exclusions. Usage is implied rather than 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is pre-covered; the description adds real value by disclosing that submit is hardcoded to false, that nothing is auto-submitted to card networks, and that existing evidence text is merged append-only rather than overwritten. It also enumerates the returned structuredContent keys, compensating for the absent output schema, though it omits any failure/qualification-miss 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?

Three sentences, front-loaded with purpose then behavior then routing, so the agent gets the decision-relevant facts first. The opening sentence is dense with stacked qualifiers and could be split, but no sentence is padding.

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, nested-object tool with no output schema, the description supplies the qualification rule, the non-destructive guarantee, the submit=false safeguard, the return field list, and the sibling routing rule. Everything an agent needs to select and invoke it correctly is present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema description coverage the schema already documents each parameter; the description goes beyond it by stating the CE 3.0 qualification semantics that bind priorTransactions and disputedTransaction together (shared IP, device fingerprint, or billing email within the 120-365-day window). It does not clarify the interaction between usageEvents and existingUncategorizedText in the merge.

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 (evaluate + stage/assemble) and resource (Visa CE 3.0 qualification and Stripe dispute evidence draft), including the exact qualification rule (120-365-day charges, 2+ settled non-refunded non-disputed priors sharing IP/device/email). It explicitly distinguishes itself from revclamp_audit_revenue_leakage by scope (single dispute vs portfolio-wide counts).

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

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

Explicitly says 'Use this tool for single-dispute CE 3.0 qualification and evidence staging; use revclamp_audit_revenue_leakage for portfolio-wide dispute readiness counts' — a clear when-to-use plus one named alternative. It does not address the closely related sibling revclamp_lint_dispute_evidence, leaving one plausible alternative unpartitioned.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), and the description's restatement of read-only adds nothing. However it does add real behavioral context beyond annotations: deterministic simulation modes, LIVE SOAP/REST lookup against the European Commission, circuit-breaker hold behavior on MS_UNAVAILABLE, and stateless ephemeral audit records. It stops short of stating rate limits or failure/error behavior for LIVE calls.

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?

Purpose, behavior, return shape, and routing are front-loaded in a single dense paragraph with no filler sentences. It is long, and the field-by-field enumeration of structuredContent is somewhat list-heavy, but every clause carries information an agent needs.

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

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

For a read-only, four-parameter tool with full schema coverage and no output schema, the description supplies the return-field inventory and the mode semantics that the schema leaves implicit. The only missing piece is what LIVE lookup failure or VIES error responses look like, which matters given the MS_UNAVAILABLE circuit-breaker path.

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; the baseline is 3. The description adds only marginal semantic value, chiefly the mandatory GR to EL prefix normalization and the reverse-charge framing of viesMode, both of which the schema largely repeats.

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 specific verbs (normalize, evaluate) and the exact resource: EU-27/XI B2B VAT identifiers and reverse-charge/VIES eligibility. It explicitly routes the accounting case to revclamp_reconcile_b2b_net_terms, so an agent can separate it from that sibling without opening either schema.

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

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

Gives a direct use case sentence ('Use this tool for EU/XI VAT tax compliance') and names the alternative tool plus the condition that selects it (Net-15/30/60 deposit and credit-note accounting). The mode enum is also framed with when-to-use semantics (deterministic simulation vs LIVE lookup).

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

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

Beyond the annotations (which only declare readOnly/idempotent/non-destructive/closed-world), the description discloses the 300-second replay window guard, timingSafeEqual comparison, the Zero-Trust live-credential blocklist with the exact JSON-RPC error code -32602 LIVE_SECRET_FORBIDDEN_IN_SANDBOX, and the full set of structuredContent fields returned. That is substantial behavioral context an agent could not get 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?

The core purpose is front-loaded, but the opening sentence is a ~60-word run-on and the return-value enumeration is an undifferentiated comma-separated wall of 18 field names. Every element is arguably relevant, but the density makes it hard to scan for the one or two facts an agent needs at call time.

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

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

With no output schema, the description correctly compensates by enumerating the structuredContent return fields, and it covers modes, defaults, limits, error semantics, and replay tolerance. Only the boundary against the sibling replay-simulation tool is left unaddressed.

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 five parameters are already documented in the schema — including the live-secret rejection list and the generate-vs-verify mode for signatureHeader. The description mostly restates this (secret guard, header formats, 16,384-char payload cap) rather than adding new meaning, so it sits at the baseline for a fully-covered 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+resource (generate/verify HMAC-SHA256 webhook signature headers) across three named provider schemes, with the exact canonical header formats given. It is unambiguous what the tool does, but it never names or distinguishes itself from the adjacent sibling revclamp_simulate_webhook_replay, which an agent could easily confuse with this one.

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

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

"Use this tool to debug webhook signature mismatches and replay skew" gives a clear triggering context, and "Omit [signatureHeader] to run in GENERATE_AND_SELF_VERIFY mode" explains the two operating modes. However there are no exclusions and no routing to alternatives, notably the replay-simulation sibling, so the agent must infer boundaries.

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