Model Context Protocol向けのAI活用型請求書自動化ツール
InvoiceFlowは、プロフェッショナルなPDF請求書の作成、AIによる支払い遅延リスクの予測、リマインダーの自動送信、入金と請求書の照合、キャッシュフローの追跡をすべてMCPプロトコル経由で実現します。
プロフェッショナルなPDF請求書作成: 明細、税金、割引、多通貨（10通貨）対応
AIリスク予測 (0-100): 請求金額、クライアントの履歴、期日、リマインダー履歴に基づく予測
スマートリマインダー: リスクレベルに応じた段階的な通知
支払い照合: 金額と支払者メールアドレスによる入金と請求書の照合（プラットフォーム非依存 — 手動入力またはWebhook経由の支払いデータに対応）
キャッシュフローレポート: 回収率、予測収入、クライアント別の内訳
クライアント管理: 支払い履歴の自動追跡
連番請求書番号: (INV-2026-0001, INV-2026-0002, ...)
10個のMCPツール + 4個のMCPリソース: 請求業務のライフサイクル全体をカバー
Related MCP server: Frihet MCP Server
mcpize.com で InvoiceFlow MCP を検索
Install をクリックし、サブスクリプションプランを選択
MCP対応クライアントでツールとリソースが自動的に利用可能になります
git clone https://github.com/enzoemir1/invoiceflow-mcp.git
cd invoiceflow-mcp
npm ci
npm run buildMCPクライアントの設定に追加:
{
"mcpServers": {
"invoiceflow": {
"command": "node",
"args": ["path/to/invoiceflow-mcp/dist/index.js"]
}
}
}新規クライアントを作成します。請求書作成前に必須です。
明細付きの請求書を作成します。小計、税金、割引、合計を自動計算します。連番の請求書番号 (INV-YYYY-NNNN) を生成します。
請求書PDFをメールで送信します（SENDGRID_API_KEYが必要）。ステータスを「送信済み」に更新します。
ステータス、クライアント、金額範囲、日付範囲、または期限超過ステータスで請求書をフィルタリングします。ページネーションをサポートしています。
請求書を支払い済み（全額または一部）としてマークします。クライアントの支払い履歴を自動的に更新します。
支払いリマインダーを送信します。リマインダー回数をインクリメントします。カスタムメッセージをサポートしています。
AIによる支払い遅延リスク予測 (0-100)。リスクレベル、要因の内訳、推奨アクション、次回リマインダー日を返します。
キャッシュフローの概要を生成します：請求総額、回収額、未払い額、期限超過額、回収率、30日間の予測。
金額と支払者メールアドレスに基づいて、入金を請求書と照合します。自動的に支払い済みとしてマークします。
リソース | 説明 |
| 未払い請求書一覧 |
| 期限超過請求書一覧 |
| 月次キャッシュフロー概要 |
| 支払い履歴付きクライアント一覧 |
4つの加重要因を使用して請求書を0〜100でスコアリングします：
要因 | 重み | 測定内容 |
請求金額 | 20% | 金額が高いほどリスクが高い |
クライアント履歴 | 35% | 支払い率、遅延支払い、平均日数 |
期日 | 30% | 期日までの日数/経過日数 |
リマインダー | 15% | 送信済みリマインダー数 |
リスクレベル: 低 (0-30), 中 (31-60), 高 (61-100)
.env.example を .env にコピーし、必要な変数を設定してください：
cp .env.example .env変数 | 必須 | 説明 |
| メール送信時 | SendGrid経由で請求書とリマインダーを送信 |
SendGridはオプションです。InvoiceFlowは、請求書作成、リスクスコアリング、キャッシュフローレポート、照合において完全にオフラインで動作します。送信メールが必要な場合にのみSendGridを追加してください。
payment_reconcile ツールは現在、提供された金額（CSV、Webhook、または手動入力）を保存済みの請求書と照合します。Webhookリスナーを備えたStripeおよびPayPal APIの直接統合はv2.0で計画されています。進捗状況は issues を参照してください。
> 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
プラン | 価格 | 月間請求書数 | 機能 |
Free | $0 | 5 | 基本的なPDF請求書 |
Pro | $12/月 | 100 | AIリスクスコアリング、スマートリマインダー、照合 |
Business | $29/月 | 500 | 多通貨、キャッシュフローレポート、優先サポート |
MCPize Marketplace で利用可能です。
npm run dev # Hot reload
npm run build # Production build
npm test # Run tests
npm run inspect # MCP Inspectorテストはコアビジネスロジックをカバーしています：
ストレージ — CRUD操作、フィルタリング、連番請求書番号
リスクモデル — 4つの加重要因を持つAIスコアリングエンジン、リスク分類
キャッシュフロー — レポート生成、回収率、予測、クライアント別内訳
npm test # Run all tests
npx vitest --watch # Watch modeInvoiceFlowは Freeモード で提供されます。invoice_demo_seed、client_manage、invoice_create、invoice_list、invoice_mark_paid、invoice_remind はオープンです。以下のツールには Proライセンス が必要です：
invoice_send — PDF生成 + SendGridメール配信
invoice_risk — 支払い遅延リスク予測
payment_reconcile — Stripe/PayPal/銀行振込と請求書の照合
cashflow_report — ポートフォリオ全体のキャッシュフロー + 30日予測
Proライセンスを購入 (€12, 永続ライセンス, 3台まで): https://automatiabcn.lemonsqueezy.com/buy/2d439c05-f463-4137-8883-950e8ee1112d
または Indie MCP Stack Bundle (€69, 4サーバーすべて) を入手してください。
export LEMONSQUEEZY_LICENSE_KEY=YOUR-KEY-HEREまたはMCPクライアント設定にて：
{
"mcpServers": {
"invoiceflow-mcp": {
"command": "npx",
"args": ["-y", "invoiceflow-mcp-server"],
"env": { "LEMONSQUEEZY_LICENSE_KEY": "YOUR-KEY-HERE" }
}
}
}検証はローカルで24時間キャッシュされるため、初回実行後は完全にオフラインで動作可能です。
MITライセンス。詳細は LICENSE を参照してください。
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.
Turn AI-host work into invoices you review before send — Continue as guest or OAuth via hosted 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.
