Custom Tools

Custom tools let app code expose a focused local development operation through the same guarded remote-tool protocol as the packaged suites.

Register a Tool

import ai.ansight.runtime.AndroidToolResult
import ai.ansight.runtime.AnsightOptions
import ai.ansight.runtime.ToolScope
import ai.ansight.runtime.androidSimpleTool
import org.json.JSONObject

val tool = androidSimpleTool(
    id = "app.current_user",
    name = "Current User",
    description = "Returns the current debug user id.",
    category = "app",
    scope = ToolScope.Read,
    keywords = "app user debug",
) { _, _ ->
    AndroidToolResult.success(
        JSONObject().put("userId", session.currentUserId)
    )
}

val options = AnsightOptions.createBuilder()
    .addTool(tool)
    .withReadOnlyToolAccess()
    .build()

Registration API

• addTool(...): adds one tool to options before runtime initialization.
• addTools(...): adds multiple tools to options before runtime initialization.
• registerTool(...): registers a tool at runtime.
• isToolRegistered(...): checks whether a tool id is currently registered.

Specific Concerns

• Prefer narrow, app-specific operations.
• Choose the correct scope: ToolScope.Read, ToolScope.Write, or ToolScope.Delete.
• Do not expose broad scripting, arbitrary file access, or secret access through custom tools.
• Registered tools are still hidden and unusable until the runtime guard allows their scope.

Tool Definition Checklist

• Stable tool id, usually under an app-owned prefix such as app.
• Clear name and description
• Category and keywords that match the workflow
• Correct scope
• Explicit argument validation and failure messages
• Structured JSON result payloads for callers