Tool calling

Overview

Tool calling lets a model request one of your functions, receive the result, and fold it into its answer. The SDK runs the whole loop: generate, parse the tool call, execute your Kotlin lambda, feed the result back, generate the final response. Parsing lives in C++; there is no Kotlin fallback parser. Every entry point is an extension function on the RunAnywhere singleton. There is no RunAnywhereToolCalling class.

Imports

import ai.runanywhere.proto.v1.ToolParameter
import ai.runanywhere.proto.v1.ToolParameterType
import com.runanywhere.sdk.public.RunAnywhere
import com.runanywhere.sdk.public.extensions.LLM.RAToolValue
import com.runanywhere.sdk.public.extensions.LLM.string
import com.runanywhere.sdk.public.extensions.generateWithTools
import com.runanywhere.sdk.public.extensions.registerTool
import com.runanywhere.sdk.public.types.RAToolDefinition

The string, int, double, bool, array, and object constructors on RAToolValue are extension functions in com.runanywhere.sdk.public.extensions.LLM and have to be imported individually.

Registering a tool

RunAnywhere.registerTool(
    RAToolDefinition(
        name = "get_weather",
        description = "Get the current weather for a city.",
        parameters = listOf(
            ToolParameter(
                name = "city",
                type = ToolParameterType.TOOL_PARAMETER_TYPE_STRING,
                description = "City name, for example 'San Francisco'.",
                required = true,
            ),
        ),
        category = "Utility",
    ),
) { args ->
    val city = args["city"]?.string.orEmpty()
    mapOf(
        "temperature" to RAToolValue.string("72"),
        "condition" to RAToolValue.string("sunny"),
        "city" to RAToolValue.string(city),
    )
}

registerTool is a suspend function. The executor is a ToolExecutor, which is suspend (Map<String, RAToolValue>) -> Map<String, RAToolValue>. Arguments and return values are both typed value maps; the SDK marshals them to and from the JSON the model sees.

Generating with tools

val result = RunAnywhere.generateWithTools(
    prompt = "What's the weather in San Francisco?",
    options = LLMGenerationOptions(max_tokens = 512, temperature = 0.7f),
    toolOptions = null,
    toolChoice = null,
    forcedToolName = null,
)

println(result.text)
result.tool_calls.forEach { println("${it.name}(${it.arguments_json})") }
result.tool_results.forEach { println(it.result_json) }

Signature:

suspend fun RunAnywhere.generateWithTools(
    prompt: String,
    options: RALLMGenerationOptions?,
    toolOptions: RAToolCallingOptions?,
    toolChoice: ToolChoiceMode?,
    forcedToolName: String?,
    validateCalls: Boolean? = null,
    history: List<String> = emptyList(),
): RAToolCallingResult

The first five parameters have no defaults, so pass null for the ones you do not need. history is prior turns as a flat alternating list ([user0, assistant0, user1, ...]) excluding the current turn, which is prompt. It is threaded to commons so the tool loop keeps multi-turn context. An explicit toolOptions overrides any tool_calling payload embedded in options. When both are absent, the SDK derives options from options and falls back to ToolCallingOptions.defaults().

Tool management

Function	Returns
`registerTool(definition, executor)`	`Unit`
`unregisterTool(toolName)`	`Unit`
`getRegisteredTools()`	`List<ToolDefinition>`
`clearTools()`	`Unit`
`executeTool(toolCall)`	`ToolResult`
`generateWithTools(...)`	`ToolCallingResult`

All are suspend functions on RunAnywhere.

ToolDefinition

Field	Type	Description
`name`	`String`	Identifier the model uses
`description`	`String`	Shown to the model
`parameters`	`List<ToolParameter>`	Inputs
`category`	`String?`	Optional grouping for catalogs and UIs
`json_schema`	`String?`	Explicit schema, instead of `parameters`
`metadata`	`Map<String, String>`	Free-form

ToolParameter

