Agentsop Tool Scoping

Tool Scoping · Per-Agent Tool Binding (Least-Privilege Discipline)

> Overlay posture: the base frameworks ([[crewai]], LangChain, LangGraph) all

> *define* tools and *bind* them, but treat scoping as a one-line "assign tools

> to the agent that needs them" footnote. This overlay makes the rubric

> first-class. Non-trivial claims cite inline against

> references/R1-source-evidence.md.

The lever the base skills under-surface: **tool definition and tool binding are

two separate decisions.** You define a tool *once* (reusable class/function), but

you *bind* it per-agent deliberately. The [[crewai]] SKILL states this in one

clause — "tool 定义可复用；但每个 agent 只绑定其角色匹配的工具"

[crewai-sop §DC-3] — and then moves on. Production failures (wrong-tool

selection, an agent running a destructive op outside its role) come from skipping

the binding decision and defaulting to "give everyone everything."

1. 何时激活 (When to Activate)

Activate when any of these hold:

• The system is multi-agent (CrewAI crew, LangGraph supervisor/swarm,

AutoGen group) AND at least one agent holds ≥1 tool.

• A single agent holds many tools (rule of thumb: ≥8 — see OP-4) and tool

selection has started degrading (picks the wrong tool, or "tool-hops").

• You are tempted to give all agents all tools — tools=[search, exec, db]

copy-pasted onto every Agent(...), or one bind_tools([...everything]) call

reused for every node. This is the canonical trigger.

• A tool has side effects (DB write, payment, email, DELETE, shell exec,

outbound HTTP POST) and you are deciding who may hold it.

• You are doing a security / blast-radius review of an agent system and need

to answer "which agent can do what, and why."

Do not activate for: a single agent with 1–3 read-only tools (scoping is

trivial), or a stateless single LLM call with no tools.

2. 核心心智模型 (Core Mental Model)

A tool is a capability grant, not a convenience. Binding a tool to an agent

is the same act as granting a Unix process a syscall, a service an IAM role, or a

container a Linux capability. The discipline is identical and ancient:

**least-privilege — an agent should hold only the tools its role actually

needs.**

Three load-bearing consequences:

• Definition ≠ binding. Define the tool once (a reusable BaseTool /

function); decide the *binding* (which agents see it) separately and

minimally. [[crewai]] says "write once, use everywhere" applies to the

*definition* layer only; the *binding* layer is per-role [crewai-sop §DC-3].

• **Every bound tool is in the agent's selection space, and the model pays for

it.** The LLM must reason over the full tool list on every turn. More tools =

bigger schema in context = higher token cost AND lower selection accuracy.

This is why a 20-tool agent picks wrong (OP-4, DC-2).

• Side-effectful tools change the blast radius of a misfire. A read-only

search tool on the wrong agent wastes tokens. A run_sql or send_payment

tool on the wrong agent (or one with no guard) is a production incident. The

LangGraph HITL discipline — "interrupt on irreversible, high-blast-radius

actions only" — is the *runtime* half; tool scoping is the *design-time* half

of the same risk-control [langgraph-sop §Step5].

The mental test before binding any tool to any agent:

> "Does THIS role's goal require THIS capability to be exercised by THIS agent

> autonomously? If a different agent could/should do it, don't bind it here."

3. SOP 工作流 (Standard Operating Procedure)

A coder agent walks this top-down. Each phase has a gate.

Phase 0 · Inventory the surface

List every tool (name, side-effect class: read | compute | write |

destructive) and every agent (name, one-verb role). If there is exactly one

agent and ≤3 read tools — stop, scoping is trivial.

Phase 1 · Map roles → minimal tool set

For each agent, write its role as a single verb (research / analyze / write /

review). Then, for each tool, ask the §2 test. Bind only on a "yes."

• Default to the empty set and add tools, not the full set and remove them.
• A "synthesis-only" agent (writer, reporter) often needs zero tools — it

consumes upstream output [crewai-sop §DC-3].

Gate: if two agents end up with identical tool sets, ask whether they are really

two roles or one (the [[crewai]] "split-vs-merge" question [crewai-sop §DC-1]).

Phase 2 · Guard side-effectful tools

