Human-friendly docs can make AI agents less reliable
A firsthand agent-building experience points to structure as a cause of bad API calls. LangChain agents were making up API usage, and the likely problem was not only the model but the way the docs were organized. Markdown files, pages, and s are often built for people who click through pages, not for an LLM that must retrieve the right detail on its own.
Poor chunking and navigation can block retrieval, so the agent may use the wrong information or invent a call. One possible solution is a layer that turns existing docs into agent-ready formats. That could include semantic chunk hierarchies, descriptors, and retrieval-optimized .
The idea may be narrow enough for LlamaIndex teams and platform teams, though existing framework may already be solving parts of it internally.
Key points
- Human-readable docs may not be easy for agents to search and use.
- Bad chunking and navigation can lead to wrong or invented API calls.
- A layer could reshape existing docs for agent use.
- Semantic chunk hierarchies, descriptors, and retrieval-optimized are proposed building blocks.
- The business value depends on measurable drops in errors and token use.