mcp-ledger-server-ts

Route invoice decision

route_exception

DestructiveIdempotent

Record an invoice routing decision—approve, hold, or reject—with a reason code while server-enforced policy checks blocking findings, overrides, and finality.

Instructions

Record a routing decision for an invoice: approve, hold or reject, with a reason code. The server re-runs the match itself and enforces policy: approving an invoice with blocking findings is refused unless reasonCode=MANUAL_OVERRIDE, override=true and a note of 10+ chars (and duplicates can never be approved); reject needs a blocking finding with the same reason code; approved/rejected invoices are final. Idempotent: repeating the identical decision returns changed=false. Prefer "hold" when unsure, it is reversible. Changes the ledger.

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": {
      "invoiceId": "<invoiceId>",
      "action": "<action>",
      "reasonCode": "<reasonCode>"
    },
    "name": "route_exception"
  }
}

Input Schema

Name	Required	Description
`note`	No	Free-text justification shown to auditors. Required (10+ chars) with MANUAL_OVERRIDE.
`action`	Yes	approve = release for payment; hold = pause for human review (reversible); reject = final refusal.
`override`	No	Set true ONLY when a human explicitly told you to force a decision against the match result.
`invoiceId`	Yes	Ledger invoice id, e.g. "inv_003". Obtain ids from list_invoices.
`reasonCode`	Yes	Why. Approve needs MATCHED_OK or WITHIN_TOLERANCE (or MANUAL_OVERRIDE). Hold/reject need a problem code such as PRICE_VARIANCE, QTY_VARIANCE, NO_RECEIPT, NO_PO, VENDOR_MISMATCH, CURRENCY_MISMATCH, DATE_ISSUE or DUPLICATE.

Output Schema

Name	Required	Description
`status`	Yes
`changed`	Yes	false when this exact decision was already recorded (safe replay).
`decision`	Yes
`invoiceId`	Yes
`matchOutcome`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Nov 6, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=true) by disclosing the server-side re-match, the exact policy gates for approval, that duplicates can never be approved, the finality of approved/rejected states, and that repeating an identical decision returns changed=false. 'Changes the ledger' makes the destructive consequence concrete rather than merely flagged.

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-loads purpose, then policy, then idempotency, then the advisory to hold — every sentence carries load and none repeats the schema. The dense single block of policy clauses makes it slightly harder to scan than a bulleted breakdown would be.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, idempotent, five-parameter state-changing tool it covers everything an agent needs: the safety preconditions, failure modes, reversibility of hold, finality of approve/reject, and idempotency semantics. An output schema exists, so return-value detail is correctly left out.

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 the baseline is 3; the description earns more by explaining cross-parameter conditions the schema documents only per-field — the joint MANUAL_OVERRIDE + override=true + 10-char note requirement, and the coupling between reason code and action. It does not add format or id-example detail beyond the schema, so it falls short of a 5.

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 — 'Record a routing decision for an invoice' — plus the full action vocabulary (approve, hold, reject) and the required reason code. It is clearly the write-side decision tool, distinct from the read-oriented siblings list_invoices, get_invoice, match_invoice_to_po and ledger_summary.

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?

Gives concrete guidance on action selection and preconditions: prefer 'hold' when unsure because it is reversible, approve is refused under blocking findings without MANUAL_OVERRIDE/override/note, and reject requires a blocking finding with a matching reason code. It does not explicitly name sibling tools or state when to fetch data first (invoiceId comes from list_invoices per the schema, not the description), so it stops just short of full routing guidance.

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

Deploy Server