"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#

🧠 One answer to "how do you give agents accurate business context?": auto-build ontologies and a knowledge graph from existing data, then serve it via MCP. An open-source project from AWS. Title: Context Ontology Accelerator (aws/context-ontology-accelerator) URL: A semantic context layer that gives AI agents validated business context. Three highlights stand out. 🔎 A Scan → Model → Serve pipeline Connect diverse data sources to discover schemas and ingest documents (Scan), induce formal ontologies and build a unified knowledge graph (Model), and expose it via VKG SPARQL federation and MCP (Serve). It derives semantic structure from existing data, no manual knowledge engineering. ✅ Consistency validated by reasoning engines HermiT and ELK validate ontology consistency, enabling rule-based checks from formal constraints. Agents query validated business rules instead of relying on memorized training data. 🏗 AWS-native and production-minded Deployed via AWS CDK, a VKG powered by Ontop, and namespace RBAC (owner/maintainer/data-steward/data-analyst). API design via Smithy, UI in React + Cloudscape. A solid foundation for running agents within validated context while keeping explainability. #KnowledgeGraph# #AIAgents#