Tools

## Two ways to author a CrewAI tool A CrewAI tool is an object with a name, a natural-language description, an argument schema, and an implementation. Everything an agent's LLM knows about the tool comes from the first three; the fourth is your code. CrewAI ships two ways to produce that object. ### The @tool decorator ``` from crewai.tools import tool ``` Decorating a function with `@tool("Read Jira ticket")` produces a tool whose name is the string you pass, whose description is the function's docstring, and whose argument schema is inferred from the parameter names and type hints. This is the fastest path and it is idiomatic for stateless helpers: a formatter, a lookup against a module-level client, a pure computation. The tradeoffs are that the docstring is doing double duty as human documentation and as LLM-facing prompt text, and that you have no per-argument descriptions unless you spell them out in prose inside the docstring. ### Subclassing BaseTool ``` from crewai.tools import BaseTool ``` A `BaseTool` subclass is a Pydantic model. You declare `name: str` and `description: str` as class fields, set `args_schema: Type[BaseModel]` to a Pydantic model describing the inputs, and implement `_run(self, ...)` — note the leading underscore; `_run` is the method CrewAI invokes, not `run`. Each field in the args schema can carry `Field(..., description="...")`, and that per-argument text is what reaches the model. This matters in practice: most tool-call failures are the model guessing an argument format, and the schema description is where you say "ISO-8601 date" or "Jira key such as OPS-1421". ## What subclassing buys you - **Explicit, reviewable schema.** The tool contract lives in one Pydantic model you can test, reuse across tools, and validate independently of the LLM. - **Constructor state.** Because it is a class you instantiate (`TicketReaderTool(base_url=..., session=...)`), expensive clients are built once and shared across every call the crew makes, rather than reconstructed inside a function body. - **Per-tool behaviour fields.** `cache_function` decides whether a given result is worth caching; `result_as_answer=True` makes the tool's raw output the agent's final answer for that step instead of letting the LLM paraphrase it — useful when the tool already produces the exact deliverable and any rewriting is a fidelity risk. - **Subclassable families.** If you have eight internal API tools sharing auth and error handling, a shared base class removes eight copies of that logic. ## Validation is part of the deal CrewAI validates the arguments the model produced against the schema before your `_run` body executes. A missing required field or a wrong type produces a validation error that is handed back to the agent as the tool's observation, so the model gets a chance to retry with corrected arguments. The practical consequence is that a tight schema converts a class of runtime exceptions in your code into a recoverable, model-visible correction loop. Loose schemas — a single `str` argument that you parse yourself — push that failure into your `_run` body where it is more likely to crash or, worse, silently do the wrong thing. ## Naming and description are prompt engineering Both paths feed the tool's name and description into the agent's prompt alongside every other tool it holds. An agent with twelve tools whose descriptions all begin "This tool is useful for..." will pick badly. Write descriptions that state what the tool returns and when *not* to use it ("returns the latest deploy record for one service; does not search across services"). This is the single highest-leverage edit on a misbehaving CrewAI agent, and it is free. ## The prebuilt catalogue Before writing either, check `crewai_tools`: `SerperDevTool` for web search (it reads `SERPER_API_KEY` from the environment), `ScrapeWebsiteTool` for fetching page text, `FileReadTool` and `DirectoryReadTool` for local files, `RagTool` for semantic question-answering over a configured data source, and `CodeInterpreterTool` for executing generated Python. The `*SearchTool` variants (PDF, CSV, website) are RAG tools specialised to one source type. Every one of these is a `BaseTool` subclass, so reading their source is the fastest way to learn the idioms. ## Rule of thumb Start with `@tool`. Promote to `BaseTool` the moment you need a real argument contract, shared state, or per-tool caching and answer behaviour — those are exactly the things the decorator cannot express.