Module tools 

The embedder-supplied seam for @tools: a program calls one of the application’s own tools, and the harness that declared it answers.

Every @tools.<tool>(...) call lowers (in codegen) to one host import, submilli:tools.call(tool, argsJson) -> unknown, exactly as @mcp/<server> calls lower to submilli:mcp.call. The host fn runs the tools.call capability check before anything reaches the harness, then awaits the embedder’s ToolProvider. Normal runtime casts validate declared return types.

Waiting is not running. The provider may take as long as the harness needs, for example while a person approves the call. The time spent waiting is added to StoreData::clock_paused, which an embedder’s execution timeout subtracts, so a program’s time limit counts its own work only. The provider bounds the wait itself. Dropping the future returned by ToolProvider::call is how the engine cancels it.

Enums

ToolCallError

Why the harness did not return a value. Each maps to a catchable guest error, except ToolCallError::Cancelled, which ends the run.

Constants

TOOLS_CAPABILITY

The capability every call is checked against, with the tool in its tool field.

TOOLS_MODULE_NAME

The internal host module every @tools call dispatches through.

TOOLS_PACKAGE

The source-level name of the virtual package.

Traits

ToolProvider

The embedder-provided answerer for @tools calls. The value is a bounded JSON tree (McpResponse::take admits it), so guest conversion stays bounded whoever produced it.

Functions

install_tools_async

Install the async submilli:tools.call host fn. Reads (tool, argsJson), runs the capability check, awaits StoreData::tool_provider with the clock paused, and builds guest values directly from the returned tree.

tools_call_package_declaration

Codegen-facing definitions for the internal submilli:tools.call host fn: call(tool: string, args: string): unknown.