Skip to content

Tool Class API Reference

The Tool class represents a callable tool with associated metadata that can be used by agents in their workflows.

Class Definition

A callable tool with metadata for use in agent workflows.

Represents a function with associated metadata (name, description, signature) that can be used as a tool by an agent. Tools are immutable and can be called like regular functions.

Attributes:

Name Type Description
func ToolCallable

The underlying function that implements the tool's logic.
name str

The tool's display name.
description str

Human-readable description of the tool's purpose.
_signature ToolSignature

Internal cached signature information.
Example

Using the @tool decorator: 

@tool
def calculate(x: int, y: int) -> int:
    '''Add two numbers.'''
    return x + y
result = calculate(5, 3)
print(result)  # Output: 8

Using @tool with parameters: 

@tool(name="Calculator", description="Performs basic arithmetic")
def add(x: int, y: int) -> int:
    return x + y

Direct creation and registration: 

def multiply(x: int, y: int) -> int:
    '''Multiply two numbers.'''
    return x * y
tool = Tool.create(
    multiply,
    name="Multiplier",
    description="Performs multiplication"
)
agent.register_tool(tool)

Notes
  • Tools are immutable (frozen=True dataclass)
  • Tool signatures are cached for performance
  • Tools can be used directly as functions
  • Tool metadata is available for agent introspection
