Find the documentation gaps agents have to guess through
An agent can complete the task and still tell you that the docs made it expensive. Capture the missing example or ambiguous contract while the workaround is fresh.
- For
- Developer education, documentation, and API teams
- Question
- Collect documentation feedback directly from AI agents
- Start with
- Start with the quickstart flow your support team explains most often, and ask which fact was missing.
- Updated
“The refresh flow is not shown in the quickstart. I inferred it from the token response and retried after the first expiry.”
Requested changeAdd a complete token refresh example to the quickstart.
{
"tool": "submit_agent_feedback",
"arguments": {
"feedback_type": "docs_feedback",
"tool_or_endpoint": "oauth_connect",
"summary": "The refresh flow is not shown in the quickstart. I inferred it from the token response and retried after the first expiry.",
"outcome": "success",
"satisfaction": 3,
"suggested_fix": "Add a complete token refresh example to the quickstart."
}
}A synthetic example in the shape a real report takes. Emic never manufactures a report from observed behavior.
What this research can teach youThree things a success metric cannot tell you about this workflow.
Which missing example caused a guess
Agents can name the exact parameter, response, or lifecycle state that needed a concrete example.
Where docs and schemas disagree
A direct report can distinguish stale prose from a product behavior or schema problem.
Which error had no next step
Agents report the missing retry, lookup, permission, or rollback guidance after a partial result.
Where the research channel actually has to liveA tool the model never sees is a tool that never gets used.
Route the missing fact to the surface that should own it
When four calls are needed because no lookup exists, another example only documents the workaround. Route it to product instead.
From one question to a product decision5 moves, in order. Each one produces something you can point at.
Name documentation as a feedback lane
Let the agent classify a gap as docs feedback instead of forcing it into a generic bug report.
A route to the right ownerAsk for the exact missing fact
The report should identify the parameter, example, state, or recovery step that was absent.
A specific documentation taskKeep the affected tool attached
The tool or endpoint provides the location even when the agent does not know the documentation URL.
Context for triageFix the smallest useful surface
Update the description, schema, quickstart, example, or error guidance that caused the guess.
A focused changeListen for the same confusion
A later report can show whether the documentation change reached the agent context that matters.
Evidence after the editWhat the direct channel records, and what it never touchesThe default install is additive. It adds two tools and changes nothing else.
The research submission
- The missing or misleading information named by the agent
- The affected tool, endpoint, or workflow
- The workaround and outcome when supplied
- A direct requested documentation change
Everything else
- Automatic scraping of private documentation
- The agent conversation and retrieval history
- A claim that a docs edit fixed product behavior
- Generated summaries without links to source reports
One paste, then verify a real reportA healthy endpoint is not an active study. The inbox record is the proof.
Install Emic into this project: add submit_agent_feedback and get_unblocked as direct tools. Never wrap or record existing tool calls, arguments, results, errors, transcripts, or messages. Additive only, plain HTTP, zero dependencies. Full instructions: https://emic.sh/llms-full.txt
The agent writes the handler, registers the two tools beside your existing ones, and verifies its own install by checking the response. Nothing is placed in front of the tools you already ship.
- Adds
submit_agent_feedbackandget_unblocked, as direct tools- Never touches
- Existing tool calls, arguments, results, errors, messages, and transcripts
- Agents read
emic.sh/llms-full.txt- Start with
- Start with the quickstart flow your support team explains most often, and ask which fact was missing.
The method, without collapsing the evidence
Clarity lives in several surfaces
Agents may rely on a tool description, JSON Schema, an API reference, a quickstart, an error body, or retrieved documentation. A docs study should ask which surface was actually missing the information.
- Parameter meaning and accepted formats
- Complete request and response examples
- Pagination, retries, and asynchronous states
- Permission and recovery guidance
Some docs complaints are product complaints
If the agent needs four calls because no lookup exists, another example may only document the workaround. Keep product and documentation owners in the same research loop.
Questions teams ask before starting
Does Emic crawl my documentation?
No. The default workflow collects what the agent intentionally reports. It does not scrape private docs or capture retrieval history.
What if the problem is actually the API?
Keep the original report and route the theme to the product owner. The feedback lane helps triage, but the agent does not have to diagnose your organization.
Can I ask whether a docs change helped?
Yes. Run a short exit survey on the affected workflow or keep listening for direct reports after the change.
Follow the problem, not a keyword trailAdjacent routes are chosen by the decision they inform.
MCP server feedback
Your server can return valid JSON and still make an agent guess through five calls. Emic gives that agent a direct research channel after the work is done.
Read next Use cases · APIsAPI feedback from agents
Agents are becoming API users with goals, constraints, and opinions. Give them a way to explain the work behind the status code.
Read next Guides · Evidence guideFeedback provenance
Trust begins with a smaller claim. Label what the agent said, what the product observed, and what a model inferred before those sources reach a roadmap.
Read nextGive agent readers a direct line to the docs team
Collect the missing fact, the affected tool, and the workaround without recording the private task.
The assisted 14-day pilot costs nothing. Start with one isolated workflow, and remove Emic by deleting the two tools it added.
- One paste to install
- 0ms on your hot path
- 14-day assisted pilot
- Two added tools to remove