Building AI Agents
The design decisions that separate agents which work from agents which merely demo well.
Agent or Workflow? Ask Before You Build
Not every automation needs an AI agent. Learn how to tell a predictable process from a genuinely unpredictable one, and build the cheaper, more reliable option.
Tip #038Describe Your Tools Like You’re Training Someone New
An agent only picks the right tool if the description tells it exactly what the tool does and when to use it. Here’s how to write descriptions and docstrings that actually work.
Tip #039One Agent, One Job: Why Specialist Crews Beat Generalists
One agent trying to research, judge risk, and write the report isn’t one job — it’s three. Split bloated single-agent workflows into a crew of specialists.
Tip #144Force Three Genuinely Different Approaches
Ask an AI for a plan and it converges on the first idea, then pads it with strawmen — force at least three genuinely different approaches to widen the option space before you narrow.
Tip #145Never Accept Your AI’s First Plan Without the Loser
A recommendation with no rejected alternative is a default, not a decision. Force your agent to diverge, then converge — and always demand the runner-up and why it lost.
Tip #154Log a Hash of the Messages Array Before Every Call
Your agent looks broken but the model is fine — your wrapper is rewriting history between calls. Hash the messages array before each request and the mutation shows up in one log line.
Tip #155Count Your Model Calls Per Turn
One user turn can fire five model calls when a framework silently re-asks on a bad answer — here’s how to count the real number and bound the loop.
Tip #183Don’t Ask AI to Research. Ask It Five Questions
A vague research this topic prompt gives a shallow answer. Break the topic into three to five sub-questions, fan them out to parallel subagents that read real sources, then synthesize one cited report.