Reads an approved supplier-bills register (the invoice-intake SQLite database) in read-only mode to answer payables questions about unpaid bills due in the next N days and to include outgoing bills in the cash forecast.
Read-only access to Stripe finance data via a restricted API key: open customer invoices with aging buckets and days overdue, per-invoice detail (lines, totals, payment attempts, hosted link), recent payouts and per-payout breakdowns (sales, refunds, chargebacks, fees), open disputes with evidence deadlines, and available/pending balance per currency. Also feeds the day-by-day cash forecast with pending settlements and in-transit payouts.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@finops-mcp Run a 13-day cash forecast. When do we go negative?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Ask Claude about your money, in plain English, from your real Stripe data. "Who owes us money and how late are they?" "What's in Friday's payout?" "Do we have enough cash to cover rent and payroll in the next two weeks?"
finops-mcp is a Model Context Protocol server that gives Claude (Desktop, Claude Code, or any MCP client) eight read-only finance tools over Stripe and your supplier bills. It cannot create, refund, pay or change anything.
flowchart LR
U[You ask Claude] --> C[Claude]
C <-->|MCP, read-only| F[finops-mcp]
F -->|restricted key| S[(Stripe: invoices, payouts,\nbalance, disputes)]
F -->|read-only SQLite| B[(Approved bills from\ninvoice-intake)]Tool | Answers |
| Open customer invoices, days overdue, aging buckets (current, 1-30, 31-60, 61-90, 90+), totals per currency |
| One invoice: lines, totals, payment attempts, hosted link |
| Recent payouts to the bank, arrival date and status |
| What one payout is made of: sales, refunds, chargebacks, fees, mapped to journal accounts, and a check that the lines add up to the amount that hit the bank |
| Open chargebacks with the evidence deadline and days left |
| Approved, unpaid supplier bills due in the next N days |
| Stripe available and pending, per currency |
| Day-by-day cash for one currency: lowest point, first day it goes negative, overdue invoices at risk, and the assumptions behind it |
There is also a weekly_cash_review prompt: one click in Claude Desktop runs the Monday check-in (overdue customers to chase, bills due, disputes due this week, cash low point).
Money is exact: amounts are decimals in major units, zero-decimal currencies (JPY, VND, KRW...) are handled, nothing goes through floats.
Related MCP server: Stripe MCP Server
Demo mode serves a small fictional business: five open invoices (two overdue), three payouts, one chargeback, five bills.
pip install git+https://github.com/TylerNguyennn/finops-mcpAdd it to Claude Desktop (Settings → Developer → Edit Config, file claude_desktop_config.json):
{
"mcpServers": {
"finops": {
"command": "finops-mcp",
"env": { "FINOPS_DEMO": "1" }
}
}
}Or to Claude Code:
claude mcp add finops --env FINOPS_DEMO=1 -- finops-mcpThen ask: "Run a 13-day cash forecast. When do we go negative, and what would fix it?"
This is what the cash_forecast tool returns in demo mode (abridged):
opening 4,312.40 USD (Stripe available; no bank balance given)
Oct 29 +4,605.10 8,917.50 Stripe pending settles; payout po_demo_3 lands
Oct 30 -7,500.00 1,417.50 bill RENT-NOV to Riverside Property Management
Oct 31 -285.00 1,132.50 bill INV-2041 to Acme Cloud Hosting LLC
Nov 01 +980.00 2,112.50 invoice HB-1003 from Lumen Studio
Nov 04 -3,900.00 -1,787.50 bill CP-2026-11A to Crewline Contractor Payroll <- first negative
Nov 05 -1,250.00 -3,037.50 bill VA-7781 to Vector Ads Ltd <- lowest
Nov 08 +6,200.00 3,162.50 invoice HB-1004 from Atlas Fitness Group
at risk: HB-1001 Harbor Coffee Roasters 1,200.00 (10 days late), HB-1002 Pinecrest Dental 3,450.00 (20 days late)The answer is in the data: collect the two overdue invoices (4,650.00) and cash never goes below zero. The test suite checks exactly that.
In Stripe, create a restricted key (Developers → API keys → Create restricted key) with Read on: Invoices, Payouts, Balance, Balance transactions, Disputes. Everything else: None.
Configure the server:
{
"mcpServers": {
"finops": {
"command": "finops-mcp",
"env": {
"STRIPE_API_KEY": "rk_live_...",
"FINOPS_BILLS_DB": "/path/to/invoice-intake/data/register.sqlite"
}
}
}
}Variable | Meaning |
| Restricted read-only key. A full |
| Optional. The register from invoice-intake: approved and exported bills that are not marked paid. Without it, |
| Payment terms for bills with no printed due date (default 30). |
| The fictional demo data above. |
Read-only by construction. The code only calls Stripe list and retrieve endpoints; the restricted key makes that a guarantee on Stripe's side too. The bills register is opened with SQLite mode=ro. Every tool carries the MCP readOnlyHint annotation, so clients know none of them change anything.
Your data goes where your MCP client sends it. Tool results go to the Claude client you connected (for Claude Desktop, that means Anthropic's API). Nothing else leaves your machine; the server has no telemetry.
Keys live in your client config or environment, never in this repo.
Opening cash = the bank balance you pass (opening_bank_balance, default 0) + Stripe available. Stripe pending is counted pending_settles_in_days after today (default 2). Payouts already in transit land on their arrival date. Open invoices are paid on their due date; overdue ones are left out and listed as at risk unless you pass include_overdue_receivables. Approved bills are paid on their due date. New card sales, payroll and spending outside the bills register are not included. The tool returns these assumptions with every forecast so Claude repeats them.
pip install -e ".[dev]"
pytest -qThe tests drive the server through a real MCP client in-process and check the numbers above, the Stripe SDK field mapping (with fake SDK objects, no network), the read-only bills register and error messages that reach the model.
finops_mcp/
sources.py Stripe and bills-register readers (+ demo versions), all amounts as Decimal
server.py the MCP tools, prompt, and env configuration
demo/ fictional data; dates are offsets from today so the demo never ages
tests/stripe-payout-reconcile: split Stripe payouts into journal lines and match them to the bank statement.
invoice-intake: supplier invoices from a mailbox, read by Claude, checked, approved, exported to Xero or QuickBooks.
finops-mcp: ask Claude about receivables, payouts, disputes, bills and cash, read-only over Stripe.
I build payment and finance-ops automation: PSP integrations, webhooks, payouts, reconciliation, and Claude-based tools like this one. I can add your bank feed, Xero or QuickBooks, multi-entity or multi-currency reporting, and alerts to Slack, and deploy it for your team.
Get in touch through taewoo.me.
MIT
Stripe balance per currency: available (can be paid out now) and pending (still settling).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this read-only, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds genuine domain semantics by defining 'available' vs 'pending', but says nothing about currency coverage, empty results, or error 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?
A single sentence front-loads the resource and then parenthetically defines both returned buckets; 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?
With no output schema and no parameters, the description usefully explains what the two returned balance fields mean. The remaining gap is differentiation from adjacent money-flow siblings (payouts, receivables, cash_forecast).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there are no parameter semantics to explain and the baseline of 4 applies. The description's 'per currency' note correctly signals that results are keyed by currency rather than filtered by an argument.
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 resource (Stripe balance) and scopes it per currency, plus defines the two buckets returned. It does not explicitly contrast with siblings like payouts or receivables, so an agent must infer the boundary, but the resource is unmistakable.
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 phrase 'can be paid out now' implies the use case (checking what is withdrawable before triggering a payout), but there is no explicit when-to-use, when-not-to-use, or named alternative such as payouts or cash_forecast.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Day-by-day cash forecast for one currency: bank balance you give + Stripe available today, Stripe pending and payouts in transit, customer invoices on their due date, approved bills on theirs. Returns each day with movement, the lowest point and the first day cash goes negative. The assumptions list in the result must be shown to the user with the numbers.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | ||
| currency | No | USD | |
| opening_bank_balance | No | 0 | |
| pending_settles_in_days | No | ||
| include_overdue_receivables | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description adds real value beyond them: it discloses the modeling assumptions baked into the math (invoices land on due date, bills on theirs, pending settles later) and mandates that the result's assumptions list be shown to the user with the numbers. It stops short of covering pagination or how the negative-cash day is detected when multiple days tie.
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 resource and its inputs, then the return shape, then the critical display directive. No filler, and the most actionable instruction is placed last for emphasis.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description does the necessary work of explaining what comes back: per-day movement, the low point, and the first negative day. The remaining gap is parameter-level, particularly the settle-days default and the overdue-receivables toggle, which materially change the numbers an agent is instructed to 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 0%, so the description carries the full burden, yet two of the five parameters — pending_settles_in_days and include_overdue_receivables — get no explanation at all; 'Stripe pending' hints at the first but not that it is a day-count. It does clarify currency and the supplied bank balance, but the opaque defaults (2-day settle, overdue excluded) are left for the agent to guess.
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 artifact ('day-by-day cash forecast for one currency') and enumerates exactly which sources feed it: bank balance, Stripe available/pending/in-transit payouts, invoices by due date, approved bills. An agent can immediately tell this apart from point-in-time siblings like balance, payouts, receivables and payables, because it is the forward projection that combines 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?
Usage is implied by the composition breakdown — an agent can infer this is the forward-looking tool versus the current-state siblings — but the description never states when to prefer it over balance or payables, nor any preconditions. No explicit alternative routing or exclusion is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stripe disputes (chargebacks) with the evidence deadline and days left to respond.
| Name | Required | Description | Default |
|---|---|---|---|
| open_only | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so safety is covered. The description adds genuine value by flagging that the response carries an evidence deadline and days-remaining, but it omits the default open-only scoping and any pagination/limit 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?
A single front-loaded sentence with no filler; the most decision-relevant detail (deadline pressure) is placed where the agent will see it first.
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 one-parameter read-only list tool with no output schema, the description should at least state the default filter and rough return shape. It covers the value proposition but leaves the scoping behavior — the thing most likely to cause a wrong call — undocumented.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%: the single parameter 'open_only' has a default of true but no description anywhere. The description never mentions this filter, so an agent could wrongly assume it returns all disputes, including closed/paid ones. With low coverage the description was obliged to compensate and does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the resource precisely ('Stripe disputes (chargebacks)') and the payload that matters ('evidence deadline and days left to respond'), which is more than most sibling names convey. It lacks an explicit verb (list vs. detail) and never contrasts itself with siblings like receivables or payables, but the scope is unmistakable.
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 guidance on when to reach for this tool versus siblings, no prerequisites, and — critically — no mention that the tool filters to open disputes by default. An agent must infer usage entirely from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One Stripe invoice: customer, lines, totals, payment attempts and the hosted invoice link.
| Name | Required | Description | Default |
|---|---|---|---|
| invoice_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuine value beyond that by disclosing the returned payload surface (customer, lines, totals, payment attempts, hosted link), which is the only source of return-value information given there is no output schema. It omits error behavior for an unknown invoice_id, which keeps it below 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?
One sentence, zero waste, front-loaded with the resource identity followed by the returned fields. Every clause carries information an agent can act on.
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-parameter read with no output schema, the description adequately covers both what the tool targets and what comes back. The remaining gap is the identifier format and failure mode for an invalid or non-existent invoice, which a caller would need in practice.
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 a single parameter and 0% schema description coverage, the schema contributes nothing about invoice_id. The description indirectly implies it is a Stripe invoice identifier via 'One Stripe invoice', but never states the expected format (e.g. the 'in_' prefix) or whether it accepts an internal vs. external ID. Partial compensation, not full.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific resource (a single Stripe invoice) and enumerates the content it returns: customer, lines, totals, payment attempts, hosted link. That is clearly distinguishable from siblings like receivables, payouts, or disputes. It lacks an explicit verb ('retrieve'), reading as a noun phrase, which is the only reason it isn't 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?
Usage is implied by the singular-resource framing and the required invoice_id, so an agent can infer 'look up one known invoice'. However, no explicit when-to-use guidance is given, and with a sibling like 'receivables' that also surfaces invoice-level data, the description should have stated the selection rule (single known invoice vs. aggregate listing).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Approved supplier bills not yet paid, due within the window (overdue ones included). Needs FINOPS_BILLS_DB (an invoice-intake register) or demo mode.
| Name | Required | Description | Default |
|---|---|---|---|
| due_within_days | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the inclusion rule that overdue bills are returned even outside the window, and the hard data-source dependency on FINOPS_BILLS_DB or demo mode. It omits return shape and pagination, but for a read-only list that is a minor 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 tight sentences, front-loaded with the scope definition and followed by the operational prerequisite. No filler, no repetition 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?
A single-optional-parameter read tool with no output schema needs only scope, inclusion rules, and preconditions, all of which are present. It stops short of saying what fields the bills carry (amounts, aging, supplier names), which would help an agent decide whether one call is 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?
Only one optional parameter with 0% schema description coverage, so the description must carry the load; it implies the window semantics ('due within the window') and clarifies that overdue items are included regardless. It still does not state the unit for due_within_days, the default of 14, or what happens if the value is omitted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource (supplier bills) with precise scope qualifiers: approved, not yet paid, due within the window, overdue included. It implicitly contrasts with the 'receivables' sibling by naming payables, but never explicitly differentiates itself from it or from 'payouts'/'disputes'.
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 real prerequisite: 'Needs FINOPS_BILLS_DB (an invoice-intake register) or demo mode,' which tells the agent when the tool will actually work. However, it offers no explicit guidance on when to choose this over siblings like payouts, payout_breakdown, or cash_forecast, leaving the selection decision to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What one payout is made of: gross, fees and net per category (sales, refunds, chargebacks, fees), mapped to journal accounts, and whether the lines add up to the amount that hit the bank.
| Name | Required | Description | Default |
|---|---|---|---|
| payout_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the operation as read-only, idempotent, non-destructive, and open-world. The description adds valuable behavioral context about the output: gross/fees/net per category, mapping to journal accounts, and a reconciliation check against the bank amount. It does not cover rate limits or error behavior, but given the annotations, this is sufficiently transparent.
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 a single, front-loaded sentence that efficiently states the core purpose. It is slightly long but every clause adds useful information about what is returned, so it earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and a single parameter whose schema lacks description, the description carries the burden of explaining the return content. It successfully details the categories, account mapping, and reconciliation check. The missing input guidance is a minor gap, but overall it is complete for this simple read 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 description coverage is 0% for the single required parameter 'payout_id'. The description does not mention the parameter or its expected format, only implying that a payout must be specified via 'one payout'. This fails to compensate for the schema's lack of detail.
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 clearly states it provides a breakdown of one payout by category (sales, refunds, chargebacks, fees) and includes reconciliation info. It is specific to a single payout, distinguishing it implicitly from a list-oriented tool like 'payouts', though no sibling is named.
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: you call this tool when you need a detailed composition of a single payout. There is no explicit guidance on when to use it versus alternatives (e.g., 'payouts', 'balance'), nor any preconditions or exclusions mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent Stripe payouts to the bank, newest first, with arrival date and status.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, open-world, and non-destructive, so the safety profile is covered. The description adds genuinely useful behavior — result ordering and the fields returned — but says nothing about how many payouts 'recent' covers, which Stripe account/currency scope applies, or whether results are paginated.
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?
One sentence, no waste, with the resource and ordering stated up front and the returned fields trailing. Every clause carries information an agent can act on.
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 one-parameter read-only list tool with no output schema, describing the return shape (arrival date, status) plus ordering covers most of what an agent needs. The remaining gap is the unexplained limit parameter and the undefined scope of 'recent'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter (limit, default 10) has 0% schema description coverage, so the description must carry that burden and does not. The word 'recent' hints at a bounded window but never explains that limit caps the number of payouts returned, leaving the only input undocumented in both places.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific resource (Stripe payouts to the bank) with a clear ordering guarantee (newest first) and lists the fields surfaced (arrival date, status). It implicitly separates itself from payout_breakdown by framing this as the recent-list view, but it never names that sibling 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 use this versus payout_breakdown, balance, or cash_forecast, which are the obvious adjacent tools. Usage is only inferable from the word 'Recent' — no exclusions, prerequisites, or alternatives are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Open customer invoices in Stripe with days overdue and an aging bucket. min_days_overdue=1 lists only overdue invoices; 0 lists everything still open.
| Name | Required | Description | Default |
|---|---|---|---|
| min_days_overdue | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish that this is a safe, idempotent, read-only, non-destructive operation. The description adds useful behavioral context by saying the result contains open customer invoices with days overdue and an aging bucket, and by clarifying that min_days_overdue=0 includes everything still open. It stops short of covering pagination or full return structure, but it adds meaningful output context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, both front-loaded and waste-free: the first identifies the resource and returned attributes, the second explains the only parameter's meaningful values. There is no repetition 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 simple one-parameter list tool with no output schema, the description covers the core purpose, parameter behavior, and key returned attributes. The main missing piece is an explicit routing cue versus invoice_detail or payables, plus any indication of pagination or result limits.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must carry the meaning of min_days_overdue. It does explain the important distinction that 1 returns only overdue invoices while 0 returns all still-open invoices, though it does not spell out values greater than 1 explicitly or state whether negative values are handled.
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 resource and scope: open customer invoices in Stripe, enriched with days overdue and an aging bucket. It does not explicitly name or distinguish itself from siblings such as invoice_detail or payables, so an agent must infer that this is the list-level receivables aging tool rather than a single-invoice or vendor-bill 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?
The description gives a clear implied use case (reviewing open customer invoices by aging) and explains how min_days_overdue narrows the result set. However, it does not explicitly say when to use this tool instead of invoice_detail, payables, or other siblings, nor does it provide exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0balancecash_forecastdisputesinvoice_detailpayablespayout_breakdownpayoutsreceivablesScored across 8 tools
Each tool targets a distinct resource: receivables vs payables vs payouts vs disputes vs balance vs cash_forecast are clearly differentiated, and the two detail tools (invoice_detail, payout_breakdown) are unambiguously paired with their list counterparts via descriptions. There is no meaningful overlap that would cause misselection.
All names are lowercase noun phrases in a coherent style: plural nouns for collections (receivables, payouts, disputes, payables) and underscored compounds for detail/derived views (invoice_detail, payout_breakdown, cash_forecast). Minor deviation from a strict single convention (singular 'balance', no verb prefix) but overall predictable and readable.
Eight tools is well-scoped for a read-only FinOps reporting server, covering AR, AP, payouts, disputes, balance and forecasting without redundancy. Each tool earns its place.
Strong read-only lifecycle coverage for cash-flow reporting, including aging, payout reconciliation, disputes and a forward forecast. Minor gaps remain, such as no dedicated refunds tool or customer-level aggregation, but core financial workflows are covered.
Connect Claude or Cursor to books, invoices, bills, payroll, and sealed closes.
Connect your ads, shop, analytics, social, CRM and finance platforms once, then let Claude, ChatGPT, Cursor or any MCP client read, join and explain your numbers. Public statistics from the World Bank, IMF, Eurostat, OECD, WHO and SEC filings come as context, searchable and chartable from the same tools. Read-only by design, every number carries its source.
Stripe MCP Pack — read-only access to Stripe data via API key.
Ask your accounts-receivable portfolio anything. Read-only, scoped to your account.
