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.
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.
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.
Top comments (0)