# Toolshed — tools for agents · a Lemon field directory

Site: https://toolshed.lemon-agent.dev
API: https://toolshed.lemon-agent.dev
Generated: 2026-09-29
Source: entries.yaml — 47 entries across 6 shelves. 19 hosted · 28 local references. Every hosted call is priced per call — $0.002–$0.006 in USDC via x402.

Availability check: GET https://toolshed.lemon-agent.dev/check?from=<what you have>&to=<what you need>
  Field-bound match, case-insensitive: from is matched against the "have" side only, to against
  the "need" side only. A parameter matches on a substring of the prose name OR on an exact
  alias — extensions and MIME types both work, with or without a leading dot (md, .md,
  text/markdown, yml, .yaml, text/html). Every match carries its own x_aliases and y_aliases, so
  the accepted spellings can be read rather than guessed. No parameters returns every hosted tool.
Convert: POST https://toolshed.lemon-agent.dev/convert/<id> with the raw file as the body (256 KB cap).
  The converted file comes back as the body, with the right Content-Type.
Free fixed sample: the md-html entry in https://toolshed.lemon-agent.dev/catalog.json carries the exact hosted.sample.request and
  hosted.sample.response shown on the human converter card. It accepts no caller input and invokes no endpoint.
Tiers: there is no free tier. Every hosted call is a paid call, priced per call, and an
  unauthenticated POST answers HTTP 402 immediately with the envelope to pay against — the 402
  is the front door, not a rejection. You are charged only for conversions actually served.
Payment: an unpaid call answers HTTP 402 with an x402 envelope — exact scheme, USDC on Base or
  on Solana — naming the price, the payTo address and an outputSchema describing the request
  body and the response. The accepts array lists the rails that are live, Base first, at the
  same price on either (USDC is 6 decimals on both chains); take the first entry you can pay
  rather than assuming there is exactly one. No accounts, no keys, per-call pricing. Pay with
  an x402-capable client (x402-fetch, the x402 SDK, Coinbase AgentKit) holding a wallet key
  with USDC on one of those rails; it signs and retries with an X-PAYMENT header. The payment
  is verified with the Coinbase CDP facilitator before the conversion is served: a verified
  call comes back with x-payment-verified: true and settles on the rail it was paid on
  immediately afterwards; a payment the facilitator rejects gets the 402 again with an
  invalidReason and no conversion; and if the facilitator cannot be reached the call is served
  anyway, saying so with x-payment-verified: false and x-payment-error. Settlement is queued only
  for a conversion that was actually served, so a 400 on input we cannot convert is never charged,
  and a body over the 256 KB cap is refused with 413 before an envelope is built. On a deployment
  with no receiving address configured, calls answer HTTP 429 instead of 402.
  x402 v1 + v2 dual-stack: the same 402 carries the v1 envelope in the body and the v2 envelope
  base64 in a PAYMENT-REQUIRED response header; pay with X-PAYMENT (v1) or PAYMENT-SIGNATURE (v2).
OpenAPI: https://toolshed.lemon-agent.dev/openapi.json
Skill: npx skills add algonormative/lemon-toolshed
MCP: claude mcp add toolshed -- npx -y github:algonormative/lemon-toolshed
  Tools: toolshed_check, toolshed_convert, toolshed_catalog. Base URL via TOOLSHED_URL.

Editorial stance: Post a file to a hosted tool and read the converted file back — nothing to install. Where we do not host the job, the entry names the tool worth reaching for and what bites about it. We prefer the plain deterministic tool wherever one works, and a model only where the answer is a judgment call.

Every verdict below is engineering judgment, not measurement. Curation is an
owner-taste surface and these entries are drafts for review. The same fields are
available as structured JSON in catalog.json.

## Saved HTML page / static HTML file -> Markdown
id: html-markdown
hosted: yes
hosted_path: POST /convert/html-markdown
hosted_price: $0.006/call · x402
hosted_status: live
aliases_from: html, htm, text/html, application/xhtml+xml
aliases_to: markdown, md, mdown, text/markdown, text/x-markdown
local_tool: pandoc
local_install: brew install pandoc
kind: deterministic
verdict: For HTML already on disk, pandoc's reader is exact and fast, and `--wrap=none` keeps the output diff-friendly. Feeding a whole page to a model to "clean it up" burns tokens and invents heading levels; pandoc preserves precisely the structure that is there. The hosted endpoint runs Turndown instead of pandoc — same job, no install — as a priced x402 call, like every other hosted tool here.
caveats: Pandoc converts everything, including nav, ads and cookie banners — pre-strip with a readability-style extractor (trafilatura, readability-lxml) if you only want the article body. The hosted endpoint has the same blind spot.
escalate: Never for the markup. Boilerplate removal is a heuristic problem first; a model is a last resort for pages where the article body is genuinely ambiguous.
url: https://pandoc.org
verified: 2026-08-18

## Markdown -> HTML
id: md-html
hosted: yes
hosted_path: POST /convert/md-html
hosted_price: $0.004/call · x402
hosted_status: live
aliases_from: markdown, md, mdown, text/markdown, text/x-markdown
aliases_to: html, htm, text/html, application/xhtml+xml
local_tool: pandoc
local_install: brew install pandoc
kind: deterministic
verdict: Markdown to HTML is a solved parse, so the only real questions are which dialect and which extensions. Pandoc is the local answer and handles tables, footnotes and math; the hosted endpoint runs `marked` over CommonMark plus GitHub tables, which is what most agents actually want when they say "render this Markdown".
caveats: The hosted endpoint emits an HTML fragment, not a full document — no `<html>`, no stylesheet. It does not sanitize: raw HTML in the input passes through, so do not render untrusted output into a page without sanitizing it yourself.
escalate: Never.
url: https://pandoc.org
verified: 2026-08-18

## Markdown with a frontmatter fence -> JSON with the metadata and the body split apart
id: frontmatter-json
hosted: yes
hosted_path: POST /convert/frontmatter-json
hosted_price: $0.004/call · x402
hosted_status: live
aliases_from: frontmatter, md, markdown, yaml frontmatter, text/markdown
aliases_to: json, application/json, text/json
local_tool: python-frontmatter
local_install: pip install python-frontmatter
kind: deterministic
verdict: Splitting on the `---` fence is three lines of code that everyone writes slightly wrong: the fence has to be the first thing in the file, the closing fence has to be on its own line, and a `---` inside the body is a horizontal rule rather than a delimiter. The hosted endpoint returns `{"data": ..., "content": ...}` — parsed frontmatter and the untouched body — which is what a static-site pipeline or a content audit actually needs.
caveats: YAML frontmatter only — TOML (`+++`) and JSON frontmatter are not recognised. A file with no opening fence is an error rather than an empty `data` object, because silently reporting "no metadata" for a file whose fence you mistyped is the bug this would otherwise hide. The body is returned byte-for-byte, unrendered.
escalate: Never for the split. A model is the right tool only for the different job of inferring metadata a document never carried.
url: https://python-frontmatter.readthedocs.io
verified: 2026-08-30

## Markdown -> JSON token tree plus a table of contents
id: markdown-json
hosted: yes
hosted_path: POST /convert/markdown-json
hosted_price: $0.004/call · x402
hosted_status: live
aliases_from: markdown, md, mdown, text/markdown, text/x-markdown
aliases_to: json, application/json, text/json
local_tool: pandoc
local_install: brew install pandoc
kind: deterministic
verdict: `pandoc -t json` gives you pandoc's AST locally. The hosted endpoint returns `marked`'s token stream plus a derived `toc` array of `{depth, text}` — the cheap thing an agent usually wants, which is the document's shape without having to render it and re-parse the HTML. Asking a model to "extract the headings" costs tokens for an answer that quietly renumbers on the next input; a lexer does not.
caveats: The token shape is `marked`'s, not pandoc's and not a standard — it is stable across a call but it is a library's data structure, so pin behaviour you depend on with your own test. `toc` is built from ATX and setext headings only; a bold line pretending to be a heading was never structure and does not appear.
escalate: Only when the headings you want do not exist as headings and someone has to decide what the document's sections really are.
url: https://pandoc.org
verified: 2026-08-30

## Saved HTML page / static HTML file -> Plain text, readable
id: html-text
hosted: yes
hosted_path: POST /convert/html-text
hosted_price: $0.006/call · x402
hosted_status: live
aliases_from: html, htm, text/html, application/xhtml+xml
aliases_to: plain text, txt, text, text/plain
local_tool: lynx
local_install: brew install lynx
kind: deterministic
verdict: `lynx -dump -nolist` is the classic local answer. The hosted endpoint parses the page with a real DOM and walks it, so block elements become paragraph breaks and `<script>`, `<style>`, `<nav>`, `<header>`, `<footer>` and `<aside>` are dropped with their contents — which is the difference between readable prose and an analytics snippet wedged between two sentences. Stripping tags with a regex is the failure mode and it has been for thirty years.
caveats: Dropping the chrome elements is a heuristic, not readability extraction: a page that puts its article inside `<aside>` loses it, and a page with no semantic elements keeps its navigation. Links become their text, not their URL. `<pre>` content is preserved verbatim; everything else has its whitespace collapsed.
escalate: Only where the article body is genuinely ambiguous. Try a readability extractor (trafilatura, readability-lxml) before a model — it is cheaper and reproducible.
url: https://lynx.invisible-island.net
verified: 2026-08-30

## HTML page containing data tables -> JSON rows keyed by the header row
id: html-json
hosted: yes
hosted_path: POST /convert/html-json
hosted_price: $0.006/call · x402
hosted_status: live
aliases_from: html, htm, text/html, application/xhtml+xml
aliases_to: json, application/json, text/json
local_tool: pandas
local_install: pip install pandas lxml
kind: deterministic
verdict: `pandas.read_html` locally. The hosted endpoint parses the page with a real DOM and returns every `<table>` as `{caption, columns, rows}` with each row an object keyed by the header cells — a stable shape whether the page has one table or nine. Handing a table to a model to "read the numbers out" is the expensive way to get a transcription error you cannot see.
caveats: `colspan` and `rowspan` are NOT expanded — a merged-cell layout table comes back misaligned, and this is a data-table reader, not a layout reader. Values stay strings with whitespace collapsed; no type guessing, for the same reason csv-json refuses it. Nested tables are returned as their own entries rather than inlined. A page with no table at all is an error.
escalate: When the table is not marked up as a table — a grid built from divs, or a merged-cell report where a human has to say what the rows mean.
url: https://pandas.pydata.org/docs/reference/api/pandas.read_html.html
verified: 2026-08-30

## Markdown (with math, code blocks, citations) -> PDF
id: markdown-to-pdf
hosted: no
aliases_from: markdown, md, mdown, text/markdown, text/x-markdown
aliases_to: pdf, application/pdf
local_tool: pandoc
local_install: brew install pandoc typst
kind: deterministic
verdict: Pandoc plus a Typst or LaTeX engine gives the same PDF on every run, with real pagination, footnotes and cross-references. The naive alternative — print-to-PDF from a Markdown previewer — loses footnote links and repaginates differently on every machine, which shows up as a diff you can't reproduce.
caveats: PDF output needs an external engine; Typst is fast and light, LaTeX (texlive) is heavy but still the only option for some journal templates.
escalate: Never for the conversion. A model is only useful upstream — writing or restructuring the Markdown before pandoc touches it.
url: https://pandoc.org
verified: 2026-08-18

## Markdown -> DOCX styled to a house template
id: markdown-to-docx
hosted: no
aliases_from: markdown, md, mdown, text/markdown, text/x-markdown
aliases_to: docx, doc, word, application/vnd.openxmlformats-officedocument.wordprocessingml.document
local_tool: pandoc
local_install: brew install pandoc
kind: deterministic
verdict: `--reference-doc=template.docx` maps headings, tables and code blocks onto a real Word style sheet, so a human reviewer gets an editable document instead of a wall of Normal-styled text. Pasting rendered Markdown into Word is the failure mode: styles arrive as direct formatting and the first edit shatters them.
caveats: Word-native features (comments, tracked changes, floats with anchors) don't round-trip; you get clean structure, not pixel-matched design.
escalate: Never — style mapping is a template problem, not a judgment problem. Rewriting content for a different audience is a separate upstream step.
url: https://pandoc.org
verified: 2026-08-18

