> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openhands.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# openhands.sdk.tool

> API reference for openhands.sdk.tool module

### class Action

Bases: `Schema`, `ABC`

Base schema for input action.

#### Properties

* `model_config`: = (configuration object)
  Configuration for the model, should be a dictionary conforming to \[ConfigDict]\[pydantic.config.ConfigDict].
* `visualize`: Text
  Return Rich Text representation of this action.
  This method can be overridden by subclasses to customize visualization.
  The base implementation displays all action fields systematically.

### class ExecutableTool

Bases: `Protocol`

Protocol for tools that are guaranteed to have a non-None executor.

This eliminates the need for runtime None checks and type narrowing
when working with tools that are known to be executable.

#### Properties

* `executor`: [ToolExecutor](#class-toolexecutor)\[Any, Any]
* `name`: str

#### Methods

#### **init**()

### class FinishTool

Bases: `ToolDefinition[FinishAction, FinishObservation]`

Tool for signaling the completion of a task or conversation.

#### Properties

* `model_config`: = (configuration object)
  Configuration for the model, should be a dictionary conforming to \[ConfigDict]\[pydantic.config.ConfigDict].

#### Methods

#### classmethod create()

Create FinishTool instance.

* Parameters:
  * `conv_state` – Optional conversation state (not used by FinishTool).
    params\* – Additional parameters (none supported).
* Returns:
  A sequence containing a single FinishTool instance.
* Raises:
  `ValueError` – If any parameters are provided.

#### name = 'finish'

### class Observation

Bases: `Schema`, `ABC`

Base schema for output observation.

#### Properties

* `ERROR_MESSAGE_HEADER`: ClassVar\[str] = '\[An error occurred during execution.]n'
* `content`: list\[TextContent | ImageContent]
* `is_error`: bool
* `model_config`: = (configuration object)
  Configuration for the model, should be a dictionary conforming to \[ConfigDict]\[pydantic.config.ConfigDict].
* `text`: str
  Extract all text content from the observation.
  * Returns:
    Concatenated text from all TextContent items in content.
* `to_llm_content`: Sequence\[TextContent | ImageContent]
  Default content formatting for converting observation to LLM readable content.
  Subclasses can override to provide richer content (e.g., images, diffs).
* `visualize`: Text
  Return Rich Text representation of this observation.
  Subclasses can override for custom visualization; by default we show the
  same text that would be sent to the LLM.

#### Methods

#### classmethod from\_text()

Utility to create an Observation from a simple text string.

* Parameters:
  * `text` – The text content to include in the observation.
  * `is_error` – Whether this observation represents an error.
    kwargs\* – Additional fields for the observation subclass.
* Returns:
  An Observation instance with the text wrapped in a TextContent.

### class ThinkTool

Bases: `ToolDefinition[ThinkAction, ThinkObservation]`

Tool for logging thoughts without making changes.

#### Properties

* `model_config`: = (configuration object)
  Configuration for the model, should be a dictionary conforming to \[ConfigDict]\[pydantic.config.ConfigDict].

#### Methods

#### classmethod create()

Create ThinkTool instance.

* Parameters:
  * `conv_state` – Optional conversation state (not used by ThinkTool).
    params\* – Additional parameters (none supported).
* Returns:
  A sequence containing a single ThinkTool instance.
* Raises:
  `ValueError` – If any parameters are provided.

#### name = 'think'

### class Tool

Bases: `BaseModel`

Defines a tool to be initialized for the agent.

This is only used in agent-sdk for type schema for server use.

#### Properties

* `name`: str
* `params`: dict\[str, Any]

#### Methods

#### model\_config = (configuration object)

Configuration for the model, should be a dictionary conforming to \[ConfigDict]\[pydantic.config.ConfigDict].

#### classmethod validate\_name()

Validate that name is not empty.

#### classmethod validate\_params()

Convert None params to empty dict.

### class ToolAnnotations

Bases: `BaseModel`

Annotations to provide hints about the tool’s behavior.

Based on Model Context Protocol (MCP) spec:
[https://github.com/modelcontextprotocol/modelcontextprotocol/blob/caf3424488b10b4a7b1f8cb634244a450a1f4400/schema/2025-06-18/schema.ts#L838](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/caf3424488b10b4a7b1f8cb634244a450a1f4400/schema/2025-06-18/schema.ts#L838)

#### Properties

* `destructiveHint`: bool
* `idempotentHint`: bool
* `model_config`: ClassVar\[ConfigDict] = (configuration object)
  Configuration for the model, should be a dictionary conforming to \[ConfigDict]\[pydantic.config.ConfigDict].
* `openWorldHint`: bool
* `readOnlyHint`: bool
* `title`: str | None

### class ToolDefinition

Bases: `DiscriminatedUnionMixin`, `ABC`, `Generic`

Base class for all tool implementations.

This class serves as a base for the discriminated union of all tool types.
All tools must inherit from this class and implement the .create() method for
proper initialization with executors and parameters.

Features:

* Normalize input/output schemas (class or dict) into both model+schema.
* Validate inputs before execute.
* Coerce outputs only if an output model is defined; else return vanilla JSON.
* Export MCP tool description.

#### Examples

Simple tool with no parameters:
: class FinishTool(ToolDefinition\[FinishAction, FinishObservation]):
: @classmethod
def create(cls, conv\_state=None,
`<br/>`

```
**
```

`<br/>`
params):
`<br/>`

> return \[cls(name=”finish”, …, executor=FinishExecutor())]

Complex tool with initialization parameters:
: class TerminalTool(ToolDefinition\[TerminalAction,
: TerminalObservation]):
@classmethod
def create(cls, conv\_state,
`<br/>`

```
**
```

`<br/>`
params):
`<br/>`

> executor = TerminalExecutor(
> : working\_dir=conv\_state.workspace.working\_dir,
> `<br/>`
>
> ```
> **
> ```
>
> `<br/>`
> params,
> `<br/>`
> )
> return \[cls(name=”terminal”, …, executor=executor)]

#### Properties

* `action_type`: type\[[Action](#class-action)]
* `annotations`: [ToolAnnotations](#class-toolannotations) | None
* `description`: str
* `executor`: Annotated\[[ToolExecutor](#class-toolexecutor) | None, SkipJsonSchema()]
* `meta`: dict\[str, Any] | None
* `model_config`: ClassVar\[ConfigDict] = (configuration object)
  Configuration for the model, should be a dictionary conforming to \[ConfigDict]\[pydantic.config.ConfigDict].
* `name`: ClassVar\[str] = ''
* `observation_type`: type\[[Observation](#class-observation)] | None
* `title`: str

#### Methods

#### action\_from\_arguments()

Create an action from parsed arguments.

This method can be overridden by subclasses to provide custom logic
for creating actions from arguments (e.g., for MCP tools).

* Parameters:
  `arguments` – The parsed arguments from the tool call.
* Returns:
  The action instance created from the arguments.

#### as\_executable()

Return this tool as an ExecutableTool, ensuring it has an executor.

This method eliminates the need for runtime None checks by guaranteeing
that the returned tool has a non-None executor.

* Returns:
  This tool instance, typed as ExecutableTool.
* Raises:
  `NotImplementedError` – If the tool has no executor.

#### abstractmethod classmethod create()

Create a sequence of Tool instances.

This method must be implemented by all subclasses to provide custom
initialization logic, typically initializing the executor with parameters
from conv\_state and other optional parameters.

* Parameters:
  args\*\* – Variable positional arguments (typically conv\_state as first arg).
  kwargs\* – Optional parameters for tool initialization.
* Returns:
  A sequence of Tool instances. Even single tools are returned as a sequence
  to provide a consistent interface and eliminate union return types.

#### classmethod resolve\_kind()

Resolve a kind string to its corresponding tool class.

* Parameters:
  `kind` – The name of the tool class to resolve
* Returns:
  The tool class corresponding to the kind
* Raises:
  `ValueError` – If the kind is unknown

#### set\_executor()

Create a new Tool instance with the given executor.

#### to\_mcp\_tool()

Convert a Tool to an MCP tool definition.

Allow overriding input/output schemas (usually by subclasses).

* Parameters:
  * `input_schema` – Optionally override the input schema.
  * `output_schema` – Optionally override the output schema.

#### to\_openai\_tool()

Convert a Tool to an OpenAI tool.

* Parameters:
  * `add_security_risk_prediction` – Whether to add a security\_risk field
    to the action schema for LLM to predict. This is useful for
    tools that may have safety risks, so the LLM can reason about
    the risk level before calling the tool.
  * `action_type` – Optionally override the action\_type to use for the schema.
    This is useful for MCPTool to use a dynamically created action type
    based on the tool’s input schema.

#### NOTE

Summary field is always added to the schema for transparency and
explainability of agent actions.

#### to\_responses\_tool()

Convert a Tool to a Responses API function tool (LiteLLM typed).

For Responses API, function tools expect top-level keys:
(JSON configuration object)

* Parameters:
  * `add_security_risk_prediction` – Whether to add a security\_risk field
  * `action_type` – Optional override for the action type

#### NOTE

Summary field is always added to the schema for transparency and
explainability of agent actions.

### class ToolExecutor

Bases: `ABC`, `Generic`

Executor function type for a Tool.

#### Methods

#### close()

Close the executor and clean up resources.

Default implementation does nothing. Subclasses should override
this method to perform cleanup (e.g., closing connections,
terminating processes, etc.).