Principle:Neuml Txtai Custom Function Tools
| Knowledge Sources | |
|---|---|
| Domains | NLP, Agent, Tool_Use |
| Last Updated | 2026-02-09 00:00 GMT |
Overview
Custom Function Tools is the principle of wrapping arbitrary Python callables as agent-usable tools by pairing them with descriptive metadata, enabling agents to extend their capabilities with any user-defined logic.
Description
Autonomous agents are only as powerful as the tools they can access. While txtai provides built-in tools such as embeddings search and web search, real-world applications demand domain-specific capabilities -- currency conversion, database queries, API calls, or mathematical computations. The Custom Function Tools principle addresses this by providing a mechanism to turn any Python callable into a tool the agent can invoke.
The approach works by combining a callable (target) with a configuration dictionary that supplies:
- name -- a short identifier the LLM uses to reference the tool.
- description -- a natural-language explanation injected into the agent prompt so the LLM understands when and why to call the tool.
- inputs -- a schema mapping parameter names to their types and descriptions, enabling the LLM to construct correct arguments.
- output / output_type -- an optional declaration of the return type.
At runtime, the FunctionTool class stores the callable and delegates all invocations of its forward method directly to that callable. Because it inherits from smolagents.Tool, it participates in the same tool protocol as every other tool in the system -- the agent sees a uniform interface regardless of whether the underlying implementation is a vector search, a web request, or a simple arithmetic function.
A critical design decision is that FunctionTool skips forward-signature validation (skip_forward_signature_validation = True), because the wrapped callable may have an arbitrary signature that does not match the forward(self, ...) convention. Instead, it trusts the explicit inputs schema provided in the configuration.
Usage
Use Custom Function Tools when:
- You need to give an agent access to a domain-specific function (e.g., a pricing calculator, a database lookup, or a third-party API wrapper).
- The callable does not have type annotations or Google-style docstrings that would allow automatic tool creation via smolagents.tool.
- You want full control over the tool's name, description, and input schema as presented to the LLM.
- You are composing a heterogeneous toolset where some tools are embeddings searches, some are built-in defaults, and some are custom functions.
Theoretical Basis
The Custom Function Tools principle is rooted in two key ideas:
1. The Adapter Pattern
In software engineering, the Adapter pattern converts the interface of a class into another interface that clients expect. Here, FunctionTool adapts an arbitrary callable into the smolagents.Tool interface that the agent framework expects. The configuration dictionary serves as the "glue" that supplies the missing metadata.
2. Tool Descriptions as Prompts
Large language models select tools based on natural-language descriptions. Research on tool-use (Schick et al., 2023) demonstrates that clear, concise descriptions significantly improve tool-selection accuracy. The description field in the config directly influences the agent's ability to choose the right tool at the right time.
The delegation model is straightforward:
FunctionTool.forward(*args, **kwargs)
-> self.target(*args, **kwargs)
-> returns result to agent observation
The agent sees the tool's inputs schema and description, constructs appropriate arguments, and the framework routes those arguments through forward to the wrapped callable. The return value is fed back into the agent's observation stream.