> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo/guardrails/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemo/guardrails/_mcp/server.

# nemoguardrails.guardrails.tool_schema

Internal tool types for IORails tool-calling rails.

These engine-internal dataclasses are the normalized, provider-neutral shape the
tool rails validate against. They are NOT part of the public API and NOT carried
on `GenerationOptions`: the request surface stays the provider-native
`llm_params` block, which `ModelEngine` parses into a `Toolset` (and incoming
tool results into `ToolResult` objects) per inference call.

`Tool` is a declared tool definition (what the caller offers); `ToolCall` (in
`nemoguardrails.types`) is an invocation the model emitted. Field names are
provider-neutral so the per-provider adapters all produce the same shape:
`arguments_schema` is OpenAI `parameters` / Anthropic `input_schema` / Gemini
`parameters`; `ToolResult.call_id` is the OpenAI `tool_call_id` / Responses
`call_id` / Anthropic `tool_use_id` / Gemini function-call `id`. OpenAI Chat
Completions is the engine implemented today.

## Module Contents

### Classes

| Name                                                                  | Description                                                                    |
| --------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| [`Tool`](#nemoguardrails-guardrails-tool_schema-Tool)                 | A declared tool definition the caller offered to the model.                    |
| [`ToolExchange`](#nemoguardrails-guardrails-tool_schema-ToolExchange) | One assistant turn's tool calls paired with the tool results that answer them. |
| [`ToolResult`](#nemoguardrails-guardrails-tool_schema-ToolResult)     | A normalized tool result extracted from incoming messages by the engine.       |
| [`Toolset`](#nemoguardrails-guardrails-tool_schema-Toolset)           | The set of tools declared on a request, indexed by tool key.                   |

### Functions

| Name                                                                                                  | Description                                                                            |
| ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| [`_no_arguments_reason`](#nemoguardrails-guardrails-tool_schema-_no_arguments_reason)                 | Block reason for a tool that accepts no arguments, or `None` when the call is allowed. |
| [`_schema_accepts_no_arguments`](#nemoguardrails-guardrails-tool_schema-_schema_accepts_no_arguments) | Whether an argument schema declares no way to supply arguments.                        |
| [`validate_arguments`](#nemoguardrails-guardrails-tool_schema-validate_arguments)                     | Validate model-supplied tool-call arguments against the tool's schema.                 |

### API

```python
class nemoguardrails.guardrails.tool_schema.Tool(
    name: str | None = None,
    type: str = 'function',
    description: str | None = None,
    arguments_schema: dict | None = None,
    strict: bool | None = None
)
```

Dataclass

A declared tool definition the caller offered to the model.

`name` is set for function tools and `None` for hosted/server tools that
are identified only by `type` (e.g. web\_search). `arguments_schema` is the
JSON Schema for the call arguments, or `None` when none is declared. A hosted
tool with no schema is allowlist-only (the provider owns the call shape); a
function tool that declares no parameters accepts no arguments, so a call that
supplies any is rejected.

**`arguments_schema`** `dict | None = None`

---

**`description`** `str | None = None`

---

**`key`** `str`

Allowlist / lookup identifier: the function `name`, else the `type`.

---

**`name`** `str | None = None`

---

**`strict`** `bool | None = None`

---

**`type`** `str = 'function'`

---

```python
class nemoguardrails.guardrails.tool_schema.ToolExchange()
```

**Bases:** `NamedTuple`

One assistant turn's tool calls paired with the tool results that answer them.

**`calls`** `list[ToolCall]`

---

**`results`** `list[ToolResult]`

---

```python
class nemoguardrails.guardrails.tool_schema.ToolResult(
    call_id: str | None = None,
    name: str | None = None,
    content: str | list[dict] | None = None,
    is_error: bool = False
)
```

Dataclass

A normalized tool result extracted from incoming messages by the engine.

The ToolResultRail consumes a list of these; the per-provider extraction (e.g.
OpenAI `role:"tool"` messages) lives in the engine adapter, so the rail never
sees provider wire shapes. `content` is a string or a list of content blocks
(the latter covers multimodal results). `is_error` flags a failed result
where the provider exposes one (e.g. Anthropic `is_error` / Bedrock
`status:"error"`).

**`call_id`** `str | None = None`

---

**`content`** `str | list[dict] | None = None`

---

**`is_error`** `bool = False`

---

**`name`** `str | None = None`

---

```python
class nemoguardrails.guardrails.tool_schema.Toolset(
    tools: collections.abc.Iterable[nemoguardrails.guardrails.tool_schema.Tool] | None = None
)
```

The set of tools declared on a request, indexed by tool key.

Backed by a single `key -> Tool` mapping built at construction, so there is
no separate list that can drift out of sync with the index. Look tools up with
:meth:`get` (`toolset.get(name)`); iterate or count via the read-only
:attr:`tools`.

**`__slots__`** `= ('_by_key',)`

---

**`_by_key`** `dict[str, Tool] = {}`

---

**`tools`** `tuple[Tool, ...]`

The declared tools in declaration order (read-only view of the index).

---

```python
nemoguardrails.guardrails.tool_schema.Toolset.get(
    key: str
) -> nemoguardrails.guardrails.tool_schema.Tool | None
```

Return the declared tool registered under *key* (function name or hosted-tool type), or None.

```python
nemoguardrails.guardrails.tool_schema._no_arguments_reason(
    tool: nemoguardrails.guardrails.tool_schema.Tool,
    arguments: dict
) -> str | None
```

Block reason for a tool that accepts no arguments, or `None` when the call is allowed.

Hosted/server tools (no `name`) are allowlist-only -- the provider owns the call
shape -- so arguments are accepted here. A function tool that declares no parameters
must be called with no arguments, so any supplied argument is rejected.

```python
nemoguardrails.guardrails.tool_schema._schema_accepts_no_arguments(
    schema: dict
) -> bool
```

Whether an argument schema declares no way to supply arguments.

True for an empty schema (`{}`) or an object schema that names no `properties`
and opens no other input channel (`additionalProperties`, `patternProperties`,
or a composition/reference keyword). Such a schema describes a tool that takes no
arguments; jsonschema treats it as permissive, so callers enforce emptiness directly.

```python
nemoguardrails.guardrails.tool_schema.validate_arguments(
    tool: nemoguardrails.guardrails.tool_schema.Tool,
    arguments: dict
) -> str | None
```

Validate model-supplied tool-call arguments against the tool's schema.

Returns `None` when the arguments are valid. Returns a human-readable reason when
the arguments violate the schema, when the declared schema itself is not valid JSON
Schema (e.g. a non-JSON-Schema dialect reaching this validator before its engine
adapter normalizes it), or when a function tool that declares no parameters is called
with arguments.