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 two failure modes: not knowing what they don't know (known unknowns) and not being able to discover what exists (unknown unknowns). Two innovative solutions have been proposed to address these issues: Mintlify's SKILL.md and Armin Ronacher's REPL-first MCP. SKILL.md offers a structured briefing, incorporating decision tables and explicit gotchas, to provide agents with pre-coded knowledge about using APIs, thus preventing errors like using deprecated methods or misconfiguring parameters. In contrast, Ronacher's REPL-first MCP allows agents to interact dynamically with the system, using a Python shell to explore and understand the API environment, thus addressing the unknown unknowns by discovering the current state of collections and schemas. While each approach individually resolves specific problems, their combined use ensures that agents are equipped to handle both static and dynamic challenges, enabling them to write more accurate and context-aware code. Despite these advancements, agents may still misinterpret user intentions or fail to grasp complex requirements, but the integration of SKILL.md and REPL significantly reduces common errors, allowing developers to focus on more complex issues.