Skip to main content
Glama
matthiaskloft

evidence-ledger-mcp

relink_html

Connects each evidence card in an HTML summary to your own local PDFs, adding an "Open PDF" button at the cited passage and writing a private, openable copy beside the original.

Instructions

Give a reader links from a summary or embedded HTML file (from summarize_ledger or embed_ledger, e.g. one a co-author sent) to their own PDFs in folder (best: a sources/ folder of only the cited PDFs named <citation key>.pdf, kept out of version control; never a whole library) or in a link_map (a .private.json file as for resolve_links). Records are read from the data the file carries, sources matched as in resolve_links, and each evidence card gets a "Your copy" line with an "Open PDF" button opening the PDF at the passage's page, or else at the cited page, and, where the map gives an open link, an "Open in library" button with the page appended (?page=N). Writes <name>.private.html next to the original (a rerun replaces a copy it wrote, no other file) and never changes the original. The copy is marked private in its name, title and a banner, and is not indexed: tell the user it links to files on this computer and must not be shared or published; they share the original instead. Links are relative when the PDFs are inside the copy's folder (so a team sharing that folder can open them), absolute file:// links otherwise; they work when the copy is opened from disk, not from a website. Returns record ids by status.

Input Schema

NameRequiredDescriptionDefault
htmlYes
folderNo
link_mapNo
bibliographyNo

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.4.0

TDQS

A4.3/5.0
Behavior5/5

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

With no annotations provided, the description carries the full behavioral burden and does so thoroughly: it states what file is written, that a rerun replaces only a copy it wrote, that the original is never changed, and that the output is marked private and not indexed. It also discloses link behavior, relative versus absolute paths, and the limitation that links work from disk rather than a website.

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 is front-loaded with the purpose and the key usage constraints. It is dense and could be easier to scan with paragraphs or bullets, but most sentences add necessary operational or privacy context rather than repeating structured fields.

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?

For a complex file-mutating tool with no annotations and an output schema, the description supplies strong operational context: input sources, matching behavior, output naming, privacy warnings, and link path rules. The main completeness gap is the unexplained `bibliography` parameter, but the required `html` path and the core file/link behavior are sufficiently covered.

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 0%, so the description must explain all four parameters. It gives useful semantics for `html`, `folder`, and `link_map`, including expected file types and constraints, but it never mentions the `bibliography` parameter, leaving one optional parameter undocumented in both schema and description.

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 states a specific transformation: it gives readers links from a `summarize_ledger`/`embed_ledger` HTML file to their own PDFs and writes a marked-private `<name>.private.html` copy. It also distinguishes the tool from its source siblings by naming `summarize_ledger`, `embed_ledger`, and `resolve_links`.

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 usage context: the input should come from `summarize_ledger` or `embed_ledger`, the `folder` should ideally be a `sources/` folder of cited PDFs, and it warns against pointing at a whole library. It does not explicitly compare when to choose `relink_html` instead of a sibling such as `resolve_links`, but the practical constraints and alternatives for PDF lookup are well covered.

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