“I have made this longer than usual because I have not had time to make it shorter.”
Great text looks effortless. It’s as if the writer sat down, arranged some thoughts, and wrote something so great that it couldn’t have been anything else.
In reality, the paradox of writing is that it takes a lot of words to write something meaningful. I spent an entire week writing this single essay. Each day, I would start with a fresh sheet of paper and write and write and write. When I went home, I’d crumple up all of my drafts and toss them. Six days of brutal torture later, I finally had the perfect 1,498-word essay. All it took was around 20,000 raw words.
Not all of those raw words were bad, but many of them were “loose.” I would find places where my ideas were muddled or incomplete, which meant that I needed to shore up those areas with mini-essays, which had more problems that required defending, which resulted in even more mini-mini-essays. It kept going until I explored the entire problem space. Then, I could go back and compress all of those words down to an indestructible gem of an essay.
But I’m not here to sing the gospel of why writers should get paid millions of dollars (though if you believe that, please send me a message; I know a friend [me] who could use those millions of dollars).
Instead, I want to talk about the value of text in AI agents. As single-turn models are paired with a harness [0] and evolve into multi-turn agents, much of the current attention is on the value of improving the harness and building the right environments for training.
There’s a much lower-hanging fruit.
Just feed the model really good text.
Human Compression
This essay isn’t about prompting, but in the interest of completeness, here are a couple of quick lines about prompting.
Working with LLMs is an information asymmetry problem. In a new session, a model has zero context but near infinite amounts of knowledge. On the other hand, the human has all the context. To best work with a model, the human should jam as much of their context into the prompt as possible.
But we humans are lazy.
I often fire off a vague prompt and silently pray that it can somehow read my mind to create the perfect output. Then, when the inevitably disappointing result comes back, I add on a couple of extra restrictions, run it again, and keep looping until the model is forced onto the correct path. In the process, I gradually gain clarity about my end goal and document the different steps in solving my problem. It isn’t the same as writing an essay from the kernel of an idea, but it’s close enough.
To ensure that lazy humans like me get a good experience, companies will often append a system prompt before each query so that the model gets additional context.
!image.png
There’s a definite Goldilocks zone within a system prompt. It can’t be too ambiguous; otherwise, the model might misunderstand and steer in an unintended direction. It also can’t be too complex, which might destroy the ability to solve many problems within a broad problem space.
However, an agent might loop for thousands of iterations. While important, the initial prompt quickly diminishes in value as the agent reasons through ambiguity and makes design choices to continue its progress.
Tool Calls
In a narrow sense, tool calls define an agent’s ability to act.
Tool calls are when a model outputs a very specific output, such as {"name": "write_great_essay", "wordcount": "1,600"}, and the harness uses that to interact with external systems, APIs, and custom functions to gather information, perform actions, or execute complex workflows that extend beyond the model’s built-in capabilities.
In plain English, think of an AI model as a butler in a big English mansion. Alone, the model can only clean the house and decorate rooms. The harness and its corresponding tools are an army of footmen that the model can delegate tasks to, like buying groceries and sending messages.
These footmen determine what kind of actions are possible and define what information enters the process.
Early AI agents were brittle. If a footman was tasked with buying flowers and came back with a mop, the model wouldn’t know what to do. These days, however, the model is smart enough to absorb the mistake and continue operations, either by sending the footman out again or deluding itself that the footman brought back a mop-shaped flower.
This opened agents to entire realms of new mistakes.
In a no-tool environment, wrongness is generally a textual problem. Writing a vague prompt that returns an inadequate paragraph is a problem of a certain size and type. A tool call of misunderstood purpose or, worse, a misunderstood usage of a tool is a different kind of potentially multiplicative error.
Now that people are giving their agents prod access, it’s like giving the footman a nuke. With the right sequence, the whole city around the mansion blows up.
Similes and metaphors aside, agents broadly need the following kinds of clarity around their tool usage:
- What each tool is for, what it is intended to do, and what it is not meant to do.
- When a tool should be used and when it should not be used
- What outcomes of tool usage are considered successes, and what outcomes indicate errors
- What to do with successes, failures, or ambiguous outcomes
In every case, we need to stop the agent from guessing. Many current guardrails are static rules that need to be manually programmed in. The better solution, however, is in the documentation around each tool.
Documentation
If tool calls are the agent’s ability to act, documentation is where an agent learns what each action means and does. Think of it like a handbook for the footman with guidelines around the footman’s purpose, what kind of mistakes are possible, and what kind of outcomes are normal.
Up until a year or so ago, documentation was a mostly human-facing affair. It was meant to be read by developers, searched in human-friendly ways, and contained examples optimized for human understanding. They also contained certain kinds of ambiguity that humans could be counted on to read past, incomplete context in which humans could fill in the gaps, and so on.
It was not written for agents.
When we ask the agent to do things like retrieve relevant information or solve a customer issue through chat, the agent doesn’t have access to our full internal vision at the prompt level. That means some of its instructions start coming from its understanding of the tools themselves.
This is important enough to get its own slightly dark example.
Part of why butlers are so valuable is because they have innate context. They know to get flowers for a celebration or to sing a lullaby when it’s time for bed. However, if an agent is given the task of putting a baby to bed, it might choose the option of feeding the baby some alcohol. While technically correct, doing so also comes with the side effect of dehydration, dangerously low blood sugar, and respiratory failure.
When an agent needs to call upon an external tool, much of its behavior predicates on the tool’s context that they’ve been given. In an average case, the documentation around alcohol will be relaxation, lowered inhibitions, and blackouts. It wouldn’t include the fact that even a low dose could lead to acute alcohol poisoning in babies.
In a more ambitious sense, API documentation as optimized for and used by agentic AI is less a facet of how the product is described and more of what the product is. It’s less a manual and more a component of a tool’s function that shapes its use.
All this adds up to a much different vision for documentation.
An agent’s limited context window means that documentation can’t be literal books that squeeze out the initial instruction set. At the same time, the agent’s unwavering willingness to follow instructions means that documentation needs to be kept much more fresh than used to be the case.
So the future of documentation is one where it gives an agent granular understanding of the tool along with certain guardrails that keep it on task with no drift or confusion. In other words, we need to compress the context in the same way that I wrote and rewrote this essay until it was perfect.
[0] Pulling from Langchain, “A harness is every piece of code, configuration, and execution logic that isn't the model itself. A raw model is not an agent. But it becomes one when a harness gives it things like state, tool execution, feedback loops, and enforceable constraints.”