SaaS Documentation for AI Agents: The Boundary Between Reading, Tools, and Actions

Two labels mark evidence boundaries on this page. Documented means the statement it sits beside is directly supported by the linked specification or vendor documentation, quoted. Recommendation means a model, threshold or division of labour that CoreAEX prescribes and no specification documents. Untagged text is ordinary explanation or a conclusion following from something already labelled. Note that a specification stating what implementors SHOULD do is documentation of a requirement, not an observation of how any product behaves - that distinction is load-bearing throughout.

"Agent-ready documentation" is two projects wearing one name, and they have different owners. Whether an agent can reach and interpret your documentation is a documentation-access and content-clarity problem, shared across documentation, SEO and web engineering, and it runs on the same access mechanics as any other retrieval - which our crawler-access work already covers. Whether an agent may do something is a question of interfaces, authorization, safety and operations, running on tool definitions, credentials, scopes and confirmation. That second one is led by engineering and security, and no amount of documentation work produces it.

Within MCP integrations, the protocol makes a useful version of the same distinction - separating context-bearing resources from executable tools and assigning them different control models and safeguards. Documented That helps clarify ownership, but it is not a universal map of every AI system: MCP tools can be read-only, resources can require access controls, and implementations remain free to choose their own interaction patterns. A documentation team can make its content clearer, better scoped and version-explicit, and should. It cannot create callable operations, credentials, authorization or execution controls.

What "agent-ready documentation" merges

In our experience the phrase arrives from outside the documentation team - from a board question, a competitor's announcement, or a vendor pitch - and it bundles together things that have almost nothing to do with each other:

• An agent reading your docs to answer a user's question about your product.
• An agent calling your API to do something on a user's behalf.
• Publishing a machine-readable file so that "AI can find you."
• Running an MCP server so your product appears inside an AI application.

The first is primarily a documentation-access and content-clarity problem: the web-delivery checks are established, but the evidence about what happens downstream - whether an AI system retrieves, cites or answers correctly from a page - is thin, and the evidence section below is honest about how thin. The second is a product, engineering and security problem. The third mostly does less than it is sold as - we have looked at llms.txt specifically and that page is the verdict, not repeated here. The fourth is a product decision with a security surface.

Treating them as one project is how a documentation team ends up owning an authorization design, or an engineering team ends up rewriting help-centre articles. The rest of this page separates them and says who owns each.

Reading and acting are different mechanisms

The clearest evidence for the separation comes from the one place it is written down: the Model Context Protocol builds it into its own design. A scope note before anything else, because it governs everything in this section. MCP defines interactions between MCP hosts, clients and servers. It does not govern ordinary web crawling, documentation retrieval, OpenAPI integrations, or any agent system that does not use it. What it offers is a worked example of separating information from execution - useful evidence, not a universal architecture.

The Model Context Protocol is an open protocol for connecting model applications to external systems. It is worth being accurate about what it is: it is stewarded by a Linux Foundation entity, its governance page names maintainers as individuals, and it states that "there are no seats reserved for specific companies." Calling it any single company's protocol is not supportable at its own governance page's wording.

The specification defines three things a server can offer, and the wording of each is the point. Documented Everything quoted in this section and the table below is from the specification at revision 2026-07-28:

The MCP specification's own descriptions of its three server primitives, revision 2026-07-28

Primitive	The specification's words	Control
Resources	"Context and data, for the user or the AI model to use"	"application-driven"
Prompts	"Templated messages and workflows for users"	"user-controlled"
Tools	"Functions for the AI model to execute"	"model-controlled"

On tools, the specification is explicit about what that control means: they are "designed to be model-controlled, meaning that the language model can discover and invoke tools automatically based on its contextual understanding and the user's prompts." Resources are "designed to be application-driven, with host applications determining how to incorporate context based on their needs."

The two are guarded differently, and that difference is the useful part. The tools specification carries a warning: "For trust & safety and security, there SHOULD always be a human in the loop with the ability to deny tool invocations." The top-level security section adds that "Tools represent arbitrary code execution and must be treated with appropriate caution" and that "Hosts must obtain explicit user consent before invoking any tool."

The resources specification handles safety differently rather than not at all. Its security section has five items - URI validation, access controls for sensitive resources, binary encoding, permission checks, and path sanitisation against directory traversal - and no consent requirement or human-in-the-loop sentence. That is a documented difference in which safeguards the specification applies where. It is not evidence that resource access is ungated, and the access-control and permission requirements on that same page are the reason it is not.

Nor does the split map cleanly onto read-versus-write, and the specification says so itself. Its tool annotations include a readOnlyHint, defined in the protocol's schema as "If true, the tool does not modify its environment." A tool can be read-only - a database query or a computation is a tool. Resources, meanwhile, can carry sensitive data and require permission checks before access. Model-controlled and application-driven describe who decides that a primitive gets used, not whether the operation changes anything.

One boundary on all of this, and it matters. The specification says what implementors should do; it is not a description of how any shipped product behaves. Both pages state that "implementations are free to expose [tools/resources] through any interface pattern that suits their needs - the protocol itself does not mandate any specific user interaction model." So the correct reading is that MCP assigns different control models and safeguards to its two primitives - not that any given AI application behaves that way, and not that every system draws the line in the same place.

Where OpenAPI fits, and what it is not

OpenAPI is an interface description format, and its own specification was not written for AI.

Version 3.2.0, published 19 September 2025, describes itself this way: "The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to HTTP APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection." It names its consumers as "documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases." Documented

We ran a full-text search of the specification's normative source for AI-related terms. The counts are zero across the board: AI, LLM, artificial intelligence, machine learning, agentic, function calling, tool calling, prompt and model context do not appear. The only case-insensitive matches for agent are inside the word "Magenta" in a colour example. That is a measured absence in one version of one document. It shows that OAS 3.2.0 defines no AI-specific semantics, no agent-control model and no tool-invocation behaviour. It does not establish what any contributor intended, and it does not stop a system using an OpenAPI document as input to an AI integration - which is what the two OpenAI cases below do.

An OpenAPI document is not automatically a callable tool across systems. OpenAI's documentation shows both halves of this clearly. Its GPT Actions surface does require one: "A GPT Action requires an Open API schema to describe the parameters of the API call, which is a standard for describing APIs." But its general function-calling guide does not mention OpenAPI at all - there, function parameters "are defined by a JSON schema." Documented OpenAI's own cookbook describes the step between them plainly: "We will transform this sample spec into a set of function definitions that can be supplied to the chat completion API."

The practical reading: a good OpenAPI description is genuinely useful to an agent integration, and how directly it gets used depends on the system - one product surface takes it as the contract, the general function-calling API does not. Either way, something still has to decide which operations to expose, under whose credentials, and what happens when one fails. Recommendation That is engineering work, and it is where the decisions with consequences live.

Why crawlable documentation does not make a product agent-operable

This is the section the rest of the page exists to support. A perfectly crawlable, well-written, server-rendered documentation site tells an agent what your product does. It gives the agent no way to do it.

The gap is not subtle. To act, an agent needs an interface it can call, a credential scoped to the caller, a decision about which operations it may perform, a way for a person to refuse, and something sensible to happen when a call fails. None of those is a property of a web page, and none of them is created by publishing one.

A practice-level version of the same distinction has emerged on the agent side. AGENTS.md - an open format for guiding coding agents, stewarded by the Agentic AI Foundation under the Linux Foundation - positions itself as a dedicated location for agent instructions while README files keep their conventional human-facing role. Its own framing: "Think of AGENTS.md as a README for agents: a dedicated, predictable place to provide the context and instructions to help AI coding agents work on your project," because "README.md files are for humans: quick starts, project descriptions, and contribution guidelines." Documented

Scope that carefully. AGENTS.md is an open format rather than a specification, and its scope is coding agents working inside a repository - not an agent operating your SaaS product. It is quoted here as evidence that the split between human-facing and agent-facing material is recognised in practice - not as evidence about documentation websites, and not as a statement about why the format was created, which its own page does not give.

The inverse is also true, and it is the part teams underestimate. An agent that can call your API still needs to understand what your product's concepts mean, what a parameter does, and which constraints apply - and that is documentation work. The two projects are separable, not independent. Neither one substitutes for the other.

What the execution side actually requires

