Beancount.io

Delete Ledger Files

deleteLedgerFiles

DestructiveIdempotent

Delete files in one atomic commit; pass each file's sha from readLedgerFiles to refuse the delete if it changed since. Deleting a file still included by another ledger file is refused as BAD_USER_INPUT naming the includers; remove the include from the including file(s) first, then delete. An include counts when its target resolves to the deleted path the way the ledger loads it, relative to the directory of the file that declares it, and glob includes never count. Each new/resulting file is limited to 1 MiB of UTF-8 bytes, including dry runs. dry_run previews without committing: the same refusal as the commit, plus a unified diff per touched file and bean-check's verdict over the projected contents.

Input Schema

Name	Required	Description
`files`	Yes
`dryRun`	No	Alias of dry_run, as REST and GraphQL spell it.
`ledger`	No	Target ledger as owner/name. Required for an unpinned credential; defaults to the credential's ledger restriction.
`dry_run`	No	If true, validates all operations and returns a preview without committing.
`message`	No	Alias of description, as REST and GraphQL spell it.
`description`	No	One sentence describing what these changes do. Shown to the user for approval and used verbatim as the commit message.

Output Schema

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

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedOct 26, 2026

addedInput schema / properties / dryRun

Added value: +{
+  "description": "Alias of dry_run, as REST and GraphQL spell it.",
+  "type": "boolean"
+}

removedInput schema / properties / dry_run / default
```
Removed value: -false
```

addedInput schema / properties / message

Added value: +{
+  "description": "Alias of description, as REST and GraphQL spell it.",
+  "type": "string"
+}

changedInput schema / required

Previous value: -[
-  "description",
-  "files"
-]New value: +[
+  "files"
+]

First observedOct 24, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds substantial context: atomic commit behavior, BAD_USER_INPUT refusal naming includers, the 1 MiB UTF-8 limit including dry runs, and dry-run preview contents with unified diffs and bean-check verdicts.

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?

The description front-loads the purpose and then adds only operationally relevant constraints. It is dense and has some long sentences, but every clause about sha, includes, size limits, and dry runs earns its place for a destructive tool.

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?

Given the output schema exists, the description need not explain return values. It covers deletion behavior, refusal conditions, include resolution rules, size limits, and dry-run previews, leaving no critical gaps for an agent invoking this destructive tool.

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 description coverage is high at 83%, so the schema already documents most parameters. The description still adds meaning by tying sha to readLedgerFiles and by detailing what dry_run actually returns beyond the schema's generic preview wording.

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 ('Delete files') plus the distinctive scope 'in one atomic commit'. The refusal mechanics and include handling make it clearly distinguishable from sibling tools like updateLedgerFiles or renameLedgerFile.

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?

Explains key preconditions clearly: pass sha from readLedgerFiles to avoid overwriting concurrent changes, remove includes from including files before deletion, and use dry_run for preview. It does not explicitly name when to choose this over sibling mutation tools, so it falls short of full alternative routing.

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.