Skip to main content
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
ParameterTypeDefaultDescription
namestr—Unique tool name within a toolkit.
input_schemadict—JSON Schema for the tool arguments. Enforced at call time.
titleOptional[str]nameHuman-readable display name.
descriptionOptional[str]""Short description of the tool.
rulesOptional[list[str]]NoneBehavioral guidance for LLMs.
thumbnail_urlOptional[str]NoneIcon or thumbnail shown in UIs.
defsOptional[dict[str, dict]]NoneReusable JSON Schema definitions merged into the schema via $defs.
Method
Python
async def execute(self, context: ToolContext, **kwargs):
    ...

​
Tool return types

Tools commonly return subclasses of Content declared in meshagent.api.messaging.
Content typeWhen to use it
JsonContentStructured JSON output, such as API payloads or summarized data.
TextContentPlain-text answers or status messages.
FileContentBinary content such as generated documents, images, or archives.
LinkContentA URL pointing to an external resource.
EmptyContentNo payload, usually for successful operations that do not need a response body.

​
ToolContext

ToolContext carries the runtime information a tool needs.
PropertyDescription
callerThe participant who called the tool.
on_behalf_ofThe participant a calling agent is acting for, if any.
caller_contextOptional caller-specific context data. Useful for chat context, handoffs, or custom workflow state.
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
ParameterTypeDefaultDescription
namestr—Toolkit identifier used for discovery and invocation.
toolslist[BaseTool]—The tools this toolkit exposes.
ruleslist[str]list[str]Optional global guidance that applies to the toolkit.
titleOptional[str]nameHuman-readable toolkit name.
descriptionOptional[str]""Description used for discovery and display in MeshAgent Studio.
thumbnail_urlOptional[str]NoneIcon or thumbnail for the toolkit.
validation_modeValidationMode"full"Validation policy used when the toolkit is invoked.
publicboolTrueWhether 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, ServiceHost, connect_remote_toolkit(...), and MeshAgent’s room-hosting helpers 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
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 to decide which services or users can register, inspect, and call tools.