Any tool classed write or destructive:

• Bind it to exactly one agent (single funnel, auditable).
• Pair it with a runtime guard: HITL interrupt() before the side effect in

LangGraph [langgraph-sop §Step5], or an approval/confirm step in CrewAI.

• Make the underlying operation idempotent so a retry/re-run is a no-op —

see [[agentsop-llm-tool-idempotency]] and [[agentsop-http-tool-wrapping]]. LangGraph's payment

case (charged twice on resume) is exactly this failure [langgraph-sop §Case4].

Phase 3 · Enforce per-agent tool-count limit

If any agent now holds >8 tools, selection accuracy degrades (OP-4). Options:

split the role, group tools behind a router/sub-agent, or move read-only helpers

into the prompt as context instead of tools.

Phase 4 · Audit

Produce a binding matrix (agents × tools). For each write/destructive cell,

confirm there is exactly one owner and a guard. For each agent, confirm tool

count ≤ limit. This matrix is the security artifact a reviewer reads.

4. 操作模型 (Operation Models)

Format: Trigger → Action → Output → Evidence.

OP-1 · Least-privilege role→tool mapping

• Trigger: Assembling a multi-agent crew/graph with a shared tool pool.
• Action: For each agent, start from tools=[]. Add a tool only when the

role's goal *requires that agent* to exercise it. Reuse the tool *definition*

across agents, but bind per-role.

• Output: Each Agent(tools=[...]) / per-node bind_tools([...]) holds the

minimal set; a binding matrix.

• Evidence: [crewai-sop §DC-3] "每个 agent 只绑定其角色匹配的工具";

[langgraph-sop §Step4] topology binds tools to nodes, not globally.

OP-2 · Side-effect tool guarding

• Trigger: A tool performs a write or destructive operation.
• Action: Bind it to one agent only. Add a runtime guard (HITL interrupt /

human approval) before the effect, and make the op idempotent.

• Output: A single-owner, guarded, idempotent side-effectful tool.
• Evidence: [langgraph-sop §Step5] interrupt on irreversible only;

[langgraph-sop §Case4] double-charge from unguarded side effect; cross-link

[[agentsop-llm-tool-idempotency]], [[agentsop-http-tool-wrapping]].

OP-3 · Shared-registry vs per-agent binding decision

• Trigger: You have a tool registry and N agents and must decide how to wire.
• Action: Share at the definition layer (one registry of tool classes).

Decide binding per-agent via OP-1. Never tools=registry.all() on every

agent.

• Output: One definition source, N minimal per-agent bindings.
• Evidence: [crewai-sop §DC-3] definition-reuse vs binding-scope split.

OP-4 · Per-agent tool-count limit

• Trigger: An agent's tool list grows (≥8) or it starts mis-selecting tools.
• Action: Cap tools per agent (~8 as a working ceiling). If over, split the

role, introduce a routing sub-agent, or demote read-only tools to context.

• Output: Every agent ≤ the ceiling; improved selection accuracy.
• Evidence: too-many-tools degrades selection — same root cause as

CrewAI's ">5 agents = coordination failure" scaling wall [crewai-sop §6.1 AP-1];

see DC-2.

OP-5 · Zero-tool synthesis agents

• Trigger: An agent only consumes upstream output (writer, reporter, judge).
• Action: Bind no tools. Feed it context via task context=[...]

(CrewAI) or state (LangGraph).

• Output: A tool-free agent that cannot "wander" into capabilities.
• Evidence: [crewai-sop §DC-3] "reporter=[] (纯综合)".

OP-6 · Binding-matrix audit

• Trigger: Pre-ship review, or security review of an agent system.
• Action: Build an agents × tools matrix. Flag any write/destructive

tool bound to >1 agent or lacking a guard; flag any agent over the count limit.

• Output: A reviewable capability matrix + remediation list.
• Evidence: Phase 4; mirrors least-privilege IAM review practice.

OP-7 · Tighten scope as the fastest misuse fix

• Trigger: An agent is observed using a tool outside its role (e.g. a

researcher invoking a code executor).

• Action: Remove the tool from that agent's binding (the whitelist tighten),

