🌫️ Vague recipe
New here? A workflow (the recipe) is vague when it doesn’t say enough for the agent to decide without guessing—for example, “organize the files” without saying why to organize them, what criteria to use, or where to save the result. A vague recipe is the most common cause of WAT failures: it’s not that the agent “didn’t understand”; the recipe didn’t say enough.
A day-to-day example: you ask, "make a summary of this month's sales so I can send it to the store's WhatsApp group." It seems clear, but it's full of gaps—what exactly should the summary include (total, by product, by salesperson)? Where does the data come from (yesterday's spreadsheet, today's, a system)? How many lines can the summary have? The agent has no way to refuse the task, so it fill in each gap with the most reasonable assumption you can find — and what seems "reasonable to it" rarely matches "what you had in mind." The result comes out generic: a correct paragraph about numbers, but without the angle you wanted.
🔍 Under the hood: what the agent does when details are missing
When given an incomplete instruction, the agent follows a predictable path—and that's what produces a generic result:
- 1. Read the request and identifies what's missing to execute it (format, source, criteria, destination).
- 2. Choose the most common assumption — the interpretation that comes up most often in similar requests, not your specific interpretation.
- 3. Run it with this assumption and delivers something technically correct but generic.
- 4. Doesn’t notify that it chose—because, from its point of view, the gap has been filled and the task is done.
✗ Vague
"Organize these reports for me."
✓ Clear
"Rename the files in the 'relatorios/' folder to the format AAAA-MM-relatorio.pdf, based on the date in the current name. If a name has no date, leave it aside and let me know at the end."
✗ Vague
"Make a summary of this month’s sales for the group."
✓ Clear
"Use the spreadsheet 'vendas-agosto.xlsx', tab 'resumo'. Include the monthly total, the 3 best-selling products, and a comparison with July. Maximum 5 lines, simple language for the WhatsApp group."
💡 Practical Tip
Before writing the recipe, ask yourself: “If I gave this text to a new intern who had never seen my business, would they know exactly what to do?” If the answer is “only if they guessed,” the recipe is still too vague.
🔑 Tool without a key or permission
New here? Many tools require a API key (a specific password that authorizes the use of a service, such as sending email or posting on a site) to work. If the key hasn’t been configured, or the agent doesn’t have permission to use that tool (Track 0 already covered permissions), the workflow step that depends on it simply can’t run — no matter how clear the rest of the instructions are.
This is an easy mistake to confuse with "the agent doesn’t know how to do this": in reality, it knows exactly what to do; it just doesn’t have the key to the door. The solution is never to rewrite the workflow — it’s to configure the missing credential (covered in depth in Track 4’s Secrets module).
🔍 Inside
- API key: a service-specific password, different from your personal password — each external tool may require one.
- Permission: the limit you set yourself on what the agent can do on its own.
Real example: you ask, “send the customer an email letting them know the order has shipped.” If the email tool (for example, a Gmail MCP server—the subject of Track 2) has never received the access key to your account, the agent gets to the sending step and stops there—the message is already written, but it won’t go out. That’s different from an execution error: the agent didn’t “try and fail”; it recognized that the door is locked and, if built well, stops and lets you know instead of making up that it sent the email.
⚠️ Distinct failure mode: the agent “invents” a path
A dangerous variation of the lack of access is hallucination — when the agent, unable to find the right file, folder, or command, makes up a similar path instead of saying "I couldn't find it." Example: you ask it to run "the cash closing script," and there isn't a file with that exact name—instead of stopping and asking, a poorly guided agent might assume that fechamento.py is the wrong file (it isn't) and run it anyway, producing a result that looks right but isn't what you asked for.
🧩 An agent without enough context
Sometimes the workflow is clear and the tool has permission, but the agent still gets it wrong because it lacks context — background information it would need to make the right decision. Example: asking it to "write a summary in the company's tone" without ever having shown it examples of that tone. The CLAUDE.md (covered in Track 0) exists precisely to carry this context persistently, without repeating everything with every request.
Lack of context also shows up in a more costly way: when the agent enters a loop — a cycle that repeats without ever reaching the end — because there's not enough information to know when to stop. Imagine a workflow that says "revise this text until it's good" without any criteria for what "good" means. Each turn, the agent revises it again, finds something to adjust (it always does), and goes back to revising — without a stopping criterion, the cycle can continue for dozens of turns. Each turn consumes tokens (the unit that measures how much the model "reads" and "writes" — and what determines the cost of each run), so a poorly designed loop isn't just a waste of time: it's a real cost that can rise without control, sometimes because of a workflow that seemed harmless.
💡 Practical Tip
Every workflow that says “repeat until...” needs an objective stopping criterion (a number of rounds, a verifiable condition), not a subjective goal like “until it’s good.” Without one, you could end up paying for a loop that would never stop on its own.
❓ Ambiguous workflow
Unlike "vague" (which lacks detail), a workflow ambiguous there's too much conflicting detail, or it allows more than one reasonable interpretation. Example: "send the report to the client by Friday, prioritizing quality" and, three lines later, "don't spend more than 10 minutes reviewing" — the two instructions compete with each other, and the agent could choose either one.
The practical difference between vague and ambiguous matters because the fixes are opposite. A vague recipe is fixed adding detail. An ambiguous workflow is resolved removing the contradiction — deciding which of the competing instructions takes precedence, and writing it down instead of leaving it implicit.
✗ Poorly made workflow
"Reply to all the day's emails, giving each one your full attention. Oh, and clear the inbox by noon."
Two competing goals: maximum quality vs. a tight deadline. The agent decides on its own which to prioritize—and may change its mind with each run.
✓ Well-written workflow
"By noon, reply to as many simple emails (1-2 lines) as you can. Leave complex emails marked as pending for me to review — don’t try to resolve them quickly."
The priority is clear: speed on simple tasks without sacrificing quality on complex ones — because those miss the deadline.
Caption: the four most common WAT failure points, side by side with the specific fix for each — none of them is fixed the same way.
🚨 How to tell: warning signs
Each type of failure leaves a different clue in the agent’s behavior. Learning to read these clues helps you avoid "fighting" with the agent without understanding why it isn’t getting things right.
Thinking about the WAT cycle (covered in module 1.2: the agent reads the workflow, decides what to do next, uses a tool, and repeats), the failure almost always enters right at the start of that cycle—in the workflow reading or the decision— and only shows up for you at the very end, as a wrong result, high cost, or wasted time. The diagram below shows the path:
Caption: the failure almost never starts in the tool — it enters early, in the workflow or the agent’s decision, and only becomes visible at the end as a poor result, high cost, or wasted time.
It does something reasonable, but different from what you wanted
Sign of a vague recipe — it filled in the gap with a reasonable assumption, but it wasn't yours.
It stops and asks for a password/credential
Sign of a tool without a key — it correctly identified the blocker and is asking for help.
The result “doesn’t fit the house style”
Sign of insufficient context — it didn't have examples of the expected pattern.
It varies—it does things one way in one session and another way in the next
Sign of ambiguity — the workflow allows more than one valid interpretation.
✅ Fix checklist
When a result doesn't turn out as expected, go through this checklist before blaming the agent—in most cases, the fix is in one of these four lines.
✅ Quick checklist
- ☐ Does the recipe clearly say what to do, with what, and where to save it?
- ☐ Does every tool required for the step have its key/permissions configured?
- ☐ Does the agent have enough examples or rules (CLAUDE.md) for the expected standard?
- ☐ Are two workflow instructions competing with each other?
💡 Practical Tip
Save this checklist — it comes back in full in module 1.5 (Build), when you review why the newsletter automation didn’t work as expected on the first try.
Copy this checklist before running any new workflow—paste it into a notes app and check items off as you go:
[ ] O QUE fazer está escrito (não só "organize", "resuma", "revise")
[ ] COM QUE dados/arquivos trabalhar está nomeado (caminho ou fonte exata)
[ ] ONDE salvar ou entregar o resultado está definido
[ ] Toda ferramenta usada no workflow tem chave/permissão já testada
[ ] O CLAUDE.md tem exemplo do padrão esperado (se o resultado exige "tom" ou "estilo")
[ ] Não há duas instruções competindo (prazo vs. qualidade, rapidez vs. cuidado)
[ ] Se existe "repita até...", há um critério de parada objetivo (não subjetivo)How to verify: run the workflow once on a small, low-cost case before trusting it at scale. If the result matches what you expected without needing adjustments, the seven items above are probably covered. If it doesn’t, go back to the checklist and find which line is unchecked—that’s where the defect is, not in the agent’s "capability."
Quick check (optional): the agent stops and asks for a specific service password. What’s the most likely cause?