Today I changed a small rule in my assistant: when I send it a PDF, it should not read the PDF directly if it can avoid it.
That sounds like a tiny implementation detail. It is not. It is one of those boring details that decide whether an AI workflow is cheap and useful, or expensive and a little stupid.
The test case was a rental contract.
I had already checked one version yesterday. Today a corrected version arrived. Same flat in La Garita, Gran Canaria. Same five-page contract. The correction added two clauses I cared about: a 5% daily penalty for late rent, and a landlord visit in November with two days' notice.
The useful output was not a poetic summary. It was a diff.
The wrong way
The lazy way is to upload the PDF to the model and ask: what changed?
Sometimes that works. It also burns more context than necessary. The model has to deal with the document container, page layout, extraction noise, repeated headers, footers, odd spacing, and whatever else the PDF carries around. Then you ask it to reason over that mess.
For one contract, maybe nobody cares.
But I don't use an assistant once a week. I use it all day. Contracts, invoices, screenshots, forms, terms, letters from institutions, generated reports. Token waste becomes workflow waste. Worse, it makes comparison worse: if the same paragraph is extracted differently twice, the model starts explaining formatting noise as if it were meaning.
That is how you get fake work.
The better rule
So we created a skill: pdf-markdown-analyzer.
Its rule is simple: convert the PDF locally to Markdown first. Then analyze the Markdown.
No cloud OCR by default. No sending the PDF somewhere else. No pretending that every document needs a heavy parser. Start with the cheap local path and only escalate if the output is empty or obviously broken.
On this machine, the fallback tool is PyMuPDF. It was already installed as fitz, and it handled the contract fine. The skill also prefers pymupdf4llm when available, because it is built for Markdown-style extraction. That package is not installed here yet, so the first version uses the thing that actually exists.
That last sentence matters. A workflow that depends on the tool you wish you had is not a workflow. It is a future excuse.
What validation looked like
The first validation failed.
Not because of the PDF. Because the skill examples used python, and this host only has python3.
Good. That is exactly why validation exists. A pretty instruction that fails on the actual machine is worse than no instruction. It gives the agent confidence and then trips it at runtime.
After the correction, the test was concrete:
- take the new rental contract PDF;
- convert it to Markdown;
- check that the output has metadata, a source hash, and page markers;
- verify that the text includes the title and the two clauses we were looking for;
- confirm that the output is not tiny, which would suggest a scanned or image-only PDF.
The generated Markdown had five page markers, about 12,700 characters, and the two exact phrases I cared about: recargo del 5% diario and podrá visitar la vivienda.
That is enough evidence to trust the next step.
Why Markdown helps
Markdown is boring in the right way.
It is searchable with rg. It can be diffed with diff -u. It can be archived next to the original PDF. It can include a SHA256 hash so I know which source produced it. It can be read by a model without paying for the PDF wrapper every time.
And when a corrected contract arrives, I don't want a vibe check. I want this:
- old clause
+ new clause
Then the assistant can spend tokens on judgment instead of extraction.
In this case, judgment meant saying: the 5% daily penalty is disproportionate, and the inspection clause should say the visit is by appointment, at a reasonable time, and only to check conservation.
That is where AI is useful. Not in admiring the document. In finding the sentence that changes the deal.
The small lesson
Most AI improvements are not dramatic. They are little cuts in waste.
Convert before analyzing. Validate before installing. Compare text before asking for interpretation. Use the boring local tool before reaching for a bigger one.
That is the pattern I want more of in my assistant: less magic, more receipts.
The PDF is still the legal document. Markdown is the working copy.
That distinction keeps the workflow honest.