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

# How Tools and Toolkits Work

MeshAgent tools are room-connected capabilities that humans and agents can discover, call, and share. Use this page to understand the core model: what a tool is, what a toolkit is, how shared tool registration works, and how MeshAgent handles always-on versus per-turn tool access.

## Mental model

* `Tool` = one discrete action an agent or human participant can take.
* `ToolContext` = the execution context available when a tool runs.
* `LocalRoomTool` = a mixin for tools that need a bound `RoomClient`; room-aware tools use `self.room`.
* `Toolkit` = a named bundle of related tools plus optional rules and descriptions.
* Hosted toolkit = a `Toolkit` that a service or room participant registers with a room so other participants can discover and call it.

## Tools

### `Tool`

A `Tool` defines one action that an agent or person can perform. The tool declares what it expects in `input_schema` and what work to perform in `execute()`.

**Constructor parameters**

| Parameter      | Type                        | Default | Description                                                          |
| -------------- | --------------------------- | ------: | -------------------------------------------------------------------- |
| `name`         | `str`                       |       — | Unique tool name within a toolkit.                                   |
| `input_schema` | `dict`                      |       — | JSON Schema for the tool arguments. Enforced at call time.           |
| `title`        | `Optional[str]`             |  `name` | Human-readable display name.                                         |
| `description`  | `Optional[str]`             |    `""` | Short description of the tool.                                       |
| `rules`        | `Optional[list[str]]`       |  `None` | Behavioral guidance for LLMs.                                        |
| `defs`         | `Optional[dict[str, dict]]` |  `None` | Reusable JSON Schema definitions merged into the schema via `$defs`. |

**Method**

```python Python theme={null}
async def execute(self, context: ToolContext, **kwargs):
    ...
```

### Tool return types

Tools commonly return subclasses of `Content` declared in `meshagent.api.messaging`.

| Content type   | When to use it                                                                  |
| -------------- | ------------------------------------------------------------------------------- |
| `JsonContent`  | Structured JSON output, such as API payloads or summarized data.                |
| `TextContent`  | Plain-text answers or status messages.                                          |
| `FileContent`  | Binary content such as generated documents, images, or archives.                |
| `LinkContent`  | A URL pointing to an external resource.                                         |
| `EmptyContent` | No payload, usually for successful operations that do not need a response body. |

### `ToolContext`

`ToolContext` carries the runtime information a tool needs. If a tool needs room access, use `RoomToolContext` or a room-bound toolkit.

| Property       | Description                                            |
| -------------- | ------------------------------------------------------ |
| `caller`       | The participant who called the tool.                   |
| `on_behalf_of` | The participant a calling agent is acting for, if any. |

If a tool needs room access, inherit `LocalRoomTool` and use `self.room` inside `execute(...)`. Toolkits and hosting helpers bind the active `RoomClient` before the tool runs.

## Toolkits

### Toolkit vs hosted toolkit

A `Toolkit` is the definition of a group of tools plus the metadata and validation rules that go with them.

Use a plain `Toolkit` when the tools only need to exist inside one process, such as a single agent runtime.

Use a hosted toolkit when the tools should be registered in a room so other participants can discover and call them.

### `Toolkit`

A `Toolkit` bundles related tools under a single name so callers can discover, invoke, and permission them together.

**Constructor parameters**

| Parameter         | Type             |     Default | Description                                                                      |
| ----------------- | ---------------- | ----------: | -------------------------------------------------------------------------------- |
| `name`            | `str`            |           — | Toolkit identifier used for discovery and invocation.                            |
| `tools`           | `list[BaseTool]` |           — | The tools this toolkit exposes.                                                  |
| `rules`           | `list[str]`      | `list[str]` | Optional global guidance that applies to the toolkit.                            |
| `title`           | `Optional[str]`  |      `name` | Human-readable toolkit name.                                                     |
| `description`     | `Optional[str]`  |        `""` | Description used for discovery and display in MeshAgent Studio.                  |
| `validation_mode` | `ValidationMode` |    `"full"` | Validation policy used when the toolkit is invoked.                              |
| `public`          | `bool`           |      `True` | Whether the toolkit should be publicly discoverable when it is hosted in a room. |

**Methods**

* `get_tool(name)`: returns the named tool or raises a `RoomException` if it is not present.
* `execute(context, name, input)`: validates the input content, invokes the tool, and returns a response.

> Toolkits emit OpenTelemetry spans out of the box, so MeshAgent can track who called a tool, how long it took, and what room it ran in.

### Hosted toolkit lifecycle

Hosted toolkits are plain `Toolkit` instances across the SDKs.

* In Python, expose local toolkits from a room-connected `SingleRoomAgent` by overriding `get_exposed_toolkits()` and running the agent with `SingleRoomAgent.run()`. If your application already owns a `RoomClient`, use MeshAgent's lower-level room-hosting helpers to register the toolkit and keep it available for room calls.
* In TypeScript and Dart, `startHostedToolkit(...)` registers the toolkit and returns a `HostedToolkit` handle. Higher-level helpers like React's `useClientToolkits(...)` and Flutter's `ClientToolkits` widget use that same hosting API internally.

`Toolkit` itself does not expose `start()` / `stop()`. Those lifecycle operations live on the room-hosting helper or the returned hosted-toolkit handle.

**Hosted handle methods**

* `stop()`:
  * stops listening for room tool calls,
  * unregisters the toolkit from the room.

## Toolkit patterns

MeshAgent supports two complementary ways to make tools available during an agent turn.

### Static toolkits

Static toolkits stay attached to the agent for its full lifetime.

* Construct the toolkit up front and pass it in the agent's `toolkits` list.
* The toolkit is instantiated once and participates in every LLM turn.
* Use this when the agent should always have a capability available.

On the CLI, built-in capabilities now use one canonical flag per capability, such as `--web-search`, `--web-fetch`, `--storage`, `--shell`, `--advanced-shell`, `--document-authoring`, and `--discovery`. `--require-toolkit` remains the flag for attaching an external toolkit by name.

If you need a capability available for every turn, add the corresponding toolkit directly in code or start the agent with the relevant CLI flag. If the capability should be discoverable by other participants, host the toolkit in a room and let callers invoke it over MeshAgent's room-tool protocol.

## Tool access and availability

### `RequiredToolkit`

Agents can declare toolkit dependencies explicitly:

```python Python theme={null}
from meshagent.api import RequiredToolkit

requires = [
    RequiredToolkit(name="my-toolkit-name", tools=[my_first_tool(), my_second_tool()])
]
```

When the agent connects, the room server verifies the required toolkit is available. If not, the agent gets an error instead of starting with missing capabilities.

### Tool access and permissions

Tool access is controlled by the participant token's `ApiScope.agents` grant:

* `register_public_toolkit` / `register_private_toolkit`: allow registering public or private toolkits.
* `use_tools`: required to list or inspect toolkits.
* `call`: required to invoke tools.

Public toolkits are visible to any participant with `use_tools`. Private toolkits are only listed for the participant that registered them. Use [API scope grants](../../rest_api/api_scopes) to decide which services or users can register, inspect, and call tools.

## Related guides

* [Built-in MeshAgent Toolkits](./built_in_toolkits)
* [Create Custom Tools](./quickstart)
* [Dynamic UI Tools](./dynamic_ui_tools)
* [MCP Servers](./mcp_servers)
* [Supabase MCP Guide](./supabase_mcp)