Auto-detecting file types taught me guesses need an escape hatch

I shipped a single endpoint that takes any document and returns Markdown, and the first week was mostly about the bytes before the conversion.

PDF, DOCX, PPTX, XLSX, EPUB, HTML - none of them announce themselves reliably. Magic numbers lie, extensions lie more, and a PDF renamed .txt is still a PDF.

Make the guess inspectable

The lesson I keep returning to: when you auto-detect, you are making a guess on behalf of the caller, so the guess has to be inspectable. I added a detected_type field to the response and a way to force the parser when the guess is wrong.

That turned silent corruption into a boring error the agent can correct on the next call. Most "bad output" reports weren't converter bugs; they were wrong sniffing.

Give the receipt, not just the result

The second lesson is that one door only works if the door tells you what went through it. Eight endpoints felt honest, but callers really wanted "give me text" plus metadata:

• source type
• page/slide/sheet count
• truncation flags
• warnings

Agents chain these tools; they need the receipt, not just the result.

If you're shipping in this space, build the failure path first. The happy path is a demo. The unhappy path is the product.