rather than prompt-engineering "please don't use X."

• Output: A structurally-prevented misuse instead of a hoped-for one.
• Evidence: [crewai-sop §DC-3] "agent 跨工具滥用 → 收紧工具白名单是最快的 fix".

5. 困境决策案例 (Dilemma Cases)

DC-1 · Shared tool registry vs per-agent tool sets

场景: You have web_search, code_executor, db_query and three agents

(researcher / analyst / reporter). The convenient move is

tools=[search, exec, db] on all three.

两条路:

• A. Blanket share — every agent gets all three. Zero wiring thought.

Problem: the researcher also calls code_executor to "just quickly compute,"

violating role separation; failures become un-localizable (who ran the bad

query?); every agent pays the full 3-tool schema cost every turn.

• B. Per-role binding — researcher=[search], analyst=[exec, db],

reporter=[]. Clearer responsibilities, localizable errors, smaller per-turn

schema [crewai-sop §DC-3].

判断规则:

• Share at the definition layer (one BaseTool per tool — reuse is good).
• Decide binding by OP-1: a tool is bound only if the role needs that agent

to exercise it.

• If you genuinely cannot say which single agent owns a write tool, your roles

are under-specified — go back to role design [crewai-sop §DC-1].

红线: Never let "it's easier to share" be the binding rationale. Ease of

wiring is not a capability requirement.

Evidence: [crewai-sop §DC-3], [langgraph-sop §Step4].

DC-2 · The 20-tool agent that picks the wrong tool

场景: A single "do-everything" agent accumulates 20 tools over time. It now

calls delete_record when the user asked to *read* a record, or burns turns

hopping between near-duplicate tools (search_v1, search_v2, lookup).

陷阱: The instinct is to "improve the prompt" so the model picks better. But

the root cause is the selection space is too large — 20 tool schemas in

context dilute attention and inflate token cost, exactly as ">5 agents" causes

coordination collapse in CrewAI [crewai-sop §6.1 AP-1]. Prompt tweaks paper

over a structural problem.

三条路:

• A. Prompt-engineer the selection — describe each tool more carefully.

Helps marginally; does not fix the count.

• B. Split the agent by capability cluster — research-agent (search tools),

data-agent (db/exec tools), each ≤8 tools. Mirrors the CrewAI "split when one

agent does two jobs" rule [crewai-sop §DC-1].

• C. Router + scoped sub-agents — a thin supervisor routes to a sub-agent

whose small tool set matches the sub-task [langgraph-sop §Step4].

判断规则:

• Tool count > ~8 → suspect the count, not the prompt (OP-4).
• Duplicate/overlapping tools → consolidate definitions first.
• Mixed read + destructive tools on one agent → split so destructive tools live

on a single guarded owner (OP-2), shrinking the dangerous agent's surface.

红线: A destructive tool on a 20-tool agent is the worst case — high

mis-selection probability × high blast radius. Scope it out *first*.

Evidence: [crewai-sop §6.1 AP-1], [langgraph-sop §Step4/§Case4].

DC-3 · Should a destructive tool ever be shared across agents?

场景: Two agents both "occasionally need" to write to the database.

判断规则:

• Default no — a write/destructive tool gets exactly one owning agent

(single auditable funnel), per OP-2.

• If two agents truly both need it, the write should usually be **extracted into

a dedicated single-owner "writer" agent/node** that the others call — not

duplicated. This is the supervisor-funnel argument applied to capabilities

[langgraph-sop §Step4].

• Whichever agent owns it: guard with HITL/approval and idempotency

([[agentsop-llm-tool-idempotency]], [[agentsop-http-tool-wrapping]]).

红线: Two agents holding the same unguarded destructive tool = two

independent ways to cause the same irreversible incident, and an ambiguous audit

trail.

Evidence: [langgraph-sop §Step5/§Case4], [crewai-sop §DC-3].

6. 反模式与边界 (Anti-Patterns & Boundaries)

| # | Anti-pattern | Symptom | Fix |

|---|---|---|---|

| AP-1 | Blanket tool sharing (tools=[all] on every agent) | role bleed, un-localizable failures, inflated token cost | per-role binding (OP-1, DC-1) |

