Principle:CrewAIInc CrewAI Tool Assignment

Overview

A configuration pattern for binding tools to agents (persistent access) or tasks (scoped access), controlling which capabilities are available during execution.

Description

Tool Assignment determines which tools an agent can use and when those tools are available. CrewAI provides a two-level assignment model:

Agent-Level Tools

Tools assigned at the agent level are persistent -- they are available for every task the agent executes. These represent the agent's core capabilities, analogous to the skills a worker brings to every job. Agent-level tools are specified via the tools parameter on the Agent constructor.

Additionally, MCP servers are assigned at the agent level via the mcp_servers parameter. All tools discovered from configured MCP servers are added to the agent's persistent tool set.

Task-Level Tools

Tools assigned at the task level are scoped -- they are only available during the execution of that specific task. When a task specifies tools, those tools supplement the agent's persistent tools for the duration of that task. In some cases, task-level tools can override agent-level tools of the same name, providing task-specific behavior.

This two-level assignment provides both:

Persistent capabilities (agent tools): Always-available tools that define the agent's general skill set.
Task-specific capabilities (task tools): Tools that are only relevant for a particular task, preventing tool clutter in the LLM's selection space.

Tool Set Resolution

When an agent executes a task, the effective tool set is resolved as follows:

Start with the agent's persistent tools.
Add tools discovered from the agent's MCP servers.
Merge in the task's scoped tools.
The resulting union is the set of tools available to the LLM.

Key Considerations

Minimize tool sets: Only assign tools that are relevant. Every additional tool increases the LLM's decision space and can degrade selection accuracy. A focused set of 3-8 tools is generally more effective than a large set of 20+.
Use task-level tools for specialization: If a tool is only needed for one specific task, assign it at the task level rather than burdening the agent with it for all tasks.
MCP servers are agent-level only: There is no mechanism to assign MCP servers at the task level. Plan agent design accordingly.
Tool name uniqueness: Within the resolved tool set for a given task execution, tool names should be unique. Duplicate names can cause unpredictable tool selection.
Cost control: Use max_usage_count on individual tools to limit invocations, especially for expensive API-backed tools.

Theoretical Basis

This principle follows the Capability-Based Security model where agents are granted specific capabilities (tools) that constrain their action space. Rather than giving agents unrestricted access to all tools, each agent is granted only the capabilities it needs. This follows the principle of least privilege, reducing the risk of unintended tool usage and making agent behavior more predictable.

The two-level assignment (agent + task) mirrors role-based access control systems where a user has permanent role-based permissions supplemented by context-specific permissions for particular operations.

Relationship to Implementation

Implementation:CrewAIInc_CrewAI_Tool_Assignment_Config

The Agent.tools, Agent.mcp_servers, and Task.tools configuration fields in CrewAI provide the concrete mechanism for tool assignment at both levels.

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment