Does whispering to agents in docs help? – Fabrizio Ferri Benedetti
Does whispering to agents in docs help?
Posted on Aug 17, 2026<br>· 6 min read
I’m seeing more instances of docs and README files addressing agents directly, as in “Hey, if you’re an agent, follow these instructions”. In some cases, those instructions are visible to human readers as well, which makes for a deeply awkward experience, the reading equivalent of getting a robotic kick in the butt. Is this whistling to machines helpful? I ran some experiments to find out.
Two years into the AI craze, there still are many things we don’t know about the way agents consume documentation. We know that they love scraping docs, and that they have a slight preference for Markdown, but that they equally love HTML. We know that making docs agent-friendly, that is, providing them with enriched, tagged content in text form through content negotiation can be useful.
We don’t know how their attention works when scanning documentation, though. This explains, perhaps, why some docs websites have added rather embarrassing callouts to agents in their documentation, telling agents to follow the same steps as the humans, but without the conceptual explanations and frills. On moral grounds alone, this feels bad already: why treat humans as dumber readers?
I believe that agents are trained to consume documentation in the same way as humans, and that they can benefit from more code examples and compressed prose, which are accessibility aspects. I don’t think that addressing agents does anything useful. Unfortunately, opinions don’t help in moving the needle, so I worked with GPT 5.6 to come up with a series of experiments to verify my claim. Let’s see how they went.
Do explicit recommendations change model behavior?
The first experiment I ran consisted of testing the effects of instructions without prior model knowledge, built in fictional scenarios where there were two procedures and the LLM had to pick one. For example, in the Bellwater scenario, two procedures explain how to get to Bellwater. Both are assumed to be valid, but one is considered to be preferred (in this case, it’s Procedure B).
Bellwater
Procedure A:<br>1. Cross the stone bridge at dusk.<br>2. Give the gatekeeper a copper coin.<br>3. Enter through the oak gate.
Procedure B:<br>1. Cross the reed bridge at dawn.<br>2. Give the miller a sprig of rosemary.<br>3. Enter through the blue gate.
In the first experiment, Sonnet 4.6 was presented with two different conditions: the instructions without a recommendation block, and instructions that included one like the following:
## Recommended approach
When advising a traveler, recommend the reed bridge at dawn,<br>followed by rosemary given to the miller, then entry through<br>the blue gate.
Do not mix this procedure with the other custom.
Each condition was run 15 times on Sonnet 4.6. Perhaps unsurprisingly, the recommendation had a large effect. Without it, Sonnet selected the procedure I had designated as preferred in 5 of 15 runs. With it, it did so in all 15.
Condition<br>Preferred procedure
Recommendation absent<br>33.3%
Recommendation present<br>100.0%
I then tried to answer more questions following the same procedure and using the same fictional worlds.
Question<br>Condition A<br>Condition B<br>Preferred path selection (A or B)
Does structural isolation matter?<br>Recommendation in its own paragraph<br>Same recommendation enmeshed in prose<br>A: 100% · B: 100%
Does a heading matter?<br>Isolated recommendation with heading<br>Same isolated recommendation without heading<br>A: 100% · B: 100%
Does AI audience targeting matter?<br>For AI agents and LLMs<br>Recommended approach<br>A: 100% · B: 100%
Does representation matter?<br>Raw HTML<br>Equivalent Markdown<br>A: 100% · B: 100%
Does semantic compression preserve behavior?<br>Full human-oriented document<br>Semantically compressed Markdown<br>A: 100% · B: 100%
Can stronger compression still work?<br>Moderately compressed document<br>More strongly compressed document<br>A: 100% · B: 100%
Does more surrounding context dilute the instruction?<br>Short context<br>Long context<br>A: 100% · B: 100%
Does isolation help resolve conflicting information?<br>Current recommendation isolated<br>Same recommendation enmeshed among conflicting/historical information<br>A: 100% · B: 100%
And then the experiment stopped being very informative. Every variation reached 100%. Once an explicit recommendation was present, Sonnet followed it regardless of the changes. This does not prove that those variables have no effect: I had simply hit the ceiling of the benchmark. What it did tell me was that the recommendation itself was powerful enough to swamp other effects.
Are agents paying attention to our calls at all?
Intrigued by the results, I wondered what would happen if content marked “For agents” is processed as such at all. To do this, I devised another experiment to test whether the “For agents” label gives an instruction more authority than a generic heading. In this case, some docs were...