Two Approaches to Helping AI Agents Use Your API (And Why You Need Both)

AI coding agents often encounter predictable failures when interacting with APIs, primarily due to issues of "known unknowns" and "unknown unknowns." Mintlify's skill.md addresses the "known unknowns" by providing agents with a static briefing that includes decision tables and common pitfalls, preventing the use of deprecated methods or misconfigurations that documentation alone might not avert. Meanwhile, Armin Ronacher's REPL-first MCP tackles the "unknown unknowns" by offering a Python shell where agents can dynamically discover the existing system environment, such as collections and schema details. Both approaches are essential because they complement each other by addressing different failure modes; skill.md offers static knowledge to avoid known mistakes, while the REPL enables dynamic discovery of the current environment. Together, they help prevent routine failures, allowing developers to focus on more complex challenges that AI agents might face.