What does Haystack's ComponentTool wrap, and where does its schema come from?

## The idea Haystack already models units of work as components: a retriever, a splitter, a web search, a custom `@component` you wrote. A tool, from the model's point of view, is also a unit of work with a name, a description and a typed argument list. `ComponentTool` is the adapter between the two, so the same tested object serves both a deterministic pipeline and an agent. ``` search_tool = ComponentTool( component=InMemoryBM25Retriever(document_store=store), name="search_docs", description="Search the internal knowledge base and return matching documents.", ) ``` ## Where the schema comes from The JSON parameter schema advertised to the model is generated by introspecting the wrapped component's `run()` method: parameter names, type hints, defaults and whether each is required. Nested structures are handled — dataclasses and Pydantic models expand into object schemas — so a component whose `run()` takes `filters: dict[str, Any]` or a typed config object still produces a usable schema. Two consequences follow. First, **type hints are load-bearing**: an untyped or `Any`-typed parameter gives the model no guidance and produces vague or wrong arguments. Second, if the generated schema is not what you want — you want to hide a parameter, rename it, or constrain it with an enum — pass `parameters` explicitly and it takes precedence. You can also mark a parameter as *not* the model's business: `inputs_from_state` binds an argument to a value carried in the agent's state, and the framework supplies it at invocation time rather than asking the model to guess it. ## Name and description `name` defaults to a snake_case form of the component's class name, and `description` falls back to the component's docstring. Both defaults are conveniences, not recommendations. The description is the only prose the model sees when deciding whether this tool is the right one, so it should say what the tool *is for* and when to reach for it, not what class it wraps. Wrong-tool-selection failures in an agent are, more often than not, description failures. Names matter mechanically too: the invoker resolves calls by name, names must be unique within the tool list, and providers constrain the allowed character set. ## Getting the output back to the model A component returns a dict of Python objects — `{"documents": [Document, ...]}`. The model can only read text. `ComponentTool` therefore converts the result before it becomes a tool message. By default it serializes the output structure; `outputs_to_string` lets you take control with `{"source": "documents", "handler": my_render_fn}` so that, for instance, ten `Document` objects become ten titled snippets instead of a wall of JSON containing embeddings and scores. This is not cosmetic: the serialized result lands in the prompt of every subsequent step, so a fat default rendering multiplies cost across the whole run. Separately, `outputs_to_state` can route parts of the same result into the agent's state, so structured data survives the run without being squeezed through text. ## Warm-up and lifecycle Components that need `warm_up()` — model-loading ones especially — are warmed as part of the agent's own `warm_up()`, so an agent placed in a pipeline gets its tools warmed when the pipeline warms. Building a `ComponentTool` around a heavyweight component still means that component is instantiated once and shared across the agent's steps, not rebuilt per call. ## Serialization `ComponentTool` supports `to_dict`/`from_dict`, which is what allows an agent that uses it to survive a pipeline `to_dict()`/YAML round trip — provided the wrapped component is itself serializable. A tool built from a closure over a live connection object is where that breaks. ## When not to use it If the work is a plain function with no component lifecycle — a unit conversion, a date lookup — the `@tool` decorator on the function is lighter and produces the same schema-from-signature behaviour. `ComponentTool` earns its place when the callee is genuinely a component: it has `warm_up`, configuration, serialization, or you want the exact same object used elsewhere in your pipelines.