# tool

## ``autogen.tools.tool``

### ``Tool``

```
Tool(*, name=None, description=None, func_or_tool, parameters_json_schema=None)
```

A class representing a Tool that can be used by an agent for various tasks.

This class encapsulates a tool with a name, description, and an executable function. The tool can be registered with a ConversableAgent for use either with an LLM or for direct execution.

| ATTRIBUTE                     | DESCRIPTION                                                                                               |
|-------------------------------|-----------------------------------------------------------------------------------------------------------|
| `name`                        | The name of the tool.<br>**TYPE:**`str`                                                                  |
| `description`                 | The description of the tool.<br>**TYPE:**`str`                                                           |
| `func_or_tool`                | The function or Tool instance to create a Tool from.<br>**TYPE:**`Union[Tool, Callable[..., Any]]`      |
| `parameters_json_schema`      | A schema describing the parameters that the function accepts. If None, the schema will be generated from the function signature.<br>**TYPE:**`Optional[dict[str, Any]]`|

Create a new Tool object.

| PARAMETER                     | DESCRIPTION                                                                                               |
|-------------------------------|-----------------------------------------------------------------------------------------------------------|
| `name`                        | The name of the tool.<br>**TYPE:**`str`**DEFAULT:**`None`                                              |
| `description`                 | The description of the tool.<br>**TYPE:**`str`**DEFAULT:**`None`                                         |
| `func_or_tool`                | The function or Tool instance to create a Tool from.<br>**TYPE:**`Union[Tool, Callable[..., Any]]`      |
| `parameters_json_schema`      | A schema describing the parameters that the function accepts. If None, the schema will be generated from the function signature.<br>**TYPE:**`Optional[dict[str, Any]]`**DEFAULT:**`None`|

Source code in `autogen/tools/tool.py`

```
def __init__(self, *, name: str | None = None, description: str | None = None, func_or_tool: Union["Tool", Callable[..., Any]], parameters_json_schema: dict[str, Any] | None = None) -> None:
    """Create a new Tool object.
    Args:
        name (str): The name of the tool.
        description (str): The description of the tool.
        func_or_tool (Union[Tool, Callable[..., Any]]): The function or Tool instance to create a Tool from.
        parameters_json_schema (Optional[dict[str, Any]]): A schema describing the parameters that the function accepts. If None, the schema will be generated from the function signature.
    """
    if isinstance(func_or_tool, Tool):
        self._name: str = name or func_or_tool.name
        self._description: str = description or func_or_tool.description
        self._func: Callable[..., Any] = func_or_tool.func
        self._chat_context_param_names: list[str] = func_or_tool._chat_context_param_names
    elif inspect.isfunction(func_or_tool) or inspect.ismethod(func_or_tool):
        self._chat_context_param_names = get_context_params(func_or_tool, subclass=ChatContext)
        self._func = inject_params(func_or_tool)
        self._name = name or func_or_tool.__name__
        self._description = description or func_or_tool.__doc__ or ""
    else:
        raise ValueError(
            f"Parameter 'func_or_tool' must be a function, method or a Tool instance, it is '{type(func_or_tool)}' instead."
        )
    self._func_schema = (
        {
            "type": "function",
            "function": {
                "name": name,
                "description": description,
                "parameters": parameters_json_schema,
            },
        }
        if parameters_json_schema
        else None
    )
```

#### ``name`property``

```
name
```

#### ``description`property``

```
description
```

#### ``func`property``

```
func
```

#### ``tool_schema`property``

```
tool_schema
```

Get the schema for the tool.

This is the preferred way of handling function calls with OpenAI and compatible frameworks.

#### ``function_schema`property``

```
function_schema
```

Get the schema for the function.

This is the old way of handling function calls with OpenAI and compatible frameworks. It is provided for backward compatibility.

#### ``realtime_tool_schema`property``

```
realtime_tool_schema
```

