Agent-facing documentation needs testing against real customer tasks

Agent-facing documentation needs product-level testing

Developers remain responsible for applications their agents build, but an agent can choose a dependency before a developer has assessed its fit. Once working code relies on that choice, replacing it means rework. So vendors and open source leaders need to test how their documentation affects implementation: whether agents follow requirements, use the technology correctly, and recognize when another product would serve the customer better.

Agent choices can become commitments before human review

This influence extends the role developers already play in technology adoption. Stephen O’Grady’s The New Kingmakers helped establish the importance of appealing to developers; vendors now also need to make their products understandable and usable by developers’ agents. Agents can write code and select the tools and libraries behind an application. Developers retain ownership, even when agents make decisions that shape what they receive.

Research recently highlighted by Richard Seroter shows how strongly an agent can influence a person’s choices. Anthropic, which sells AI models and benefits from their adoption, studied 50 professional analysts working with agents whose preferences had been secretly randomized. Across four analytical choices, participants followed the agents’ guidance 86% of the time. Anthropic’s researchers describe an assumed subordinate role in which the agent “writes the code, runs the numbers, and offers advice,” even as it influences the decisions themselves.

An agent might select a library, build an application around it, and then present the result for review. Replacing the library would mean giving up some completed work, so keeping it becomes the easier path. This explains why an early recommendation matters to vendors: a technology can enter a project before anyone makes a purchasing decision. Its place in the implementation can then influence later spending.

Test discovery, correct use, and suitability separately

Because early selection matters, vendors need to distinguish being considered from being used successfully. Microsoft developer advocate Waldek Mastykarz proposes a discovery test: give the agent a representative task without naming the product, then check whether it selects that product. A second test names the product and checks whether the agent describes and uses it accurately. Microsoft benefits when developers adopt its tools and services, so these tests serve a commercial interest as well as a documentation goal.

Supabase has pursued that opportunity through documentation, skills, reusable task instructions supplied to agents, and related material intended to help agents and large language models recognize, understand, and recommend its platform. As the platform provider, Supabase benefits when those recommendations bring developers into its ecosystem. But recognition only gets the product considered. The implementation still has to work, and a recommendation can precede any purchase order.

The competition for consideration has produced answer engine optimization, or AEO: efforts to influence what agents and answer engines recommend. Like search engine optimization, it rewards visibility and creates opportunities to manipulate default choices. Familiar technologies, persuasive instructions, and easily retrieved material can all influence an answer. Those qualities explain how a product gains attention; customer requirements determine whether it belongs in the application.

Availability also helps explain why open source projects can attract agent recommendations. Products and projects with less accessible information may receive less consideration even when they fit the task. Documentation availability therefore affects the choices an agent brings to a developer.

Consideration and correct use still leave a third question: suitability. An agent may discover a product and implement it correctly even though it lacks a required deployment option or becomes too expensive at the customer’s scale. Discovery tests measure whether the product enters the decision; correctness tests examine whether the agent can use it. Suitability tests must assess the customer’s requirements and the consequences of choosing it.

Test instructions against implementation failures

Correctness testing becomes concrete when an agent attempts a real task. In June, Microsoft’s Garry Trinder described an agent trying to upgrade a SharePoint Framework project by manually changing package versions. The upgrade required additional changes that the CLI for Microsoft 365, a command-line tool, could perform. This incomplete approach offered a way to test whether documentation could redirect the agent.

Trinder first tested a direct tip pointing the agent toward the tool, which it used in one of five runs. The documentation was then changed to explain that updating package versions alone would cause build failures. With that explanation, the agent used the tool in all five runs. The test concerned tool selection within an existing Microsoft project, where Microsoft also benefits from successful use of its development tools.

The change worked by connecting the tool to a defect in the agent’s plan. A direct recommendation named the preferred tool; the failure explanation showed why the proposed package edits would leave the task unfinished. Writing that explanation required product knowledge: which upgrade steps were missing, what would break, and how the tool handled the remaining work. The evaluation then checked whether the agent acted on that knowledge.

Supabase encountered a different gap between product awareness and implementation quality. The company reported that agents knew about its platform but omitted security requirements and guessed commands. It also found that agents sometimes skipped separate reference files, so it moved essential security guidance into the main instructions. This put requirements in material the agent was more likely to consult while doing the work.

Access to the right material also depends on how current it is. Supabase directs agents to current documentation to reduce their reliance on remembered APIs, the interfaces software uses to interact with a service. A newer model can still use outdated product information, so instructions must guide it toward the documentation that applies to the implementation now. The company addressed both where agents found information and which version they used.

These cases suggest different checks for a documentation evaluation. Trinder’s experiment tested whether a failure explanation changed tool selection; Supabase’s reported failures pointed to security guidance, command accuracy, and access to current instructions. Teams can use those failure types to define observable outcomes for their own tasks. The question is whether an agent completes the work correctly after consulting the material.

Adding another hundred pages would leave those questions unanswered unless the new material addressed the relevant failures. An agent could become better at describing a product while still overlooking a security requirement or attempting an incomplete upgrade. Useful guidance identifies how the customer’s task can fail and explains how to avoid that failure. Tests should then check the resulting implementation rather than count product mentions.

Govern instructions as changes to product behavior