| AP-2 | No guard on destructive tools | double-charge / accidental delete on retry or mis-selection | single owner + HITL + idempotency (OP-2, [[agentsop-llm-tool-idempotency]]) |

| AP-3 | One mega-agent with 20 tools | wrong-tool selection, tool-hopping, cost | cap ≤8, split or route (OP-4, DC-2) |

| AP-4 | Prompt-patching tool misuse | "please don't use X" in backstory | remove the tool from the binding (OP-7) |

| AP-5 | Sharing the destructive tool itself instead of the definition | two paths to the same incident | extract single-owner writer (DC-3) |

| AP-6 | Binding tools to synthesis agents | writer/reporter "wanders" into search/exec | bind zero tools (OP-5) |

Boundaries — this overlay does NOT cover:

• *How* to implement a tool (ret, errors, HTTP wrapping) → [[agentsop-http-tool-wrapping]].
• *How* to make a tool safe to retry → [[agentsop-llm-tool-idempotency]].
• *Runtime* HITL gating mechanics → base LangGraph skill [langgraph-sop §Step5].
• Whether to use multi-agent at all → [[crewai]] / agent-topology selection.
• This is a design-time scoping rubric, not a sandbox/permission *runtime*.

7. 跨框架对照 (Cross-Framework Mapping)

The scoping decision is universal; only the binding syntax differs.

| Framework | Define a tool | Bind per-agent (the scoping point) | Scoping notes |

|---|---|---|---|

| CrewAI | BaseTool subclass / @tool | Agent(role=..., tools=[search]) — per agent | Definition reusable, binding per-role [crewai-sop §DC-3]. allow_delegation further widens effective capability — keep it False on workers [crewai-sop §DC-5]. |

| LangGraph | a callable / @tool | model.bind_tools([...]) per node, or per create_react_agent | Tools bound to the node that needs them, not globally; topology decides who routes to the tool-bearing node [langgraph-sop §Step2/§Step4]. Guard destructive tools with interrupt() [langgraph-sop §Step5]. |

| LangChain (agents) | @tool / Tool | tools list passed to each AgentExecutor | Same definition-vs-binding split; the base LangChain docs note "give the agent the tools it needs" but leave the per-agent rubric implicit — this overlay fills that gap. |

| OpenAI Assistants | tools=[{type/function...}] | per-Assistant tools array | Each Assistant is a scoping boundary; create role-specific Assistants rather than one with every function. |

| Claude tool_use | tools=[{name, input_schema}] in the API call | the tools list of a given request/agent | Scope by sending only the tools relevant to that agent's turn; large tool lists raise mis-selection and token cost identically. |

One-line cross-walk: CrewAI agent.tools ≈ LangGraph per-node

bind_tools ≈ Assistant tools array ≈ Claude request tools — in every case,

**the right-hand list is the capability grant, and least-privilege says keep it

minimal.**

Appendix · Binding matrix template

              | web_search | run_sql (write) | send_email (write) | code_exec |
--------------+------------+-----------------+--------------------+-----------+
researcher    |     ✓      |        ·        |         ·          |     ·     |
analyst       |     ·      |        ·        |         ·          |     ✓     |
db_writer*    |     ·      |        ✓ (HITL)  |         ·          |     ·     |
notifier*     |     ·      |        ·        |       ✓ (HITL)      |     ·     |
reporter      |     ·      |        ·        |         ·          |     ·     |   ← zero-tool synthesis
--------------+------------+-----------------+--------------------+-----------+
* single owner of a destructive tool; guarded + idempotent

Audit rule: every (write) column has exactly one ✓, and it is (HITL).

Sources

• [crewai-sop] = crewai-sop-skill/SKILL.md (per-agent tools §DC-3; split §DC-1; delegation §DC-5; scaling AP-1)
• [langgraph-sop] = langgraph-sop-skill/SKILL.md (bind_tools to nodes §Step2/4; HITL §Step5; double-charge §Case4)
• [[crewai]], [[agentsop-http-tool-wrapping]], [[agentsop-llm-tool-idempotency]] — sibling overlays
• Full evidence with quotes: references/R1-source-evidence.md