How to write agent-friendly API documentation

API documentation is evolving to accommodate AI agents that require clear, structured, and machine-readable information to function effectively alongside human developers. This emergent need necessitates a blend of human-readable and machine-readable artifacts, such as OpenAPI specifications and JSON Schema, to ensure AI agents can retrieve, parse, and execute actions correctly within product workflows. Unlike human developers, AI agents cannot infer missing information, so precise definitions of required fields, valid states, error responses, and sequencing rules are crucial to prevent errors and ensure reliable operations. As AI agents become integral to development workflows, documentation must clearly outline workflows, maintain consistent terminology, and include machine-readable versions to enhance retrieval and execution. The introduction of llms.txt files serves as a discovery tool, guiding AI systems to relevant documentation without parsing full HTML pages. Consequently, comprehensive agent-ready documentation becomes essential, not only for explaining product usage to developers but also for enabling AI systems to discover tools, choose actions, and recover from errors efficiently.