This section names what sits on the far side of the boundary, and then stops. The purpose is to let a documentation lead recognise the work and route it, not to teach it. Everything below is engineering and security territory.

Usefully, the MCP specification documents most of it in its own requirements, which makes the list something better than our opinion about what matters. Documented Every quotation in the list below is from that specification:

• Authorization and least privilege. The specification notes that the set of tools a server returns "MAY vary by the authorization presented on the request - for example, returning only the tools the caller's granted scopes permit - since credentials are per-request input, not connection state." Scoping is a per-request property, not a setup step.
• Confirmation. Beyond the human-in-the-loop warning above, clients SHOULD "prompt for user confirmation on sensitive operations" and "show tool inputs to the user before calling the server, to avoid malicious or accidental data exfiltration."
• Rate limiting and input validation. Servers MUST "validate all tool inputs," "implement proper access controls," "rate limit tool invocations" and "sanitize tool outputs."
• Error responses that a model can act on. The specification distinguishes protocol errors from tool execution errors, and describes the latter as containing "actionable feedback that language models can use to self-correct and retry with adjusted parameters." This is the one row where documentation and engineering genuinely overlap: what an error message says is a writing decision with an execution consequence.
• Audit logging. Clients SHOULD "log tool usage for audit purposes."

Note what that list is not. It is a set of requirements the specification places on implementors. It is not a description of what any deployed system does, and this page offers no guidance on building, configuring or securing any of it. If your organisation is deciding whether to expose tools at all, that decision belongs with the people who own the blast radius.

Versions, deprecations and the wrong-version problem

An agent following instructions for the wrong version of your product is a documentation failure with an execution consequence, and it is the one execution-adjacent risk a documentation team genuinely owns.

A page that does not say which version it describes is ambiguous to a reader and ambiguous to anything else that retrieves it. If three versions of an API reference are live and only the navigation distinguishes them, the distinguishing information is not in the content.

What nobody documents is how any system handles this. We looked specifically for guidance on versioned documentation, version-path URLs and version-selector interfaces across Google's canonicalisation and localised-versions documentation, its AI-features page and its crawler list, and the crawler documentation published by OpenAI, Anthropic and Perplexity. None of those pages mentions documentation versioning in any form. Google's canonicalisation guidance is the closest relevant material and is entirely generic - it addresses duplicate content, and it states that canonical methods are not required at all: "none of them are required; your site will likely do just fine without specifying a canonical preference." Documented

So version signalling is a reader-clarity decision made without engine guidance, and our recommendations here are labelled accordingly. Recommendation

• State the version on the page, in the content - not only in a selector, a breadcrumb or a URL segment. A passage extracted from the page should still say what it applies to.
• Make a superseded page say so on the page itself, with a link to what replaces it.
• Date what changed. A changelog with dated entries is the cheapest version signal there is.
• State constraints where the constraint applies, not in a general limits page. The specification's own non-normative guidance on stateful tools makes the same point about tool descriptions: a retention policy "should be stated in the creation tool's description (e.g., 'baskets expire after 24 hours of inactivity') so the model can see it when deciding to create state." That is a design note about tool text rather than a documented finding, and it is quoted as one - but the principle transfers to prose: a constraint a reader has to go and find is a constraint that gets missed.

What has actually been measured

There is real research on whether documentation quality changes what a model can do. All of it manipulates machine-facing interface text - tool descriptions, docstrings, schemas - and none of it manipulates a documentation website. That distinction is not pedantry; it is the difference between the object being studied and the object most readers of this page own.

In a targeted search completed on 2 September 2026, we did not locate a study that changes a documentation website, help centre or product page and measures whether an AI system subsequently retrieved, cited or correctly answered from it. That is a statement about what a search found on a date, not a claim that no such work exists.

Within the interface-text research, the useful finding is that the effect is conditional and its sign can reverse:

• More is not monotonically better. Hsieh and colleagues found that zero-shot prompts with tool documentation matched or beat few-shot demonstrations - and in the body of the same paper, that "a degradation in performance after the document length exceeds 600 words." The headline and the limit come from the same study and belong together.
• Retrieval quality gates the direction. Jain and colleagues found that supplying API documentation raised valid invocations of rarely-documented APIs from 38.58% to 47.94% for one model - while "negatively impact[ing] high frequency APIs when using sub-optimal retrievers (a 39.02% absolute drop)." Documentation is not a free good.
• Improvement can cost you elsewhere. Hasan and colleagues, augmenting MCP tool descriptions, report a median improvement of 5.85 percentage points in task success - alongside a 67.46% increase in execution steps and regressions in 16.67% of cases. Their abstract carries the trade-off with the figure, which is unusually honest.

