Agent knows only public API knowledge

When an agent operates with only public API knowledge, it answers questions about your codebase using information from its training data - open-source documentation, public GitHub repositories, Stack Overflow, and official library references. It knows what the Stripe API looks like in general, what a typical PostgreSQL schema looks like, how Express.js middleware works. It does not know what your Stripe integration looks like, what your PostgreSQL schema looks like, or how your Express middleware is wired.

This state is almost universal at L1. The agent is genuinely helpful for generic programming tasks - "how do I write a regex that matches email addresses," "what does Array.reduce do," "show me an example of a React useEffect" - but degrades significantly the moment the question becomes internal. "What parameters does our UserService.create method accept?" gets answered with a guess based on what UserService.create usually looks like in public codebases. The guess is often structurally plausible but specifically wrong.

The core problem is that the agent has no way to distinguish between your API and the public API it was trained on. If your internal library wraps a popular framework and diverges from the default conventions, the agent will follow the public convention and produce code that fails at runtime. This failure mode is particularly insidious because the code looks correct - it would be correct for the standard library. Only a developer who knows the internal divergence will catch it.

• Hidden correctness degradation - agents confidently produce wrong internal-API usage without any signal that they're guessing; the errors surface later in testing or code review, not at generation time
• Quantifies the context gap - measuring how often agents suggest the wrong internal API variant reveals exactly how much value is being lost to the public-API-only limitation
• Makes internal library investment risky - teams that build internal abstractions on top of popular libraries are penalized at this level; the more your codebase diverges from public conventions, the worse agent output quality becomes
• Motivates the simplest MCP investment - pointing an agent at your actual source code (via a filesystem MCP server or Claude Code's native file access) immediately closes the gap for the most common failure mode
• Differentiates agent types - understanding this limitation helps teams route tasks correctly: use agents for generic tasks where public knowledge is sufficient, and route internal-API tasks to agents with actual codebase access

1. Catalog your internal divergences - identify where your codebase deliberately deviates from public conventions: custom wrappers, renamed methods, non-standard configuration, internal service APIs. These are the highest-risk areas for public-API-only agents.
2. Test agent accuracy on internal APIs - pick 10 real internal API usage examples and ask your agent to write them from scratch. Score how many are correct without correction. This number is your baseline accuracy on internal context.
3. Enable file access in your AI client - Claude Code and Cursor both support reading local files natively, without MCP servers. This is the fastest way to give an agent internal context. Ensure your developers know how to add relevant files to the agent's context window.
4. Create an internal API cheat sheet - for the highest-divergence internal APIs, write a short description of how they differ from the public convention. Keep it as a markdown file that developers can paste into agent context. This is a manual workaround until proper MCP integration is in place.
5. Add internal docs to a basic MCP server - the step beyond manual file-pasting is a docs MCP server that exposes your internal documentation. Even a simple server that reads from a local directory of markdown files dramatically improves agent accuracy on internal APIs.

Assuming the model "knows" your internal library because it's based on a popular framework. If your internal HTTP client wraps Axios but changes the method signatures, the agent will use Axios signatures. Wrapping does not inherit documentation in the model's training data. Every internal abstraction is invisible to a public-knowledge-only agent.

Using agents for internal API integration tasks without checking output. Developers who trust agent output without verification on internal API usage will ship bugs. The output looks correct. A review process that treats agent-generated internal API calls as requiring human verification catches these errors before they reach production.

Not updating the agent when internal APIs change. Even when developers do provide internal API context (via pasted docs or file context), they often paste outdated versions. Internal APIs evolve; the context provided to agents often doesn't. A doc MCP server that reads from the live internal documentation directory solves this; manual paste workflows do not.

Conflating IDE autocomplete with API knowledge. IDE language servers and type-aware autocompletion tools do know your internal APIs - they parse your actual codebase. This is different from agent knowledge. A developer might see correct autocomplete suggestions from their IDE and assume the AI chat assistant has the same knowledge. It does not.