Tool Calling

Commons owns the tool-calling run loop. JavaScript owns a registry of executor callbacks and nothing else: the prompt formatting, parsing, iteration, and follow-up generation all happen in C++ through one native call.

The surface

Function	Signature
`registerTool`	`(definition: ToolDefinition, executor: ToolExecutor) => Promise<void>`
`unregisterTool`	`(toolName: string) => Promise<void>`
`getRegisteredTools`	`() => Promise<ToolDefinition[]>`
`clearTools`	`() => Promise<void>`
`executeTool`	`(toolCall: ToolCall) => Promise<ToolResult>`
`generateWithTools`	`(prompt, options?: Partial<ToolCallingOptions>, extra?: GenerateWithToolsOptions) => Promise<ToolCallingResult>`

Every one of these is async. There is no parseToolCall on the React Native surface. Types come from @runanywhere/proto-ts/tool_calling, not from @runanywhere/core. The one exception is ToolExecutor, which is a TypeScript-level type exported by @runanywhere/core.

Defining a tool

ToolDefinition and ToolParameter are proto messages. Build them with fromPartial and use the ToolParameterType enum for the parameter type.

import { RunAnywhere } from '@runanywhere/core'
import {
  ToolDefinition,
  ToolParameterType,
  type ToolValue,
} from '@runanywhere/proto-ts/tool_calling'

await RunAnywhere.registerTool(
  ToolDefinition.fromPartial({
    name: 'get_weather',
    description: 'Gets the current weather for a city or location',
    parameters: [
      {
        name: 'location',
        type: ToolParameterType.TOOL_PARAMETER_TYPE_STRING,
        description: 'City name, for example "Tokyo" or "London"',
        required: true,
        enumValues: [],
      },
    ],
  }),
  async (args: Record<string, ToolValue>): Promise<Record<string, ToolValue>> => {
    const location = args.location?.stringValue ?? 'San Francisco'
    const response = await fetch(`https://wttr.in/${encodeURIComponent(location)}?format=j1`)
    const data = await response.json()
    const current = data.current_condition?.[0]
    return {
      location: { stringValue: location },
      temperature_c: { stringValue: current?.temp_C ?? 'N/A' },
      condition: { stringValue: current?.weatherDesc?.[0]?.value ?? 'Unknown' },
    }
  }
)

Call await RunAnywhere.clearTools() before re-registering, for example when a component remounts, so you do not stack duplicates.

ToolValue

Executors receive and return Record<string, ToolValue>, not plain JSON. ToolValue is a typed oneof, so read the branch you expect and write the branch you mean.

Branch	Type
`stringValue`	`string`
`numberValue`	`number`
`boolValue`	`boolean`
`nullValue`	`boolean`
`arrayValue`	`ToolValueArray`
`objectValue`	`ToolValueObject`

The SDK converts between this tree and the plain JSON the model emits, so args.count?.numberValue is how you read a numeric argument.

ToolParameter

Field	Type	Notes
`name`	`string`
`type`	`ToolParameterType`	`STRING`, `NUMBER`, `BOOLEAN`, `OBJECT`, `ARRAY`
`description`	`string`	Read by the model; be specific
`required`	`boolean`
`enumValues`	`string[]`	Empty means unconstrained
`jsonSchema`	`string \| undefined`
`defaultValue`	`ToolValue \| undefined`

The field is enumValues, not enum, and defaultValue is a ToolValue, not a string.

Generating

const result = await RunAnywhere.generateWithTools('What is the weather in San Francisco?')

console.log(result.text)
console.log(result.toolCalls)
console.log(result.toolResults)
console.log(result.iterationsUsed)

With no tools option the loop uses everything currently registered.

ToolCallingOptions

Passed as a Partial<ToolCallingOptions> second argument.

Field	Type	Default	Notes
`tools`	`ToolDefinition[]`	registered tools	Overrides the registry for this call
`autoExecute`	`boolean`	`true`	False hands calls back instead of running them
`maxToolCalls`	`number`	`5`
`temperature`	`number`	`0.8`	Falls back to `llmOptions.temperature`
`maxTokens`	`number`	`100`	Falls back to `llmOptions.maxTokens`
`systemPrompt`	`string`	`''`
`replaceSystemPrompt`	`boolean`	`false`	True suppresses the injected tool instructions
`keepToolsAvailable`	`boolean`	`false`	Keeps definitions live across sequential calls
`format`	`ToolCallFormatName`	`TOOL_CALL_FORMAT_NAME_JSON`	Also `_LFM2`
`toolChoice`	`ToolChoiceMode`	unset	`AUTO`, `NONE`, `REQUIRED`, `SPECIFIC`
`forcedToolName`	`string`	unset	Used with `TOOL_CHOICE_MODE_SPECIFIC`
`requireJsonArguments`	`boolean`	`false`
`disableThinking`	`boolean`	`false`