Source code in clientai/agent/tools/base.py 
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
@dataclass(frozen=True)
class Tool:
    """A callable tool with metadata for use in agent workflows.

    Represents a function with associated metadata
    (name, description, signature) that can be used
    as a tool by an agent. Tools are immutable and
    can be called like regular functions.

    Attributes:
        func: The underlying function that implements the tool's logic.
        name: The tool's display name.
        description: Human-readable description of the tool's purpose.
        _signature: Internal cached signature information.

    Example:
        Using the @tool decorator:
        ```python
        @tool
        def calculate(x: int, y: int) -> int:
            '''Add two numbers.'''
            return x + y
        result = calculate(5, 3)
        print(result)  # Output: 8
        ```

        Using @tool with parameters:
        ```python
        @tool(name="Calculator", description="Performs basic arithmetic")
        def add(x: int, y: int) -> int:
            return x + y
        ```

        Direct creation and registration:
        ```python
        def multiply(x: int, y: int) -> int:
            '''Multiply two numbers.'''
            return x * y
        tool = Tool.create(
            multiply,
            name="Multiplier",
            description="Performs multiplication"
        )
        agent.register_tool(tool)
        ```

    Notes:
        - Tools are immutable (frozen=True dataclass)
        - Tool signatures are cached for performance
        - Tools can be used directly as functions
        - Tool metadata is available for agent introspection
    """

    func: ToolCallable
    name: str
    description: str
    _signature: ToolSignature = field(
        default_factory=lambda: ToolSignature.empty(),  # type: ignore
        repr=False,
    )

    @classmethod
    def create(
        cls,
        func: ToolCallable,
        name: Optional[str] = None,
        description: Optional[str] = None,
    ) -> "Tool":
        """Create a new Tool instance from a callable.

        Factory method that creates a Tool with proper signature analysis and
        metadata extraction. Uses function's docstring as description if none
        provided.

        Args:
            func: The function to convert into a tool.
            name: Optional custom name for the tool. Defaults to function name.
            description: Optional custom description. Defaults to docstring.

        Returns:
            A new Tool instance.

        Raises:
            ValueError: If function lacks required type hints
                        or has invalid signature.

        Example:
            Basic tool creation:
            ```python
            def format_text(text: str, uppercase: bool = False) -> str:
                '''Format input text.'''
                return text.upper() if uppercase else text
            tool = Tool.create(format_text)
            ```

            Custom metadata:
            ```python
            tool = Tool.create(
                format_text,
                name="Formatter",
                description="Text formatting utility"
            )
            ```
        """
        actual_name = name or func.__name__
        actual_description = (
            description or getdoc(func) or "No description available"
        )
        signature = ToolSignature.from_callable(func, actual_name)

        return cls(
            func=func,
            name=actual_name,
            description=actual_description,
            _signature=signature,
        )

    @property
    def signature(self) -> ToolSignature:
        """
        Get the tool's signature information.

        Provides access to the analyzed signature of the tool's function,
        creating it if not already cached.

        Returns:
            Signature information for the tool.

        Example:
            ```python
            @tool
            def my_function(x: int, y: str) -> str:
                return f"{y}: {x}"
            sig = my_function.signature
            print(sig.parameters)  # Shows parameter information
            ```
        """
        if self._signature is None:
            sig = ToolSignature.from_callable(self.func, self.name)
            object.__setattr__(self, "_signature", sig)
            return sig
        return self._signature

    def __call__(self, *args: Any, **kwargs: Any) -> Any:
        """
        Execute the tool's function with the provided arguments.

        Makes the Tool instance callable, delegating to the underlying
        function. This allows tools to be used like regular functions
        while maintaining their metadata.

        Args:
            *args: Positional arguments to pass to the function.
            **kwargs: Keyword arguments to pass to the function.

        Returns:
            The result of the tool's function execution.

        Example:
            Using a tool with positional arguments:
            ```python
            @tool
            def calculate(x: int, y: int) -> int:
                return x + y
            result = calculate(5, 3)
            ```

            Using a tool with keyword arguments:
            ```python
            result = calculate(x=5, y=3)
            ```
        """
        return self.func(*args, **kwargs)

    @cached_property
    def signature_str(self) -> str:
        """
        Get a string representation of the tool's signature.

        Provides a cached, formatted string version of the tool's signature
        for display purposes. This is useful for documentation and debugging.

        Returns:
            A formatted string representing the tool's signature.

        Example:
            ```python
            @tool
            def calculate(x: int, y: int) -> int:
                return x + y
            print(calculate.signature_str)

            # Output: "calculate(x: int, y: int) -> int"
            ```
        """
        return self.signature.format()

    def format_tool_info(self, indent: str = "") -> str:
        """Format the tool's information in a standardized way for LLM prompts.

        Creates a consistently formatted string representation of the tool
        that includes its name, signature, and description in a hierarchical
        format.

        Args:
            indent: Optional indentation prefix for each line.
                   Useful for nested formatting. Defaults to no indentation.

        Returns:
            A formatted string containing the tool's complete information.

        Example:
            Basic formatting:
            ```python
            @tool(name="Calculator")
            def add(x: int, y: int) -> int:
                '''Add two numbers together.'''
                return x + y
            print(add.format_tool_info())
            # Output:
            # - Calculator
            #   Signature: add(x: int, y: int) -> int
            #   Description: Add two numbers together
            ```

            With custom indentation:
            ```python
            print(add.format_tool_info("  "))
            # Output:
            #   - Calculator
            #     Signature: add(x: int, y: int) -> int
            #     Description: Add two numbers together
            ```
        """
        return (
            f"{indent}- {self.name}\n"
            f"{indent}  Signature: {self.signature_str}\n"
            f"{indent}  Description: {self.description}"
        )

    def __str__(self) -> str:
        """
        Get a complete string representation of the tool.

        Provides a formatted string containing all relevant tool
        information using the standardized format defined by
        format_tool_info(). This ensures consistency between
        string representation and prompt formatting.

        Returns:
            A formatted string containing the tool's complete information.

        Example:
            ```python
            @tool(name="Calculator")
            def add(x: int, y: int) -> int:
                '''Add two numbers together.'''
                return x + y
            print(str(add))

            # Output:
            # - Calculator
            #   Signature: add(x: int, y: int) -> int
            #   Description: Add two numbers together
            ```

        Note:
            This method uses format_tool_info() to ensure consistency between
            string representation and prompt formatting. The format is designed
            to be both human-readable and suitable for LLM processing.
        """
        return self.format_tool_info()

signature: ToolSignature property

