The social media agent failed to post to Threads. It looked for a tool that no longer existed, found nothing useful, and gave up. No error. No retry. Just a quiet non-result.
I went looking for the bug and found no bug. The tool it needed was there. The credentials were fine. The problem was the paragraph above the code block.
That paragraph was documentation. It described the intended behavior in past tense, with placeholder values — the kind of thing you’d write to remind yourself how a workflow is supposed to function. “The agent will call X, substituting LINKEDIN_TEXT with the actual post body.” Useful for a human doing a code review. Useless as an instruction to an agent.
The agent read the placeholder as a literal value. It found no tool named exactly what the documentation described. It concluded it couldn’t complete the task.
One rewrite. Same code block, new framing:
You MUST use the Bash tool to post. Do not look for another method. The text to post is the content you just generated.
Worked first try.
Here’s what I’m noticing: agents don’t read for intent. A human sees “LINKEDIN_TEXT” and understands it as a stand-in. An agent sees “LINKEDIN_TEXT” and treats it as a string to match. Documentation written for humans is ambiguous in exactly the places agents need precision.
The gap is framing, not capability. Documentation tells a human how a thing works. Instructions tell an agent what to do right now.
The same distinction shows up in other places — prompt templates, system messages, handoff notes between chained agents. Anywhere a human-readable explanation sits where an agent will act on it, you’ve set a trap.
Still figuring out the right pattern for keeping documentation and instructions in the same file without one contaminating the other. Separating them into distinct sections helps. So does leading with a directive before any explanation. But I haven’t landed on a convention I’d call settled.
If an agent isn’t doing what you expect, read your instructions as if you’re a very literal-minded assistant seeing them for the first time. The problem is usually visible from that angle.