Field	Type	Description
`name`	`String`	Parameter name
`type`	`ToolParameterType`	Data type
`description`	`String`	Shown to the model
`required`	`Boolean`	Defaults to `false`
`enum_values`	`List<String>`	Allowed values. Empty is unconstrained
`json_schema`	`String?`	Per-parameter schema
`default_value`	`ToolValue?`	Default when the model omits it

ToolParameterType values are TOOL_PARAMETER_TYPE_STRING, NUMBER, BOOLEAN, OBJECT, ARRAY, and UNSPECIFIED. Fully qualified, so ToolParameterType.TOOL_PARAMETER_TYPE_STRING, not ToolParameterType.STRING.

ToolCallingOptions

Defaults are max_tool_calls = 5, auto_execute = true, format = TOOL_CALL_FORMAT_NAME_JSON.

Field	Type	Description
`tools`	`List<ToolDefinition>`	Per-call tool set. Empty falls back to the registered tools
`auto_execute`	`Boolean`	Execute calls, or hand them back to the caller
`max_tool_calls`	`Int?`	Calls per turn. Unset or `0` means `5`
`temperature`	`Float?`	Sampling override
`max_tokens`	`Int?`	Token override
`system_prompt`	`String?`	System prompt for tool-enabled generation
`replace_system_prompt`	`Boolean`	Replace entirely, skipping auto-injected tool instructions
`keep_tools_available`	`Boolean`	Keep definitions live across sequential calls in one turn
`format`	`ToolCallFormatName?`	`TOOL_CALL_FORMAT_NAME_JSON` or `TOOL_CALL_FORMAT_NAME_LFM2`. Unset lets commons pick the model default
`tool_choice`	`ToolChoiceMode`	`AUTO`, `NONE`, `REQUIRED`, or `SPECIFIC`
`forced_tool_name`	`String?`	Pairs with `TOOL_CHOICE_MODE_SPECIFIC`
`require_json_arguments`	`Boolean`	Reject non-JSON argument payloads
`disable_thinking`	`Boolean?`	Suppress the model’s reasoning phase

toolChoice and forcedToolName passed to generateWithTools() override whatever the options carry.

ToolCallingResult

Field	Type	Description
`text`	`String`	Final assistant text
`tool_calls`	`List<ToolCall>`	Calls the model made
`tool_results`	`List<ToolResult>`	Populated when `auto_execute` was true
`is_complete`	`Boolean`	False when the loop is waiting for more results
`iterations_used`	`Int`	Generation turns, including the final synthesis
`thinking_content`	`String?`	Reasoning trace, when the model emits one
`raw_text`	`String`	Unparsed model output
`conversation_id`	`String?`	For continuing with results
`error_message`, `error_code`	`String?`, `Int`	Terminal error detail

ToolCall carries id, name, arguments_json, type, created_at_ms, and raw_text. Arguments arrive as a JSON string, not a map. ToolResult carries tool_call_id, name, result_json, error, success, started_at_ms, and completed_at_ms. The result is likewise a JSON string. Pairing a call with its result:

val call = result.tool_calls.firstOrNull()
val outcome = call?.let { c -> result.tool_results.firstOrNull { it.name == c.name } }
val succeeded = outcome != null && outcome.error.isNullOrBlank()

ToolValue

RAToolValue is a typealias for the generated ToolValue. Build values with the companion extensions and read them with the property extensions.

Constructor	Accessor	Kotlin type
`RAToolValue.string(v)`	`.string`	`String?`
`RAToolValue.int(v)`	`.int`	`Int?`
`RAToolValue.double(v)`	`.number`	`Double?`
`RAToolValue.bool(v)`	`.bool`	`Boolean?`
`RAToolValue.array(values)`	`.array`	`List<RAToolValue>?`
`RAToolValue.object(fields)`	`.object`	`Map<String, RAToolValue>?`

object is a Kotlin keyword, so both the constructor and the accessor need backticks: RAToolValue.`object`(fields). toJSONString(pretty), RAToolValue.parseObjectJSON(json), and RAToolValue.jsonString(map) convert between value maps and JSON. The accessor is .string, not .stringValue.