The sampling defaults are the same ones generate() uses. There is no separate 0.7 or 256.

GenerateWithToolsOptions

The optional third argument.

Field	Type	Notes
`signal`	`AbortSignal`	`controller.abort()` cancels the native run loop
`llmOptions`	`Partial<LLMGenerationOptions>`	`maxTokens`, `temperature`, `topP`, `systemPrompt`, `disableThinking`
`validateCalls`	`boolean`	Omit to let commons apply its default of true
`history`	`string[]`	Prior turns, flat alternating user/assistant, excluding this one

topP comes from llmOptions only and defaults to 1.0.

const controller = new AbortController()

const result = await RunAnywhere.generateWithTools(
  prompt,
  { maxToolCalls: 3, autoExecute: true },
  { signal: controller.signal, llmOptions: { maxTokens: 512, temperature: 0.7 } }
)

ToolCallingResult

Field	Type	Meaning
`text`	`string`	Final assistant response
`toolCalls`	`ToolCall[]`	Calls the model made
`toolResults`	`ToolResult[]`	Populated when `autoExecute` was true
`isComplete`	`boolean`	False when waiting on more tool results
`iterationsUsed`	`number`	Generation turns including the final synthesis
`conversationId`	`string \| undefined`
`rawText`	`string`	Pre-parse model output
`thinkingContent`	`string \| undefined`
`errorMessage`	`string \| undefined`
`errorCode`	`number`

ToolCall carries id, name, argumentsJson, type, createdAtMs, and rawText. ToolResult carries toolCallId, name, resultJson, error, success, startedAtMs, and completedAtMs.

Manual execution

Set autoExecute: false to inspect calls before running them, then execute the ones you approve.

const result = await RunAnywhere.generateWithTools(prompt, { autoExecute: false })

for (const call of result.toolCalls) {
  if (!isAllowed(call.name)) continue
  const toolResult = await RunAnywhere.executeTool(call)
  console.log(toolResult.success, toolResult.resultJson)
}

executeTool never throws. An unknown tool, unparseable arguments, or a throwing executor all come back as a ToolResult with success: false and a populated error.

Multi-step chains

With maxToolCalls above 1 the model can chain calls inside one generation.

const result = await RunAnywhere.generateWithTools(
  'What is 15% of the temperature in New York right now?',
  { maxToolCalls: 3 }
)

console.log(result.toolCalls.length)
console.log(result.iterationsUsed)

Error handling

Return an error object from an executor rather than throwing. A thrown error still becomes a failed ToolResult, but an explicit { error: { stringValue: '…' } } gives the model something to reason about.

;async (args) => {
  try {
    const response = await fetch(url)
    if (!response.ok) {
      return { error: { stringValue: `API returned ${response.status}` } }
    }
    const data = await response.json()
    return { temperature: { numberValue: data.temp } }
  } catch (e) {
    return { error: { stringValue: e instanceof Error ? e.message : 'Request failed' } }
  }
}

Symptom	Cause	Fix
`Unknown tool: x`	Name in the model output matches no registration	Check `ToolDefinition.name` exactly
Argument parse failure	Model emitted non-object JSON	Set `requireJsonArguments: true`, sharpen descriptions
Loop hits the cap	Model keeps calling tools	Lower `maxToolCalls` or clarify descriptions
Executor hangs	External call has no timeout	Use `AbortController` inside the executor
No call parsed	Model does not support tool calling	Pick a tool-capable model, or try `format: _LFM2`

LLM Generation

Options and defaults

Streaming

Token streaming

System Prompts

Control model behavior

Error Handling

SDKException reference

Getting Started

Swift SDK

Kotlin SDK

React Native SDK

Flutter SDK

Web SDK

Vibe Coding

The surface

Defining a tool

ToolValue

ToolParameter

Generating

ToolCallingOptions

GenerateWithToolsOptions

ToolCallingResult

Manual execution

Multi-step chains

Error handling

LLM Generation

Streaming

System Prompts

Error Handling

​The surface

​Defining a tool

​ToolValue

​ToolParameter

​Generating

​ToolCallingOptions

​GenerateWithToolsOptions

​ToolCallingResult

​Manual execution

​Multi-step chains

​Error handling

​Related

LLM Generation

Streaming

System Prompts

Error Handling

The surface

Defining a tool

ToolValue

ToolParameter

Generating

ToolCallingOptions

GenerateWithToolsOptions

ToolCallingResult

Manual execution

Multi-step chains

Error handling

Related