## DOCX -> Markdown + extracted media
id: docx-to-markdown
hosted: no
aliases_from: docx, doc, word, application/vnd.openxmlformats-officedocument.wordprocessingml.document
aliases_to: markdown, md, mdown, text/markdown, text/x-markdown
local_tool: pandoc
local_install: brew install pandoc
kind: deterministic
verdict: Pandoc reads the DOCX XML directly, so headings, lists, tables and footnotes land as real Markdown structure, and `--extract-media` writes embedded images to disk instead of dropping them. Pasting a DOCX into a model to "convert it" is the failure mode: you pay tokens for a plausible-looking file with quietly renumbered lists and vanished tables.
caveats: Tracked changes and comments are discarded unless you pass `--track-changes=all`; pseudo-headings faked with bold text stay paragraphs, because they were never structure.
escalate: Only when there is no structure to recover — a document where every heading was faked with formatting and you want semantic headings inferred.
url: https://pandoc.org
verified: 2026-08-18

## Live DOM in a browser or headless page (JS-rendered) -> Markdown
id: rendered-dom-to-markdown
hosted: no
aliases_from: rendered dom, dom, url, webpage
aliases_to: markdown, md, mdown, text/markdown, text/x-markdown
local_tool: turndown
local_install: npm install turndown
kind: deterministic
verdict: When the content only exists after JavaScript runs, the conversion belongs where the DOM is — Turndown runs in-page or in Node against a parsed DOM and takes custom rules for app-specific markup. Fetching the raw HTML and running a static converter gets you an empty shell.
caveats: Smaller rule set than pandoc; tables need the GFM plugin and you own the escaping edge cases.
escalate: Never for markup. Use a model only to decide which region of a hostile app UI is "the content" — then hand that node to turndown.
url: https://github.com/mixmark-io/turndown
verified: 2026-08-18

## Markdown (multi-chapter manuscript) -> EPUB 3
id: markdown-to-epub
hosted: no
aliases_from: markdown, md, mdown, text/markdown, text/x-markdown
aliases_to: epub, application/epub+zip, ebook
local_tool: pandoc
local_install: brew install pandoc
kind: deterministic
verdict: `pandoc -o book.epub` produces a valid EPUB with a real table of contents, metadata and chapter splitting via `--split-level`; readers care about that structure far more than typography. The naive path — export to PDF and sideload — gives a fixed-layout file that is unreadable on a six-inch screen.
caveats: Run epubcheck before publishing; store-specific requirements (Apple, Kobo) go beyond mere validity.
escalate: Never.
url: https://pandoc.org
verified: 2026-08-18

## DOCX/XLSX/PPTX (batch) -> PDF
id: office-docs-to-pdf-batch
hosted: no
aliases_from: office docs, docx, xlsx, pptx, office
aliases_to: pdf, application/pdf
local_tool: libreoffice
local_install: brew install --cask libreoffice
kind: deterministic
verdict: `soffice --headless --convert-to pdf --outdir out/ *.docx` is the only free path that renders Office layout faithfully enough to hand to someone, and it batches on a server with no Office licence. Pandoc converts the content but is not a layout engine — it will not preserve a deck's slides or a spreadsheet's pagination.
caveats: Fidelity is high, not perfect: fonts must be installed on the host, and exotic SmartArt or macro-driven content drifts. Concurrent runs need separate profiles via `-env:UserInstallation=`.
escalate: Never.
url: https://www.libreoffice.org
verified: 2026-08-18

## HTML + CSS (invoice, report, generated page) -> Paginated PDF
id: html-to-paginated-pdf
hosted: no
aliases_from: html, htm, text/html, application/xhtml+xml
aliases_to: pdf, application/pdf
local_tool: weasyprint
local_install: pip install weasyprint
kind: deterministic
verdict: WeasyPrint implements print CSS — `@page`, running headers, page counters — so a report template paginates the same way in CI as on your laptop, with no browser in the image. Headless Chrome does the same job but its output shifts with the Chrome version, which is a bad property for anything invoice-shaped.
caveats: No JavaScript execution — render dynamic content to static HTML first. Very modern CSS layout features can differ from a browser's rendering.
escalate: Never.
url: https://weasyprint.org
verified: 2026-08-18

