Skip to content

Tool

A tool is a function, it's signature, optionally properties, validator to validate input params, and explainer to describe output and potential errors

Source code in blue/tools/tool.py 
 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
class Tool:
    """A tool is a function, it's signature, optionally properties, validator to validate input params, and explainer to describe output and potential errors"""

    def __init__(
        self, name: str, function: Callable[..., Any], description: str = None, properties: Dict[str, Any] = None, validator: Callable[..., Any] = None, explainer: Callable[..., Any] = None
    ):
        """Initialize a Tool instance.

        Parameters:
            name: Name of the tool
            function: The function that the tool will execute
            description: Description of the tool. Defaults to None.
            properties: Properties of the tool. Defaults to None.
            validator: A callable to validate input parameters. Defaults to None.
            explainer: A callable to explain the output. If None, no explanation is provided.
        """
        self.name = name
        if description is None:
            description = ""
        self.description = description
        self.properties = properties
        self.function = function
        self.validator = validator
        self.explainer = explainer

        # Initialize properties, parameters, validator, and explainer
        self._initialize(properties=properties)

    def _initialize(self, properties=None):
        """Initialize the tool with properties, logger, and signature.

        Parameters:
            properties: Properties to override default properties.
        """
        self._initialize_properties()
        self._update_properties(properties=properties)

        self._initialize_logger()

        # signature
        self.properties['signature'] = {}
        self._extract_signature()

    def _initialize_properties(self):
        """Initialize default properties for tool."""
        self.properties = {}

        # Tool type
        self.properties["tool_type"] = "function"

    def get_properties(self, properties=None):
        """Get properties of the tool, with optional property overrides.

        Parameters:
            properties: Properties to override default properties.

        Returns:
            Merged properties dictionary.
        """
        if properties is None:
            properties = {}
        return json_utils.merge_json(self.properties, properties)

    def _update_properties(self, properties=None):
        if properties is None:
            return

        # override
        for p in properties:
            self.properties[p] = properties[p]

    def _initialize_logger(self):
        self.logger = log_utils.CustomLogger()
        # customize log
        self.logger.set_config_data(
            "stack",
            "%(call_stack)s",
        )

    def _extract_signature(self):
        """Extract the signature of the tool's function and store it in properties."""
        signature = tool_utils.extract_signature(self.function, mcp_format=True)
        self.properties['signature'] = signature

    def get_signature(self):
        """Get the signature of the tool's function from properties.

        Returns:
            The signature of the tool's function as a dictionary.
        """
        return self.properties['signature']

    def get_parameters(self):
        """Get the parameters of the tool's function from its signature defined in properties.

        Returns:
            The parameters of the tool's function as a dictionary.
        """
        signature = self.get_signature()
        if signature:
            if 'parameters' in signature:
                return signature['parameters']
        return None

    def get_parameter(self, parameter):
        """Get a specific parameter's details from the tool's function signature properties.

        Parameters:
            parameter: The name of the parameter to retrieve.

        Returns:
            The details of the specified parameter as a dictionary, or None if not found.
        """
        parameters = self.get_parameters()
        if parameters:
            if parameter in parameters:
                return parameters[parameter]
        return None

    def get_parameter_type(self, parameter):
        """Get the type of a specific parameter from the tool's function signature properties.

        Parameters:
            parameter: The name of the parameter to retrieve.

        Returns:
            The type of the specified parameter, or None if not found.
        """
        parameter = self.get_parameter(parameter)
        if parameter:
            if 'type' in parameter:
                return parameter['type']
        return None

    def set_parameter_description(self, parameter, description):
        """Set the description of a specific parameter in the tool's function signature properties.

        Parameters:
            parameter: The name of the parameter to set the description for.
            description: The description to set.

        Returns:
            The updated parameter details as a dictionary, or None if the parameter was not found.
        """
        parameter = self.get_parameter(parameter)
        if parameter:
            parameter['description'] = description
        return parameter

    def set_parameter_required(self, parameter, required):
        """Set whether a specific parameter is required in the tool's function signature properties.

        Parameters:
            parameter: The name of the parameter to set.
            required: Boolean indicating if the parameter is required.

        Returns:
            The updated parameter details as a dictionary, or None if the parameter was not found.
        """
        parameter = self.get_parameter(parameter)
        if parameter:
            parameter['required'] = required
        return parameter

    def set_parameter_hidden(self, parameter, hidden):
        """Set whether a specific parameter is hidden in the tool's function signature properties.

        Parameters:
            parameter: The name of the parameter to set.
            hidden: Boolean indicating if the parameter is hidden.

        Returns:

        """
        parameter = self.get_parameter(parameter)
        if parameter:
            parameter['hidden'] = hidden
        return parameter

    def is_parameter_required(self, parameter):
        """Check if a specific parameter is required in the tool's function signature properties.

        Parameters:
            parameter: The name of the parameter to check.

        Returns:

        """
        parameter = self.get_parameter(parameter)
        if parameter:
            if 'required' in parameter:
                return parameter['required']
        return None

    def is_parameter_hidden(self, parameter):
        """Check if a specific parameter is hidden in the tool's function signature properties.

        Parameters:
            parameter: The name of the parameter to check.

        Returns:
            Boolean indicating if the parameter is hidden, or None if not found.
        """
        parameter = self.get_parameter(parameter)
        if parameter:
            if 'hidden' in parameter:
                return parameter['hidden']
        return None

    def get_returns(self):
        """Get the return of the tool's function from its signature defined in properties.

        Returns:
            The return of the tool's function as a dictionary.
        """
        signature = self.get_signature()
        if signature:
            if 'returns' in signature:
                return signature['returns']
        return None

    def get_returns_type(self):
        """Get the return type of the tool's function from its signature defined in properties.

        Returns:
            The return type of the tool's function, or None if not found.
        """
        returns = self.get_returns()
        if returns:
            if 'type' in returns:
                return returns['type']
        return None

    def set_returns_description(self, description):
        """Set the description of the return value in the tool's function signature properties.

        Parameters:
            description: The description to set.

        Returns:
            The updated return details as a dictionary, or None if the return was not found.
        """
        returns = self.get_returns()
        if returns:
            returns['description'] = description
        return returns