If documentation edits can change implementation choices, teams need to review those edits accordingly. Google’s Remigiusz Samborski recently described controls for changes to Google Agent Skills: versioning, evaluation evidence, automated checks, AI review, and approval by a human subject matter expert. These checks happen before export to GitHub. Google benefits when developers use its products successfully through agents, giving the company a commercial reason to improve instruction reliability.

The controls connect a particular version of the instructions to evidence about its effects. Automated checks and AI review contribute to that assessment, while a human expert retains approval responsibility. Other teams can apply the same principle with a process suited to their work: identify the change, test the behavior it should produce, and assign someone qualified to approve it. Approval should cover the test’s relevance as well as the instructions’ wording.

Relevant tests begin with people who understand the product and the customer’s work. Product and business experts need to choose representative tasks, define consequential failures, and identify limitations that agents must recognize. Documentation and developer-marketing teams can then turn that knowledge into instructions available during execution. This puts their expertise to work when the agent makes a choice, rather than relying on a developer to remember a hypothetical webinar from six months earlier.

For a database, a proposed evaluation could start with the customer’s existing schema, the structure of its stored data, and follow the migration through to a working application. The task would include permissions and recovery from failure because successful setup leaves those operational questions unresolved. The evaluation would show whether the instructions support the full migration. It would also reveal where product knowledge needs to become explicit guidance.

For an API company, an illustrative evaluation could ask an agent to implement safe retries without charging a customer twice. A retry sends a request again after an apparent failure, but the original request may already have taken effect. So the test would need to examine the charging outcome as well as whether a request eventually succeeds. This proposed scenario shows how a business consequence determines what technical correctness requires.

AI can help generate and run such evaluations, while people decide which outcomes count. A narrowly chosen task can leave important failures outside the test, and a set of favorable tasks can hide poor fit. Reviewers therefore need to assess the evaluation’s coverage alongside the agent’s performance. Their choices carry both technical and commercial consequences.

That responsibility continues as products and workflows change. Instructions need maintenance, and their evaluations need to track the tasks customers now perform. Otherwise, a passing test may reward an outdated approach. Treating agent-facing material as a maintained interface makes its effects on execution part of ongoing product work.

Include reasons to choose another product

A complete evaluation also needs cases where selecting the product would be the wrong outcome. AEO gives vendors a reason to seek more recommendations, while customers need recommendations that honor their requirements. Teams should therefore define conditions under which the agent should recommend an alternative. This makes suitability directly testable.

Dwight Merriman, MongoDB’s cofounder, advocated a useful precedent during the database’s early years. He insisted on publishing both the situations where MongoDB worked well and those where it was weak. As a cofounder, Merriman had a commercial stake in adoption, making his willingness to explain poor fit especially relevant. The appropriate use cases changed as the database evolved, so the guidance also needed to change.

A proposed deployment test could give an agent a requirement the product does not support. The evaluator would check whether the agent identifies the conflict and explains it before proposing an implementation. Success would mean preserving the customer’s requirement even when that rules out the vendor. Publishing clear limitations gives the agent the information it needs to reach that decision.

A proposed cost test would examine an implementation that works technically but becomes expensive at the customer’s expected scale. The agent should identify the relevant cost and explain how it could change the choice. Evaluating that warning requires a usage scenario with enough context to make the cost meaningful. Technical success alone leaves the customer’s commercial decision incomplete.

Vendors may hesitate to supply information that sends customers elsewhere. Yet an unsupported deployment or unsuitable cost structure can damage trust when implementation exposes the mismatch. Clear limitations let developers and their employers judge the trade-off before committing work. Helping customers make a choice they can justify has strategic value.

Those limitations need the same maintenance as implementation instructions. Merriman’s example shows why: a use case that once exposed a weakness can become appropriate as a product develops, while new requirements can reveal other limits. Teams should test whether agents apply the current conditions for fit. Customers whose constraints exclude the product need that answer before implementation begins.

Give developers a decision point before implementation

Developers can bring that suitability check forward by stating constraints before asking an agent to recommend a technology. They can specify deployment requirements, expected scale, and other conditions that would rule a product out. They can also ask what evidence would favor an alternative and compare options before the agent builds around one. These safeguards make the decision explicit while changing direction requires less rework.

The review should ask the agent to explain why its selection fits those stated conditions. Developers can then examine the reasoning alongside the proposed implementation and decide whether to proceed. A clear decision point separates selecting a dependency from authorizing the work that will make replacement costly. Human review happens while the choice is still easy to change.

Recap

Agent-facing documentation now influences decisions that can commit engineering time and shape later spending. For business leaders, that makes its quality a product responsibility. Being recommended is useful only when the product fits the customer’s requirements and the agent can implement it correctly.

Leaders should assign ownership for that outcome. Product experts need to define representative tasks, consequential failures, and conditions that should rule the product out. Documentation teams need to make that knowledge available during execution. Changes should be tested against those outcomes before approval, with evaluations maintained as the product evolves.

The same discipline applies inside organizations using agents. Teams should state deployment, security, and cost constraints before an agent selects dependencies, then review the proposed choice before implementation makes replacement expensive.

The business objective is a technology decision the customer can justify, not simply another recommendation. Sometimes that means helping an agent use the product successfully. Sometimes it means helping the agent recognize that another product fits better. Both outcomes deserve a place in the evaluation.