Tool Design Rules for Safe, Composable Claude Agents
These are the enumerated rules this site uses for designing tools that Claude agents call - scoping, naming, and validating them so multiple tools compose safely instead of accumulating hidden risk as an agent's toolset grows.
How to Use This Checklist
- Apply these rules when defining any new tool, not only for tools with obvious side effects.
- Treat "narrow scope" and "clear naming" as prerequisites for review - a tool that's hard to describe in one sentence is usually trying to do too much.
- Re-audit an agent's full toolset periodically, not just each tool in isolation - composability risk shows up between tools, not within one.
- Use the validation and permission rules as a pre-merge checklist for any tool touching production data or systems.
Scoping Rules
- Give every tool exactly one well-defined action. A tool named
manage_orderthat can look up, modify, cancel, and refund is four tools wearing one name - split it so each action can be reasoned about, permissioned, and logged independently. - Prefer several narrow tools over one broad tool "for flexibility." Flexibility at the tool-definition layer becomes unpredictability at the agent-behavior layer - Claude will use whatever surface area a tool exposes, including parts you didn't intend for routine use.
- Keep a tool's side effects match its description exactly. A
get_user_profiletool that also updates a "last viewed" timestamp has an undocumented side effect - name it to reflect everything it does, or split the write out. - Bound what data a tool can access to what the task actually needs. A tool that queries a full customer record when the task only needs a shipping address is carrying unnecessary risk for no functional benefit.
- Treat bash or generic-command tools as the exception, not the default. A broad shell-execution tool gives an agent maximum leverage and the harness minimum ability to gate, audit, or parallelize - promote specific actions to dedicated tools instead.
Naming Rules
- Name tools for what they do, not how they're implemented.
refund_order, notcall_billing_endpoint- the model reasons about the tool's purpose, and an implementation-shaped name forces it to infer intent from internals. - Use a verb-object pattern consistently across the toolset.
create_ticket,search_orders,send_email- consistent naming reduces the model's uncertainty about which tool applies to a given step. - Never reuse a tool name for a functionally different action across agents. If two agents in the same system both expose
search, but one searches documents and the other searches customer records, a shared harness or shared prompt fragment can silently misroute. - Write tool descriptions that state when to call it, not just what it does. "Look up account balances" invites more triggering ambiguity than "Call this when the user asks for their current balance or recent transaction total."
Validation Rules
- Validate every tool input before it executes, never trust it as pre-sanitized. The model's arguments are generated text, not verified data - apply the same input validation you would to a user-submitted form.
- Validate every tool output before it re-enters the model's context. An unexpectedly large, malformed, or unexpected-shape result should be caught and truncated or rejected, not passed back to the model unchecked.
- Reject silently-wrong inputs loudly. Returning a tool result with
is_error: trueand a clear message lets Claude adapt; silently returning an empty or default value teaches it the call succeeded when it didn't. - Enforce schema constraints the model can't argue its way around. Use enums for fixed value sets and required fields for anything the tool cannot function without - don't rely on a description alone to enforce a constraint the schema can enforce directly.
- Sanitize file paths and identifiers before touching the filesystem or a database. A model-supplied path or ID is untrusted input - resolve and validate it against an allowed root or an allowed-ID set before using it in any operation with side effects.
Permission and Safety Rules
- Gate destructive or irreversible tool calls behind explicit confirmation. Deletions, payments, and production writes should never execute automatically without either a human approval step or a strong, reviewed justification for skipping one.
- Scope credentials per tool, not per agent. A tool that only needs to read a calendar should not share a credential that can also write to billing - the blast radius of a compromised or misused tool should be limited to what that tool actually needs.
- Log every call to a tool with side effects, independent of the conversation transcript. A conversation log can be edited, truncated, or lost; a dedicated audit log for sensitive tool calls survives independently.
- Set a hard limit on how many times a tool can be called in a single agent turn. An unbounded retry or loop against a tool with side effects can turn a bug into an incident faster than a human can intervene.
Composability Rules
- Review the full toolset for overlapping purpose, not just each tool individually. Two tools that can both technically accomplish a task create ambiguity the model has to resolve on its own, often inconsistently across calls.
- Keep tool count focused - too many tools degrades selection accuracy. An agent choosing between forty loosely related tools makes worse choices than one choosing between eight well-scoped ones; use tool search or task-specific toolsets instead of exposing everything everywhere.
- Test tool interactions, not just individual tool schemas. A tool that works correctly in isolation can still produce a bad outcome when its output feeds into a second tool's input in a way nobody tested.
- Document which tools are safe to call in parallel and which aren't. A read-only lookup tool and a tool that mutates state behave differently under concurrent calls - make that distinction explicit rather than leaving the harness to guess.
FAQs
What's the single highest-leverage rule on this list?
Scoping each tool to one well-defined action - most of the naming, validation, and permission rules become easier to apply once a tool's purpose is narrow and unambiguous.
Why validate tool inputs and outputs separately?
They fail differently. Bad input lets a malformed or malicious argument reach a real system; bad output lets a broken or oversized result silently corrupt the model's next turn. Catching one doesn't catch the other.
Isn't a broad bash tool more flexible than many narrow tools?
It's more flexible for the model, but less controllable for the harness - a dedicated tool gives you a hook to gate, audit, render, or parallelize a specific action, while a shell command is an opaque string every time. Reserve bash for genuine breadth needs and promote anything sensitive to its own tool.
How many tools is "too many" for a single agent?
There's no fixed number, but selection accuracy degrades as the toolset grows and tools become harder to tell apart. If tools start overlapping in purpose or the model starts picking inconsistently, that's the signal to split by task or add tool search rather than add more tools flat.
Should every tool require human confirmation to be safe?
No - that would make agents unusable for routine work. Reserve confirmation gates for destructive, irreversible, or high-cost actions, and let read-only or low-stakes actions execute automatically.
What does "scope credentials per tool" protect against?
A single overprivileged credential shared across many tools means any one tool being misused - by a bug, a bad model call, or a prompt injection - can affect everything that credential can touch. Narrow credentials keep the blast radius contained.
Why does tool naming matter if the description is accurate?
Because the model uses the name as a first-pass signal before reading the full description, and a name that misleads (implementation-shaped, inconsistent verb pattern) adds friction the description then has to overcome on every call.
How does this list relate to the security guardrail rules elsewhere in this section?
Tool design rules are about the shape of the tool itself; Security Guardrail Rules cover the broader system around it - permissions, logging, and output validation as a whole-system concern rather than a per-tool one.
What's a concrete sign a tool needs to be split?
If you can't describe what it does in one sentence without using "and," or if two different call sites use it for functionally different purposes, it's carrying more than one action and should be split.
Should tool schemas be strict about types and enums?
Yes wherever the value set is known - enums and required fields let the schema itself reject invalid input before the tool's code ever runs, which is more reliable than relying on prose in the description.
Why set a hard limit on tool call counts per turn?
Because an unbounded loop against a side-effecting tool - a retry storm, a runaway agent - turns what should be a caught bug into a production incident before anyone notices, especially outside business hours.
Related
- Security Guardrail Rules Every Tech Lead Should Enforce - the system-level permission and audit rules that build on tool-level scoping.
- Prompt and Context Hygiene: Rules for Keeping Agents Reliable - how tool results feed back into the context these rules protect.
- The Core Claude Rules: A Quick-Reference List - the condensed version of these rules alongside every other category.
- Claude Rules Best Practices - every rule in this section restated as one checklist.
Stack versions: Written against the Claude model lineup current as of ~June 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (the default), and Claude Haiku 4.5 - and the official
anthropicPython SDK (latest 0.x release). Model names, pricing, and SDK versions move quickly - verify current specifics at platform.claude.com/docs before relying on them.