Agent-friendly docs for documentarians


"Here’s what we can piece together from the available information:
  • Truncation is real and varies by platform. Claude Code truncates between 100-150k of text. Other platforms presumably have limits too, but won’t say what they are. If your page is large, some of it is getting cut.
  • Source order matters. Whatever content appears first in your page source is what the agent is most likely to see. Tabs, accordions, and other UI patterns that flatten into long sequential content in the source mean that later sections may be invisible to agents.
  • Serving markdown helps, but only if the agent requests it. Most agents don’t. And even if they do, you need your server configured to respond appropriately to content negotiation.
  • Character count is the metric that matters, not line count. As I showed earlier, a 97-line HTML file can be 4.5x larger than the portion of a 6,000-line markdown file that an agent can process.
"The lack of transparency here isn’t just an inconvenience. It’s a real barrier to the agent-friendly docs movement. 

"Documentarians can’t optimize for constraints they can’t see. We’re left running experiments, comparing notes, and hoping the platforms eventually decide to tell us what’s going on under the hood."

Comments

Post a Comment

Empathy recommended

Popular posts from this blog

Hamza Chaudhry

"Although a nuclear confrontation based on fake intelligence may seem unlikely, the stakes during crises are high and timelines are short, creating situations where fake data could well tilt the balance toward nuclear war. "The evolution of nuclear systems has led to further ambiguity in crises and shorter timeframes for verifying intelligence. An intercontinental ballistic missile from Russia could reach the U.S. within 25 minutes. A submarine-launched ballistic missile could arrive even sooner.  "Many modern missiles carry ambiguous payloads, making it unclear whether they are nuclear-tipped. AI tools for verifying the authenticity of content are not sufficiently reliable, making this ambiguity difficult to resolve in a short window. "The likeliest nuclear hotspots are also the arenas involving actors with low levels of trust on both sides — be that the U.S. and the Chinese Communist Party or Russia, or India and Pakistan. Even if communication is established in a...
Read more

When their AI chums have Bob's data

Image
1 "How do we discuss Bob's prognosis with him?"   Ask Doctor Agent! "How to discuss our auction of Bob's home with him?"   Ask Realtor Agent! "How do we obtain a confession from Bob?"  Ask District Attorney Agent! 2 But why would Bob's data reside within AI agents? We have a fascination with androids. One part of this fascination includes the idea of ' self-repair .'  Many of us long for the ability to diagnose and cure ourselves without the need to expose ourselves to other humans, like doctors and nurses, for example.  We'd much prefer tiny sensors throughout our bodies that could signal to us when/how we might need to alter our metabolisms.  Yet who —besides a tech bro —can make the sensors and/or digital assistant? Who can program the assistant, much less afford the things to begin with?  No worries. Firms around the world are already testing various solutions! Soon all one will have to do is surrender oneself and all will be...
Read more

Swarm 🦹‍♂️

"Knowledge discovery from data typically includes solving some type of an optimization problem that can be efficiently addressed using algorithms belonging to the class of evolutionary and bio-inspired computation .  "In this chapter, we give an overview of the various kinds of evolutionary algorithms, such as genetic algorithms, evolutionary strategy, evolutionary and genetic programming, differential evolution, and coevolutionary algorithms, as well as several other bio-inspired approaches, like swarm intelligence and artificial immune systems.  "After elaborating on the methodology, we provide numerous examples of applications in astronomy and geoscience and show how these algorithms can be applied within a distributed environment, by making use of parallel computing, which is essential when dealing with Big Data."
Read more