Is your tech stack AI ready?

We're at the start of a transformation; the rise of AI can be likened to the rise of mobile devices some 15 years ago or the rise of cloud computing.

Those technologies didn't replace everything we knew and used, but did completely transform our industry.

The explosion of innovation and opportunity was visceral as we came to grips with what this technology could unlock, however for enterprises there would be significant investment before the value could be realised.

So, is your tech stack AI ready?

Part 1: Context engineering, engineering

Context engineering is now cementing itself as a true engineering responsibility and area of expertise. We've evolved past 'prompt engineering', now recognising that good prompt design is only as good as the data (read: context) available to the LLM to yield a response.

The methods and tactics used for good context engineering will differ for the specific use cases, but the overarching challenges are the same:

How do you give the LLM the right amount of relevant information so it truly understands, without getting lost or confused

It's important to note 'relevant' is italicised and bold, for good reason!

We know that pasting enormous slabs of general information tenuously connected to the topic at hand yields better results than zero information, however life is significantly easier and more enjoyable when you have the confidence your queries are connected to real, rich, and deterministic context.

Too much context results in confusion and pollution of response quality.

Too little context results in generic answers and often confident hallucinations.

The right amount of context is where you get sharp and reliable responses. This is the challenge.

Part 2: Agents: Brilliant amnesiacs

The way in which AI agents build software is changing. AI is taking more of the workload while engineers act as coordinators and orchestrators of agents, jumping in to provide guidance, feedback, and improve upon what was created.

This 'co-piloting' of engineering work is very different from pair programming. Your digital offsider may be perky and eager, but they have the memory of a goldfish despite their ambitions.

LLMs are stateless, so you're frequently needing to re-onboard them into your environment with every request. Your agent is eternally doomed to forget their achievements and be repeatedly onboarded into the same environment, with every request.

If we use the analogy of company onboarding (nearly always done poorly, mind you), consider the handbooks, guides, policies, docs, and references provided. What are the agent's equivalents, which pieces are relevant to this request, and does the agent have access to them?

Is the knowledge written down, in a complete and up to date format they can access?

Such a small question represents a non-trivial challenge for nearly every tech company.

Part 3: Dude, where's my shirt?

Imagine an eCommerce website's chatbot. You visit the site, log in, and type the simple question into the chat field: "When do I get my tshirt?".

Such a simple question is a good example of how to expose hidden complexity by breaking down the steps:

System checks memory → Memory tool
Recent orders listed → Orders tool
Return items by ID → Product catalog service
Find tracking number → Shipping service
Get ETA on delivery → External delivery company's API
Collate and respond

Simple! The question triggers a six step process so the customer can get an ETA on their delivery.

These natural language user experiences are forcing engineers to wrangle with existing data in new ways to translate simple questions into simple responses, through mountains of complexity. This has traditionally been the domain of APIs, however with the rise of MCPs (which sit on top of APIs) the chatbot UX is becoming more an expectation and less a delighter.

While MCPs are needed to enable agentic workflows across different systems, their creation (and governance) is not so simple.

Part 4: Live wires

The tasks involved to expose your mountains of data to your agent can feel like a checklist through your ecosystem.

Docs in Confluence? Use the Confluence MCP.
Application monitoring context needed? Use the Datadog MCP.
Got a design system? MCP for Storybook.
APIs? Use Appear's MCP.

This will unlock the live system understanding for your agents, at the cost of tokens and agent drift (which is a topic for another post), but it will supercharge your IDE, and force you to write strict prompts and add clear rules to guide the agents.

What if, however, you want to be creating MCPs for internal tooling, innovation, and context engineering to help your teams get better outcomes from AI? You can be cautiously optimistic of third-party vendor MCPs, but what about your teams creating their own?

Part 5: Designing for Brilliant Amnesiacs

Remember our eager, goldfish-brained agents from Part 2? Now imagine giving them access to your production systems.

