Skip to main content
Glama

RevClamp MCP Server

by com.revclamp
OverviewDiscussionsAdmin

Evaluate Single-Customer Stripe Basil Ghost Usage

revclamp_evaluate_ghost_usage
Read-onlyIdempotent

Evaluate whether a specific customer's AI or API usage event constitutes unpaid ghost usage across multi-subscription Stripe 2025-03-31.basil state, enforcing fail-closed pagination (has_more must be explicitly false) and configurable 0-14 day dunning grace windows. Executes as a stateless, read-only entitlement evaluator with zero side effects. Returns structuredContent containing ok, mode, statelessEphemeralAudit, tenantId, and evaluation (isGhostLeak, isGhostUsage, reason). Use this tool for real-time per-customer entitlement gating; use revclamp_audit_revenue_leakage for batch multi-customer portfolio audits.

Input Schema

NameRequiredDescriptionDefault
demoNoOptional simulation flag (boolean) for deterministic ghost-usage preview.
customerIdNoStripe customer identifier to evaluate (format example: 'cus_9s6XKzkNRiz8i3', max 64 chars).
usageEventNoOptional metered usage event object containing customer_id (or stripe_customer_id), event_name, and occurred_at (or occurred_at_sec).
occurredAtSecNoOptional alias for usageTimestampSec: Unix epoch timestamp in integer seconds (e.g. 1761264000) when the usage event occurred (used when usageTimestampSec is omitted).
subscriptionsYesRequired Stripe customer subscriptions payload: either a Stripe list object ({ data: [...], has_more: false }) or a raw array of up to 50 subscription objects containing id, status ('active', 'trialing', 'past_due', 'canceled', 'unpaid'), current_period_end, or items.data[].current_period_end in Unix seconds.
usageTimestampSecNoOptional Unix epoch timestamp in integer seconds (e.g. 1761264000) when the AI/API usage event occurred (defaults to current server Unix timestamp if omitted).
subscriptionsHasMoreNoPagination completeness flag (boolean). Must be explicitly set to false when passing a raw subscriptions array so RevClamp can verify no active subscription was truncated on a later page.
dunningGracePeriodDaysNoDunning grace window in integer days (valid range: 0 to 14, default: 3) after latest_invoice_failed_at during which past_due subscriptions remain entitled.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.5/5.0
Behavior4/5

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.

Conciseness4/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines5/5

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.

All RevClamp MCP Server toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources