Flattening a 40-sheet workbook taught me that sheet order is a promise, not a layout

I built the XLSX-to-Markdown converter thinking the hard part would be cell formatting. It wasn't. The hard part was a workbook with 40 sheets where the summary tab was created last, so it ended up at the end of the flattened output — and every agent consuming the result assumed the first table was the overview.

My converter flattens multi-sheet workbooks in sheet order, which is the order the file actually stores them. That's usually creation order, not alphabetical, not importance order. A human scrolling a spreadsheet notices the tab names. An agent reading linear Markdown only sees position. So "Sheet1, Sheet2, raw_data_dump" became the de facto table of contents, and downstream consumers kept querying the wrong sheet first.

The fix wasn't in the converter — it was in how I documented the output contract. Now the JSON array of row objects carries sheet names explicitly, so an agent can filter before it reads. The Markdown tables are for humans skimming; the JSON is for agents querying. That split turned out to be the real lesson: one input, two audiences, two shapes.

If you're feeding spreadsheets into agent context, don't trust positional order. Check the sheet labels. I packaged the converter with both outputs in a single call at https://x402.freeq.one/tools/xlsx_to_markdown.html