Beancount.io

List Journal Entries

listLedgerEntries

Read-onlyIdempotent

List journal entries, each with the entry_hash getEntryContext, updateEntrySource, and deleteEntrySource take. Narrows by account, filter, time, and directiveTypes; pages with limit and offset; total counts every match. Same data as the journal resource.

Input Schema

Name	Required	Description
`time`	No	Time expression, e.g. 2026-08.
`limit`	No	Page size, 1-1000; defaults to 20.
`filter`	No	Fava advanced-filter expression. `#tag` and `^link` match exactly; bare or "quoted" words match narration/payee (transactions) or comment (notes); `field:value` looks up `account` (posting accounts included), `tag`, `link`, `payee`, `narration`, `date`, or entry metadata; `field>100` compares amounts and bare `>100` matches posting units; `any(...)`/`all(...)` scope a test to postings; `-` negates, `,` is OR, juxtaposition is AND, parentheses group. Quote values holding a colon, a space, or a leading digit — `account:"Assets:Bank:Checking"`, `date:"2026"` — there are no escape sequences.
`ledger`	No	Target ledger as owner/name. Required for an unpinned credential; defaults to the credential's ledger restriction.
`offset`	No	Entries to skip; defaults to 0.
`account`	No	Account filter, e.g. Assets:Bank.
`directiveTypes`	No	Directive types to include, e.g. ["Transaction"]; case does not matter.

Output Schema

Name	Required	Description	Default
`ok`	Yes
`error`	No
`result`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 26, 2026

changedInput schema / properties / filter / description

Previous value: -"Filter expression: payee, narration, tag, or link."New value: +"Fava advanced-filter expression. `#tag` and `^link` match exactly; bare or \"quoted\" words match narration/payee (transactions) or comment (notes); `field:value` looks up `account` (posting accounts included), `tag`, `link`, `payee`, `narration`, `date`, or entry metadata; `field>100` compares amounts and bare `>100` matches posting units; `any(...)`/`all(...)` scope a test to postings; `-` negates, `,` is OR, juxtaposition is AND, parentheses group. Quote values holding a colon, a space, or a leading digit — `account:\"Assets:Bank:Checking\"`, `date:\"2026\"` — there are no escape sequences."

First observedOct 24, 2026

TDQS

A4.3/5.0

Behavior4/5

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

Annotations already establish read-only, idempotent, non-destructive behavior, so the description need not repeat safety semantics. It adds useful behavioral context by stating pagination via limit/offset and that total counts every match, though it leaves return-shape details to the output schema.

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 compact and front-loaded, leading with the core action and then covering filtering, pagination, total count, and the entry_hash relationship. Every clause contributes useful information without excess prose.

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 seven-parameter optional-filter listing tool with full schema coverage, annotations, and an output schema, the description supplies the needed framing. It covers purpose, filtering scope, pagination, total behavior, and the entry_hash linkage without needing to restate schema details.

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 description coverage is 100%, so the input schema already carries the detailed parameter semantics, including filter syntax and defaults. The description helpfully groups the parameters by filtering and pagination, but it does not materially add syntax or meaning beyond the schema.

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 uses a specific verb and resource: 'List journal entries.' It also explains that each entry includes the entry_hash consumed by getEntryContext, updateEntrySource, and deleteEntrySource, making the tool's output and downstream role clear.

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?

It clearly frames the tool as a filtered, paginated journal-entry listing and notes that it returns the same data as the journal resource. That gives useful context, but it does not explicitly compare against alternatives such as runBqlQuery or state when not to use this listing tool.

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

All Beancount.io tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.