Claude Agent SDK Patterns: Prompts, Tools, Context

Once you have shipped a couple of agents with the Claude Agent SDK, you start noticing that the same shapes recur. The agents that work share a handful of structural decisions; the ones that flail tend to violate the same few principles. This post collects the reusable, code-level patterns I keep returning to — for prompts, for tools, and for context — so you can apply them deliberately instead of rediscovering them through painful debugging sessions.

None of these are framework features you toggle on. They are ways of organizing the code and text you feed the SDK. That is what makes them portable: they survive SDK updates, model upgrades, and changes in which MCP servers you connect.

Pattern 1: The layered system prompt

Treat the system prompt as a layered document, not a paragraph. The top layer is identity and mission — one or two sentences on what this agent is for. The middle layer is operating rules: what it may and may not do, how to handle ambiguity, when to ask versus act. The bottom layer is the definition of done and the output contract. Separating these layers means you can edit the rules without disturbing the identity, and a teammate can read the prompt and immediately find the part they need to change.

A practical refinement: keep durable instructions in the system prompt and put task-specific details in the user message. The system prompt is the agent's constitution; the user message is the work order. Mixing them is how prompts rot — every new task tempts you to bolt another clause onto the system prompt until it becomes an unreadable wall that the model itself struggles to follow.

Pattern 2: Tools as a narrow, legible API

Design your tool catalog the way you would design a public API, because to the model it is one. Each tool should do one thing, have a name that reads like an action, and carry a description that tells the model exactly when to use it and when not to. Prefer a few composable tools over many overlapping ones — if two tools could plausibly handle the same request, the model will sometimes pick the wrong one, and your accuracy quietly drops.

flowchart TD
  A["System prompt: identity + rules + done"] --> B["Task in user message"]
  B --> C["Model selects from narrow tool catalog"]
  C --> D{"Tool result clear?"}
  D -->|Yes| E["Advance task"]
  D -->|No / error| F["Return structured error to model"]
  F --> C
  E --> G{"Done condition met?"}
  G -->|No| C
  G -->|Yes| H["Emit final answer per output contract"]

Tool outputs deserve as much design care as tool inputs. Return compact, structured results — the relevant fields, not a raw dump — because everything a tool returns becomes context the model must read on the next turn. When a tool fails, return a structured error the model can reason about ("record not found for id X") rather than a stack trace. A good error message lets the agent recover; a bad one derails the loop.

Pattern 3: Context as a budget you actively spend

Think of the context window as a budget you spend on every turn, not a bucket you fill once. The patterns that keep long runs coherent all amount to spending that budget on the right things: keep the system prompt and recent turns sharp, summarize or drop stale tool output, and push large artifacts to files the agent reads on demand instead of carrying them inline.

A reusable move here is the "scratchpad file" pattern: instead of holding a growing plan or a long intermediate result in the conversation, the agent writes it to a file and reads it back when needed. This keeps the live context small and the loop fast, and it survives across subagent boundaries. It also gives you, the engineer, an artifact to inspect after the run.

Pattern 4: Explicit planning before action

For any task with more than a couple of steps, prompt the agent to produce a short plan before it touches a tool. This is not ceremony — a written plan makes the model's intended path inspectable, lets it self-correct when a step fails, and gives the context manager an anchor to keep referring back to. The pattern is simple to encode: "First outline the steps you will take. Then execute them one at a time, noting the result of each." Agents that plan recover from surprises far better than agents that improvise turn by turn.

Pattern 5: The output contract

Decide what "finished" looks like in a machine-checkable way and state it in the prompt. If a downstream system consumes the agent's result, specify the exact format — a JSON object with named fields, a status plus a summary, whatever the consumer needs. Then validate the output against that contract before you trust it, and on a mismatch feed the validation error back into the loop for one repair attempt. This closes the gap between "the agent said it was done" and "the result is actually usable."

Pattern 6: Compose, don't monolith

When an agent's system prompt grows past a screen or its tool catalog past a dozen entries, that is a signal to decompose. Split the work into focused agents — one that researches, one that acts, one that reviews — each with a tight prompt and a small tool set, coordinated by an orchestrator. The composition keeps each piece legible and testable. The cost is tokens and latency, so decompose when complexity demands it, not reflexively. The art is knowing where one agent ends and the next begins.

Frequently asked questions

System prompt or user message — where do task details go?

Durable rules and identity belong in the system prompt; the specific work order belongs in the user message. This keeps the system prompt stable and readable across many tasks instead of accumulating one-off clauses until the model can no longer follow it.

How should tools report failures?

As structured, human-readable errors the model can reason about and recover from — "no record for id 42" beats a raw exception. The error becomes context, so it should help the agent choose its next move rather than confusing it.

What is the scratchpad file pattern?

Having the agent write growing plans or large intermediate results to a file and re-read them on demand, instead of carrying them inline in the conversation. It keeps live context small, speeds the loop, and leaves an inspectable artifact behind.

When should I split one agent into several?

When the system prompt outgrows a screen or the tool catalog outgrows roughly a dozen entries, or when distinct phases (research, act, review) want different tools and rules. Decompose for legibility and reliability, but remember each agent adds token and latency cost.

Bringing agentic AI to your phone lines

CallSphere applies these prompt, tool, and context patterns to voice and chat agents — legible roles, narrow tools, and tight context — so they handle every call and message and book work without a human in the loop. Hear it for yourself at callsphere.ai.

---

Source & attribution: This is an independent, original explainer inspired by Anthropic's coverage on the Claude blog. Claude, Claude Code, Claude Cowork, Claude Opus, and the Model Context Protocol are products and trademarks of Anthropic. CallSphere is not affiliated with or endorsed by Anthropic.