evidence-ledger-mcp

Overview Schema Source Related Servers Discussions Admin

import_ledger

Convert older-schema or hand-built ledgers into a new JSON Lines ledger, upgrading schema versions and preserving IDs, dates, and quote hashes; invalid records are still written for repair.

Instructions

Import a ledger of any older schema version, or a pre-schema hand-built list, as a new JSON Lines ledger at path, which must not exist. The source is YAML, JSON ({"ledger": header, "records": [...]} or a plain list of records) or JSON Lines (header on the first line, one record per line). A plain list needs work (title and type); a source with a header must not be given work. The header's schema_version is upgraded step by step to this server's (a newer or unknown version is refused); records keep their ids, claim ids, provenance dates and quote hashes (an older sha256-n1 hash stays valid), and the server assigns missing ids and claim ids and the hash of a quote lacking one. Records that fail validation are still written so that they can be fixed; the result holds path, records, from_version (null for a pre-schema list), steps (such as "0.2.0→0.3.0") and problems (all found at once, as validate_ledger reports them, empty if valid).

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": {
      "source": "<source>",
      "path": "<path>"
    },
    "name": "import_ledger"
  }
}

Input Schema

Name	Required	Description	Default
`path`	Yes
`work`	No
`source`	Yes

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.5.0Nov 3, 2026

TDQS

A4.7/5.0

Behavior5/5

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

With no annotations at all, the description carries the full burden and does so well: it discloses that writes happen even when records fail validation, that the header's schema_version is upgraded step by step and refused if newer/unknown, that ids/claim ids/hashes are assigned when missing, and that older `sha256-n1` hashes stay valid. It also renames `validate_ledger` as the reference for the `problems` semantics, which is meaningful behavioral context rather than restatement.

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?

It is a single front-loaded paragraph that starts with the action and destination before drilling into formats and semantics, and every sentence carries information. It is dense and parenthetical-heavy enough that a reader must parse it in one pass, but nothing is genuinely wasted.

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 version-upgrading import with zero annotation coverage, the description covers accepted formats, version refusal, id/hash assignment, invalid-record tolerance, and upgrade steps. It also enumerates the return fields (`path`, `records`, `from_version`, `steps`, `problems`), which overlaps the output schema but is not harmful for a tool whose result shape matters to follow-up calls.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must compensate, and it does for all three parameters: `source` is defined by its three accepted encodings (YAML, JSON object with ledger/records, plain list, JSON Lines with first-line header), `path` is constrained to non-existent targets, and `work` is tied to the plain-list case with its required `title` and `type`. That adds real meaning the bare `string`/`object` schema cannot convey.

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 opens with a specific verb+resource ('Import a ledger') and immediately scopes it: any older schema version or a pre-schema hand-built list, converted to a new JSON Lines ledger at `path`. That scope cleanly separates it from siblings like create_ledger, validate_ledger, and export_ledger, which an agent can rule out without opening any schema.

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 gives clear preconditions — `path` must not exist, a plain list requires `work`, a headered source must not pass `work`, and newer/unknown versions are refused — so the agent knows which inputs are legal. It stops short of explicitly naming alternatives (e.g., use validate_ledger to check without writing, create_ledger for a fresh ledger), so routing is inferred rather than stated.

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

Deploy Server