__init__(name, function, description=None, properties=None, validator=None, explainer=None)

Initialize a Tool instance.

Parameters:

Name Type Description Default
name str

Name of the tool

 required
function Callable[..., Any]

The function that the tool will execute

 required
description str

Description of the tool. Defaults to None.

 None
properties Dict[str, Any]

Properties of the tool. Defaults to None.

 None
validator Callable[..., Any]

A callable to validate input parameters. Defaults to None.

 None
explainer Callable[..., Any]

A callable to explain the output. If None, no explanation is provided.

 None
Source code in blue/tools/tool.py 
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
def __init__(
    self, name: str, function: Callable[..., Any], description: str = None, properties: Dict[str, Any] = None, validator: Callable[..., Any] = None, explainer: Callable[..., Any] = None
):
    """Initialize a Tool instance.

    Parameters:
        name: Name of the tool
        function: The function that the tool will execute
        description: Description of the tool. Defaults to None.
        properties: Properties of the tool. Defaults to None.
        validator: A callable to validate input parameters. Defaults to None.
        explainer: A callable to explain the output. If None, no explanation is provided.
    """
    self.name = name
    if description is None:
        description = ""
    self.description = description
    self.properties = properties
    self.function = function
    self.validator = validator
    self.explainer = explainer

    # Initialize properties, parameters, validator, and explainer
    self._initialize(properties=properties)

get_parameter(parameter)

Get a specific parameter's details from the tool's function signature properties.

Parameters:

Name Type Description Default
parameter

The name of the parameter to retrieve.

 required

Returns:

Type Description