MCPs provide non-deterministic firepower: different models, prompts, and toolchains produce different sequences of calls, even when the intent is the same. Your server can't assume a consumer's bias, interpretation, or tool selection logic.

Let's revisit our t-shirt customer. The agent needs to chain together five services to answer "when do I get my tshirt?" But what happens when the shipping MCP's documentation says the ETA field returns "estimated delivery" without specifying the format? One model interprets "3-5 days" as a countdown. Another reads "2025-06-03" as a timestamp.

A third hallucinates a date entirely because the field was null and the docs didn't say that was possible. Your customer gets told their shirt arrives yesterday. Support ticket raised. Trust eroded.

The bar for contracts and documentation just got higher. You're no longer writing for veteran teammates who'll ping you on Slack when something's ambiguous. You're writing for brilliant, optimistic, ephemeral amnesiacs that need strict, rich, explicit instructions to behave predictably.

Predictability is a function of the quality of instructions.

What good MCP documentation looks like

Treat your OpenAPI/JSON Schema as a runtime contract, not a brochure:

Typed everything. Error models, nullable fields, enum values—if an agent has to guess, it will guess wrong.
Worked examples. Not just schema definitions, but "here's a real request and response for the happy path, and here's what failure looks like."
Rate limits as first-class citizens. Publish them in docs. Return typed 429s with Retry-After headers. Show agent-friendly backoff examples.
Versioning that machines can parse. Changelogs, deprecation windows, and breaking change notices shouldn't require a human to interpret.

This is the problem we're solving at Appear—deriving accurate, live API schemas and keeping documentation in sync with actual system behaviour. Because the gap between "what the docs say" and "what the API does" is exactly where agents go off the rails.

Part 6: Trust No Agent

Your old security measures still matter. But LLMs act like tireless, creative vulnerability scanners—fuzzing prompts, chaining tools in weird orders, brute-forcing edge cases you didn't intend to expose.

Anything ambiguous becomes an attack surface.

Confusing pagination? An agent might loop indefinitely. Permissive search? It might exfiltrate more data than intended. Weak auth flow? It will find the gaps you forgot existed.

The non-negotiables

Least privilege at the tool boundary. Scoped keys, per-tool quotas, tenancy checks. An agent helping with order tracking shouldn't have access to refund processing.

Schema validation on everything. Request and response. If the agent sends malformed input, reject it at the boundary—don't let it propagate.

Assume hostile content. In multi-tenant and retrieval-augmented systems, user content often becomes part of the prompt. Segregate contexts per user. Never intermingle untrusted content. Require structured arguments validated against schema; reject free-text commands.

Observability from day one. Propagate trace IDs from agent → tool → service. Log structured request/response envelopes for forensics. When (not if) something goes wrong, you'll need the audit trail.

Idempotency isn't optional

Agents retry. Networks fail. Context windows get exhausted mid-flow and the agent restarts.

Support idempotency keys on mutating endpoints. Document replay semantics. Make it safe for an agent to call your endpoint three times when it meant to call it once.

Conclusion: Context is critical (and hard)

We're at the same inflection point we saw with mobile and cloud, except AI is more sensitive to context quality. Loose contracts, missing examples, and ambiguous guardrails don't just cause bugs. They cause agents to confidently explore the negative space of your system.

The companies that win this transition will be the ones that treat their specs as executable truth, ship golden paths that agents can copy verbatim, and prove zero-trust by default at every tool boundary.

Your tech stack doesn't need to be rebuilt for AI. But your documentation, contracts, and boundaries? Those need to level up.

Getting Started

Getting your APIs AI-ready doesn't require a rewrite - it requires visibility. Appear automatically captures schemas from live traffic, validates & enriches them, and keeps your documentation in sync with actual system behaviour. No manual spec maintenance, no drift, no guesswork for agents.

We're building the schema automation platform for enterprises, API teams, and developers who need their APIs to work reliably with AI agents—without the overhead.

Ready to make your APIs AI ready? Get started for free.