mcp-ledger-server-ts

List invoices

list_invoices

Read-onlyIdempotent

Retrieves accounts-payable invoices, optionally filtered by status or vendor, and returns compact summaries with IDs and key details so you can discover invoice IDs.

Instructions

List invoices in the accounts-payable ledger, optionally filtered by status or vendor. Returns compact summaries (id, vendor, PO, total, dates, status), sorted by id. Use this first to discover invoice ids. Read-only.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "list_invoices"
  }
}

Input Schema

Name	Required	Description
`limit`	No	Maximum number of invoices to return (default 25).
`status`	No	Only return invoices in this status. "received" = not yet reviewed, "on_hold" = waiting for a human or more data.
`vendorId`	No	Only return invoices from this vendor, e.g. "V-ACME".

Output Schema

Name	Required	Description	Default
`count`	Yes
`invoices`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Nov 6, 2026

TDQS

A4.2/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so 'Read-only' in the description is redundant. The description does add genuine behavior: the projection returned ('compact summaries'), the default sort ('sorted by id'), and the scoping caveat that these are summaries rather than full records. It omits what happens when results exceed the 100 limit, which matters for a listing tool.

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?

Three short sentences, front-loaded with the scope, then the return shape, then the routing hint, with zero filler. Every clause carries information the agent needs.

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?

Rich annotations plus an output schema mean the safety profile and return contract are covered, and the description correctly stops short of re-explaining them. The one gap is truncation/pagination behavior when limit is hit, which is not stated anywhere the agent can see.

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 100% and includes enum value meanings for status, so the schema already carries the parameter semantics. The description only restates that status and vendor filters exist, adding no format, default, or interaction detail beyond the schema, so the baseline 3 applies.

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 ('List invoices in the accounts-payable ledger') plus the optional filters, and adds 'Use this first to discover invoice ids', which implicitly separates it from get_invoice without naming it. An agent knows exactly what this returns and how it relates to the detail-fetch sibling.

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 clear sequencing guidance ('Use this first to discover invoice ids'), which tells the agent to call this before per-invoice tools. It lacks an explicit when-not or a named alternative (get_invoice, ledger_summary), so it falls 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