Production AI systems need better API design, not lower standards

At a glance

What this is: This is a WorkOS recap of an Enterprise Ready Conference 2025 panel arguing that production AI systems need clearer APIs, denser documentation, and stronger guardrails rather than relaxed design standards.

Why it matters: For IAM and platform teams, the article matters because AI-driven workflows still depend on tightly governed API exposure, workflow boundaries, and accountability, especially when automated systems are given production access.

Context

Production AI systems depend on a governance assumption many teams are now testing to failure: that an automated system can safely infer intent from weakly designed interfaces. In practice, ambiguous APIs, hidden internal jargon, and broad operation exposure create the same kind of access and execution confusion for AI systems that they create for humans.

The article argues that the control problem is not whether AI can call tools, but whether the surrounding API and workflow design makes correct use reliable. That puts conceptual clarity, documentation density, and guardrails squarely in the identity and access discussion, because these systems only work when exposure is deliberately constrained.

Key questions

Q: How should teams design APIs so AI agents can use them safely?

A: Teams should make APIs explicit, structured, and predictable. That means machine-readable errors, documented states, clear rate-limit behaviour, and complete schemas. Agents do not infer intent well, so any ambiguity in the contract turns into retries, misreads, or brittle workarounds that are hard to govern at scale.

Q: Why do unclear APIs create more risk when AI agents are involved?

A: Unclear APIs increase risk because AI systems rely on semantic precision to choose actions at runtime. If the interface uses internal jargon or inconsistent abstractions, the system may select the wrong operation, chain unsafe steps, or exceed intended scope. The problem is not intelligence alone. It is that ambiguity turns access into guesswork.

Q: What do security teams need to verify before exposing an MCP server to users?

A: Teams need to verify who can register as a client, what scopes they can request, how tokens are validated, and how consent maps to real tool permissions. If any of those links are vague, the MCP server can expand access beyond the user’s intent or the organisation’s policy. Auditability should be built in before go-live.

Q: How do you know whether documentation is good enough for AI use?

A: A practical test is whether an agent can extract the right answer from the documentation without prompting around gaps or inventing missing steps. If the result depends on filler or long prose, the docs are not sufficiently dense or structured for machine consumption. Measure success by retrieval accuracy and correct task completion, not document length.

Technical breakdown

Why semantic clarity matters for AI-facing APIs

AI systems are semantic engines, not mind readers. They depend on stable terminology, intuitive abstractions, and documentation that maps cleanly to real business actions. When an API exposes internal jargon or poorly defined objects, the model may still respond, but the result is brittle execution because the agent cannot reliably infer the operator's intent or the control boundary around each action. This is why the article's panelists emphasised clean primitives rather than more prose. Practical implication: treat ambiguous API semantics as an access-design flaw, not just a developer experience issue.

Practical implication: Review exposed operations and rename or reframe anything that an automated system could misread as multiple actions.

Workflow primitives are the control layer production AI needs

The article draws a sharp line between fuzzy tasks and concrete platform work. LLMs are good at reading, summarising, and synthesising, but production systems need durable primitives such as scheduling, status checks, transactions, and result aggregation. Those primitives define the actual workflow boundary. If teams expose every underlying API call instead of packaging the work into bounded workflow steps, the system becomes harder to govern and easier to misuse. Practical implication: design agent interactions around workflow primitives, not raw system capability.

Practical implication: Expose bounded workflow steps rather than direct access to every underlying production action.

MCP changes the exposure question, not the need for control

Model Context Protocol makes integration easier, but the article shows why easier integration is not the same as safer integration. When MCP is used as a one-to-one wrapper for internal APIs, teams can accidentally surface destructive actions without rethinking the use case, privilege boundary, or operational context. The protocol itself does not remove the need for access design. It makes the decision about what to expose more visible, because poor mapping choices are now usable by the model in real time. Practical implication: govern MCP as a controlled exposure surface, not a shortcut to publishing every internal capability.

Practical implication: Apply the same exposure review to MCP endpoints that you would apply to privileged APIs.

Breaches seen in the wild

• Nx s1ngularity attack 2025: Attackers stole Nx's npm token via a GitHub Actions flaw and shipped malware that stole 2,349 secrets and abused developers' AI CLIs.

Read and download The State of NHI & AI Agent Breach Report 2026, covering 150+ breaches impacting Non-Human Identities including AI Agents.

NHI Mgmt Group analysis