Examples

Calculator:

RunAnywhere.registerTool(
    RAToolDefinition(
        name = "calculate",
        description = "Evaluates a math expression with + - * / and parentheses.",
        parameters = listOf(
            ToolParameter(
                name = "expression",
                type = ToolParameterType.TOOL_PARAMETER_TYPE_STRING,
                description = "The expression to evaluate, for example '(3 + 4) * 2'.",
                required = true,
            ),
        ),
        category = "Utility",
    ),
) { args ->
    val expression = args["expression"]?.string.orEmpty()
    runCatching {
        mapOf("result" to RAToolValue.string(evaluate(expression).toString()))
    }.getOrElse {
        mapOf("error" to RAToolValue.string("Could not evaluate '$expression'"))
    }
}

Return an error value rather than throwing. A thrown executor aborts the turn; an error value lets the model recover or explain. Zero-parameter tool:

RunAnywhere.registerTool(
    RAToolDefinition(
        name = "get_device_info",
        description = "Returns the device manufacturer, model, and Android version.",
        parameters = emptyList(),
        category = "Utility",
    ),
) {
    mapOf(
        "manufacturer" to RAToolValue.string(Build.MANUFACTURER),
        "model" to RAToolValue.string(Build.MODEL),
        "android_version" to RAToolValue.string(Build.VERSION.RELEASE),
    )
}

Registering a set at startup:

suspend fun registerTools(context: Context) {
    runCatching {
        registerTimeTool()
        registerDeviceInfoTool()
        registerCalculatorTool()
    }.onFailure { Log.w("Tools", "tool registration failed: ${it.message}") }
}

Timeouts

Small on-device models sometimes fail to converge on a tool loop. Bound the call and cancel the generation when it expires, rather than leaving the UI waiting:

val result = try {
    withTimeout(60_000) {
        withContext(Dispatchers.Default) {
            RunAnywhere.generateWithTools(prompt, options, toolOptions, toolChoice, forcedToolName)
        }
    }
} catch (e: TimeoutCancellationException) {
    RunAnywhere.cancelGeneration()
    showTimeoutMessage()
    return
}

Errors

result.tool_results.forEach { toolResult ->
    if (!toolResult.error.isNullOrBlank()) {
        Log.w("ToolCalling", "${toolResult.name} failed: ${toolResult.error}")
    }
}

generateWithTools() throws SDKException with ERROR_CODE_NOT_INITIALIZED before RunAnywhere.initialize(). Individual tool failures come back on ToolResult, not as exceptions. See Error handling.

Notes

Executors run inside the generation loop, so a slow one blocks inference for its duration. Keep network calls out, or bound them yourself. Descriptions are the only thing the model has to decide with. A description that names the inputs and says what comes back beats one that names the function again. Keep returned payloads small. Everything a tool returns is fed back through the context window.

LLM generation

Text generation

VLM

Vision language models

System prompts

Control model behavior

Error handling

Error handling patterns

Getting Started

Swift SDK

Kotlin SDK

React Native SDK

Flutter SDK

Web SDK

Vibe Coding

Overview

Imports

Registering a tool

Generating with tools

Tool management

ToolDefinition

ToolParameter

ToolCallingOptions

ToolCallingResult

ToolValue

Examples

Timeouts

Errors

Notes

LLM generation

VLM

System prompts

Error handling

​Overview

​Imports

​Registering a tool

​Generating with tools

​Tool management

​ToolDefinition

​ToolParameter

​ToolCallingOptions

​ToolCallingResult

​ToolValue

​Examples

​Timeouts

​Errors

​Notes

​Related

LLM generation

VLM

System prompts

Error handling

Overview

Imports

Registering a tool

Generating with tools

Tool management

ToolDefinition

ToolParameter

ToolCallingOptions

ToolCallingResult

ToolValue

Examples

Timeouts

Errors

Notes

Related