contabridge-mcp

Overview Schema Source Related Servers Discussions Admin

Book invoices with VAT as journal

invoices_to_journal

Read-onlyIdempotent

Book issued and received invoices as journal entries with VAT split, rechecking totals and flagging duplicates or mismatches for review.

Instructions

Book issued and received invoices (facturas emitidas y recibidas) as journal entries with VAT split out.

Read each invoice (PDF, photo, Facturae, email) yourself and pass its figures; this tool does the bookkeeping deterministically. Per invoice: {"kind": "issued"|"received", "number": "F-2026-031", "date": "2026-02-28", "nif": "B12345678", "name": "Talleres Ruiz SL", "taxes": [{"base": "1000.00", "rate": "21", "vat": "210.00" (optional, checked), "recargo_rate": "5.2" (optional)}], "irpf_rate": "15" or "irpf_amount": "150.00" (optional), "total": "1060.00" (optional but recommended: checked), "account": "43000012" (optional), "counterpart_account": "62300000" (optional, default 700 / 600), "concept": optional}. Shortcut for one VAT rate: "base" + "vat_rate". Negative amounts = factura rectificativa (sides swap).

Issued: Debe 430 total (+ 473 IRPF retenido por el cliente) / Haber 700 base + 477 IVA. Received: Debe 600 base + 472 IVA / Haber 4751 IRPF + 400 total. Tax is recomputed (base x rate, half up); a 1-cent difference with the invoice total is absorbed in the largest tax line, more than that sends the invoice to review with the reason, unbooked. Duplicates (same kind + NIF + number) also go to review.

Args: accounts: Override default roots {customers 430, suppliers 400, sales 700, purchases 600, vat_output 477, vat_input 472, irpf_withheld 4751, irpf_suffered 473}. party_accounts: {NIF: subaccount}, e.g. {"B12345678": "43000012"}. Invoices with no account are booked to the generic 430/400 and listed in generic_party_account so the accountant assigns them. vat_accounts: {rate: subaccount}, e.g. {"21": "47700021", "10": "47700010", "re5.2": "47700052"}. target_format / account_digits / company_code / ...: as in build_journal.

Returns the import file, vat_summary (base and cuota per rate for the libro registro / modelo 303), vat_register (one row per invoice and rate), review and open_items to pass to bank_to_journal.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "invoices": "<invoices>"
    },
    "name": "invoices_to_journal"
  }
}

Input Schema

Name	Required	Default
`accounts`	No
`invoices`	Yes
`a3_format`	No
`date_style`	No
`fiscal_year`	No
`company_code`	No	00001
`vat_accounts`	No
`account_split`	No
`decimal_comma`	No
`target_format`	No	csv
`xero_tax_rate`	No	No VAT
`account_digits`	No
`party_accounts`	No
`start_entry_number`	No

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.3.0Nov 9, 2026

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Well beyond the annotations: it discloses rounding behaviour (base x rate, half up), 1-cent tolerance absorbed into the largest tax line, larger discrepancies routed unbooked to `review`, duplicate detection on kind+NIF+number, default counterpart accounts, and that negative amounts mean a factura rectificativa with swapped sides. It does not cover permission/auth concerns or transactionality, but for a file-generating computation tool that is minor.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, then the per-invoice payload example, then posting rules, args and returns – a logical order with no filler sentences. The Debe/Haber posting lines are dense accounting jargon and the description is long, but each block carries distinct information needed to call the tool correctly.

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?

Covers the core risk areas (tax recomputation, review routing, duplicates, account mapping) and, since an output schema exists, the short returns sentence is adequate rather than required. The remaining gap is the cluster of formatting parameters that are delegated to build_journal without explanation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must carry the load; it does so well for the high-value parameters (accounts, party_accounts, vat_accounts, and the full per-invoice object with optional/required flags). However, seven parameters (a3_format, date_style, fiscal_year, account_split, decimal_comma, xero_tax_rate, start_entry_number) are only covered by 'as in build_journal', forcing a lookup in another tool's documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: book issued and received invoices as journal entries with VAT split out, and clarifies the division of labour (the agent extracts figures, the tool does deterministic bookkeeping). The Spanish/English naming and the per-invoice contract make the scope unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Makes the usage context explicit – read the PDF/photo/Facturae/email yourself and pass figures in – and describes the downstream flow: `review` items are unbooked, `open_items` are passed to bank_to_journal. It does not explicitly say when to prefer build_journal over this tool, so the alternative routing is only implied by the 'as in build_journal' cross-reference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server