dspy.Tool

dspy.Tool(func: Callable, name: Optional[str] = None, desc: Optional[str] = None, args: Optional[dict[str, Any]] = None, arg_types: Optional[dict[str, Any]] = None, arg_desc: Optional[dict[str, str]] = None)

Tool class.

This class is used to simplify the creation of tools for tool calling (function calling) in LLMs. Only supports functions for now.

Initialize the Tool class.

Users can choose to specify the name, desc, args, and arg_types, or let the dspy.Tool automatically infer the values from the function. For values that are specified by the user, automatic inference will not be performed on them.

Parameters:

Name	Type	Description	Default
func	Callable	The actual function that is being wrapped by the tool.	required
name	Optional[str]	The name of the tool. Defaults to None.	None
desc	Optional[str]	The description of the tool. Defaults to None.	None
args	Optional[dict[str, Any]]	The args and their schema of the tool, represented as a dictionary from arg name to arg's json schema. Defaults to None.	None
arg_types	Optional[dict[str, Any]]	The argument types of the tool, represented as a dictionary from arg name to the type of the argument. Defaults to None.	None
arg_desc	Optional[dict[str, str]]	Descriptions for each arg, represented as a dictionary from arg name to description string. Defaults to None.	None

Example:

def foo(x: int, y: str = "hello"):
    return str(x) + y

tool = Tool(foo)
print(tool.args)
# Expected output: {'x': {'type': 'integer'}, 'y': {'type': 'string', 'default': 'hello'}}

Source code in dspy/primitives/tool.py

def __init__(
    self,
    func: Callable,
    name: Optional[str] = None,
    desc: Optional[str] = None,
    args: Optional[dict[str, Any]] = None,
    arg_types: Optional[dict[str, Any]] = None,
    arg_desc: Optional[dict[str, str]] = None,
):
    """Initialize the Tool class.

    Users can choose to specify the `name`, `desc`, `args`, and `arg_types`, or let the `dspy.Tool`
    automatically infer the values from the function. For values that are specified by the user, automatic inference
    will not be performed on them.

    Args:
        func (Callable): The actual function that is being wrapped by the tool.
        name (Optional[str], optional): The name of the tool. Defaults to None.
        desc (Optional[str], optional): The description of the tool. Defaults to None.
        args (Optional[dict[str, Any]], optional): The args and their schema of the tool, represented as a
            dictionary from arg name to arg's json schema. Defaults to None.
        arg_types (Optional[dict[str, Any]], optional): The argument types of the tool, represented as a dictionary
            from arg name to the type of the argument. Defaults to None.
        arg_desc (Optional[dict[str, str]], optional): Descriptions for each arg, represented as a
            dictionary from arg name to description string. Defaults to None.

    Example:

    ```python
    def foo(x: int, y: str = "hello"):
        return str(x) + y

    tool = Tool(foo)
    print(tool.args)
    # Expected output: {'x': {'type': 'integer'}, 'y': {'type': 'string', 'default': 'hello'}}
    ```
    """
    self.func = func
    self.name = name
    self.desc = desc
    self.args = args
    self.arg_types = arg_types
    self.arg_desc = arg_desc
    self.has_kwargs = False

    self._parse_function(func, arg_desc)

Functions

__call__(**kwargs)

Source code in dspy/primitives/tool.py

@with_callbacks
def __call__(self, **kwargs):
    parsed_kwargs = self._validate_and_parse_args(**kwargs)
    result = self.func(**parsed_kwargs)
    if asyncio.iscoroutine(result):
        raise ValueError("You are calling `__call__` on an async tool, please use `acall` instead.")
    return result

acall(**kwargs) async

Source code in dspy/primitives/tool.py

@with_callbacks
async def acall(self, **kwargs):
    parsed_kwargs = self._validate_and_parse_args(**kwargs)
    result = self.func(**parsed_kwargs)
    if asyncio.iscoroutine(result):
        return await result
    else:
        # We should allow calling a sync tool in the async path.
        return result

from_mcp_tool(session: mcp.client.session.ClientSession, tool: mcp.types.Tool) -> Tool classmethod

Build a DSPy tool from an MCP tool and a ClientSession.

Parameters:

Name	Type	Description	Default
session	ClientSession	The MCP session to use.	required
tool	Tool	The MCP tool to convert.	required

Returns:

Type	Description
Tool	A Tool object.

Source code in dspy/primitives/tool.py

@classmethod
def from_mcp_tool(cls, session: "mcp.client.session.ClientSession", tool: "mcp.types.Tool") -> "Tool":
    """
    Build a DSPy tool from an MCP tool and a ClientSession.

    Args:
        session: The MCP session to use.
        tool: The MCP tool to convert.

    Returns:
        A Tool object.
    """
    from dspy.utils.mcp import convert_mcp_tool

    return convert_mcp_tool(session, tool)