Hsieh and Hasan are cited here from preprint records; Jain and colleagues' paper was peer-reviewed and published in the ICSE 2025 Software Engineering in Practice track. All three study machine-facing interface material rather than public documentation websites.

The vendors' own guidance points the same way and is worth reading as guidance rather than measurement. Anthropic's tool-use documentation states: "Provide extremely detailed descriptions. This is by far the most important factor in tool performance," and recommends "at least 3-4 sentences for each tool description." That is the most quotable sentence in this whole area, and two things about it need saying: the page states no study, sample or metric behind the ranking, and it is about tool descriptions, not documentation articles. Notably, the other two vendors make no comparable claim - OpenAI's accuracy guidance concerns the number of functions ("Keep the number of initially available functions small for higher accuracy"), and Google's entire description guidance is "Be clear and specific." Documented

Agent benchmark scores do not fill the gap either, because of where they run. WebArena states plainly: "We achieve reproducibility by making the environment standalone, without relying on live websites." τ-bench's agent interacts with databases and "a (simulated) user" generated by another language model - and it supplies the agent a domain policy document whose quality is held fixed rather than varied. The most instructive case is ToolBench, built on 16,464 live third-party APIs: within roughly seven months of ToolBench's own preprint, a successor draft (later peer-reviewed and published as StableToolBench) replaced them with a virtual server because, in its authors' words, previous work relied on "large-scale real online APIs suffering from instability of API status." Documented

We found no agent benchmark that varies documentation quality as an experimental condition. Where documents are present, they are inputs held constant. So a benchmark score tells you something about models and harnesses, and nothing about your docs.

A readiness matrix, with owners

The column that matters is the last one. Recommendation Documentation leads three of these layers and contributes to several others; engineering and security retain ownership of executable interfaces, authorization and operational controls.

What agent readiness requires, and who owns each layer

Layer	What must exist	Owner
Discovery	Crawlable, stable documentation URLs	Documentation and SEO - covered by our crawler-access work
Understanding	Clear product concepts, parameters and constraints	Documentation
Interface	OpenAPI, MCP tools or another machine-callable contract	Engineering and platform, with documentation or developer-relations input
Authorization	Explicit scopes and least-privilege access	Engineering and security
Execution	Predictable requests, responses and errors	Engineering, with documentation input on what an error says
Safety	Confirmation rules, idempotency and recovery	Engineering and security
Versioning	Current versions, deprecations and changelogs	Documentation - and no system documents how it handles them
Observation	Logs showing what the agent attempted and what happened	Engineering and platform; product and security define what must be observable

Read down the owner column before committing to a project. A brief that says "make our docs agent-ready" and means all eight rows is not a documentation brief. A brief that means rows one, two and seven is, and it is achievable.

What to tell someone who asked for agent-ready docs

Ask which of two outcomes they want, because the answer routes the work. Recommendation

If the answer is "I want AI assistants to describe our product correctly" - that is a retrieval and accuracy problem. It is documentation work: reachable pages, unambiguous statements, explicit versions, constraints stated where they apply. It needs no protocol and no new file format. If the concern is that an assistant is already saying something wrong, that has its own workflow.

If the answer is "I want agents to be able to use our product" - that is a product and engineering decision with a security surface, and the documentation team is a contributor rather than the owner. The first questions are which operations should be exposed at all, under whose credentials, with what confirmation, and what happens when one fails.

And be straight about the evidence. Clearer, better-scoped, version-explicit documentation is defensible on its own terms - readers can act on it, support handles fewer tickets, and sales stops correcting it. What is not established is that any of it changes whether an AI system retrieves, cites or correctly uses your pages. No study we located tests that, and the research that does exist measures a different object and finds effects that reverse under the wrong conditions.

That is a reason to do the work for the reasons that were always good, and not to promise an outcome nobody has measured.

---

