RevClamp MCP Server

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false. The description adds substantive context beyond annotations: it is stateless and ephemeral, performs zero external Stripe mutations, and enumerates the structuredContent return fields so an agent knows what to expect.

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: purpose first, behavioral guarantees second, routing guidance third. The enumeration of return fields is long but earns its place because 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?

Complete for a stateless audit tool with no output schema: annotations cover safety, the input schema covers all parameters, and the description covers return fields and sibling routing. 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 description coverage is 100%, so the schema already documents all six parameters with types, ranges, defaults, and examples. The description does not add parameter-level semantics beyond the schema, so the baseline of 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 and resource: a deterministic 90-day B2B revenue leakage and chargeback readiness audit across Stripe subscriptions, usage telemetry, and disputes. It clearly distinguishes itself from the named sibling tools for single-customer checks and single-dispute evidence staging.

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

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

Explicitly says to use this tool for portfolio-wide multi-customer audits and names the alternatives: revclamp_evaluate_ghost_usage for single-customer entitlement checks and revclamp_stage_stripe_dispute_ce3 for a single dispute's Visa CE 3.0 evidence bundle. This gives clear when-to-use and when-to-use-something-else 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?

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 readOnly, idempotent, non-destructive, and closed-world behavior, so the redundancy of 'read-only... zero side effects' is minor. The description adds real value by disclosing statelessness, fail-closed pagination behavior (has_more must be explicitly false), and the exact structuredContent fields returned, which matters because there is no output 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?

Front-loaded with the core purpose and sibling routing, then return shape. It is dense but mostly earns its space; the only waste is slight repetition of read-only/no-side-effects already implied by annotations.

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 evaluator with nested subscription objects and no output schema, the description covers purpose, routing, pagination safety, dunning behavior, and return fields. It does not discuss authentication, Stripe API key requirements, or precise error behavior, but the critical invocation semantics are present.

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

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

Schema coverage is 100%, so the schema carries the field-level detail. The description still adds conceptual meaning: it frames subscriptions as multi-subscription basil state, explains the fail-closed purpose of subscriptionsHasMore, and connects dunningGracePeriodDays to past_due entitlement, beyond the bare 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 and resource: evaluating whether one customer's AI/API usage is unpaid ghost usage across multi-subscription Stripe basil state. It also names the sibling it is not (batch portfolio audits via revclamp_audit_revenue_leakage), so an agent can distinguish it 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 says when to use it (real-time per-customer entitlement gating) and when to use the alternative (revclamp_audit_revenue_leakage for batch multi-customer portfolio audits). It also states the fail-closed pagination precondition, leaving little to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantive context: it is deterministic, stateless (statelessEphemeralAudit, tenantId), non-destructive of existing merchant notes, and it discloses the fixed-wrapper capacity threshold plus the SKIP_POST_PRESERVE_DRAFT staging behavior when at capacity. The long field enumeration at the end dilutes rather than deepens this, which keeps it below 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?

The body is a single run-on sentence packing every threshold, delimiter literal, and rule into one clause chain, followed by a bare comma-separated dump of ~22 return field names. Information is present but not front-loaded or grouped, and the return-field list reads as exhaust rather than explanation.

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 10 parameters, nested objects, and no output schema, listing return fields is genuinely useful, and the CE 3.0 rules plus capacity thresholds are covered. However, the returned fields are named without meaning (e.g., overallVerdict, merchantLogAtCapacity), preset semantics and demo/preset override behavior are unexplained, and there is no guidance on which input path to choose.

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 baseline is 3; the description largely restates schema facts (18,000 UTF-16 ceiling, delimiter markers, prior-charge >= 2 with IP/device overlap). It does not resolve the one genuinely ambiguous point the schema leaves open, namely how evidenceLogText and accessActivityLog interact as aliases or when preset overrides custom input.

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 ('Deterministically lint') and a precisely scoped resource ('a Stripe dispute evidence[access_activity_log] payload') with the exact checks performed (18,000 UTF-16 ceiling, delimiters, CE 3.0 qualification). The purpose is unmistakable, but it never names the closest sibling (revclamp_stage_stripe_dispute_ce3) to draw the boundary explicitly.

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

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