Clear API semantics are now part of AI governance, not just developer ergonomics: the article shows that production AI systems fail when exposed interfaces encode internal language instead of externally legible business actions. That is not a documentation problem alone, because semantic confusion becomes execution ambiguity once a model is allowed to choose and combine tools. Practitioners should treat API meaning as a governed control boundary, especially where automated systems are the caller.

Workflow granularity is the practical limit of safe automation: successful systems separate fuzzy interpretation from concrete execution, using bounded workflow primitives for scheduling, transactions, and status handling. That separation matters because the model can be useful without being handed unrestricted operational scope. The implication is that production AI architecture should privilege task-shaped access over capability-shaped access.

MCP does not justify weaker standards for privileged operations: the panel's production-database example illustrates a familiar governance failure, not a new one. If a human would never be granted a one-click destructive action without controls, an AI system should not receive that exposure simply because the integration path is convenient. The control question is not whether the model can call the tool, but whether the tool should be exposed in that form at all.

Accountability cannot be outsourced to the model: the article's emphasis on authorship and responsibility is a useful reminder that AI assistance does not change ownership of the work. That principle matters for identity governance because delegated execution still requires a named responsible party, even when the task was drafted, summarised, or partially executed by an automated system. Teams need governance that preserves human accountability while constraining machine action.

Information density is becoming a security property of documentation: if an LLM or agent can only extract two useful sentences from a bloated guide, then filler is not harmless. Dense, precise documentation improves correctness, reduces mis-execution, and lowers the chance that an agent fills gaps with unsafe assumptions. For practitioners, documentation quality is now part of the operational control plane around automated access.

What this signals

Conceptual clarity debt: when APIs inherit internal jargon, production AI systems inherit the same ambiguity and the risk is mis-execution at the point of action. Teams should treat semantics, not model capability, as the first governance layer for automated workflows.

Documentation quality is becoming a control surface for agentic systems because chat-based retrieval rewards dense, precise instructions over padded narrative. If an agent cannot reliably extract the right steps, the environment is not yet ready for machine use.

The strongest pattern in the article is not a new AI feature but a familiar architecture choice: bounded workflows outperform raw exposure when the caller may be automated. That holds across NHI, agentic AI, and broader IAM design because exposure without shape creates governance drift.

For practitioners

• Tighten API semantics for agent consumption Audit externally exposed endpoints for internal jargon, overloaded nouns, and actions that do not map cleanly to one outcome. Rewrite those interfaces so an automated caller can infer intent without guessing.
• Package production work into bounded workflow primitives Expose scheduling, status checks, transaction steps, and result aggregation as discrete workflow units rather than letting agents compose raw low-level operations.
• Review MCP exposure as a privileged access decision Classify every MCP-connected capability by the real-world impact of the action it unlocks, then remove or constrain any operation that would be unsafe if invoked directly.
• Measure documentation by extraction quality, not page count Test whether an LLM can answer implementation questions from the docs without hallucinating missing steps. If it cannot, the issue is not length but information density and structure.
• Preserve named accountability for AI-assisted work Require a responsible owner for any AI-generated or AI-assisted operational change, especially where the work can affect production systems or access paths.

Key takeaways

• Production AI systems do not become safer when APIs are vague, overexposed, or full of internal jargon.
• Workflow primitives and dense documentation are the practical controls that make automated execution predictable.
• Teams should govern AI-facing interfaces as access surfaces, with explicit boundaries and named accountability.

Key terms

• Conceptual Clarity: The degree to which an interface, workflow, or document expresses one business action in language that callers can interpret consistently. In AI systems, unclear concepts create execution errors because models depend on semantic structure to choose the right tool and sequence.
• Workflow Primitive: A workflow primitive is a bounded operation that performs one clear business function, such as scheduling, status checking, or transaction handling. In AI-enabled systems, primitives matter because they constrain what an automated actor can do without exposing the full underlying API surface.
• Documentation Density: The amount of decision-relevant information a document carries per unit of length. For AI-assisted use, dense documentation is more reliable than verbose documentation because models extract meaning from structure and specificity, not filler or repetition.
• MCP Exposure Surface: The set of endpoints, tools, and sessions that can be reached through an MCP integration. It is broader than the network path alone because it includes identity context, tool permissions, and the lifetime of the access path.

Deepen your knowledge

NHI governance, agentic AI identity, and machine identity lifecycle are core topics in our NHI Foundation Level course, the industry's only accredited NHI security programme. If you are building or maturing an IAM programme, it is worth exploring.