Get the schema for the tool.

This is the preferred way of handling function calls with OpenAI and compatible frameworks.

#### ``register_for_llm``

```
register_for_llm(agent)
```

Registers the tool for use with a ConversableAgent's language model (LLM).

This method registers the tool so that it can be invoked by the agent during interactions with the language model.

| PARAMETER                     | DESCRIPTION                                                                                               |
|-------------------------------|-----------------------------------------------------------------------------------------------------------|
| `agent`                       | The agent to which the tool will be registered.<br>**TYPE:**`ConversableAgent`                           |

Source code in `autogen/tools/tool.py`

```
def register_for_llm(self, agent: "ConversableAgent") -> None:
    """Registers the tool for use with a ConversableAgent's language model (LLM).
    This method registers the tool so that it can be invoked by the agent during
    interactions with the language model.
    Args:
        agent (ConversableAgent): The agent to which the tool will be registered.
    """
    if self._func_schema:
        agent.update_tool_signature(self._func_schema, is_remove=False)
    else:
        agent.register_for_llm()(self)
```

#### ``register_for_execution``

```
register_for_execution(agent)
```

Registers the tool for direct execution by a ConversableAgent.

This method registers the tool so that it can be executed by the agent, typically outside of the context of an LLM interaction.

Source code in `autogen/tools/tool.py`

```
def register_for_execution(self, agent: "ConversableAgent") -> None:
    """Registers the tool for direct execution by a ConversableAgent.
    This method registers the tool so that it can be executed by the agent,
    typically outside of the context of an LLM interaction.
    Args:
        agent (ConversableAgent): The agent to which the tool will be registered.
    """
    agent.register_for_execution()(self)
```

#### ``register_tool``

```
register_tool(agent)
```

Register a tool to be both proposed and executed by an agent.

Equivalent to calling both `register_for_llm` and `register_for_execution` with the same agent.

Note: This will not make the agent recommend and execute the call in the one step. If the agent recommends the tool, it will need to be the next agent to speak in order to execute the tool.

Source code in `autogen/tools/tool.py`

```
def register_tool(self, agent: "ConversableAgent") -> None:
    """Register a tool to be both proposed and executed by an agent.
    Equivalent to calling both `register_for_llm` and `register_for_execution` with the same agent.
    Note: This will not make the agent recommend and execute the call in the one step. If the agent
    recommends the tool, it will need to be the next agent to speak in order to execute the tool.
    Args:
        agent (ConversableAgent): The agent to which the tool will be registered.
    """
    self.register_for_llm(agent)
    self.register_for_execution(agent)
```

### ``tool``

```
tool(name=None, description=None)
```

Decorator to create a Tool from a function.

| PARAMETER                     | DESCRIPTION                                                                                               |
|-------------------------------|-----------------------------------------------------------------------------------------------------------|
| `name`                        | The name of the tool.<br>**TYPE:**`str`**DEFAULT:**`None`                                              |
| `description`                 | The description of the tool.<br>**TYPE:**`str`**DEFAULT:**`None`                                         |

| RETURNS                       | DESCRIPTION                                                                                               |
|-------------------------------|-----------------------------------------------------------------------------------------------------------|
| `Callable[[Callable[..., Any]], Tool]` | Callable":[[Callable[..., Any]], Tool]: A decorator that creates a Tool from a function.               |

Source code in `autogen/tools/tool.py`

```
@export_module("autogen.tools")
def tool(name: str | None = None, description: str | None = None) -> Callable[[Callable[..., Any]], Tool]:
    """Decorator to create a Tool from a function.
    Args:
        name (str): The name of the tool.
        description (str): The description of the tool.
    Returns:
        Callable[[Callable[..., Any]], Tool]: A decorator that creates a Tool from a function.
    """
    def decorator(func: Callable[..., Any]) -> Tool:
        return Tool(name=name, description=description, func_or_tool=func)
    return decorator
```