There is no statement of when to call this versus alternatives, no prerequisites, and no exclusions. The mention of 'SKIP_POST_PRESERVE_DRAFT' and a staging action hints that a separate staging tool exists, but the description never routes the agent there or explains the handoff.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the description only needs to add context. It does add substantive behavior beyond annotations: pure stateless execution, exact integer minor-unit arithmetic with no floating-point drift, and the enumerated return fields in structuredContent. Gaps remain around alias precedence (orderTotalCents vs totalOrderCents, creditNoteCents vs creditNotesCents) and how tolerance interacts with the deposit threshold, which are behavioral ambiguities an agent would want 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?

Three front-loaded sentences with the purpose first and the alternative last; the long parenthetical return-field list is dense but functional since there is no output schema. Minor redundancy in restating read-only, which annotations already cover.

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 financial tool with an output schema absent, the description supplies purpose, usage routing, arithmetic semantics, and the return-shape field list, which is most of what an agent needs. The alias-precedence and tolerance-deposit interaction remain undocumented, keeping it just short of complete.

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

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

Schema description coverage is 100%, with defaults, ranges, enums, and examples given for every one of the 12 parameters, so the schema does the heavy lifting and the baseline is 3. The description adds no parameter-level meaning beyond what the schema already states.

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 (reconcile) and resource (B2B wholesale Net-15/30/60 invoice deposits, partial payments, credit notes) plus the arithmetic guarantee. It explicitly names a sibling (revclamp_validate_eu_vat_vies) as the tool for a different job, so an agent can distinguish it 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?

States the exact scenario it is for (B2B wholesale order deposit gating and Net-terms balance calculation) and routes EU VAT validation to a named sibling. It does not cover the other six siblings or describe when not to use it, so it falls short of full when/when-not/alternatives coverage.

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 covered. The description adds real value beyond that: it explains the deterministic evaluation model, the 72-hour dedup Set keyed on eventId, the monotonic guard on event.createdSec, and that the operation is a statelessEphemeralAudit. It does not explain failure/`ok:false` conditions or error behavior, 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?

Two dense, front-loaded sentences with no filler — the core purpose and mechanism come first, then the return contract. The second sentence enumerating return fields is justified because no output schema exists. It is slightly run-on and could be split for readability, 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?

For a simulation tool with no output schema, the description does the necessary work of enumerating returned fields (ok, simulation, steps, finalStatus, naiveFinalStatus, naiveHandlerBug) and framing what the comparison detects. It stops short of describing edge behaviors such as what happens when `events` and `scenarioPreset` conflict, or what an `ok:false` result indicates.

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 beyond the schema by explaining the semantic effect of the key parameters — the 1-10 event cap, the 60s-2592000s idempotency window with its 72h default, and the monotonic timestamp comparison rule. It reinforces rather than merely repeats the schema, though it does not clarify the interplay between `demo`, `scenarioPreset`, and `events` precedence.

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: evaluate a sequence of 1-10 subscription lifecycle webhooks against an idempotency dedup Set and a monotonic timestamp guard. The purpose (replay/out-of-order FSM simulation) is clearly distinct from the sibling revclamp_verify_webhook_signature, which handles signature verification, even though siblings are not named. An agent can tell immediately this is a simulation/diagnostic tool, not a write or verification tool.

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

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

Usage is implied through the inputs — pass a custom `events` array or fall back to a `scenarioPreset` — but there is no explicit 'use this when…' statement or exclusion against the sibling tools. The agent must infer that this is the right tool for replay/out-of-order scenarios rather than, say, reconciliation. Adequate but with a clear gap in 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?

Beyond the readOnlyHint/idempotent/non-destructive annotations, it discloses the key behavioral guarantees: submit is hardcoded to false, the tool never auto-submits to card networks, staging is stateless/ephemeral, and existing evidence text is preserved via append-only merge. It also enumerates the return payload (ok, mode, tenantId, ce3Qualification, drawer with stripeUpdateParams) despite there being no output 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?

Structure is strong — purpose first, then behavioral guarantees, then return shape, then sibling routing. It is somewhat dense, particularly the long enumeration of returned structuredContent fields, which could be trimmed since it is not needed to select or invoke the tool.

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

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

