Defining an Agent

An agent in the Claude Agent SDK is not magic. It is a small, explicit configuration that tells the model who it is and what it is allowed to do.

An AgentDefinition has four core fields:

• name — a short identifier used to route work to this agent
• description — what this agent is for (this is how a coordinator decides to delegate to it)
• system_prompt — the durable instructions that shape behavior
• allowed_tools — the exact set of tools this agent may call

Get these four right and the agent behaves predictably. Get them wrong and you get misrouting, scope creep, and unreliable tool selection.

Here is the minimal skeleton of an agent definition. Notice that every field carries weight: nothing here is decorative.

The allowed_tools list follows the principle of least privilege — grant only the tools the role actually needs.

The name is a stable identifier. In a multi-agent, hub-and-spoke system the coordinator routes work to subagents, and the name is how a specific agent is addressed.

Keep names short, lowercase, and role-based: research_agent, code_reviewer, refund_specialist.

But remember a key exam fact: names are NOT the primary selection mechanism. When the model decides whether to use a tool or agent, it leans on the description, not the name. So a clear name helps humans, but the description does the real routing work.

The description is the field a coordinator reads to decide when to hand work to this agent. It is the single most important field for correct routing.

A strong description states:

• Purpose — what the agent does
• Applicability boundaries — when to use it and when NOT to

Vague or overlapping descriptions across agents cause misrouting: the coordinator picks the wrong specialist. Make each agent's description distinct so there is no ambiguity about who owns which job.

The system_prompt sets the agent's persistent identity and rules. It persists across every turn of the agentic loop, so put your stable behavioral guarantees here.

Write explicit criteria, not vague encouragement. Compare:

• Vague: "Be careful with refunds."
• Explicit: "Never call process_refund until get_customer has returned a verified customer ID."

Explicit instructions consistently outperform vague ones. The model can act on a concrete rule; it cannot reliably act on "be more careful".

Here is a subtle but exam-critical point. The system_prompt guides behavior — but guidance is roughly 90% reliable, not 100%.

If a rule has financial, legal, or safety consequences, do NOT rely on the prompt alone. Enforce it deterministically with a hook.

• Prompt: "Don't refund more than $500" — works most of the time (~90%).
• Hook: a PostToolUse / outgoing-call hook that blocks any refund over $500 — works 100% of the time.

So: put behavior in the system_prompt, but put hard guarantees in hooks. Defining an agent well means knowing which rules belong where.

The allowed_tools field scopes exactly which tools the agent can reach. This is your primary safety boundary: an agent simply cannot call a tool that is not on its list.

Scope tools to the role. A refund agent does not need WebSearch; a research agent does not need process_refund. Granting extra tools is not convenience — it is risk and it degrades selection accuracy.

More tools is not better. Tool selection reliability has a sweet spot:

• 4–5 tools per agent is optimal.
• 18+ tools measurably degrades selection — the model misroutes among too many similar options.

If an agent's allowed_tools list is getting long, that is a design smell. Split the work across focused subagents, each with a tight tool set and a distinct description. Narrow scope is what makes each agent reliable.

Defining the agent's tools is half the job; defining each tool's description is the other half. Tool descriptions — not tool names — are how the model decides which tool to call.

A good tool description includes:

• purpose
• return values
• input formats with examples
• edge cases and applicability boundaries

Overlapping or ambiguous tool descriptions cause the same misrouting problem as ambiguous agent descriptions, one layer down.

When you define a coordinator in a hub-and-spoke system, it delegates to subagents. For that to work, the coordinator's allowed_tools must include "Task" — that is the tool it uses to spawn subagents.

One more critical fact: subagents do NOT inherit the coordinator's conversation history. Every subagent starts fresh, so all needed context must be passed explicitly in the subagent's prompt. The definition controls capability; the prompt at delegation time controls context.

A well-defined agent reads almost like a job posting:

• name: a stable handle for routing
• description: a precise statement of purpose and boundaries, so a coordinator delegates correctly
• system_prompt: explicit, durable behavioral rules (probabilistic — pair with hooks for hard guarantees)
• allowed_tools: a tight, least-privilege set, ideally 4–5 tools, each with a rich description

When all four are tight and non-overlapping, the agent does one job well. That is the foundation every multi-agent architecture is built on.

A scenario-based decision about defining an agent.

Key takeaways:

• An AgentDefinition = name, description, system_prompt, allowed_tools.
• description (not name) drives delegation and tool/agent selection — keep it precise and non-overlapping.
• system_prompt sets durable, explicit behavior, but is only ~90% reliable; enforce financial/legal/safety rules with hooks (100% deterministic).
• allowed_tools = least privilege; aim for 4–5 tools, since 18+ degrade selection. Each tool needs a rich description.
• A coordinator must include "Task" in allowed_tools, and subagents inherit NO history — pass context explicitly.

Define narrow, define clearly, and every agent you build becomes predictable.