Princípio do Menor Privilégio

The Principle of Least Privilege says: give each agent only the tools its role actually needs — nothing more.

In a multi-agent system, the coordinator decomposes work and delegates to specialist subagents. Each subagent should receive a tightly scoped toolset. A research subagent does not need a refund tool. A read-only reviewer does not need Write or Bash.

This is not just security hygiene. Scoped tools also make Claude select the right tool more reliably, which directly improves accuracy on the exam scenarios.

Tool selection is driven by the model reading tool descriptions. The more tools you pile onto one agent, the harder that choice becomes.

• 4-5 tools per agent is the sweet spot for reliable selection.
• At 18+ tools, selection reliability degrades noticeably.
• Overlapping or ambiguous descriptions cause misrouting to the wrong tool.

Least privilege and good accuracy point the same direction: keep each agent's toolset small and role-specific.

In the Agent SDK, you scope a subagent with an AgentDefinition. Its fields are name, description, system_prompt, and allowed_tools.

The allowed_tools list is exactly where least privilege lives — it is the allowlist of tools that subagent may call. Give a researcher search and read tools only; never hand it write or refund actions.

Least privilege is about giving the right minimum — not crippling the agent.

The coordinator in a hub-and-spoke system must be able to delegate, so its allowedTools has to include "Task". Without it, the coordinator cannot spawn subagents at all.

So: the coordinator gets Task plus only what it needs to aggregate and route. Each spoke gets just its job-specific tools.

A common split is read-only investigators versus write-capable executors.

Claude Code's built-in tools make this concrete:

• Read-only: Glob (find files by pattern), Grep (search contents), Read (load a file).
• Mutating: Write (create), Edit (precise change), Bash (shell).

A code-review agent that only inspects code should get the read-only set. Withholding Write, Edit, and Bash means it physically cannot change the repo, even if a prompt is misread.

It is tempting to give every agent the full toolbox "just in case." Resist it.

The fact sheet is blunt: scope tools to the role. Each agent's tools should map to its responsibilities, not to whatever might be handy.

Two reasons:

• Safety — an agent cannot misuse a tool it was never given.
• Reliability — fewer, role-relevant tools mean clearer, non-overlapping descriptions and better selection.

Least privilege limits which tools exist for an agent. But for a critical business rule inside an allowed tool, an allowlist is not enough.

Example: the support agent legitimately has process_refund, but refunds over $500 must be blocked. A prompt enforces a rule only ~90% of the time. A hook enforces it 100% deterministically.

Use an outgoing-call hook to block policy-violating actions when failure has financial, legal, or safety consequences.

Least privilege also applies in time: an agent should not exercise a sensitive tool until preconditions are met.

In the customer support scenario, process_refund must not run until get_customer has returned a verified customer ID. A programmatic precondition gives a deterministic guarantee that prompt guidance alone cannot.

So privilege is conditional: the tool is in the allowlist, but a hook or precondition gates when it may fire.

Least privilege is not only an SDK concept — Claude Code Skills support it too.

A skill's frontmatter can set allowed-tools to restrict what that skill may invoke, plus context: fork to isolate verbose output and argument-hint for inputs.

A skill that only formats text should not be allowed to run Bash. Restricting it in frontmatter keeps the privilege boundary close to the capability.

Tools that reach external systems often need credentials — and credentials are privilege.

For MCP servers, inject secrets via environment variables like ${GITHUB_TOKEN}, and never commit tokens. Use .mcp.json at project scope (shared in VCS) for the server config, but keep the actual secret out of the file.

This keeps the token scoped to the environment that genuinely needs it, instead of leaking it into source control where every agent and teammate inherits it.

A well-scoped hub-and-spoke system layers least privilege cleanly:

• Coordinator: Task + routing tools, nothing destructive.
• Researcher: WebSearch, WebFetch, Read — read-only.
• Reviewer: Glob, Grep, Read — no writes.
• Executor: Edit, Write, Bash — and its risky calls are gated by hooks/preconditions.

Every agent stays near the 4-5 tool sweet spot, descriptions stay crisp, and the dangerous capabilities are both scoped and deterministically guarded.

Apply least privilege to a multi-agent design decision.

Key takeaways for least-privilege agent design:

• Give each agent only the tools its role needs — scope by role, not convenience.
• Aim for 4-5 tools per agent; selection degrades at 18+.
• Set allowed_tools per AgentDefinition; the coordinator must include Task to delegate.
• Split read-only (Glob/Grep/Read) from write-capable (Write/Edit/Bash) agents.
• For critical rules inside an allowed tool, enforce with hooks and preconditions (100% deterministic), not prompts (~90%).
• Restrict skills via allowed-tools frontmatter, and inject secrets through env vars — never commit tokens.