With 9 optional parameters, nested objects, and no output schema, this description fills the gaps: it explains the eligibility criteria driving the computation, the no-submit safety contract, and what the response contains. Nothing essential for a correct call 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 earns a step up by explaining the CE 3.0 qualification logic that connects the parameters — a 120-to-365-day window requiring at least 2 settled, non-refunded, non-disputed prior transactions sharing IP, device fingerprint, or billing email. That adds meaning the schema alone does not convey about how priorTransactions and disputedTransaction relate.

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 (evaluate Visa CE 3.0 qualification and assemble a Stripe dispute evidence draft) and names the exact alternative (revclamp_audit_revenue_leakage) for the portfolio-wide case. An agent can distinguish it from the sibling 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?

It explicitly routes the agent: 'Use this tool for single-dispute CE 3.0 qualification and evidence staging; use revclamp_audit_revenue_leakage for portfolio-wide dispute readiness counts.' It also implies the applicable condition ('Visa CE 3.0 applies to fraudulent disputes'). However, it never mentions revclamp_lint_dispute_evidence, a closely related sibling, so the boundary with that tool is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered; the description still adds real value beyond that by disclosing the GR→EL prefix normalization rule, the deterministic-vs-LIVE execution distinction, the circuit-breaker hold behavior, and the statelessEphemeralAudit flag. It does not mention authentication requirements or rate/latency characteristics of the LIVE VIES call, 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?

Content is front-loaded: identity and normalization come first, then eligibility, then modes, then return shape, then sibling routing. The second sentence is a single very long clause chain dense with parenthetical field lists, which costs some readability, but every sentence carries information and nothing is padded.

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

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

With no output schema, the description usefully names the structuredContent keys (ok, mode, normalizedVat, reverseChargeEligible, viesDecision), which the agent would otherwise have to discover at runtime. Error semantics for a failed LIVE lookup and any auth prerequisites for the European Commission endpoint are the remaining gaps, but for a 5-parameter read-only tool this is close to sufficient.

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 the mode enum and its default. The description only partially restates the enum ('VALID', 'INVALID', 'MS_UNAVAILABLE', 'LIVE') and omits FORMAT_ONLY and GLOBAL_MAX_CONCURRENT_REQ, adding no syntax or format detail beyond what the schema provides — 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?

The description opens with a specific verb pair (normalize/evaluate) and a precisely bounded resource (EU-27 and XI B2B VAT identifiers, reverse-charge eligibility). It explicitly names the sibling it is not (revclamp_reconcile_b2b_net_terms) and its domain, so an agent can distinguish it from all eight siblings 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?

It states the use case directly ('Use this tool for EU/XI VAT tax compliance') and supplies the alternative plus the condition that selects it (Net-15/30/60 deposit and credit-note accounting). The mode enumeration also tells the agent which evaluation path to pick for 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?

Well beyond the readOnly/non-destructive annotations, the description discloses the timing-safe comparison, the 300-second replay window guard, the Zero-Trust live-credential blocklist with the exact -32602 LIVE_SECRET_FORBIDDEN_IN_SANDBOX error, default payload/secret fallbacks, and the full structuredContent shape. This is unusually rich behavioral context for a sandbox 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?

The core purpose is front-loaded, but it is delivered as two very long run-on sentences stuffed with parenthetical header formats and a long enumerated blocklist. Listing every structuredContent field inline aids completeness but bloats the prose, and some enumeration belongs in structured data rather than the description.

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 no output schema, the description compensates well: it names the returned fields, explains the guard/failure code, the replay window, defaults for omitted inputs, and both operating modes. An agent has what it needs to call this 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 all 8 parameters are already documented, and most of the description's parameter talk (rotation secrets, default secret, non-test whsec_ rejection) restates the schema. The only added semantic is that omitting signatureHeader switches to GENERATE_AND_SELF_VERIFY mode, which is marginal added value against 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?

The description states a specific verb and resource: generate and verify canonical HMAC-SHA256 signature headers for Stripe, Shopify, and RevClamp webhooks, plus a debug use case. It is clearly distinguishable from most siblings, though the very close sibling revclamp_simulate_webhook_replay is never named or contrasted.

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 closing sentence gives a usage context ('debug webhook signature mismatches and replay skew'), and the signatureHeader param note explains the generate-vs-verify mode. However there are no exclusions and no comparison to the near-identical sibling simulate_webhook_replay, leaving the agent to infer which to pick.

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