JavaScript Custom Tools

Custom tools let JavaScript app code expose a focused local development operation through the same guarded remote-tool protocol as the native suites. Use Native Custom Tools for handlers implemented in Swift or Kotlin.

Register a Tool

const registration = Ansight.registerTool(
  {
    id: "app.current_user",
    name: "Current User",
    category: "app",
    scope: "read",
    description: "Returns the current debug user id.",
  },
  async (_args, context) => ({
    success: true,
    result: {
      userId: session.currentUserId,
      platform: context.platform,
    },
  }),
);

await registration.ready;

Call registration.unregister() or Ansight.unregisterTool(id) to remove a JS-backed custom tool.

Registration API

• registerTool(definition, handler): registers one JavaScript-backed tool.
• unregisterTool(id): unregisters one tool.
• listRegisteredTools(): returns registered JavaScript tool ids.
• clearRegisteredTools(): unregisters JavaScript-backed tools.

Specific Concerns

• Prefer narrow, app-specific operations.
• Keep native-only workflows in Swift or Kotlin with Native Custom Tools.
• Choose the correct scope: "read", "write", or "delete".
• Handlers receive string arguments and a context object with request/session/platform metadata.
• 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
• Arguments and result schemas when callers need structured inputs or outputs
• Explicit failure messages for invalid arguments or unavailable app state