"Every API team is about to serve an agentic consumer, whether they design for it or not." — A sharp piece from Pinecone on what it actually means to design agent-friendly APIs. Designing Agent-Friendly APIs The post outlines six principles for AX (Agent Experience) design. Here are the three that matter most. 🔴 Highlight 1: Errors must be instructions, not status codes "Invalid request" burns token budget while the agent guesses. The right design includes three elements in every error: what was wrong (specific field and expectation), the fix (concrete next action), and a docs link when necessary. "Response is too large. To reduce the size, try a lower top_k value." gives an agent everything it needs to self-correct on the next call. RFC 9457 Problem Details for machine-readable codes, and separate error codes for missing vs. invalid credentials — these aren't nice-to-haves, they're the difference between autonomous recovery and budget drain. 🔵 Highlight 2: One-endpoint-per-MCP-tool mirrors fail twice Large APIs converted 1:1 into MCP servers can consume "hundreds of thousands of tokens before the first call." Cloudflare exposes `search()` and `execute()` over a typed SDK — covering 2,500 endpoints for about a thousand tokens. The principle: instead of `list_users` + `list_events` + `create_event`, offer `schedule_event`. Curate workflow-shaped tools; treat the agent surface as a product, not a reflection of your internal endpoint structure. 🟡 Highlight 3: TTFSC — the metric that finally makes AX quality legible The author ran Claude Sonnet 5 against Pinecone's API with zero preloaded context. All three trials succeeded unattended. Median: 6 turns to first successful call, ~$0.30/run, ~90 seconds/run. The agent choosing raw REST: 3 turns. The agent choosing the Python SDK: nearly half its turns reading call signatures from TypeErrors. An older model's first action was installing a retired 2024 package — the current-generation went straight to the modern API. Deprecated shapes persist in model priors for years; ignoring them is a design decision with real economic consequences. Agents externalize the costs human developers used to silently absorb — docs hunting, debugging, workarounds — into measurable, billable, churn-inducing expenses. AX is now a required design discipline alongside DX. #APIDesign# #AIAgents#