InvoiceFlow MCP is an AI-powered invoice automation server that handles the full invoicing lifecycle — from client management and PDF creation to risk prediction, payment reconciliation, and cash flow reporting.
client_manage: Create or update clients with name, email, phone, address, tax ID, and company info. Required before creating invoices.
invoice_create: Generate invoices with line items (description, quantity, unit price, tax rate, discount), auto-calculated totals, sequential invoice numbers (INV-YYYY-NNNN), and multi-currency support (USD, EUR, GBP, CAD, AUD, JPY, CHF, TRY, BRL, INR).
invoice_list: Filter invoices by status (draft, sent, viewed, paid, overdue, cancelled, refunded), client, amount range, date range, or overdue status, with pagination.
invoice_send: Generate a PDF and deliver it via SendGrid email (requires SENDGRID_API_KEY); updates status to "sent".
invoice_mark_paid: Record full or partial payments with a specified method (Stripe, PayPal, bank transfer, cash, check, crypto, etc.) and auto-update client payment history.
invoice_remind: Send payment reminders with optional custom messages; tracks reminder count and timestamp.
invoice_risk: Score late-payment risk (0–100) using four factors — invoice amount (20%), client history (35%), due date proximity (30%), reminder history (15%) — with recommended actions.
cashflow_report: Portfolio-wide summary including total invoiced, collected, outstanding, overdue, collection rate, average days to payment, 30-day projection, and per-client breakdown.
payment_reconcile: Match incoming payments to invoices by amount and payer email; auto-marks matched invoices as paid.
Predefined resources are also available: invoices://pending (unpaid invoices), invoices://overdue (overdue invoices), invoices://stats (monthly cash flow summary), and clients://list (all clients with payment history).
Provides automated payment reconciliation by matching incoming PayPal transactions to invoices using amount and payer email, marking matched invoices as paid.
Enables email delivery of professional PDF invoices and automated payment reminders through SendGrid's email service.
Provides automated payment reconciliation by matching incoming Stripe transactions to invoices using amount and payer email, marking matched invoices as paid.
AI-powered invoice automation for the Model Context Protocol
InvoiceFlow creates professional PDF invoices, predicts late payment risk using AI, auto-sends reminders, matches incoming payments to invoices, and tracks your cash flow -- all through the MCP protocol.
Professional PDF invoices with line items, tax, discounts, multi-currency (10 currencies)
AI risk prediction (0-100) based on invoice amount, client history, due date, reminder history
Smart reminders with escalation based on risk level
Payment reconciliation matching incoming payments to invoices by amount + payer email (platform-agnostic — works with manually-entered or webhook-provided payment data)
Cash flow reporting with collection rate, projected income, client breakdown
Client management with automatic payment history tracking
Sequential invoice numbers (INV-2026-0001, INV-2026-0002, ...)
10 MCP tools + 4 MCP resources covering the full invoicing lifecycle
Related MCP server: Frihet MCP Server
Search for InvoiceFlow MCP on mcpize.com
Click Install — Free tools work immediately; unlock Pro with a €12 lifetime license (see Pro License)
Tools and resources are automatically available in any MCP-compatible client
git clone https://github.com/enzoemir1/invoiceflow-mcp.git
cd invoiceflow-mcp
npm ci
npm run buildAdd to your MCP client config:
{
"mcpServers": {
"invoiceflow": {
"command": "node",
"args": ["path/to/invoiceflow-mcp/dist/index.js"]
}
}
}Seed a realistic demo dataset — 8 clients across 5 archetypes (on-time, late-payer, high-value, new, chronic-late) and 25-45 invoices over the last 6 months — so every tool returns meaningful output without any credentials. Safe to call multiple times; each call appends a fresh batch with unique UUIDs. Returns counts plus sample_invoice_ids.
Create a new client. Required before creating invoices.
Create an invoice with line items. Auto-calculates subtotal, tax, discounts, and total. Generates sequential invoice numbers (INV-YYYY-NNNN).
Send an invoice PDF via email (requires SENDGRID_API_KEY). Updates status to "sent".
Filter invoices by status, client, amount range, date range, or overdue status. Supports pagination.
Mark an invoice as paid (full or partial). Updates client payment history automatically.
Send a payment reminder. Increments reminder count. Supports custom messages.
AI-powered late payment risk prediction (0-100). Returns risk level, factor breakdown, recommended action, next reminder date.
Generate cash flow summary: total invoiced, collected, outstanding, overdue, collection rate, 30-day projection.
Match incoming payment to invoice by amount and payer email. Auto-marks as paid.
Resource | Description |
| All unpaid invoices |
| Invoices past due date |
| Monthly cash flow summary |
| All clients with payment history |
Scores invoices 0-100 using 4 weighted factors:
Factor | Weight | What It Measures |
Invoice Amount | 20% | Higher amounts = higher risk |
Client History | 35% | Pay rate, late payments, avg days |
Due Date | 30% | Days until/past due |
Reminders | 15% | Reminders already sent |
Risk Levels: Low (0-30), Medium (31-60), High (61-100)
Copy .env.example to .env and set the variables you need:
cp .env.example .envVariable | Required | Description |
| For email sending | Send invoices and reminders via SendGrid |
SendGrid is optional. InvoiceFlow works fully offline for invoice creation, risk scoring, cash flow reporting, and reconciliation. Add SendGrid when you want outbound email delivery.
The payment_reconcile tool currently matches amounts you provide (from a CSV, a webhook, or manual entry) against stored invoices. Direct Stripe and PayPal API integration with webhook listeners is planned for v2.0 — see issues for progress.
> Create a client "Acme Corp" with email billing@acme.com
✓ Client created: Acme Corp (id: 3f2a...)
> Create an invoice for Acme Corp: 10 hours consulting at $150/hr, 20% tax
✓ Invoice INV-2026-0001 created
Subtotal: $1,500.00 | Tax: $300.00 | Total: $1,800.00> What's the risk score for invoice INV-2026-0001?
Risk Score: 42/100 (Medium)
- Invoice Amount: 25 (moderate amount)
- Client History: 50 (new client)
- Due Date: 15 (due in 28 days)
- Reminders: 10 (none sent)
Recommended: Send an early reminder with a polite tone.> Show me the cash flow report
April 2026:
Total Invoiced: $12,400.00
Collected: $8,200.00 (66.1%)
Outstanding: $4,200.00
Overdue: $1,800.00
Projected (30d): $2,400.00USD, EUR, GBP, CAD, AUD, JPY, CHF, TRY, BRL, INR
Tier | Price | Tools | Features |
Free | €0 |
| PDF invoices, multi-currency, client management, manual reminders |
Pro | €12 lifetime | + | AI risk scoring, SendGrid delivery, payment reconciliation, cash flow reporting |
One-time €12 lifetime license (3 machines) — no subscription. See Pro License below to buy and activate.
npm run dev # Hot reload
npm run build # Production build
npm test # Run tests
npm run inspect # MCP InspectorTests cover the core business logic:
Storage — CRUD operations, filtering, sequential invoice numbers
Risk Model — AI scoring engine with 4 weighted factors, risk classification
Cash Flow — Report generation, collection rates, projections, client breakdown
npm test # Run all tests
npx vitest --watch # Watch modeInvoiceFlow ships in Free mode — invoice_demo_seed, client_manage, invoice_create, invoice_list, invoice_mark_paid, and invoice_remind are open. The following tools require a Pro license:
invoice_send — generate PDF + SendGrid email delivery
invoice_risk — late-payment risk prediction
payment_reconcile — match Stripe/PayPal/bank payments to invoices
cashflow_report — portfolio-wide cash flow + 30-day projection
Buy a Pro License (€12, lifetime, 3 machines): https://automatiabcn.lemonsqueezy.com/buy/2d439c05-f463-4137-8883-950e8ee1112d
Or get the Indie MCP Stack Bundle (€69, all 4 servers).
export LEMONSQUEEZY_LICENSE_KEY=YOUR-KEY-HEREOr in your MCP client config:
{
"mcpServers": {
"invoiceflow-mcp": {
"command": "npx",
"args": ["-y", "invoiceflow-mcp-server"],
"env": { "LEMONSQUEEZY_LICENSE_KEY": "YOUR-KEY-HERE" }
}
}
}Validation is cached locally for 24 h — fully offline-capable after first run.
MIT License. See LICENSE for details.
Built by Automatia BCN.
Generate a portfolio-wide cash flow summary across all invoices. Returns {period, total_invoiced, total_collected, total_outstanding, total_overdue, collection_rate (percent), avg_days_to_payment (or null if no paid history), projected_income_30d (forecast based on due dates and historical pay rate), breakdown_by_status, breakdown_by_client}. Takes no input — always reports on the current full dataset. Ideal for dashboards and monthly close.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint: true, idempotentHint: true, and destructiveHint: false. The description adds behavioral details like null handling for avg_days_to_payment and forecasting logic for projected_income_30d, which go beyond 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?
The description is a single, well-structured paragraph that front-loads the main purpose and lists return values concisely without extraneous 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?
Despite lacking an output schema, the description fully enumerates all return fields (period, totals, rates, breakdowns) and includes handling for null values and forecast logic, making it complete for a zero-parameter 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?
There are no parameters (schema coverage 100% with empty properties), so baseline is 4. The description correctly states 'Takes no input,' which is sufficient.
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 'Generate a portfolio-wide cash flow summary across all invoices' with specific verb ('Generate') and resource ('cash flow summary'), and the listed return fields distinguish it from sibling tools like client_manage or invoice_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Takes no input — always reports on the current full dataset. Ideal for dashboards and monthly close,' providing clear context and when-to-use guidance without needing alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create or upsert a client record used by invoice_create. Accepts name, email, company, address, city, country, tax_id, phone, default_currency ("USD"|"EUR"|"GBP"|...) and notes. Returns the stored client object including the generated id (UUID), an empty payment_history (populated as invoices are paid), and timestamps. Safe to call repeatedly: if a client with the same email already exists, the existing record is returned unchanged.
| Name | Required | Description | Default |
|---|---|---|---|
| city | No | Optional city. | |
| name | Yes | Display name shown on invoices and reports. Required. | |
| Yes | Primary billing email. Used as the dedup key — calling client_manage twice with the same email returns the existing record. Also used by payment_reconcile to match incoming payments. | ||
| notes | No | Internal notes about this client (not printed on invoices). | |
| phone | No | Optional phone number. | |
| tax_id | No | Optional VAT / tax ID (e.g. EU VAT number, US EIN). Printed on PDFs that need it. | |
| address | No | Optional billing street address. | |
| company | No | Optional legal company name (printed on the invoice when set). | |
| country | No | Optional country (full name or ISO code — printed verbatim). | |
| default_currency | No | Default invoice currency for this client. Used when invoice_create omits currency. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description fully discloses behavioral traits: safe to call repeatedly, idempotent, returns existing record on duplicate email, and describes the return structure (id, payment_history, timestamps). Annotations (idempotentHint=true, destructiveHint=false) are consistent and reinforced.
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 two sentences, front-loaded with purpose, and every sentence adds necessary context. No fluff or redundancy.
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 the tool has 10 parameters, full schema coverage, and no output schema, the description provides sufficient context: it explains the return object, idempotency via email, and links to invoice_create. Could mention update behavior, but it's implicit in 'returned unchanged'.
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 baseline is 3. The description adds value by explaining the dedup role of email and listing enum options for default_currency, but does not significantly enhance meaning for other parameters beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates or upserts a client record used by invoice_create, specifying accepted fields and return object. It distinguishes itself from sibling tools which are all invoice-related, so no confusion.
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 context by stating it's used by invoice_create and explains idempotent behavior via email dedup. However, it does not explicitly instruct when to use this tool versus alternatives, though no direct alternative exists among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new invoice for an existing client. Required: client_id (UUID) and line_items (non-empty array of {description, quantity, unit_price, tax_rate?, discount_percent?} — tax and discount are per-line). Optional: currency (defaults to the client's default_currency then USD), issue_date (YYYY-MM-DD or full ISO, defaults to today), due_date (same format, defaults to issue_date + 30 days), notes, and terms. Auto-calculates subtotal, discount_total, tax_total, and total; generates a sequential invoice_number in format INV-YYYY-NNNN; sets status="draft". Returns the full invoice object ready for invoice_send.
| Name | Required | Description | Default |
|---|---|---|---|
| notes | No | Free-text notes shown on the PDF (e.g. payment instructions, thank-you). | |
| terms | No | Free-text terms section on the PDF (e.g. "Net 30. Late fee 1.5%/mo."). | |
| currency | No | ISO 4217 code for the invoice. One of: USD, EUR, GBP, CAD, AUD, JPY, CHF, TRY, BRL, INR. Defaults to the client's default_currency, then USD. | |
| due_date | No | Payment due date — same format as issue_date. Defaults to issue_date + 30 days. Used by invoice_risk and overdue detection. | |
| client_id | Yes | UUID of the client this invoice is billed to. Must exist (created via client_manage). The stored client_email and client_name are snapshotted into the invoice at create time. | |
| issue_date | No | Invoice issue date — accepts either YYYY-MM-DD or full ISO-8601. Defaults to today (UTC). | |
| line_items | Yes | Non-empty array of line items. The invoice subtotal, tax_total, discount_total, and total are auto-computed by summing each item's (quantity × unit_price), then per-line discount, then per-line tax. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behaviors: auto-calculation of subtotal, discount_total, tax_total, total; generation of invoice_number in format INV-YYYY-NNNN; setting status to 'draft'; and returning the full invoice object. Annotations already indicate it is not read-only and not destructive, but the description adds context beyond annotations without contradiction.
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 concise yet comprehensive: 5 sentences that front-load the purpose, cover required/optional parameters, defaults, auto-calculations, and return value. Every sentence contributes essential information without redundancy.
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 creation tool with no output schema, the description covers the return value ('full invoice object') and important details like default values and auto-calculations. It does not mention error conditions or validation failures, but given the rich schema and annotations, the completeness is high.
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 adds value by explaining parameter defaults (currency defaults to client's default_currency then USD, due_date defaults to issue_date+30 days), constraints (line_items must be non-empty), and auto-calculation behavior. This provides meaning beyond the schema definitions.
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 the tool's purpose: 'Create a new invoice for an existing client.' It specifies the verb (create), resource (invoice), and includes detailed parameter requirements. The tool is distinct from siblings like invoice_send or invoice_mark_paid, which are for different actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for creating invoices but does not explicitly state when not to use it or mention alternatives. It says 'Required: client_id (UUID) and line_items' but lacks exclusions like 'Do not use this for drafts created elsewhere.' No sibling comparisons are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Populate the store with a realistic demo dataset: 8 clients across 5 archetypes (on-time, late-payer, high-value, new, chronic-late) and 25-45 invoices spanning the last 6 months (paid, sent, and overdue). Every invoice has line items, tax, payment history, and reminder metadata. Use this to evaluate InvoiceFlow via MCP Inspector without real Stripe, SendGrid, or PayPal credentials — invoice_list, cashflow_report, invoice_risk, and payment_reconcile all return meaningful results against the returned ids. Safe to call multiple times; each call appends a fresh batch with unique UUIDs. Returns counts plus sample_invoice_ids you can feed straight into invoice_risk or invoice_mark_paid.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations set destructiveHint:false and readOnlyHint:false. Description adds that each call appends a fresh batch with unique UUIDs, making it safe and non-destructive. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences in a single paragraph, front-loaded with purpose. Detailed but not verbose. Could be slightly more structured with bullet points, but it's effective.
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 zero parameters and no output schema, the description fully explains the tool's behavior, data generated, and integration with other tools. Mentions return values (counts and sample IDs). Complete for a seeding 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?
Input schema has zero parameters, so description cannot add param detail. Schema coverage is 100% (empty). Description explains what the tool does without parameters, which is sufficient.
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 the tool populates the store with a demo dataset, specifying 8 clients across 5 archetypes and 25-45 invoices with line items, tax, etc. It distinguishes from sibling tools by being a seeding tool for evaluation purposes.
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 to evaluate InvoiceFlow via MCP Inspector without real credentials' and 'Safe to call multiple times'. It implies when to use (testing) and not to use (real data). No explicit when-not to use alternatives, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search and filter invoices. Optional filters: status ("draft"|"sent"|"viewed"|"paid"|"overdue"|"cancelled"|"refunded"), client_id, min_amount, max_amount, date_from/date_to (ISO dates), overdue_only (boolean). Pagination via limit (default 50, max 200) and offset. Returns {total, invoices[]} where each invoice includes full line_items and payment state. Use this to build dashboards or drive invoice_remind/invoice_risk workflows.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Page size, 1–100. Defaults to 20. | |
| offset | No | Number of results to skip for pagination. Defaults to 0. | |
| status | No | Restrict to one lifecycle state: draft, sent, viewed, paid, overdue, cancelled, refunded. | |
| to_date | No | Filter to invoices with issue_date ≤ this ISO-8601 datetime. | |
| client_id | No | Restrict to invoices billed to this client UUID. | |
| from_date | No | Filter to invoices with issue_date ≥ this ISO-8601 datetime. | |
| max_amount | No | Inclusive upper bound on total amount. | |
| min_amount | No | Inclusive lower bound on total amount (any currency, no FX conversion). | |
| overdue_only | No | When true, returns only invoices whose due_date is past and status is not paid/cancelled/refunded. Defaults to false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds beyond this by specifying the return shape ({total, invoices[]}) and including that it returns full line_items and payment state.
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 and relatively concise, but it combines all information in a single paragraph. The contradiction with the schema reduces trust.
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 9 parameters with 100% schema coverage, no output schema, the description adequately provides return structure and usage context. The contradiction is a gap but overall completeness is good.
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 baseline is 3. However, the description contradicts the schema on limit default (says 50, schema says 20) and max (says 200, schema says 100), which will mislead an agent. It does add some explanatory context for filters like overdue_only.
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 the action ('Search and filter invoices') and resource, and distinguishes from siblings by noting the tool's output includes full line_items and payment state, with explicit use cases for dashboards and driving invoice_remind/invoice_risk workflows.
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 advises when to use this tool ('build dashboards or drive invoice_remind/invoice_risk workflows') and documents optional filters and pagination. It does not explicitly state when not to use it, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record a full or partial payment against an invoice. Updates amount_paid and amount_due; sets status="paid" only when the outstanding balance reaches zero. As a side effect, a fully-paid invoice updates the client payment_history (total_revenue, paid_invoices, avg_days_to_payment, late_payment_count) which invoice_risk then uses for future predictions. Returns a confirmation with the paid amount and remaining balance.
| Name | Required | Description | Default |
|---|---|---|---|
| amount | No | Amount paid in invoice currency; omit to settle the full remaining balance | |
| invoice_id | Yes | UUID of the invoice to update | |
| payment_method | No | How the payment was received (stripe|paypal|bank_transfer|credit_card|cash|check|crypto|other) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and destructiveHint=false, confirming it's a write operation. The description adds significant transparency by detailing side effects: updates amount_paid, amount_due, status only when balance reaches zero, and updates client payment_history. It also specifies the return value (confirmation with paid amount and remaining balance). No contradiction with 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?
The description is three sentences, front-loaded with the core purpose, followed by behavioral details and side effects. Every sentence adds value without redundancy or extraneous 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?
Given the medium complexity (3 parameters, no output schema, side effects), the description covers essential behavior, side effects, and return value. It could mention validation (e.g., invoice must exist and not be fully paid) but overall is adequate.
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 describes each parameter. The description reiterates that amount is optional for full balance settlement, but adds little beyond the schema. It integrates parameters into the tool's flow but doesn't provide new details per parameter.
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 the tool's purpose: 'Record a full or partial payment against an invoice.' It details the specific verbs and resources (updates amount_paid, amount_due, sets status conditionally) and distinguishes itself from sibling tools like invoice_create, invoice_list, and invoice_remind by focusing on payment recording.
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 does not explicitly state when to use this tool versus alternatives. While it describes the primary function and side effects, it lacks guidance on when not to use it (e.g., if payment already recorded) or references to alternative actions (e.g., invoice_create for new invoices).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record that a payment reminder has been issued for an unpaid invoice. Increments reminder_count, sets last_reminder_at, and advances draft → sent. Returns the generated reminder message (custom or default) so the caller can relay it through their preferred channel — this tool itself does not send email; use invoice_send for actual delivery. Safely refuses to remind on already-paid invoices.
| Name | Required | Description | Default |
|---|---|---|---|
| message | No | Custom reminder body; default is a friendly message referencing invoice number, amount, and due date | |
| invoice_id | Yes | UUID of the invoice to remind |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses full behavioral details: increments fields, changes status, returns a message, and safely refuses on paid invoices. No contradiction with annotations (readOnlyHint=false, destructiveHint=false).
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, no wasted words, front-loaded with the core action. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Completeness is high: describes return value (generated message), side effects, and safe refusal. No output schema, but description compensates fully. No gaps for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds meaning beyond the schema: explains that message is optional with a default friendly reminder referencing invoice details, and invoice_id is a UUID. Schema coverage is 100%, but description enriches understanding.
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 the tool records a payment reminder, specifying the side effects (increments reminder_count, sets last_reminder_at, advances status) and distinguishes it from invoice_send by noting it does not actually send email.
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 invoice_send for actual delivery and that it refuses to remind on paid invoices, providing clear when-to-use and when-not-to-use guidance. This distinguishes it from related tools like invoice_send and invoice_mark_paid.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Predict late-payment risk for a specific invoice on a 0-100 scale. The model combines invoice amount (relative to client average), client payment history (avg_days_to_payment, late_payment_count), days remaining until due date, and prior reminder_count. Returns {risk_score (0-100), risk_level ("low"|"medium"|"high"|"critical"), factors (array of {factor, impact, detail}), recommended_action (string), next_reminder_date (ISO string or null)}. Use for prioritizing collection effort on high-value invoices.
| Name | Required | Description | Default |
|---|---|---|---|
| invoice_id | Yes | UUID of the invoice to assess |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint true, indicating safe, non-destructive behavior. The description adds value by explaining the model inputs (invoice amount, client history, etc.) and output structure (risk score, factors, recommended action), which goes beyond 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?
The description is three sentences, front-loaded with the core purpose, and each sentence adds value: purpose, model inputs, output and use case. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one param, no output schema), the description fully covers purpose, behavioral model, return values, and usage context, making it complete for agent selection and invocation.
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% for the single parameter 'invoice_id', and the schema already describes it as a UUID. The description only says 'for a specific invoice', adding no additional meaning beyond the schema, so baseline score 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 clearly states the tool predicts late-payment risk for a specific invoice on a 0-100 scale, using a specific verb and resource. It also mentions the use case (prioritizing collection effort), distinguishing it from sibling tools like invoice_list or cashflow_report.
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 explicitly says to use for prioritizing collection effort on high-value invoices, providing clear context. However, it does not mention when not to use the tool or suggest alternatives, leaving a minor gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate the invoice PDF and deliver it to the client. Always generates the PDF and marks the invoice status="sent". Email delivery via SendGrid is attempted automatically when the SENDGRID_API_KEY environment variable is set; without it the PDF is still generated and the status still advances so the caller can handle delivery out-of-band. Returns a confirmation message with the PDF size.
| Name | Required | Description | Default |
|---|---|---|---|
| message | No | Custom body text for the email (default is a summary of amount and due date) | |
| invoice_id | Yes | UUID of an existing invoice (from invoice_create or invoice_list) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint=false, destructiveHint=false), the description discloses PDF generation, status change to 'sent', and conditional email attempt. No contradiction with 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?
The description is four sentences, each adding essential information: action, always generates, conditional email, return value. No redundant text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With good annotations and schema coverage, the description covers key behaviors (PDF, status, email) and return value. Could mention handling of already-sent invoices, but overall 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 the schema already documents parameters. The description adds value by specifying that 'message' defaults to a summary of amount and due date, which is not in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates and delivers an invoice PDF, marking it as 'sent'. It distinguishes from siblings like invoice_create (creates) and invoice_mark_paid (marks paid) by focusing on delivery and PDF generation.
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 explains when to use (to send invoice) and provides context on email delivery depending on environment variable. It mentions out-of-band handling as an alternative, but does not explicitly list exclusions or alternative tools by name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Match an incoming external payment (e.g. Stripe webhook, PayPal IPN, bank transfer) to an open invoice. Matching rule: the payer_email must equal the invoice client_email (case-insensitive) AND the payment_amount must equal the invoice amount_due within one cent. On match the invoice is marked paid, amount_paid/amount_due are updated, and client payment_history is recomputed exactly like invoice_mark_paid. Returns a reconciliation message on match or a "no match" message otherwise (no error). If multiple invoices match, the first one is reconciled.
| Name | Required | Description | Default |
|---|---|---|---|
| reference | No | External payment reference or transaction ID for your records | |
| payer_email | Yes | Email of the payer (matched against invoice client_email, case-insensitive) | |
| payment_amount | Yes | Amount received from the payer, in the invoice currency | |
| payment_method | No | Payment channel (stripe|paypal|bank_transfer|etc.) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description thoroughly discloses behavioral traits: on match, the invoice is marked paid, amounts are updated, and payment_history is recomputed. It also notes that no error is thrown on no match, and that the first invoice is reconciled when multiple match. This exceeds annotations which only indicate non-readonly and non-destructive.
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 concise, front-loaded with purpose, then matching rule, then effects, then return behavior. Every sentence adds value without redundancy.
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 description covers matching logic, effects, return behavior, and touches on edge cases (multiple matches). However, it does not explain the fate of 'reference' and 'payment_method' parameters (e.g., stored or ignored), and lacks detail on validation errors.
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 input schema covers 100% of parameters with descriptions. The description adds beyond schema by specifying the tolerance (within one cent) and case-insensitivity for email, providing additional context not in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool matches an incoming external payment to an open invoice, using specific verbs and resources. It distinguishes itself from siblings like invoice_mark_paid by focusing on reconciliation from external sources.
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 explains the matching rule and behavior when multiple invoices match, but does not explicitly state when to use this tool versus alternatives like invoice_mark_paid. The context of external payments vs manual marking is implied but not stated.
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.
v1.4.2client_manage11 fields changedInput schema / properties / address / descriptionAdded value: +"Optional billing street address."Input schema / properties / city / descriptionAdded value: +"Optional city."Input schema / properties / company / descriptionAdded value: +"Optional legal company name (printed on the invoice when set)."Input schema / properties / country / descriptionAdded value: +"Optional country (full name or ISO code — printed verbatim)."Input schema / properties / default_currencyAdded value: +{
+ "description": "Default invoice currency for this client. Used when invoice_create omits currency.",
+ "enum": [
+ "USD",
+ "EUR",
+ "GBP",
+ "CAD",
+ "AUD",
+ "JPY",
+ "CHF",
+ "TRY",
+ "BRL",
+ "INR"
+ ],
+ "type": "string"
+}Input schema / properties / email / descriptionAdded value: +"Primary billing email. Used as the dedup key — calling client_manage twice with the same email returns the existing record. Also used by payment_reconcile to match incoming payments."Input schema / properties / name / descriptionAdded value: +"Display name shown on invoices and reports. Required."Input schema / properties / name / minLengthAdded value: +1Input schema / properties / notes / descriptionAdded value: +"Internal notes about this client (not printed on invoices)."Input schema / properties / phone / descriptionAdded value: +"Optional phone number."Input schema / properties / tax_id / descriptionAdded value: +"Optional VAT / tax ID (e.g. EU VAT number, US EIN). Printed on PDFs that need it."invoice_create17 fields changedInput schema / properties / client_id / descriptionAdded value: +"UUID of the client this invoice is billed to. Must exist (created via client_manage). The stored client_email and client_name are snapshotted into the invoice at create time."Input schema / properties / currency / defaultRemoved value: -"USD"Input schema / properties / currency / descriptionAdded value: +"ISO 4217 code for the invoice. One of: USD, EUR, GBP, CAD, AUD, JPY, CHF, TRY, BRL, INR. Defaults to the client's default_currency, then USD."Input schema / properties / due_date / descriptionAdded value: +"Payment due date — same format as issue_date. Defaults to issue_date + 30 days. Used by invoice_risk and overdue detection."Input schema / properties / due_date / formatRemoved value: -"date-time"Input schema / properties / due_date / patternRemoved value: -"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"Input schema / properties / issue_date / descriptionAdded value: +"Invoice issue date — accepts either YYYY-MM-DD or full ISO-8601. Defaults to today (UTC)."Input schema / properties / issue_date / formatRemoved value: -"date-time"Input schema / properties / issue_date / patternRemoved value: -"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"Input schema / properties / line_items / descriptionAdded value: +"Non-empty array of line items. The invoice subtotal, tax_total, discount_total, and total are auto-computed by summing each item's (quantity × unit_price), then per-line discount, then per-line tax."Input schema / properties / line_items / items / properties / description / descriptionAdded value: +"Free-text description of the product or service. Appears verbatim on the PDF."Input schema / properties / line_items / items / properties / discount_percent / descriptionAdded value: +"Per-line discount percentage (0–100). Applied before tax. Defaults to 0."Input schema / properties / line_items / items / properties / quantity / descriptionAdded value: +"Number of units billed. Must be > 0. Decimals allowed for hourly billing (e.g. 1.5 hours)."Input schema / properties / line_items / items / properties / tax_rate / descriptionAdded value: +"Per-line tax percentage (0–100). E.g. 21 for Spanish IVA, 8.875 for NYC sales tax. Defaults to 0."Input schema / properties / line_items / items / properties / unit_price / descriptionAdded value: +"Price per unit before tax and discount, in the invoice currency. Must be ≥ 0."Input schema / properties / notes / descriptionAdded value: +"Free-text notes shown on the PDF (e.g. payment instructions, thank-you)."Input schema / properties / terms / descriptionAdded value: +"Free-text terms section on the PDF (e.g. \"Net 30. Late fee 1.5%/mo.\")."invoice_demo_seedinvoice_list9 fields changedInput schema / properties / client_id / descriptionAdded value: +"Restrict to invoices billed to this client UUID."Input schema / properties / from_date / descriptionAdded value: +"Filter to invoices with issue_date ≥ this ISO-8601 datetime."Input schema / properties / limit / descriptionAdded value: +"Page size, 1–100. Defaults to 20."Input schema / properties / max_amount / descriptionAdded value: +"Inclusive upper bound on total amount."Input schema / properties / min_amount / descriptionAdded value: +"Inclusive lower bound on total amount (any currency, no FX conversion)."Input schema / properties / offset / descriptionAdded value: +"Number of results to skip for pagination. Defaults to 0."Input schema / properties / overdue_only / descriptionAdded value: +"When true, returns only invoices whose due_date is past and status is not paid/cancelled/refunded. Defaults to false."Input schema / properties / status / descriptionAdded value: +"Restrict to one lifecycle state: draft, sent, viewed, paid, overdue, cancelled, refunded."Input schema / properties / to_date / descriptionAdded value: +"Filter to invoices with issue_date ≤ this ISO-8601 datetime."invoice_mark_paid7 fields changedInput schema / properties / amount / descriptionPrevious value: -"Amount paid (defaults to full amount due)"New value: +"Amount paid in invoice currency; omit to settle the full remaining balance"Input schema / properties / amount / exclusiveMinimumAdded value: +0Input schema / properties / amount / minimumRemoved value: -0Input schema / properties / invoice_id / descriptionPrevious value: -"The invoice ID"New value: +"UUID of the invoice to update"Input schema / properties / invoice_id / formatAdded value: +"uuid"Input schema / properties / invoice_id / patternAdded value: +"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"Input schema / properties / payment_method / descriptionPrevious value: -"How the payment was made"New value: +"How the payment was received (stripe|paypal|bank_transfer|credit_card|cash|check|crypto|other)"invoice_remind4 fields changedInput schema / properties / invoice_id / descriptionPrevious value: -"The invoice ID"New value: +"UUID of the invoice to remind"Input schema / properties / invoice_id / formatAdded value: +"uuid"Input schema / properties / invoice_id / patternAdded value: +"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"Input schema / properties / message / descriptionPrevious value: -"Custom reminder message"New value: +"Custom reminder body; default is a friendly message referencing invoice number, amount, and due date"invoice_risk3 fields changedInput schema / properties / invoice_id / descriptionPrevious value: -"The invoice ID to assess"New value: +"UUID of the invoice to assess"Input schema / properties / invoice_id / formatAdded value: +"uuid"Input schema / properties / invoice_id / patternAdded value: +"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"invoice_send4 fields changedInput schema / properties / invoice_id / descriptionPrevious value: -"The invoice ID to send"New value: +"UUID of an existing invoice (from invoice_create or invoice_list)"Input schema / properties / invoice_id / formatAdded value: +"uuid"Input schema / properties / invoice_id / patternAdded value: +"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"Input schema / properties / message / descriptionPrevious value: -"Custom message to include in the email"New value: +"Custom body text for the email (default is a summary of amount and due date)"payment_reconcile6 fields changedInput schema / properties / payer_email / descriptionPrevious value: -"Email of the payer"New value: +"Email of the payer (matched against invoice client_email, case-insensitive)"Input schema / properties / payment_amount / descriptionPrevious value: -"The payment amount received"New value: +"Amount received from the payer, in the invoice currency"Input schema / properties / payment_amount / exclusiveMinimumAdded value: +0Input schema / properties / payment_amount / minimumRemoved value: -0.01Input schema / properties / payment_method / descriptionAdded value: +"Payment channel (stripe|paypal|bank_transfer|etc.)"Input schema / properties / reference / descriptionPrevious value: -"External payment reference/ID"New value: +"External payment reference or transaction ID for your records"v1.0.0cashflow_reportclient_manageinvoice_createinvoice_listinvoice_mark_paidinvoice_remindinvoice_riskinvoice_sendpayment_reconcileScored across 10 tools
Each tool has a distinct purpose: portfolio summary, client management, invoice creation, demo seeding, invoice listing, payment recording, reminder tracking, risk prediction, PDF generation/delivery, and external payment reconciliation. No functional overlap exists.
Most tools follow a noun_verb pattern (e.g., invoice_create, invoice_list), but invoice_risk and invoice_demo_seed deviate (noun_noun and noun_noun_verb), and cashflow_report could be interpreted as compound noun. Inconsistent imperative style.
10 tools is well-scoped for an invoicing system, covering core workflows (client, invoice, payment, report, risk) without unnecessary bloat.
Missing client listing/deletion and invoice update/deletion; lacks refund handling. Demo seeding and risk tools add value, but CRUD gaps may cause agent failures in some workflows.
Invoicing you drive by talking to your AI: log time, raise invoices and track what's owed via MCP.
Compliant invoicing for freelancers: create, issue and track invoices from your AI agent.
Send invoices from Claude and ChatGPT. One sentence becomes a PDF with a Stripe payment link.
Invoice and receipt extractor: reads PDF and image invoices/receipts with AI, pulling date…
