{"record":{"id":"c43f08412ba971dc","repo":"moeru-ai/airi","slug":"use-toolname-params-requires-a-non-empty-string","errorCode":null,"errorMessage":"use(toolName, params) requires a non-empty string toolName","messagePattern":"use\\(toolName, params\\) requires a non-empty string toolName","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"integrations/minecraft/src/cognitive/conscious/js-planner.ts","lineNumber":1306,"sourceCode":"  else if (typeof globalThis.lastAction?.result?.distanceToTargetAfter === 'number') {\n    distance = globalThis.lastAction.result.distanceToTargetAfter\n  }\n\n  if (distance === null) {\n    throw new Error('Expectation failed: expectNear() requires target argument or last action distanceToTargetAfter telemetry')\n  }\n\n  if (distance <= maxDist)\n    return true\n\n  throw new Error(\n    'Expectation failed: ' + __plannerExpectationDetail(message, 'Expected distance <= ' + maxDist + ', got ' + distance),\n  )\n}\n\nglobalThis.use = (toolName, params = {}) => {\n  if (typeof toolName !== 'string' || toolName.length === 0)\n    throw new Error('use(toolName, params) requires a non-empty string toolName')\n\n  const invocationArgs = params && typeof params === 'object' && !Array.isArray(params) ? [params] : [{}]\n  const runtimeResult = __plannerCallBridge('tool', [toolName, invocationArgs])\n  globalThis.lastAction = runtimeResult\n  globalThis.lastRun.actions.push(runtimeResult)\n  return runtimeResult\n}\n\nglobalThis.skip = () => globalThis.use('skip', {})\n\nfor (const toolName of __plannerActionNames) {\n  if (toolName === 'skip')\n    continue\n\n  globalThis[toolName] = (...args) => {\n    const runtimeResult = __plannerCallBridge('tool', [toolName, args])\n    globalThis.lastAction = runtimeResult\n    globalThis.lastRun.actions.push(runtimeResult)","sourceCodeStart":1288,"sourceCodeEnd":1324,"githubUrl":"https://github.com/moeru-ai/airi/blob/27111382b4a79a7e983289d6e983a06af185ed0f/integrations/minecraft/src/cognitive/conscious/js-planner.ts#L1288-L1324","documentation":"globalThis.use(toolName, params) is the primary bridge from the sandbox script to the host action runtime. It requires toolName to be a non-empty string; anything else (undefined, number, object, empty string) throws immediately before any bridge call. This guards __plannerCallBridge from receiving an invalid tool identifier.","triggerScenarios":"Calling use() with no arguments; use(undefined, ...); use(123); use('') ; use(someVariable) where the variable was never assigned; calling a dynamically-constructed tool name that evaluated to undefined.","commonSituations":"Model writes use(actionName) but actionName was not defined earlier; destructuring or variable typo; the model assumed a global function name equals the tool string; passing an object as the first arg by mistake.","solutions":["Pass a literal known tool name string, e.g. use('moveTo', { x, y, z }).","If using a variable, log it first to confirm it is a non-empty string.","Use the auto-generated top-level helpers (moveTo, chat, etc.) which call use internally with the correct name.","Spell-check against the action list returned by the planner bootstrap."],"exampleFix":"// before\n//   use(targetTool, { x: 10 })  // targetTool is undefined\n//\n// after\n//   use('moveTo', { x: 10, y: 64, z: -5 })","handlingStrategy":"validation","validationCode":"// Validate before calling use():\n// function safeUse(name: unknown, params = {}) {\n//   if (typeof name !== 'string' || name.length === 0)\n//     throw new Error(`use() needs a non-empty string tool name, got: ${typeof name}`)\n//   return use(name, params)\n// }","typeGuard":"function isToolName(v: unknown): v is string {\n  return typeof v === 'string' && v.length > 0\n}","tryCatchPattern":null,"preventionTips":["Always pass a literal, known tool name to use().","If using a variable, log it first to confirm it is a non-empty string.","Prefer the auto-generated top-level helpers (moveTo, chat, etc.).","Cross-check names against the action list seeded into the sandbox."],"tags":["llm-planner","sandbox","validation","use-bridge"],"backgroundTag":null,"analyzedSha":"27111382b4a79a7e983289d6e983a06af185ed0f","analyzedAt":"2026-08-12T18:33:34.132Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}