Skip to main content
Glama
amos689

paper-preflight

by amos689
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Propose fixes for a bibliography

preflight_bib_fix
Read-onlyIdempotent

Propose unified diffs that fix broken bibliography identifiers, add missing DOIs, and optionally update metadata from verified records; you apply the diff yourself.

Instructions

Propose edits to the .bib files, taken from the verified records, as a unified diff. Nothing is written: apply the diff with your own editing tools.

level="safe" only fixes identifiers written so that links break and adds DOIs the registry has; level="unsafe" also rewrites authors, title, year and venue from the record, removes identifiers that point to another work and cites a preprint as its published version (keeping the eprint). Show unsafe diffs to the user before applying them. References nobody could find are never "fixed".

Use it after preflight_check has reported errors or warnings in the bibliography.

Input Schema

NameRequiredDescriptionDefault
keysNoOnly these citation keys (default: every key with a fix).
pathNoA LaTeX project folder or .tex file, a Markdown, Quarto or Typst manuscript (.md, .qmd, .typ), a Word manuscript (.docx), or a reference list (.bib, .bbl, .json, .ris, .yml, .txt, .pdf), relative to the workspace root (default: the root itself)..
levelNosafe: only broken identifiers and missing DOIs; unsafe: also authors, title, year and venue from the record.safe
offlineNotrue: answer only from the local cache and never touch the network (references not cached yet come back as unverified).

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv1.0.0
    • addedInput schema / properties / keys / description
      Added value: +"Only these citation keys (default: every key with a fix)."
    • addedInput schema / properties / level / description
      Added value: +"safe: only broken identifiers and missing DOIs; unsafe: also authors, title, year and venue from the record."
    • addedInput schema / properties / offline / description
      Added value: +"true: answer only from the local cache and never touch the network (references not cached yet come back as unverified)."
    • addedInput schema / properties / path / description
      Added value: +"A LaTeX project folder or .tex file, a Markdown, Quarto or Typst manuscript (.md, .qmd, .typ), a Word manuscript (.docx), or a reference list (.bib, .bbl, .json, .ris, .yml, .txt, .pdf), relative to the workspace root (default: the root itself)."
  2. First observedv0.1.0

TDQS

A4.7/5.0
Behavior5/5

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

Goes well past the readOnlyHint/idempotentHint annotations: it states nothing is written and the caller must apply the diff, enumerates exactly what safe versus unsafe rewrites, warns to show unsafe diffs to the user first, notes unfindable references are never fixed, and explains the offline/cache behaviour. These are consequential side-effect and workflow facts an agent cannot infer from annotations.

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?

Front-loads the core action and the no-write guarantee, then layers level semantics, the user-confirmation caveat, and the sequencing hint. Every sentence carries information; nothing is filler.

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?

With an output schema present, return values need not be described, and the description still covers the diff format, mutation scope, level trade-offs, and the preflight_check dependency. An agent has everything needed to call this correctly.

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 coverage is 100%, so the baseline is 3, but the description meaningfully elaborates the `level` enum beyond the schema's one-line summary by listing the specific edits each level performs and the removal semantics of `unsafe`.

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 ("Propose edits"), a precise resource (.bib files sourced from verified records) and the output form (a unified diff). The read-only framing plus the sequencing with preflight_check makes it distinguishable from every sibling at a glance.

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?

Explicitly says to use it after preflight_check has reported errors or warnings, which is a clear triggering condition, and it explains which level to reach for. It stops short of naming alternatives (e.g. preflight_bib_lookup) or stating when not to use it, so it is strong context without full routing.

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

Deploy Server

Other Tools