Sources

Sources. All opened and quoted on September 2, 2026. Model Context Protocol, specification revision 2026-07-28, confirmed current at that date by the protocol's own release announcement - the separate versioning-policy page at modelcontextprotocol.io has not been updated past an earlier revision and is not cited here for currency: the specification index for the three server features, the arbitrary-code-execution sentence and the consent-before-invoking-a-tool requirement; the tools page for model-controlled, the human-in-the-loop warning, the authorization-varying tool set, the server and client security requirements, and the stateful-tools guidance, which that page explicitly marks non-normative; the resources page for application-driven and for its security section, which sets out URI validation, access controls, encoding, permission checks and path sanitisation, and contains no consent or human-in-the-loop requirement. That is an observation about which safeguards the specification places where, and is expressly not offered as evidence that resource access is ungated; the protocol's TypeScript schema for the readOnlyHint definition, which is why this page does not equate tools with state change; and the governance page for the Linux Foundation entity and the no-reserved-seats sentence. Both primitive pages state that implementations may expose either through any interface pattern, so nothing here describes how a shipped product behaves. OpenAPI: Specification v3.2.0, published 19 September 2025 - the definition and the list of consumers; the zero-count term search was run against that version's complete normative source and is scoped to it. Vendor tool documentation, none of which displays a publication date except where noted: Anthropic, Define tools - the "by far the most important factor" and 3-4 sentence guidance, which states no study, sample or metric, and concerns tool descriptions rather than documentation pages; OpenAI, function calling - JSON Schema parameters and the function-count guidance, with no mention of OpenAPI on that page; OpenAI, GPT Actions - the schema requirement, in OpenAI's own two-word spelling; OpenAI Cookbook (October 2023) - the transformation sentence; Google, Gemini API function calling (last updated 2026-08-26 UTC) - "Be clear and specific," quoted in full because it is the whole of that guidance. AGENTS.md - an open format, not a specification, scoped to coding agents in a repository. Google, canonical URLs (last updated 2026-07-10) - the not-required sentence. Research, and what each actually measured. Cheng-Yu Hsieh, Si-An Chen, Chun-Liang Li, Yasuhisa Fujii, Alexander Ratner, Chen-Yu Lee, Ranjay Krishna and Tomas Pfister, "Tool Documentation Enables Zero-Shot Tool-Usage with Large Language Models" (arXiv preprint 2308.00675; we could not load the arXiv record to confirm its version history or any venue, so none is asserted) - the 600-word degradation is in the paper body, not the abstract. Nihal Jain, Robert Kwiatkowski, Baishakhi Ray, Murali Krishna Ramanathan and Varun Kumar, "On Mitigating Code LLM Hallucinations with API Documentation", published in the ICSE 2025 Software Engineering in Practice track, DOI 10.1109/ICSE-SEIP66354.2025.00027; arXiv version 2407.09726. This is the one peer-reviewed study of the three. Mohammed Mehedi Hasan, Hao Li, Gopi Krishnan Rajbahadur, Bram Adams and Ahmed E. Hassan, "MCP Tool Descriptions Are Smelly!" (arXiv preprint 2602.14878, no venue on the record) - evaluated on a benchmark, not live software. Benchmarks: Shuyan Zhou and colleagues, WebArena (ICLR 2024); Shunyu Yao, Noah Shinn, Pedram Razavi and Karthik Narasimhan, τ-bench (arXiv preprint 2406.12045, no proceedings record located, so not peer-reviewed on our checking; successor versions exist and these figures may be superseded); Zhicheng Guo and colleagues, StableToolBench (Findings of ACL 2024). What is not claimed here, and why. Nothing on this page asserts that documentation quality, structure or format changes whether an AI system retrieves, cites or correctly uses a page - a targeted search completed on 2 September 2026 did not locate a study testing it, which is a statement about that search rather than about the literature as a whole. Every documentation-as-variable study cited manipulates tool descriptions, docstrings or schemas, and that scope is stated beside each. No benchmark figure here describes behaviour against live production software. The readiness matrix, the owner assignments, the version-signalling guidance and the two-question routing at the end are CoreAEX's own and are documented by no specification. This page gives no implementation guidance on building, authorising or operating an agent interface, which is deliberate.