{"record":{"id":"fcd426d060932b59","repo":"moeru-ai/airi","slug":"unknown-tool-tool","errorCode":null,"errorMessage":"Unknown tool: ${tool}","messagePattern":"Unknown tool: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"integrations/minecraft/src/cognitive/conscious/js-planner.ts","lineNumber":1365,"sourceCode":"delete globalThis.historySeed\ndelete globalThis.__plannerBridge\ndelete globalThis.__plannerBridgeAvailability\ndelete globalThis.__plannerBootstrapActionNames\ndelete globalThis.__plannerLog\n})()\n`\n  }\n\n  private mapToolArgs(tool: string, args: unknown[]): Record<string, unknown> {\n    if (!this.activeRun)\n      throw new Error('Tool calls are only allowed during REPL evaluation')\n\n    if (tool === 'skip')\n      return {}\n\n    const action = this.activeRun.actionsByName.get(tool)\n    if (!action)\n      throw new Error(`Unknown tool: ${tool}`)\n\n    return this.mapArgsToParams(action, args)\n  }\n\n  private async runActionFromSandbox(tool: string, args: unknown[]): Promise<ActionRuntimeResult> {\n    return this.runAction(tool, this.mapToolArgs(tool, args))\n  }\n\n  private mapArgsToParams(action: Action, args: unknown[]): Record<string, unknown> {\n    const shape = action.schema.shape as Record<string, unknown>\n    const keys = Object.keys(shape)\n\n    if (keys.length === 0)\n      return {}\n\n    if (args.length === 1) {\n      const [firstArg] = args\n      if (isRecord(firstArg))","sourceCodeStart":1347,"sourceCodeEnd":1383,"githubUrl":"https://github.com/moeru-ai/airi/blob/27111382b4a79a7e983289d6e983a06af185ed0f/integrations/minecraft/src/cognitive/conscious/js-planner.ts#L1347-L1383","documentation":"Thrown by JavaScriptPlanner.mapToolArgs() on the host side. When the sandbox calls the bridge with method 'tool', mapToolArgs looks up the tool name in this.activeRun.actionsByName (the Map built from the availableActions passed to evaluate()). 'skip' is special-cased; any other name not present in the map throws 'Unknown tool'. This is the runtime arg-mapping path, reached after use() validated the name is a non-empty string but before validation.","triggerScenarios":"The planner script calls use('someTool') where someTool was not in the availableActions list passed to evaluate(); the action was registered under a different name; a typo in the tool name; using a deprecated/renamed action name; the actionsByName map was built from a filtered or partial action set.","commonSituations":"Action renamed between releases but the model's prompt still lists the old name; availableActions filtered by capability/context so the tool is legitimately unavailable in this run; model hallucinated a tool name; case mismatch (e.g. 'MoveTo' vs 'moveTo').","solutions":["Log the available action names at the start of the run and use only those exact names.","Correct the tool name spelling/casing to match the registered action.","If the action should be available, check that it is included in the availableActions array passed to evaluate().","Update the planner prompt's tool catalogue to match the current action registry."],"exampleFix":"// before\n//   use('moveClose', { target: 'player' })  // not in actionsByName\n//\n// after\n//   use('moveTo', { x: 10, y: 64, z: -5 })","handlingStrategy":"type-guard","validationCode":"// At run setup, expose the valid tool set to the script and check before use:\n// const valid = new Set(globalThis.__plannerActionNames)\n// function knownUse(name: string, params = {}) {\n//   if (!valid.has(name)) { log(`Unknown tool: ${name}; available: ${[...valid].join(', ')}`); return null }\n//   return use(name, params)\n// }","typeGuard":"function isKnownTool(name: string, available: string[]): name is string {\n  return available.includes(name)\n}","tryCatchPattern":null,"preventionTips":["Use only the action names seeded into __plannerActionNames for this run.","Keep the planner prompt's tool catalogue in sync with the registered actions.","Watch for case mismatches and renamed actions after upgrades.","Log the available names at turn start when debugging unknown-tool errors."],"tags":["llm-planner","runtime","unknown-tool","action-map"],"backgroundTag":null,"analyzedSha":"27111382b4a79a7e983289d6e983a06af185ed0f","analyzedAt":"2026-08-12T18:33:34.132Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}