The details of the specified parameter as a dictionary, or None if not found.
Source code in blue/tools/tool.py 
118
119
120
121
122
123
124
125
126
127
128
129
130
131
def get_parameter(self, parameter):
    """Get a specific parameter's details from the tool's function signature properties.

    Parameters:
        parameter: The name of the parameter to retrieve.

    Returns:
        The details of the specified parameter as a dictionary, or None if not found.
    """
    parameters = self.get_parameters()
    if parameters:
        if parameter in parameters:
            return parameters[parameter]
    return None

get_parameter_type(parameter)

Get the type of a specific parameter from the tool's function signature properties.

Parameters:

Name Type Description Default
parameter

The name of the parameter to retrieve.

 required

Returns:

Type Description

The type of the specified parameter, or None if not found.
Source code in blue/tools/tool.py 
133
134
135
136
137
138
139
140
141
142
143
144
145
146
def get_parameter_type(self, parameter):
    """Get the type of a specific parameter from the tool's function signature properties.

    Parameters:
        parameter: The name of the parameter to retrieve.

    Returns:
        The type of the specified parameter, or None if not found.
    """
    parameter = self.get_parameter(parameter)
    if parameter:
        if 'type' in parameter:
            return parameter['type']
    return None

get_parameters()

Get the parameters of the tool's function from its signature defined in properties.

Returns:

Type Description

The parameters of the tool's function as a dictionary.
Source code in blue/tools/tool.py 
106
107
108
109
110
111
112
113
114
115
116
def get_parameters(self):
    """Get the parameters of the tool's function from its signature defined in properties.

    Returns:
        The parameters of the tool's function as a dictionary.
    """
    signature = self.get_signature()
    if signature:
        if 'parameters' in signature:
            return signature['parameters']
    return None

get_properties(properties=None)

Get properties of the tool, with optional property overrides.

Parameters:

Name Type Description Default
properties

Properties to override default properties.

 None

Returns:

Type Description

Merged properties dictionary.
Source code in blue/tools/tool.py 
64
65
66
67
68
69
70
71
72
73
74
75
def get_properties(self, properties=None):
    """Get properties of the tool, with optional property overrides.

    Parameters:
        properties: Properties to override default properties.

    Returns:
        Merged properties dictionary.
    """
    if properties is None:
        properties = {}
    return json_utils.merge_json(self.properties, properties)

get_returns()

Get the return of the tool's function from its signature defined in properties.

Returns:

Type Description

The return of the tool's function as a dictionary.
Source code in blue/tools/tool.py 
223
224
225
226
227
228
229
230
231
232
233
def get_returns(self):
    """Get the return of the tool's function from its signature defined in properties.

    Returns:
        The return of the tool's function as a dictionary.
    """
    signature = self.get_signature()
    if signature:
        if 'returns' in signature:
            return signature['returns']
    return None

get_returns_type()

Get the return type of the tool's function from its signature defined in properties.

Returns:

Type Description

The return type of the tool's function, or None if not found.
Source code in blue/tools/tool.py 
235
236
237
238
239
240
241
242
243
244
245
def get_returns_type(self):
    """Get the return type of the tool's function from its signature defined in properties.

    Returns:
        The return type of the tool's function, or None if not found.
    """
    returns = self.get_returns()
    if returns:
        if 'type' in returns:
            return returns['type']
    return None

get_signature()

Get the signature of the tool's function from properties.

Returns:

Type Description

The signature of the tool's function as a dictionary.
Source code in blue/tools/tool.py 
 98
 99
100
101
102
103
104
def get_signature(self):
    """Get the signature of the tool's function from properties.

    Returns:
        The signature of the tool's function as a dictionary.
    """
    return self.properties['signature']

is_parameter_hidden(parameter)

Check if a specific parameter is hidden in the tool's function signature properties.

Parameters:

Name Type Description Default
parameter

The name of the parameter to check.

 required

Returns:

Type Description