## Messy document (invoice, contract, report PDF/DOCX) -> Structured records against a schema
id: messy-doc-to-schema
hosted: no
aliases_from: messy document
aliases_to: structured records
local_tool: unstructured
local_install: pip install "unstructured[all-docs]"
kind: hybrid
verdict: Split the job rather than the tool: deterministic partitioning (unstructured's parsers, or pdftotext/pdfplumber) yields elements, positions and tables, and a model is asked only for the fields that are genuinely judgment — which of these three numbers is "the total", is this clause an indemnity. Handing the whole PDF to an LLM and asking for JSON is the expensive failure mode: it works on the demo document and fabricates on the tenth, with no signal that it did.
caveats: Heavy dependency tree (OCR, ONNX models) and quality varies a lot by document type; validate the extracted structure before trusting anything built on top of it.
escalate: The model tier is the point here — keep it narrow. Constrain output to the schema, validate every extracted number against the deterministic parse, and log both so a disagreement is visible.
url: https://github.com/Unstructured-IO/unstructured
verified: 2026-08-18

## MOBI/AZW3/LIT and other legacy ebook formats -> EPUB
id: legacy-ebook-to-epub
hosted: no
aliases_from: legacy ebook, mobi, azw3, ebook
aliases_to: epub, application/epub+zip, ebook
local_tool: calibre
local_install: brew install --cask calibre
kind: deterministic
verdict: `ebook-convert in.azw3 out.epub` carries the TOC, metadata and internal links across a dozen legacy formats — a decade of accumulated format edge cases you should not re-derive. Pandoc does not read these formats, and "free online ebook converter" sites mean uploading your library to a stranger.
caveats: DRM-protected files will not convert, and whether to remove DRM is your legal call, not the tool's. Heavily designed fixed-layout books reflow poorly.
escalate: Never.
url: https://calibre-ebook.com
verified: 2026-08-18

## PDF (digital-born — has a text layer) -> Plain text / layout-preserved text
id: pdf-digital-born-to-text
hosted: no
aliases_from: digital-born pdf, pdf, application/pdf
aliases_to: plain text, txt, text, text/plain
local_tool: pdftotext
local_install: brew install poppler
kind: deterministic
verdict: If `pdftotext -layout` returns real text, the job is already finished — the characters are in the file and extraction is exact and instant. This is the entry that governs the whole PDF branch of the directory: run pdftotext first on every PDF, and only when it comes back empty or garbled does the file deserve OCR or a model.
caveats: Multi-column and tabular layouts still interleave; `-layout` helps, and `-bbox-layout` gives coordinates when you need to reconstruct columns yourself.
escalate: Never for extraction. Escalate only for interpretation — turning extracted text into a schema (see messy-doc-to-schema).
url: https://poppler.freedesktop.org
verified: 2026-08-18

## PDF (scanned — page images, no text layer) -> Searchable PDF + extractable text
id: pdf-scanned-to-searchable
hosted: no
aliases_from: scanned pdf, pdf, application/pdf
aliases_to: searchable pdf, pdf, application/pdf
local_tool: ocrmypdf
local_install: brew install ocrmypdf
kind: hybrid
verdict: ocrmypdf adds an invisible text layer to the original pages, so the file stays a faithful scan and becomes greppable and citable; `--skip-text` and `--redo-ocr` make it safe to sweep a mixed directory. Pointing raw tesseract at the page images throws the PDF away and leaves you a text blob nobody can cite a page number from.
caveats: OCR quality is bounded by scan quality — deskew and clean help, but phone photos of curved pages stay bad. Slow and CPU-hungry on long documents.
escalate: When accuracy matters on hard scans — handwriting, historical type, dense tables — a vision model reads them better. Still run OCR first and keep its output as a cross-check: OCR fails loudly, models fail by writing plausible words.
url: https://ocrmypdf.readthedocs.io
verified: 2026-08-18

## PDF page(s) -> PNG/JPEG page images
id: pdf-to-page-images
hosted: no
aliases_from: pdf, application/pdf
aliases_to: page images, png, jpeg, jpg, image/png
local_tool: pdftoppm
local_install: brew install poppler
kind: deterministic
verdict: `pdftoppm -r 200 -png` renders pages reproducibly and is the correct pre-step whenever OCR or a vision model is the next stage, because you control DPI, page range and colour — which is exactly what downstream accuracy depends on. Screenshotting pages by hand introduces cropping and scaling nobody wrote down.
caveats: 300+ dpi over a long document produces very large files quickly; pick the lowest DPI the downstream stage tolerates and record it.
escalate: This pair is the deterministic half of a model workflow — the model comes after, on the rendered images, never instead of the render.
url: https://poppler.freedesktop.org
verified: 2026-08-18

## PDF with ruled or whitespace-aligned tables -> CSV / DataFrame
id: pdf-tables-to-csv
hosted: no
aliases_from: pdf tables, pdf, application/pdf
aliases_to: csv, text/csv, application/csv
local_tool: camelot
local_install: pip install "camelot-py[base]"
kind: deterministic
verdict: Camelot's lattice mode reconstructs cells from the table's actual ruling lines, so on a bordered table it is exact rather than approximate; stream mode handles whitespace-aligned tables with more supervision. Copy-pasting a table out of a PDF viewer merges columns unpredictably and you won't notice until a number is wrong in a report.
caveats: Digital-born PDFs only; borderless tables need tuning, and the parse-accuracy report is worth reading rather than trusting. tabula-java and pdfplumber are reasonable alternatives with different failure shapes.
escalate: Scanned tables, or tables whose header semantics are ambiguous, are legitimately model work — render pages with pdftoppm, give the model the image, then validate totals and row counts deterministically.
url: https://github.com/camelot-dev/camelot
verified: 2026-08-18

## JSON -> YAML
id: json-yaml
hosted: yes
hosted_path: POST /convert/json-yaml
hosted_price: $0.002/call · x402
hosted_status: live
aliases_from: json, application/json, text/json
aliases_to: yaml, yml, application/yaml, text/yaml, application/x-yaml
local_tool: yq
local_install: brew install yq
kind: deterministic
verdict: mikefarah's yq speaks both formats natively (`yq -P`) and preserves comments through YAML edits, which is the whole reason to use it on real config files. The hosted endpoint is the no-install version for the common case: valid JSON in, block-style YAML out.
caveats: Two unrelated tools are named yq — the Go one (mikefarah) and a Python jq wrapper (kislyuk); the flags differ, so pin which one your scripts assume. The hosted endpoint has no comments to preserve, because JSON has none.
escalate: Never.
url: https://github.com/mikefarah/yq
verified: 2026-08-18

## YAML -> JSON
id: yaml-json
hosted: yes
hosted_path: POST /convert/yaml-json
hosted_price: $0.002/call · x402
hosted_status: live
aliases_from: yaml, yml, application/yaml, text/yaml, application/x-yaml
aliases_to: json, application/json, text/json
local_tool: yq
local_install: brew install yq
kind: deterministic
verdict: `yq -o=json` is the local answer, and the direction that bites is this one: YAML is the larger language, so anchors, multi-document streams and unquoted `no`/`yes` all have to land somewhere in JSON. The hosted endpoint takes the first document of a stream and resolves anchors, which is what a config-reading agent wants.
caveats: Multi-document YAML collapses to its first document on the hosted endpoint — use local yq if you need all of them. YAML dates and other non-JSON scalar types are stringified.
escalate: Never.
url: https://github.com/mikefarah/yq
verified: 2026-08-18

## CSV -> JSON
id: csv-json
hosted: yes
hosted_path: POST /convert/csv-json
hosted_price: $0.002/call · x402
hosted_status: live
aliases_from: csv, text/csv, application/csv
aliases_to: json, application/json, text/json
local_tool: csvkit
local_install: pip install csvkit
kind: deterministic
verdict: `csvjson data.csv` turns a header row plus records into an array of objects, which is the shape almost everything downstream wants. The hosted endpoint does the same thing with an RFC-4180 parser, so quoted commas and embedded newlines survive — which is exactly what a split-on-comma one-liner gets wrong.
caveats: Every value comes out a string; the hosted endpoint does not guess types, because guessing is where leading zeros and long IDs get destroyed. Rows shorter than the header are padded with empty strings, and a row with more fields than the header is an error rather than a silent truncation.
escalate: Never for the parse. Deciding what the columns *mean* — see messy-csv-to-clean-csv — is the judgment half.
url: https://csvkit.readthedocs.io
verified: 2026-08-18

## JSON array of records -> CSV with a header row
id: json-csv
hosted: yes
hosted_path: POST /convert/json-csv
hosted_price: $0.002/call · x402
hosted_status: live
aliases_from: json, application/json, text/json
aliases_to: csv, text/csv, application/csv
local_tool: csvkit
local_install: pip install csvkit
kind: deterministic
verdict: `in2csv --format json` is the local answer, and the hosted endpoint is the inverse of our own csv-json: an array of objects in, a header row plus one line per record out, RFC-4180 quoted so commas, quotes and newlines inside values survive. The column set is the union of every record's keys in first-seen order, so a record missing a key gets an empty cell rather than a shifted row — which is what hand-rolled `Object.values().join(',')` gets wrong the first time a record differs.
caveats: CSV is flat and JSON is not. One level of nesting is flattened to dotted columns (`user.id`), and anything deeper — or any array — is written back as compact JSON in the cell rather than being invented into columns. A top-level value that is not an array of objects is an error, not a one-row guess.
escalate: Never for the serialization. A model is only worth reaching for upstream, when the question is which fields a human-facing spreadsheet should even have.
url: https://csvkit.readthedocs.io
verified: 2026-08-30

## CSV -> YAML
id: csv-yaml
hosted: yes
hosted_path: POST /convert/csv-yaml
hosted_price: $0.002/call · x402
hosted_status: live
aliases_from: csv, text/csv, application/csv
aliases_to: yaml, yml, application/yaml, text/yaml, application/x-yaml
local_tool: yq
local_install: brew install yq
kind: deterministic
verdict: `yq -p=csv -o=yaml` does this locally; the hosted endpoint runs the same RFC-4180 parser csv-json uses and dumps block-style YAML, which is the shape you want when a spreadsheet export has to become a config file or a fixture. The reason to bother rather than eyeballing it: quoted commas and embedded newlines become correctly quoted YAML scalars instead of a document that parses to the wrong thing silently.
caveats: Every value stays a string, deliberately — the same no-type-guessing rule csv-json states, so `007` and long ids survive. If you want numbers, cast them downstream where you know the schema. Header cells are trimmed; values are not.
escalate: Never. Naming and typing the columns is the judgment half, and it belongs upstream of this call.
url: https://github.com/mikefarah/yq
verified: 2026-08-30

## YAML list of records -> CSV with a header row
id: yaml-csv
hosted: yes
hosted_path: POST /convert/yaml-csv
hosted_price: $0.002/call · x402
hosted_status: live
aliases_from: yaml, yml, application/yaml, text/yaml, application/x-yaml
aliases_to: csv, text/csv, application/csv
local_tool: yq
local_install: brew install yq
kind: deterministic
verdict: `yq -o=csv` locally. The hosted endpoint takes the first document of a stream, resolves anchors, and requires the result to be a list of maps — because that is the only YAML shape that is a table. Anything else is refused rather than flattened into a plausible-looking sheet, which is the failure this endpoint exists to avoid.
caveats: Multi-document input collapses to its first document. Nested maps flatten one level to dotted columns and deeper structures are written as compact JSON in the cell; YAML dates and other non-JSON scalars are stringified.
escalate: Never for the conversion. Deciding which nested fields deserve to be columns is a schema decision, not a parse.
url: https://github.com/mikefarah/yq
verified: 2026-08-30

## JSON array -> NDJSON (newline-delimited JSON)
id: json-ndjson
hosted: yes
hosted_path: POST /convert/json-ndjson
hosted_price: $0.002/call · x402
hosted_status: live
aliases_from: json, application/json, text/json
aliases_to: ndjson, jsonl, ldjson, application/x-ndjson, application/jsonl
local_tool: jq
local_install: brew install jq
kind: deterministic
verdict: `jq -c '.[]'` is the local one-liner and it is the right one. The hosted endpoint is the no-install version: one compact JSON value per line, which is the format every streaming consumer — BigQuery loads, log shippers, `jq --stream` pipelines — actually wants. Doing it with string surgery on the array's commas is the failure mode: commas inside strings and nested arrays are not delimiters.
caveats: The input must be a JSON array; a bare object or scalar is an error rather than a one-line file, because guessing there is how a caller ends up with a stream of one. Elements are re-serialized compactly, so key order is preserved but formatting is not.
escalate: Never.
url: https://jqlang.github.io/jq/
verified: 2026-08-30

## NDJSON (newline-delimited JSON) -> JSON array
id: ndjson-json
hosted: yes
hosted_path: POST /convert/ndjson-json
hosted_price: $0.002/call · x402
hosted_status: live
aliases_from: ndjson, jsonl, ldjson, application/x-ndjson, application/jsonl
aliases_to: json, application/json, text/json
local_tool: jq
local_install: brew install jq
kind: deterministic
verdict: `jq -s '.'` slurps a stream back into an array locally. The hosted endpoint does the same and, when a line does not parse, says which line — which is the whole value of running a real parser over a log file instead of wrapping it in brackets and hoping. Blank lines are skipped; everything else must be a complete JSON value.
caveats: The whole stream is materialised in memory, so the 256 KB body cap is the real limit here — for anything larger use local `jq -s` rather than splitting the file, since a split changes what the array means. A trailing partial line is an error, not a truncation.
escalate: Never.
url: https://jqlang.github.io/jq/
verified: 2026-08-30

## TOML config file -> JSON
id: toml-json
hosted: yes
hosted_path: POST /convert/toml-json
hosted_price: $0.004/call · x402
hosted_status: live
aliases_from: toml, application/toml, text/toml
aliases_to: json, application/json, text/json
local_tool: dasel
local_install: brew install dasel
kind: deterministic
verdict: `dasel -r toml -w json` locally. TOML's whole point is that it has a spec and one reading, so a conforming parser gives you the same document every time — including the parts hand-rolled readers get wrong, like dotted keys, arrays of tables and offset date-times. Regexing a `pyproject.toml` or a `Cargo.toml` for a version string works until a value moves into a table header.
caveats: Comments are dropped, because JSON has none — this is a read path, not a round trip. TOML dates and date-times become ISO-8601 strings, since JSON has no date type, and integers outside JavaScript's safe range lose precision.
escalate: Never.
url: https://daseldocs.tomwright.me
verified: 2026-08-30

## JSON object -> TOML
id: json-toml
hosted: yes
hosted_path: POST /convert/json-toml
hosted_price: $0.004/call · x402
hosted_status: live
aliases_from: json, application/json, text/json
aliases_to: toml, application/toml, text/toml
local_tool: dasel
local_install: brew install dasel
kind: deterministic
verdict: `dasel -r json -w toml` is the local answer. The direction that bites is this one: TOML's root must be a table, so a JSON array or scalar has nowhere to go, and `null` has no TOML spelling at all. The hosted endpoint refuses both rather than emitting a file that parses to something you did not write.
caveats: A non-object root, or a `null` anywhere in the document, is an error — TOML cannot express either, and there is no honest substitute. Key order follows the JSON document; the emitted file is valid TOML but it is not formatted the way a human would have laid it out.
escalate: Never for the encoding. Whether a generated config should be checked in at all is a different conversation.
url: https://daseldocs.tomwright.me
verified: 2026-08-30

## XML document (feed, export, SOAP payload) -> JSON
id: xml-json
hosted: yes
hosted_path: POST /convert/xml-json
hosted_price: $0.006/call · x402
hosted_status: live
aliases_from: xml, application/xml, text/xml
aliases_to: json, application/json, text/json
local_tool: yq
local_install: brew install yq
kind: deterministic
verdict: `yq -p=xml -o=json` locally. XML-to-JSON is not a bijection and every tool picks a convention; ours is `fast-xml-parser`'s — attributes prefixed `@_`, text content under `#text`, repeated sibling elements collapsed into an array. Stating the convention is the product: a model asked to "turn this XML into JSON" invents a different one per call, which is unusable in a pipeline.
caveats: A document with a `<!DOCTYPE>` is REFUSED, not parsed — internal DTD entities are how an entity-expansion bomb fits inside a 256 KB body, and no output is worth that. Namespace prefixes are kept verbatim as part of the key, and an element that appears once is an object while the same element appearing twice is an array, so consumers must handle both. Values stay strings: the parser's number coercion is switched off, because it turns an id of `007` into `7`.
escalate: Never for the parse. Mapping someone's XML schema onto the JSON shape your system wants is a separate, genuinely judgment-shaped job.
url: https://github.com/mikefarah/yq
verified: 2026-08-30

## Nested JSON from an API -> Flat JSON / NDJSON / CSV rows
id: json-reshape
hosted: no
aliases_from: json, application/json, text/json
aliases_to: json / ndjson, json, ndjson, jsonl, application/json, application/x-ndjson
local_tool: jq
local_install: brew install jq
kind: deterministic
verdict: jq is a real language for this: `-r`, `@csv`, `to_entries`, `group_by` cover most reshapes in a line, and the result is an auditable program you can re-run on tomorrow's payload. Asking a model to "reshape this JSON" produces an answer, not a program — it doesn't survive the next record and quietly guesses on nulls.
caveats: Very large documents need `--stream` or NDJSON input; the syntax has a genuine learning curve that people repeatedly underestimate.
escalate: Use a model to *write the jq program* when the shape is unfamiliar — then keep the program, drop the model, and put the program in version control.
url: https://jqlang.github.io/jq/
verified: 2026-08-18

## Messy CSV (ragged rows, BOM, mixed quoting, duplicate headers) -> Clean, validated UTF-8 CSV
id: messy-csv-to-clean-csv
hosted: no
aliases_from: messy csv, csv, text/csv
aliases_to: clean csv, csv, text/csv
local_tool: qsv
local_install: brew install qsv
kind: deterministic
verdict: `qsv input` normalizes quoting and line endings, and `validate`/`headers`/`dedup` tell you what is actually wrong before the data reaches anything downstream — all at streaming speed on files far past spreadsheet size. Opening it in Excel to "fix it" is the classic failure: leading zeros vanish, long IDs become floats, and dates get silently localized.
caveats: Some subcommands depend on how the binary was built (feature flags); csvkit is slower but pip-installable everywhere and reads more input formats.
escalate: Only when the fix requires meaning — deciding that "N/A", "-" and "" are the same null, or that two differently-spelled columns are one field. Extract deterministically, let a model propose the mapping, then encode that mapping as a rule you can re-run.
url: https://github.com/dathere/qsv
verified: 2026-08-18

## XLSX workbook (specific sheet) -> CSV
id: xlsx-to-csv
hosted: no
aliases_from: xlsx, xls, excel, spreadsheet, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
aliases_to: csv, text/csv, application/csv
local_tool: csvkit
local_install: pip install csvkit
kind: deterministic
verdict: `in2csv --sheet "Sheet2" book.xlsx` gets the sheet you asked for with stable typing and scripts across a directory. Save-As-CSV in Excel exports only the active sheet, applies the machine's locale to dates and separators, and cannot be automated — which is how two people produce two different CSVs from one workbook.
caveats: Formulas export as their last cached value; merged cells and multi-row headers still need reshaping. Very large workbooks are slow — `qsv excel` is the fast path.
escalate: When the sheet is a human-formatted report rather than a table (title rows, merged headers, stacked sub-tables), identifying the header row is genuine judgment: dump deterministically first, then let a model name the header row and the sub-table boundaries.
url: https://csvkit.readthedocs.io
verified: 2026-08-18

## Large CSV -> Queryable SQLite database
id: csv-to-sqlite
hosted: no
aliases_from: csv, text/csv, application/csv
aliases_to: sqlite, db, sqlite3, application/vnd.sqlite3
local_tool: sqlite3
local_install: built-in (macOS/most Linux); brew install sqlite for a current version
kind: deterministic
verdict: `.import --csv data.csv t` buys you indexes, joins and SQL over a file too big for a spreadsheet, with no service and no ORM. Loading a multi-hundred-megabyte CSV into pandas just to filter it is the naive alternative — paying RAM for work the disk should be doing.
caveats: `.import` types every column as TEXT unless you create the table first — declare the schema when numeric comparison matters. csvkit's `csvsql --db` infers types at a large speed cost.
escalate: Never.
url: https://sqlite.org/cli.html
verified: 2026-08-18

## SQLite query result -> JSON / NDJSON for an API or an agent
id: sqlite-to-json
hosted: no
aliases_from: sqlite, db, sqlite3, application/vnd.sqlite3
aliases_to: json / ndjson, json, ndjson, jsonl, application/json, application/x-ndjson
local_tool: sqlite3
local_install: built-in
kind: deterministic
verdict: `sqlite3 -json db.sqlite "select ..."` (or `.mode json`) emits valid JSON straight from the CLI, composes with jq in a pipe, and needs no serialization layer. Hand-rolling a Python export script for this creates code you now have to maintain and test.
caveats: Needs a reasonably modern SQLite (3.33+) for the `-json` flag; check BLOB and NULL handling before shipping the output anywhere.
escalate: Never.
url: https://sqlite.org/cli.html
verified: 2026-08-18

## HEIC/HEIF photos from an iPhone -> JPEG
id: heic-to-jpeg
hosted: no
aliases_from: heic photos, heic, heif, image/heic
aliases_to: jpeg, jpg, image/jpeg
local_tool: imagemagick
local_install: brew install imagemagick libheif
kind: deterministic
verdict: `magick mogrify -format jpg -quality 88 *.heic` converts a folder in one line and keeps EXIF, which matters when the timestamps are the reason you kept the photos. Re-exporting through a photo app or a web converter tends to strip or rewrite metadata — and uploading personal photos to a random site is a privacy trade you probably didn't intend to make.
caveats: Requires a libheif-enabled build (check `magick -list format | grep -i heic`); slower and hungrier than libvips on large batches.
escalate: Never.
url: https://imagemagick.org
verified: 2026-08-18

## Large batch of source images -> Web-sized JPEG/WebP/AVIF derivatives
id: bulk-image-resize
hosted: no
aliases_from: images, png, jpeg, jpg, image/png, image/jpeg
aliases_to: web images, webp, jpeg, jpg, image/webp
local_tool: libvips
local_install: brew install vips
kind: deterministic
verdict: `vipsthumbnail` streams through a batch on a small memory footprint and gets the defaults right — shrink-on-load for JPEG, sane colour handling. The naive `magick -resize` loop over thousands of files is where the out-of-memory kills and the hour-long builds come from.
caveats: Fewer effects and filters than ImageMagick; heavy compositing or annotation work still belongs in ImageMagick, at its cost.
escalate: Never for the resize. Picking crop focal points across a large library is the one adjacent task where a model (saliency detection) earns its keep.
url: https://www.libvips.org
verified: 2026-08-18

## Static SVG -> PNG at a chosen scale
id: svg-to-png
hosted: no
aliases_from: svg, image/svg+xml
aliases_to: png, image/png
local_tool: resvg
local_install: cargo install resvg
kind: deterministic
verdict: resvg renders an SVG to PNG with no browser and no JS runtime, so it runs in CI and produces the same bytes run after run. Headless Chrome does the same job while pulling in a browser-sized dependency and a screenshot timing race.
caveats: Static SVG only — no scripting, no remote resource fetching, and web fonts must be installed locally. `rsvg-convert` (librsvg) is the distro-packaged alternative.
escalate: Never.
url: https://github.com/linebender/resvg
verified: 2026-08-18

## Image of text (screenshot, clean scan, photo) -> Plain text
id: image-to-text
hosted: no
aliases_from: image of text, png, jpeg, jpg, image/png, image/jpeg
aliases_to: plain text, txt, text, text/plain
local_tool: tesseract
local_install: brew install tesseract tesseract-lang
kind: model
verdict: Tesseract is a fixed local model — same input, same output, no API, nothing leaving the machine — and `--psm` is the knob that actually matters (6 for a block, 7 for a single line). Sending screenshots to a hosted vision API for text you could extract locally is a cost and privacy leak on the easy majority of cases.
caveats: Wants clean, high-contrast, deskewed input; handwriting, stylized type and text over busy imagery are outside its range. When it fails it produces visible garbage, which is a useful property.
escalate: Handwriting, dense multi-column layouts, or text embedded in imagery — a vision model reads those. Also whenever the target is semantic ("what is the total on this receipt") rather than the characters themselves.
url: https://github.com/tesseract-ocr/tesseract
verified: 2026-08-18

## SubRip subtitle file (.srt) -> WebVTT (.vtt)
id: srt-vtt
hosted: yes
hosted_path: POST /convert/srt-vtt
hosted_price: $0.002/call · x402
hosted_status: live
aliases_from: srt, subrip, application/x-subrip, text/srt
aliases_to: vtt, webvtt, text/vtt
local_tool: ffmpeg
local_install: brew install ffmpeg
kind: deterministic
verdict: `ffmpeg -i in.srt out.vtt` converts locally. The difference between the two formats is small and entirely mechanical — a `WEBVTT` header line and a decimal point where SubRip writes a comma — which is exactly why it is worth doing with a parser rather than a global find-and-replace: a comma inside the caption text is not a timestamp separator, and replacing it corrupts the dialogue instead of the timing.
caveats: Cue numbers are kept as WebVTT cue identifiers, which is legal and which some players display; strip them first if that matters. SubRip's `{\an8}` and `<font>` positioning tags are passed through untouched rather than translated to VTT cue settings.
escalate: Never — this is a format rewrite, not a judgment.
url: https://ffmpeg.org
verified: 2026-08-30

## WebVTT (.vtt) -> SubRip subtitle file (.srt)
id: vtt-srt
hosted: yes
hosted_path: POST /convert/vtt-srt
hosted_price: $0.002/call · x402
hosted_status: live
aliases_from: vtt, webvtt, text/vtt
aliases_to: srt, subrip, application/x-subrip, text/srt
local_tool: ffmpeg
local_install: brew install ffmpeg
kind: deterministic
verdict: The harder direction, and the reason to use a parser: WebVTT is the larger format, so the `WEBVTT` header, `NOTE`/`STYLE`/`REGION` blocks, cue settings after the timestamp and hour-less `mm:ss.mmm` stamps all have to land somewhere in SubRip, which has none of them. The hosted endpoint drops what SubRip cannot express, expands short timestamps to `hh:mm:ss,mmm` and renumbers cues from 1, which is what players expect.
caveats: Cue settings (`align`, `line`, `position`) and styling blocks are DISCARDED — SubRip has nowhere to put them, and dropping them loudly here beats a player ignoring them later. Cue identifiers are replaced by sequential numbers. Input that does not begin with `WEBVTT` is refused rather than parsed hopefully.
escalate: Never.
url: https://ffmpeg.org
verified: 2026-08-30

## Arbitrary video (any container/codec) -> H.264 MP4 that plays everywhere
id: video-to-portable-mp4
hosted: no
aliases_from: video, mp4, mov, mkv, video/mp4
aliases_to: mp4, video/mp4, h264, mov
local_tool: ffmpeg
local_install: brew install ffmpeg
kind: deterministic
verdict: `-c:v libx264 -crf 20 -preset slow -c:a aac -movflags +faststart` is the boring correct answer for delivery: CRF targets quality rather than a guessed bitrate, and faststart lets playback begin before the file finishes downloading. GUI "convert to MP4" presets routinely omit faststart, so web playback stalls until the whole file lands.
caveats: CRF values are codec-relative — don't reuse an x264 number for x265 or AV1. Hardware encoders are much faster and meaningfully worse per bit.
escalate: Never. Encoding is math; the only judgment is your quality/size target, which is a knob you set once.
url: https://ffmpeg.org
verified: 2026-08-18

## Video file with an audio track -> Audio file (m4a/wav)
id: video-to-audio-track
hosted: no
aliases_from: video, mp4, mov, mkv, video/mp4
aliases_to: audio file, wav, mp3, flac, audio/mpeg
local_tool: ffmpeg
local_install: brew install ffmpeg
kind: deterministic
verdict: `ffmpeg -i in.mp4 -vn -c:a copy out.m4a` lifts the existing audio stream with no re-encode and no generation loss; switch to `-c:a pcm_s16le out.wav` only when the next tool demands PCM. Reflexively re-encoding to MP3 adds a lossy generation for nothing.
caveats: Stream copy needs a container that accepts the codec (AAC to .m4a, not .wav); multi-track sources need an explicit `-map`.
escalate: Never.
url: https://ffmpeg.org
verified: 2026-08-18

## WAV / FLAC / arbitrary audio -> MP3 or Opus at a fixed sample rate and loudness
id: audio-transcode-and-normalize
hosted: no
aliases_from: audio, wav, flac, aiff, audio/wav, audio/x-wav
aliases_to: mp3 / opus, mp3, opus, audio/mpeg, audio/opus
local_tool: ffmpeg
local_install: brew install ffmpeg
kind: deterministic
verdict: ffmpeg does the format change, the resample (`-ar`) and loudness normalization (`loudnorm`) in a single pass, which matters because chaining separate tools resamples twice and compounds artifacts. For speech and web delivery Opus at a low bitrate is clearly better than MP3 at the same size.
caveats: Single-pass loudnorm is approximate; use the two-pass measure-then-apply form when you actually care about hitting a LUFS target.
escalate: Never.
url: https://ffmpeg.org
verified: 2026-08-18

## Recorded speech (meeting, interview, podcast) -> Transcript (text/SRT/VTT)
id: speech-audio-to-transcript
hosted: no
aliases_from: recorded speech, wav, mp3, audio/wav, audio/mpeg
aliases_to: transcript, srt, vtt, text/vtt
local_tool: whisper.cpp
local_install: brew install whisper-cpp
kind: model
verdict: This pair has no deterministic answer; speech-to-text is model work and pretending otherwise wastes a day. whisper.cpp runs the weights locally at usable speed on Apple Silicon and writes SRT/VTT directly, so recordings never leave the machine and the marginal cost per hour of audio is zero.
caveats: No speaker diarization out of the box; accuracy drops with accents, crosstalk and domain jargon, and it can emit invented text over long silences. Bigger models are considerably better and considerably slower. faster-whisper is the Python/GPU alternative.
escalate: Already model-tier. Go further only for diarization, or for a cleanup pass on punctuation and domain terminology — and always keep the raw transcript alongside the cleaned one.
url: https://github.com/ggml-org/whisper.cpp
verified: 2026-08-18

## Photo / video / PDF file -> Structured metadata (JSON)
id: media-to-metadata-json
hosted: no
aliases_from: media file, mp4, jpeg, pdf, heic
aliases_to: metadata json, json, application/json
local_tool: exiftool
local_install: brew install exiftool
kind: deterministic
verdict: `exiftool -json -r dir/` reads (and writes) metadata across essentially every format and tag standard, which makes it the right first move before any lossy pipeline: capture the metadata, then convert. The naive path drops timestamps and GPS during the convert step and you find out months later, with no way back.
caveats: Writing tags rewrites files — keep the `_original` backups, or pass `-overwrite_original` deliberately. Tag namespaces are numerous and vendor-specific.
escalate: Never for reading. A model is only relevant for deriving metadata that isn't there — captions, subjects, scene descriptions — which is a different job with different accuracy expectations.
url: https://exiftool.org
verified: 2026-08-18

## Text/CSV in a legacy encoding (CP-1252, Latin-1, Shift-JIS) showing mojibake -> Clean UTF-8
id: legacy-encoding-to-utf8
hosted: no
aliases_from: legacy encoding
aliases_to: utf-8, txt, text/plain
local_tool: iconv
local_install: built-in (GNU/BSD iconv); brew install uchardet for detection
kind: deterministic
verdict: `iconv -f WINDOWS-1252 -t UTF-8` fixes the entire class of "why are there  characters" bugs in one pass once you know the source encoding; pair it with `uchardet` or `file -I` to guess. Find-and-replacing the visible mojibake by hand is the failure mode — you fix the common characters and leave the rare ones to break a parser downstream.
caveats: Encoding detection is a guess, not a fact — verify on a sample containing known-odd characters. `//TRANSLIT` silently degrades anything unmappable.
escalate: Never for the conversion; a model is at most a tie-breaker when detection is ambiguous and you have a sample of known-correct text to compare against.
url: https://www.gnu.org/software/libiconv/
verified: 2026-08-18