Claude Agent Patterns: Prompts, Tools, and Context (Building Effective AI Agents)

After you have built one Claude agent, you start to see the same shapes recur — the prompt that always works, the tool layout that keeps Claude from guessing, the context structure that survives a forty-step run. These are patterns, in the old software sense: named, reusable solutions to recurring problems. This post collects the ones that have earned their keep across real agentic systems, at the level of actual code and prompt structure rather than abstract advice.

None of these are exotic. What makes them valuable is that they compose. A well-structured prompt plus a well-organized tool catalog plus disciplined context management produces an agent that behaves predictably even as the task grows. Skip one and the others can't fully compensate.

Key takeaways

• Structure system prompts in fixed sections: role, constraints, available tools, output contract, and stop criteria.
• Design tools as a catalog with sharp, non-overlapping descriptions — the catalog is a UI for the model.
• Keep context in tiers: pinned goal, rolling summary, recent raw turns — and curate every cycle.
• Prefer a few composable tools over many narrow ones; Claude reasons better over a small, orthogonal set.
• Encode policy in structured tool results and the prompt's output contract, not in scattered runtime branches.

Pattern 1 — the sectioned system prompt

A system prompt that drifts into a wall of prose is hard to maintain and easy for the model to misread. The durable pattern is a fixed set of labeled sections, always in the same order, so you can edit one without disturbing the others. A reliable layout is: role, hard constraints, how to use tools, the output contract, and when to stop.

SYSTEM = """
# Role
You are a support triage agent. You resolve or route customer issues.

# Constraints
- Never promise refunds; only the refund tool authorizes them.
- If you are unsure, ask one clarifying question before acting.

# Tools
Use kb_search for product facts, ticket_create to escalate,
refund_issue only after kb_search confirms eligibility.

# Output contract
End with a JSON block: {resolution, next_action, confidence}.

# Stop
Stop once next_action is set or you have asked one question.
"""

The "Stop" section is the one most prompts omit and the one that most improves behavior. Telling Claude explicitly when its job is done reduces both runaway loops and premature endings.

Pattern 2 — the tool catalog as a UI

Think of your tool definitions the way you think of a menu in a well-designed app: each option distinct, each label unambiguous, no two doing nearly the same thing. When two tools overlap, Claude has to guess, and guesses are where reliability dies. The fix is orthogonality — every tool occupies a clearly different region of capability.

flowchart TD
  A["Model needs an action"] --> B{"Reading or writing?"}
  B -->|Read| C["kb_search: facts & docs"]
  B -->|Write| D{"Reversible?"}
  D -->|Yes| E["ticket_create: escalate"]
  D -->|No| F["refund_issue: gated action"]
  C --> G["Structured result back to model"]
  E --> G
  F --> G

The diagram shows the decision a well-shaped catalog lets Claude make cleanly: read versus write, and within write, reversible versus irreversible. If your tools force the model to make this distinction by reading long descriptions, the catalog is doing the prompt's job. Encode the structure in the tool boundaries themselves.

Pattern 3 — tiered context

The context that goes to Claude each turn should not be a flat transcript. The pattern that scales is three tiers. The pinned tier holds the goal and immutable constraints — it never gets evicted. The summary tier is a rolling, compressed account of what has happened, regenerated as the run grows. The recent tier is the last few turns verbatim, where fidelity matters most.

In code this is a small class that renders these tiers in order. When the recent tier exceeds a threshold, you fold its oldest entries into the summary tier and drop them from recent. The model always sees goal, then a tight history, then the live exchange — coherent regardless of how long the run gets.

Pattern 4 — policy in data, not branches

A tempting anti-pattern is to scatter business rules through your runtime: "if the tool failed and it's a refund and the customer is premium, then...". This becomes unmaintainable fast. The better pattern pushes policy into two places the model can see: the output of tools (structured results with flags like eligible, retryable, requires_human) and the prompt's contract. The model then reasons over explicit data instead of you hard-coding every branch.

Pattern 5 — the output contract

Free-form text is a liability the moment another system depends on the agent's answer. The output-contract pattern fixes this by requiring the agent to end every run with a structured block — typically JSON — whose shape you validate before trusting it. The contract lives in the system prompt's "Output" section, and your runtime parses and checks it. If validation fails, you feed the error back to the model for one corrective turn rather than crashing downstream.

{ "resolution": "refund_issued",
  "next_action": "none",
  "confidence": 0.82,
  "sources": ["kb_4821"] }

The confidence and sources fields are the underrated parts. They let downstream code route low-confidence results to a human and let you audit which knowledge the agent actually relied on. An agent that must cite its sources tends to make fewer unsupported claims, because the contract forces it to ground each answer in something concrete.

Common pitfalls

• Prose-blob prompts. Without sections you can't safely edit one rule, and the model weights instructions inconsistently. Use labeled sections.
• Tool sprawl. Twenty narrow tools confuse the model more than five composable ones. Merge overlapping tools and lean on parameters.
• Flat context. An append-only transcript loses the goal under noise. Use tiers and curate.
• Hidden policy. Rules buried in runtime code can't be reasoned about by the model and can't be tested in isolation. Surface them as data.
• No output contract. Without a required output shape, downstream code breaks on free-form text. Demand structured output and validate it.

Apply the patterns in five steps

1. Rewrite your system prompt into the five fixed sections, ending with explicit stop criteria.
2. Audit your tool catalog for overlap; merge or sharpen any two tools that could answer the same request.
3. Replace your flat message list with a tiered context object that pins the goal.
4. Add an output contract to the prompt and validate the model's final JSON against it.
5. Move every business rule out of runtime branches into tool result flags or the prompt.

Pattern selection at a glance

Problem	Pattern	Signal you need it
Prompt hard to maintain	Sectioned prompt	Edits cause regressions
Model picks wrong tool	Catalog as UI	Overlapping tool calls
Long runs lose the plot	Tiered context	Coherence drops after many turns
Logic sprawl	Policy in data	Nested runtime conditionals

Frequently asked questions

How many tools is too many for one agent?

There is no hard limit, but past roughly a dozen tools the catalog starts to confuse the model unless the tools are genuinely orthogonal. If you have many, consider grouping related ones behind a single tool with a mode parameter, or splitting into subagents each with a focused catalog.

Should the system prompt include examples?

One or two tight examples of the output contract help a lot; long example transcripts usually hurt by eating context and biasing the model toward copying. Show the shape of a good answer, not a full sample conversation, unless the task is genuinely few-shot in nature.

How do Skills relate to these patterns?

Agent Skills are a way to package the "how to use tools" guidance so Claude loads it dynamically only when relevant, keeping the base prompt lean. They complement the catalog pattern: tools say what is possible, Skills say how to do specific procedures well.

Agentic patterns, applied to live conversations

CallSphere turns these prompt, tool, and context patterns into voice and chat agents that answer every call, pull data mid-conversation, and schedule work without a human in the loop. See the patterns in production 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.