Skip to main content
Glama
automatiabcn

invoiceflow-mcp

by automatiabcn
OverviewSchemaSourceRelated ServersDiscussions(1)Admin
TypeScript

Create Invoice

invoice_create
Idempotent

Creates a new invoice for an existing client using provided line items, auto-calculates subtotal, tax, discount, and total, generates a sequential invoice number, and returns the full invoice object ready for sending.

Instructions

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.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
notesNoFree-text notes shown on the PDF (e.g. payment instructions, thank-you).
termsNoFree-text terms section on the PDF (e.g. "Net 30. Late fee 1.5%/mo.").
currencyNoISO 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_dateNoPayment due date — same format as issue_date. Defaults to issue_date + 30 days. Used by invoice_risk and overdue detection.
client_idYesUUID 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_dateNoInvoice issue date — accepts either YYYY-MM-DD or full ISO-8601. Defaults to today (UTC).
line_itemsYesNon-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.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed17 schema fields changedv1.4.2
    • addedInput schema / properties / client_id / description
      Added 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."
    • removedInput schema / properties / currency / default
      Removed value: -"USD"
    • addedInput schema / properties / currency / description
      Added 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."
    • addedInput schema / properties / due_date / description
      Added value: +"Payment due date — same format as issue_date. Defaults to issue_date + 30 days. Used by invoice_risk and overdue detection."
    • removedInput schema / properties / due_date / format
      Removed value: -"date-time"
    • removedInput schema / properties / due_date / pattern
      Removed 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))$"
    • addedInput schema / properties / issue_date / description
      Added value: +"Invoice issue date — accepts either YYYY-MM-DD or full ISO-8601. Defaults to today (UTC)."
    • removedInput schema / properties / issue_date / format
      Removed value: -"date-time"
    • removedInput schema / properties / issue_date / pattern
      Removed 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))$"
    • addedInput schema / properties / line_items / description
      Added 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."
    • addedInput schema / properties / line_items / items / properties / description / description
      Added value: +"Free-text description of the product or service. Appears verbatim on the PDF."
    • addedInput schema / properties / line_items / items / properties / discount_percent / description
      Added value: +"Per-line discount percentage (0–100). Applied before tax. Defaults to 0."
    • addedInput schema / properties / line_items / items / properties / quantity / description
      Added value: +"Number of units billed. Must be > 0. Decimals allowed for hourly billing (e.g. 1.5 hours)."
    • addedInput schema / properties / line_items / items / properties / tax_rate / description
      Added value: +"Per-line tax percentage (0–100). E.g. 21 for Spanish IVA, 8.875 for NYC sales tax. Defaults to 0."
    • addedInput schema / properties / line_items / items / properties / unit_price / description
      Added value: +"Price per unit before tax and discount, in the invoice currency. Must be ≥ 0."
    • addedInput schema / properties / notes / description
      Added value: +"Free-text notes shown on the PDF (e.g. payment instructions, thank-you)."
    • addedInput schema / properties / terms / description
      Added value: +"Free-text terms section on the PDF (e.g. \"Net 30. Late fee 1.5%/mo.\")."
  2. First observedv1.0.0

TDQS

A4.2/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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.

Deploy Server

Other Tools