Get the tool's signature information.

Provides access to the analyzed signature of the tool's function, creating it if not already cached.

Returns:

Type Description
ToolSignature

Signature information for the tool.
Example 
@tool
def my_function(x: int, y: str) -> str:
    return f"{y}: {x}"
sig = my_function.signature
print(sig.parameters)  # Shows parameter information

signature_str: str cached property

Get a string representation of the tool's signature.

Provides a cached, formatted string version of the tool's signature for display purposes. This is useful for documentation and debugging.

Returns:

Type Description
str

A formatted string representing the tool's signature.
Example 
@tool
def calculate(x: int, y: int) -> int:
    return x + y
print(calculate.signature_str)

# Output: "calculate(x: int, y: int) -> int"

__call__(*args, **kwargs)

Execute the tool's function with the provided arguments.

Makes the Tool instance callable, delegating to the underlying function. This allows tools to be used like regular functions while maintaining their metadata.

Parameters:

Name Type Description Default
*args Any

Positional arguments to pass to the function.

 ()
**kwargs Any

Keyword arguments to pass to the function.

 {}

Returns:

Type Description
Any

The result of the tool's function execution.
Example

Using a tool with positional arguments: 

@tool
def calculate(x: int, y: int) -> int:
    return x + y
result = calculate(5, 3)

Using a tool with keyword arguments: 

result = calculate(x=5, y=3)

Source code in clientai/agent/tools/base.py 
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
def __call__(self, *args: Any, **kwargs: Any) -> Any:
    """
    Execute the tool's function with the provided arguments.

    Makes the Tool instance callable, delegating to the underlying
    function. This allows tools to be used like regular functions
    while maintaining their metadata.

    Args:
        *args: Positional arguments to pass to the function.
        **kwargs: Keyword arguments to pass to the function.

    Returns:
        The result of the tool's function execution.

    Example:
        Using a tool with positional arguments:
        ```python
        @tool
        def calculate(x: int, y: int) -> int:
            return x + y
        result = calculate(5, 3)
        ```

        Using a tool with keyword arguments:
        ```python
        result = calculate(x=5, y=3)
        ```
    """
    return self.func(*args, **kwargs)

__str__()

Get a complete string representation of the tool.

Provides a formatted string containing all relevant tool information using the standardized format defined by format_tool_info(). This ensures consistency between string representation and prompt formatting.

Returns:

Type Description
str

A formatted string containing the tool's complete information.
Example 
@tool(name="Calculator")
def add(x: int, y: int) -> int:
    '''Add two numbers together.'''
    return x + y
print(str(add))

# Output:
# - Calculator
#   Signature: add(x: int, y: int) -> int
#   Description: Add two numbers together
Note

This method uses format_tool_info() to ensure consistency between string representation and prompt formatting. The format is designed to be both human-readable and suitable for LLM processing.

Source code in clientai/agent/tools/base.py 
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
def __str__(self) -> str:
    """
    Get a complete string representation of the tool.

    Provides a formatted string containing all relevant tool
    information using the standardized format defined by
    format_tool_info(). This ensures consistency between
    string representation and prompt formatting.

    Returns:
        A formatted string containing the tool's complete information.

    Example:
        ```python
        @tool(name="Calculator")
        def add(x: int, y: int) -> int:
            '''Add two numbers together.'''
            return x + y
        print(str(add))

        # Output:
        # - Calculator
        #   Signature: add(x: int, y: int) -> int
        #   Description: Add two numbers together
        ```

    Note:
        This method uses format_tool_info() to ensure consistency between
        string representation and prompt formatting. The format is designed
        to be both human-readable and suitable for LLM processing.
    """
    return self.format_tool_info()

create(func, name=None, description=None) classmethod

Create a new Tool instance from a callable.

Factory method that creates a Tool with proper signature analysis and metadata extraction. Uses function's docstring as description if none provided.

Parameters:

Name Type Description Default
func ToolCallable

The function to convert into a tool.

 required