Boolean indicating if the parameter is hidden, or None if not found.
Source code in blue/tools/tool.py 
208
209
210
211
212
213
214
215
216
217
218
219
220
221
def is_parameter_hidden(self, parameter):
    """Check if a specific parameter is hidden in the tool's function signature properties.

    Parameters:
        parameter: The name of the parameter to check.

    Returns:
        Boolean indicating if the parameter is hidden, or None if not found.
    """
    parameter = self.get_parameter(parameter)
    if parameter:
        if 'hidden' in parameter:
            return parameter['hidden']
    return None

is_parameter_required(parameter)

Check if a specific parameter is required in the tool's function signature properties.

Parameters:

Name Type Description Default
parameter

The name of the parameter to check.

 required

Returns:

Source code in blue/tools/tool.py 
193
194
195
196
197
198
199
200
201
202
203
204
205
206
def is_parameter_required(self, parameter):
    """Check if a specific parameter is required in the tool's function signature properties.

    Parameters:
        parameter: The name of the parameter to check.

    Returns:

    """
    parameter = self.get_parameter(parameter)
    if parameter:
        if 'required' in parameter:
            return parameter['required']
    return None

set_parameter_description(parameter, description)

Set the description of a specific parameter in the tool's function signature properties.

Parameters:

Name Type Description Default
parameter

The name of the parameter to set the description for.

 required
description

The description to set.

 required

Returns:

Type Description

The updated parameter details as a dictionary, or None if the parameter was not found.
Source code in blue/tools/tool.py 
148
149
150
151
152
153
154
155
156
157
158
159
160
161
def set_parameter_description(self, parameter, description):
    """Set the description of a specific parameter in the tool's function signature properties.

    Parameters:
        parameter: The name of the parameter to set the description for.
        description: The description to set.

    Returns:
        The updated parameter details as a dictionary, or None if the parameter was not found.
    """
    parameter = self.get_parameter(parameter)
    if parameter:
        parameter['description'] = description
    return parameter

set_parameter_hidden(parameter, hidden)

Set whether a specific parameter is hidden in the tool's function signature properties.

Parameters:

Name Type Description Default
parameter

The name of the parameter to set.

 required
hidden

Boolean indicating if the parameter is hidden.

 required

Returns:

Source code in blue/tools/tool.py 
178
179
180
181
182
183
184
185
186
187
188
189
190
191
def set_parameter_hidden(self, parameter, hidden):
    """Set whether a specific parameter is hidden in the tool's function signature properties.

    Parameters:
        parameter: The name of the parameter to set.
        hidden: Boolean indicating if the parameter is hidden.

    Returns:

    """
    parameter = self.get_parameter(parameter)
    if parameter:
        parameter['hidden'] = hidden
    return parameter

set_parameter_required(parameter, required)

Set whether a specific parameter is required in the tool's function signature properties.

Parameters:

Name Type Description Default
parameter

The name of the parameter to set.

 required
required

Boolean indicating if the parameter is required.

 required

Returns:

Type Description

The updated parameter details as a dictionary, or None if the parameter was not found.
Source code in blue/tools/tool.py 
163
164
165
166
167
168
169
170
171
172
173
174
175
176
def set_parameter_required(self, parameter, required):
    """Set whether a specific parameter is required in the tool's function signature properties.

    Parameters:
        parameter: The name of the parameter to set.
        required: Boolean indicating if the parameter is required.

    Returns:
        The updated parameter details as a dictionary, or None if the parameter was not found.
    """
    parameter = self.get_parameter(parameter)
    if parameter:
        parameter['required'] = required
    return parameter

set_returns_description(description)

Set the description of the return value in the tool's function signature properties.

Parameters:

Name Type Description Default
description

The description to set.

 required

Returns:

Type Description

The updated return details as a dictionary, or None if the return was not found.
Source code in blue/tools/tool.py 
247
248
249
250
251
252
253
254
255
256
257
258
259
def set_returns_description(self, description):
    """Set the description of the return value in the tool's function signature properties.

    Parameters:
        description: The description to set.

    Returns:
        The updated return details as a dictionary, or None if the return was not found.
    """
    returns = self.get_returns()
    if returns:
        returns['description'] = description
    return returns
Last update: 2025-10-07