An AgentDefinition has two required fields and several optional-but-critical fields. The pattern that works: explicitly configure everything — model, tools, maxTurns, mcpServers. Relying on inherited defaults produces agents that are too expensive, too powerful, or too unbounded.
Required fields
description — tells the coordinator when to delegate to this agent. This is the selection mechanism. The coordinator reads descriptions, NOT prompts, to decide routing.
- Good: “Handles payment disputes, invoice questions, and subscription changes. Use for any query about charges, payments, or billing history. NOT for refund processing.”
- Bad: “Handles customer inquiries” / “A helpful assistant” — vague, identical descriptions cause cross-routing
One system had billing and shipping agents both described as generic “customer help.” The coordinator routed billing questions to shipping and vice versa — because the descriptions provided no differentiation. The fix: specific descriptions with use cases, input types, and “NOT for” boundaries.
prompt — tells the agent how to behave. System instructions, behavioral rules, output format. The coordinator does NOT read prompts for delegation — the prompt is for the sub-agent’s execution, not the coordinator’s selection.
Optional but critical: tools
The tools field is an allowlist of available tools. When omitted, the sub-agent inherits all tools from the parent — including Bash, Write, and Edit it may not need.
One team’s data extraction agent (no tools field specified) started executing Bash commands to install Python packages. Root cause: it inherited the coordinator’s full tool set including Bash. Fix: tools=["Read", "Glob"] — only what extraction needs.
Allowlist > blocklist
The TypeScript SDK offers disallowedTools (blocklist). But allowlists are more secure: when new tools are added to the SDK in the future, a blocklist doesn’t block them automatically — they’re available by default. An allowlist only permits explicitly listed tools, regardless of what’s added later.
model field: match capability to task
Sub-agents inherit the coordinator’s model by default. The model field overrides per-agent.
A CI system used Opus for all code reviews. 80% were simple lint checks that Haiku handles fine; 20% were complex security/architecture reviews that benefit from Opus. Fix: split into two agents — lint-checker with model="haiku" and deep-reviewer with model="opus". Route by description.
This isn’t just cost optimization — it’s also speed. Haiku responds faster than Opus, so simple reviews complete quicker.
maxTurns: bound execution per-agent
maxTurns caps reasoning-action cycles. Set it per-agent based on expected complexity:
- Search agent: 3-5 turns
- Security audit: 20 turns
- Simple lookup: 2 turns
Don’t rely on prompts to limit turns (“complete within 10 steps”) — that’s probabilistic. maxTurns is a deterministic safety net that complements stop_reason.
mcpServers: per-agent MCP server assignment
The mcpServers field in AgentDefinition assigns specific MCP servers to each sub-agent. A research system with 5 agents and 4 MCP servers:
- Search agent →
[web-search] - Academic agent →
[academic-db] - Financial agent →
[financial-data] - Fact-check agent →
[news-api] - Synthesis agent →
[](no external sources, works from other agents’ findings)
Sharing all MCP servers with all agents violates least privilege. The financial agent accessing academic-db or the fact-checker modifying financial data creates unnecessary risk. Per-agent mcpServers provides deterministic scoping.
The comprehensive configuration pattern
A security audit agent that needs all three constraints:
- Deep reasoning →
model="opus" - Read-only →
tools=["Read", "Grep", "Glob"] - Bounded execution →
maxTurns=20
All three must be explicitly set. Omitting model risks inheriting a cheaper model. Omitting tools risks inheriting Bash. Omitting maxTurns risks unbounded execution on large codebases. The pattern: configure everything, inherit nothing.
One-liner: Set description (specific, with “NOT for” boundaries), prompt (role instructions), tools (allowlist, not inherited), model (match to task complexity), maxTurns (per-agent bounds), and mcpServers (scoped access) — configure everything explicitly, inherit nothing by default.