name Optional[str]

Optional custom name for the tool. Defaults to function name.

 None
description Optional[str]

Optional custom description. Defaults to docstring.

 None

Returns:

Type Description
Tool

A new Tool instance.

Raises:

Type Description
ValueError

If function lacks required type hints or has invalid signature.
Example

Basic tool creation: 

def format_text(text: str, uppercase: bool = False) -> str:
    '''Format input text.'''
    return text.upper() if uppercase else text
tool = Tool.create(format_text)

Custom metadata: 

tool = Tool.create(
    format_text,
    name="Formatter",
    description="Text formatting utility"
)

Source code in clientai/agent/tools/base.py 
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
@classmethod
def create(
    cls,
    func: ToolCallable,
    name: Optional[str] = None,
    description: Optional[str] = None,
) -> "Tool":
    """Create a new Tool instance from a callable.

    Factory method that creates a Tool with proper signature analysis and
    metadata extraction. Uses function's docstring as description if none
    provided.

    Args:
        func: The function to convert into a tool.
        name: Optional custom name for the tool. Defaults to function name.
        description: Optional custom description. Defaults to docstring.

    Returns:
        A new Tool instance.

    Raises:
        ValueError: If function lacks required type hints
                    or has invalid signature.

    Example:
        Basic tool creation:
        ```python
        def format_text(text: str, uppercase: bool = False) -> str:
            '''Format input text.'''
            return text.upper() if uppercase else text
        tool = Tool.create(format_text)
        ```

        Custom metadata:
        ```python
        tool = Tool.create(
            format_text,
            name="Formatter",
            description="Text formatting utility"
        )
        ```
    """
    actual_name = name or func.__name__
    actual_description = (
        description or getdoc(func) or "No description available"
    )
    signature = ToolSignature.from_callable(func, actual_name)

    return cls(
        func=func,
        name=actual_name,
        description=actual_description,
        _signature=signature,
    )

format_tool_info(indent='')

Format the tool's information in a standardized way for LLM prompts.

Creates a consistently formatted string representation of the tool that includes its name, signature, and description in a hierarchical format.

Parameters:

Name Type Description Default
indent str

Optional indentation prefix for each line. Useful for nested formatting. Defaults to no indentation.

 ''

Returns:

Type Description
str

A formatted string containing the tool's complete information.
Example

Basic formatting: 

@tool(name="Calculator")
def add(x: int, y: int) -> int:
    '''Add two numbers together.'''
    return x + y
print(add.format_tool_info())
# Output:
# - Calculator
#   Signature: add(x: int, y: int) -> int
#   Description: Add two numbers together

With custom indentation: 

print(add.format_tool_info("  "))
# Output:
#   - Calculator
#     Signature: add(x: int, y: int) -> int
#     Description: Add two numbers together

Source code in clientai/agent/tools/base.py 
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
def format_tool_info(self, indent: str = "") -> str:
    """Format the tool's information in a standardized way for LLM prompts.

    Creates a consistently formatted string representation of the tool
    that includes its name, signature, and description in a hierarchical
    format.

    Args:
        indent: Optional indentation prefix for each line.
               Useful for nested formatting. Defaults to no indentation.

    Returns:
        A formatted string containing the tool's complete information.

    Example:
        Basic formatting:
        ```python
        @tool(name="Calculator")
        def add(x: int, y: int) -> int:
            '''Add two numbers together.'''
            return x + y
        print(add.format_tool_info())
        # Output:
        # - Calculator
        #   Signature: add(x: int, y: int) -> int
        #   Description: Add two numbers together
        ```

        With custom indentation:
        ```python
        print(add.format_tool_info("  "))
        # Output:
        #   - Calculator
        #     Signature: add(x: int, y: int) -> int
        #     Description: Add two numbers together
        ```
    """
    return (
        f"{indent}- {self.name}\n"
        f"{indent}  Signature: {self.signature_str}\n"
        f"{indent}  Description: {self.description}"
    )