A local MCP server for checking contractor invoices against Article 4, generating review materials and draft letters, and recording Sanne’s decisions.
List invoices by month, optionally scoped to a folder.
Read a specific invoice’s parsed lines and original text.
Look up work orders, indexed prices by execution date, and contract rules/readings.
Check one invoice in its batch context, or check all invoices and write review.html, review-list.md, and Dutch draft dispute letters.
Record Sanne’s decisions in decisions.csv, including pay, dispute, hold, sent, resolved, undo, and related details.
Open the local dashboard for Sanne to approve, dispute, or hold invoices; chat and dashboard decisions share the same log.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@invoice-check check the January invoices"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A local MCP server and a Claude skill that check contractor invoices against Article 4 of the framework contract and prepare everything Sanne needs to decide.
Woonkring Oostervelde is a housing association. Sanne in accounts payable checks the contractors' invoices by hand every month, and this project covers the 40 invoices of January. The tool applies Article 4 of the framework contract (prices, indexation, call-out fees, hours, extra work, VAT) with exact decimals, and the Claude skill drives it. Sanne decides everything in a local dashboard in the browser. Nothing is sent or paid automatically: the tool only proposes verdicts and drafts Dutch letters.
Related MCP server: mcp-ledger-server
Install uv once. Windows PowerShell: powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex". macOS or Linux: curl -LsSf https://astral.sh/uv/install.sh | sh (see docs.astral.sh/uv).
In Claude Desktop open Cowork, then Customize, then Plugins, and add the marketplace laughable-9/oostervelde-invoice-check.
Install the plugin invoice-check.
Start a Cowork task and say "check the January invoices". On first run a window opens to pick a folder; it is set up for you.
Requirements: a paid plan with code execution turned on. Local MCP servers work only in Cowork or Claude Code, not in normal chat.
claude plugin marketplace add laughable-9/oostervelde-invoice-check
claude plugin install invoice-check@oosterveldeOr, from a clone of this repo: claude --plugin-dir .. Then ask it to check the January invoices; on first run pick a folder and it is set up for you.
uv run --extra dev pytestA review list, output/<run>/review-list.md, with every invoice, its proposed verdict and the evidence.
Draft letters in Dutch for the disputed invoices, in the same run folder.
A dashboard (review.html) that opens in the browser, where Sanne approves, disputes or holds each invoice.
decisions.csv, an append-only log of her decisions.
server.py MCP server: tools, review list, letters, decisions log
dashboard.py local dashboard server that Sanne uses
report.py builds the review.html page
rules.py the Article 4 checks, all amounts in exact decimals
parsers.py reads the invoice, work order and price files
skills/invoice-check/SKILL.md the Claude skill: how to run the check
.claude-plugin/ plugin.json and marketplace.json
.mcp.json starts the MCP server through uv
pyproject.toml dependencies (mcp; dev extra: pytest), uv.lock pins them
tests/ pytest suite and expected.json (our verdicts and amounts)
invoices/ the 40 January invoices (text)
work-orders-export.csv, price-agreement-2025.csv, contract-excerpt.md input data
reference/ Sanne's verdicts on the first 10 invoices
output/ generated runs and comparison.md
NOTES.md how I read the contract, decisions and open pointsOver all 40 invoices: 17 approve, 22 dispute, 1 hold. To dispute: EUR 2,649.85 excl. VAT and EUR 3,412.47 incl. VAT. On the 10 invoices Sanne checked, we agree on 8 verdicts. See output/comparison.md for the differences and NOTES.md for the decisions.
Check the batch, write output//review.html (Sanne's one-stop page), review-list.md and one Dutch letter per disputed invoice (letters/.CONCEPT.txt until she decides).
| Name | Required | Description | Default |
|---|---|---|---|
| month | No | ||
| folder | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose the write side effects well: it creates a review HTML page, a markdown list, and per-invoice letter files at specific paths. However, it says nothing about overwrite behavior, whether existing files are replaced, whether anything is actually sent to customers, or cost/time of running over a whole batch.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded with the action and then the deliverables, with parentheticals used to explain the HTML page's purpose and the .CONCEPT.txt drafting convention. Dense but every clause carries information; only the slightly tangled grammar costs a point.
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 batch tool with no annotations and no output schema, the description does cover the return artifacts (the files written), which is the most important missing piece. It falls short on the two optional parameters and on safety/overwrite semantics, which an agent needs before invoking it on real data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and both parameters (month, folder) are nullable with no titles beyond 'Month'/'Folder'. The description never mentions either parameter, so an agent cannot tell whether month scopes the billing period or that folder selects the input batch, nor that omitting both means 'all'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action (check the batch) and enumerates concrete artifacts produced: output/<run>/review.html, review-list.md, and one Dutch letter per disputed invoice. The 'batch' framing implicitly distinguishes it from the single-invoice sibling check_invoice, though it never says so outright.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit statement of when to run this versus check_invoice or check_invoice-level workflows, and no prerequisites or exclusions. The only hint is the word 'batch' and the aside 'until she decides', which implies a draft-review workflow but leaves the agent to infer it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check one invoice. It runs in its batch so duplicates and credit notes are seen.
| Name | Required | Description | Default |
|---|---|---|---|
| folder | No | ||
| invoice | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral-disclosure burden. It usefully states that the check runs in its batch so duplicates and credit notes are seen, but it omits whether the operation is read-only or mutating, what permissions are required, what side effects occur, and what happens on failure.
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 short and front-loaded: the first sentence names the target and the second adds behavioral context. There is no filler, though the second sentence could be clearer about what 'its batch' means.
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 two-parameter tool with no annotations and no output schema, the description should explain the operation, the folder parameter, and the expected result. It provides only a minimal batch-context clue and leaves the agent without enough information to invoke the tool confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description needs to compensate. It only implies that 'invoice' identifies one invoice and says nothing about the optional 'folder' parameter, invoice format, or how batch membership is determined. This leaves both parameters substantially under-specified.
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 gives a verb and resource ('Check one invoice'), so the basic target is clear. However, 'check' is vague and the second sentence only adds batch context rather than explaining what checking actually does or returns. It partially distinguishes this from check_all by specifying 'one invoice', but not clearly enough to rise above a minimum-viable purpose statement.
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 say when to use this tool instead of siblings like read_invoice, list_invoices, or check_all. The batch note implies that duplicate and credit-note awareness is relevant, but it does not state that as an explicit usage condition or exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List price for a code on an execution date (YYYY-MM-DD or DD-MM-YYYY), indexed per Art. 4.2.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | ||
| folder | No | ||
| execution_date | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It usefully discloses accepted date formats and an indexing rule ('indexed per Art. 4.2'), but it does not explain behavior for missing codes, permissions, or the role of the optional folder parameter.
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 definition is a single front-loaded sentence with no filler. It packs the resource, required inputs, date format options, and domain indexing rule into compact wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with three parameters, the description covers the main purpose and date semantics. However, it leaves the folder parameter unexplained and does not describe the return value or error behavior, making it only minimally 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 description coverage is 0%, so the description must compensate for all three parameters. It clarifies the code and execution_date inputs, including accepted date formats, but completely omits the folder parameter, leaving one of three parameters undocumented in both schema and description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb-resource pair ('List price') and ties it to a code and execution date, so the tool's core purpose is clear. It does not explicitly differentiate from siblings, but none of the listed siblings appear to retrieve prices, so the risk of confusion is low.
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 says what the tool returns but gives no explicit guidance on when to use it, when not to use it, or which alternative tool to choose. The reference to Art. 4.2 provides domain context but is not usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Contract text (Dutch and English) and our reading for a rule (R0-R20), decision (Q1-Q21) or article (4.1-4.10).
| Name | Required | Description | Default |
|---|---|---|---|
| folder | No | ||
| rule_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It implies a read operation by saying it returns contract text and 'our reading,' but discloses nothing about permissions, error behavior, or output format.
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 dense sentence with no filler, and the parenthetical ranges communicate parameter formats efficiently. It is reasonably front-loaded with the returned content, though the sentence is slightly compressed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations and no output schema, the description should explain the read behavior and both parameters. It covers identifier types but omits folder semantics and behavioral context, making it incomplete for confident 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 0%, and the description does compensate for the required rule_id by naming the accepted identifier formats (R0-R20, Q1-Q21, 4.1-4.10). However, the optional 'folder' parameter is not explained in the description or schema, leaving a meaningful gap.
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 identifies the specific resource (contract text and the system's reading) and the identifier classes it accepts: rule R0-R20, decision Q1-Q21, or article 4.1-4.10. It lacks an explicit verb like 'retrieve' and there are no close siblings to differentiate from, so it is clear but not quite a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives or when not to call it; usage is only implied by needing contract text for an identifier. Prerequisites and workflow context are absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One row of the work order export (type, max hours, MU and GA approvals, build year).
| Name | Required | Description | Default |
|---|---|---|---|
| wo | Yes | ||
| folder | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and discloses almost nothing: no read-only statement, no not-found behavior, no permission requirements, no pagination or scoping notes. Mentioning the fields returned is the only behavioral hint.
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?
It is a single terse fragment with no wasted words, but the parenthetical field list is not front-loaded structure and the fragment lacks a clear subject-verb framing, making it under-specified rather than efficient.
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?
No output schema and no annotations mean the description must cover return format, safety, and parameters. It only lists some returned fields and leaves the 'folder' parameter, error behavior, and read-only nature unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so both parameters need explanation. The phrase 'work order export' weakly implies 'wo' is a work order identifier, but the optional 'folder' parameter is completely unexplained in both schema and description.
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 fragment 'One row of the work order export' describes the return shape (a single work order row) more than the action, but an agent can infer a single-record fetch. It does not name the identifier-based retrieval explicitly nor differentiate from siblings beyond being the only work-order tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no prerequisites, and no mention of alternatives among siblings like list_invoices or check_invoice. Usage is only obliquely implied by the word 'One row'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List invoices (contractor, number, date, work order, total). month: 'YYYY-MM', optional.
| Name | Required | Description | Default |
|---|---|---|---|
| month | No | ||
| folder | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. "List invoices" implies a read operation, but the description does not state permissions, ordering, pagination, or whether folder scoping is supported, so important behavioral context is missing.
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, compact, and free of filler. The parenthetical field list is slightly ambiguous, but overall the sizing is appropriate for a simple list tool.
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?
There is no output schema, so the description should fully explain return values and filtering behavior. It lists several expected fields, which helps, but it omits the folder parameter, ordering/pagination behavior, and usage relative to sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for two parameters. The description usefully explains the month format ('YYYY-MM') and optionality, but it completely omits the folder parameter, leaving half of the tool's inputs undocumented.
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 gives a specific verb and resource ("List invoices") and enumerates several invoice fields, so the agent can infer the tool returns invoice records. It does not explicitly distinguish itself from the sibling read_invoice tool or explain when listing is preferred over reading a single invoice.
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 only usage guidance is that month is optional and formatted as 'YYYY-MM'. There is no explicit statement about when to use this tool versus read_invoice, check_invoice, check_all, or other siblings, and no exclusion conditions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start the local dashboard (127.0.0.1 only) and return its URL. Sanne decides there or in the chat; both land in the same decisions.csv. month: 'YYYY-MM' or 'all'.
| Name | Required | Description | Default |
|---|---|---|---|
| month | No | ||
| folder | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full load, and it does disclose two real traits: the server binds to 127.0.0.1 only, and the call returns a URL. It omits what happens if the dashboard is already running, whether the process persists after the call returns, and why the month scoping matters — gaps that matter for a tool with side effects.
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, front-loaded with the core action and constraint, which is good. The second sentence leans on unexplained context ('Sanne', decisions.csv) that an agent cannot act on, so part of the text does not earn its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, and the description does cover the single return value (a URL) plus the localhost restriction. But for a server-launching tool with two optional, undocumented parameters, it says nothing about the dashboard's contents, the default folder, or lifecycle behavior — leaving real operational questions unanswered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It documents only 'month', giving the expected 'YYYY-MM' format and the 'all' sentinel — though that conflicts with the schema's null default, leaving ambiguity about whether null means all. The 'folder' parameter is not mentioned at all, so half the inputs remain opaque.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Start the local dashboard') plus the return value ('return its URL'), so the action is unmistakable. It does not name or differentiate itself from any sibling (record_decision in particular), and the follow-on sentence about 'Sanne' and decisions.csv blurs rather than sharpens the purpose.
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 clause 'Sanne decides there or in the chat; both land in the same decisions.csv' implies this is the UI-based counterpart to the chat/record_decision path, which is a usable hint. But it never states when an agent should open the dashboard versus calling a sibling directly, and there are no exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Parsed lines plus the original text of one invoice (id such as 'h-2026-0031').
| Name | Required | Description | Default |
|---|---|---|---|
| folder | No | ||
| invoice | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the return content ('parsed lines plus the original text') but says nothing about permissions, error behavior, folder semantics, or how the invoice is resolved.
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?
It is a single, front-loaded sentence with no wasted words. The key return content and ID example are presented immediately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool, the return content is described and the required ID has an example. However, the unexplained folder parameter and absence of annotations leave meaningful gaps for correct 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 0% with two parameters. The description gives a useful example format for the required invoice parameter, but the optional folder parameter is left completely unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific resource and return shape: parsed lines plus original text for one invoice, with an example ID format. It implicitly distinguishes itself from list_invoices by focusing on a single invoice, though it does not name alternatives explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides no guidance on when to use this tool versus siblings such as list_invoices or check_invoice. The usage is only implied by the phrase 'one invoice' and the example ID.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record Sanne's call in decisions.csv. decision: pay (pay in full), letter_ok (agree with the dispute: letter ready), sent (she sent the letter; sent_date YYYY-MM-DD, default today), hold (optional note), confirmed (unknown work order confirmed), not_ours (whole invoice disputed; reason required), disagree (verdict approve|dispute|hold, optional amount, reason required), resolved (closes a waiting dispute; kind credit_note|corrected_invoice|contractor_right|withdrawn and a reason), let_go (pay in full, all findings small; a repeat needs a reason), undo (back to the previous state). Old names approve, dispute, change still work. An overrule needs a reason. amount_excl_vat: amount disputed (letter_ok, disagree to dispute); defaults to the proposal.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | ||
| folder | No | ||
| reason | No | ||
| invoice | Yes | ||
| verdict | No | ||
| decision | Yes | ||
| sent_date | No | ||
| linked_invoice | No | ||
| amount_excl_vat | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and discloses substantial behavior: it writes to decisions.csv, defines a decision state machine, notes required reasons, defaults, legacy aliases, and that undo returns to the previous state. It still omits permissions, idempotency, and what the tool returns after recording.
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 action is front-loaded and most clauses carry useful constraint information, but the decision list is a dense semicolon-separated wall of text with nested parentheticals. It is appropriately sized for the domain but could be structured more scanably.
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 9-parameter mutation tool with no annotations, no output schema, and 0% schema coverage, the description covers decision semantics well but is not complete: it omits several parameters and does not explain the result of recording a decision. It is adequate but leaves clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains decision values, reason requirements, sent_date format/default, amount_excl_vat behavior, verdict options, and kind options for resolved, but leaves invoice, folder, and linked_invoice unexplained, so meaningful gaps remain.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: "Record ... in decisions.csv." The extensive decision-value list makes clear this is a decision-recording tool, distinct from the read/check-oriented siblings, though the phrase "Sanne's call" is internal jargon and the first sentence does not explicitly say it records an invoice decision.
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?
It gives detailed conditions for choosing each decision value, including when a reason is required, what defaults apply, and that old names still work. It does not explicitly say when to call this tool versus siblings like check_invoice or read_invoice, but the decision-value guidance is unusually concrete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0check_allcheck_invoiceget_priceget_ruleget_work_orderlist_invoicesopen_dashboardread_invoicerecord_decisionScored across 9 tools
The data-lookup tools (get_work_order, get_price, get_rule) and the action tools (check_invoice, check_all, open_dashboard, record_decision) are clearly distinct. The main friction is between list_invoices, read_invoice and check_invoice, which all operate on a single invoice but differ only subtly (browse vs. extract text vs. validate); descriptions do help, though an agent could still reach for read when check was meant.
All names are snake_case verb-first (list_, read_, get_, check_, open_, record_), which gives a strong, readable pattern. Minor deviations: check_all drops the object noun and uses the same verb as check_invoice for a batch-wide action, which slightly blurs the verb semantics.
Nine tools is well within the sweet spot and each maps to a distinct step in the invoice-review workflow: enumerate, inspect, fetch reference data, validate, surface UI, and record the outcome. Nothing appears redundant or bolted on.
The lifecycle is essentially end-to-end: list/read invoices, pull work-order, price and rule context, run single or batch checks, open a review dashboard, and persist decisions with a rich state machine. The notable gap is read-back: there is no tool to list prior decisions.csv entries or pending 'waiting disputes' other than via the dashboard, so an agent cannot inspect history in-band.
Evidence-backed UBL, PDF, and image invoice checks before approval or payment.
Create, send and track invoices from a conversation in Claude, ChatGPT or any MCP client that supports OAuth. Draft an invoice from one sentence or from last month's invoice for the same client, finalize it, email it to your client and send payment reminders for overdue ones. See revenue by month and by client, download PDFs and e-invoices (ZUGFeRD, XRechnung), and export DATEV packages for your tax advisor. Invoices follow the tax rules of 25 countries, including reverse charge and the small-business VAT exemption. New invoices are drafts, and nothing is emailed until you ask. Pay per invoice with no subscription: the first invoice is free.
Make PDF invoices from your AI chat: clients, numbering, VAT, overdue reports. All data is local.
Create PDF invoices from your AI chat: clients, numbering, VAT, overdue reports. All data is local.
