Why API docs written for humans fail AI agents — and how to fix them

A developer at FamNest discovered a critical flaw in API documentation when an AI coach agent repeatedly made malformed calls to an internal retrieval endpoint, using wrong field names and inventing non-existent parameters. The root cause was not a broken endpoint but documentation written for human readers who can infer missing details — something AI agents cannot do. Unlike humans, agents rely entirely on the tokens provided to them, treating ambiguous prose as fact rather than a gap to reason through. The author argues that the growing adoption of llms.txt for AI-readable docs solves only the discovery problem, not the deeper 'contract problem' of whether an agent can call an endpoint correctly without human intervention. The key fix proposed is replacing prose descriptions with typed schemas that include enums, bounds, and defaults, giving agents a precise, unambiguous interface to work with.