{"record":{"id":"7e59e1d8bbb8799e","repo":"mastra-ai/mastra","slug":"tool-invalid-format","errorCode":"TOOL_INVALID_FORMAT","errorMessage":"TOOL_INVALID_FORMAT","messagePattern":"TOOL_INVALID_FORMAT","errorType":"error_code","errorClass":"MastraError","httpStatus":null,"severity":"error","filePath":"packages/core/src/utils.ts","lineNumber":368,"sourceCode":"    inputSchema,\n  };\n}\n\n/**\n * Ensures a tool has an ID and inputSchema by generating one if not present\n * @param tool - The tool to ensure has an ID and inputSchema\n * @returns The tool with an ID and inputSchema\n */\nexport function ensureToolProperties(tools: ToolsInput): ToolsInput {\n  const toolsWithProperties = Object.keys(tools).reduce<ToolsInput>((acc, key) => {\n    const tool = tools?.[key];\n    if (tool) {\n      // Check if the tool is a plain function (not a Tool instance or Vercel tool)\n      // This catches the common mistake of passing a tool factory function instead of the tool itself\n      // We need to cast to unknown first since ToolsInput doesn't include functions in its type,\n      // but users can still pass functions at runtime which causes silent failures\n      if (typeof tool === 'function' && !((tool as unknown) instanceof Tool) && !isVercelTool(tool)) {\n        throw new MastraError({\n          id: 'TOOL_INVALID_FORMAT',\n          domain: ErrorDomain.TOOL,\n          category: ErrorCategory.USER,\n          text: `Tool \"${key}\" is not a valid tool format. Tools must be created using createTool() or be a valid Vercel AI SDK tool. Received a function.`,\n        });\n      }\n\n      if (isVercelTool(tool)) {\n        acc[key] = setVercelToolProperties(tool) as VercelTool;\n      } else {\n        acc[key] = tool;\n      }\n    }\n    return acc;\n  }, {});\n\n  return toolsWithProperties;\n}","sourceCodeStart":350,"sourceCodeEnd":386,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/utils.ts#L350-L386","documentation":"Mastra throws `TOOL_INVALID_FORMAT` (a USER-domain MastraError) when an entry in a `tools` map is a plain function — the classic mistake of registering a tool factory (e.g. a function returned by a `createTool`-producing helper, or a Vercel-AI-SDK-style factory) instead of an actual Tool instance. Plain functions would otherwise silently fail at runtime, so this check fails fast.","triggerScenarios":"Passing `tools: { myTool: createMyTool(options) }` where `createMyTool` is itself the tool-returning factory but you forgot to call it, so the value is a function; passing a bare function where a `Tool` instance or Vercel tool object is expected in agent config, workflow steps, or `ensuredTools`.","commonSituations":"Copy-pasting tool definitions where the factory is curried with options; accidental name collision shadowing a Tool variable with its factory function; mixing Vercel AI SDK `tool()` outputs with Mastra tools incorrectly.","solutions":["Call the factory: `tools: { myTool: createMyTool({...}) }` instead of passing the factory function itself.","Verify the registered value with the check Mastra uses: it must be a `Tool` instance (MASTRA_TOOL_MARKER) or a Vercel tool (an object, not a function).","If you truly need dynamic tool creation, build the map at config time: `tools: { myTool: myToolFactory(options) }`."],"exampleFix":"// before\nnew Agent({ tools: { weather: createWeatherTool } });\n// after\nnew Agent({ tools: { weather: createWeatherTool({ apiKey }) } });","handlingStrategy":"type-guard","validationCode":"function assertValidToolEntries(tools: Record<string, unknown>) {\n  for (const [key, tool] of Object.entries(tools)) {\n    if (typeof tool === 'function') throw new Error(`tools.${key} is a function — call the factory to get the Tool instance`);\n  }\n}","typeGuard":"function isMastraTool(v: unknown): v is Tool {\n  return (\n    (v instanceof Tool) ||\n    (typeof v === 'object' && v !== null && (v as any)[MASTRA_TOOL_MARKER] === true)\n  );\n}","tryCatchPattern":"try {\n  new Agent({ name: 'x', tools });\n} catch (e) {\n  if (e instanceof MastraError && e.id === 'TOOL_INVALID_FORMAT') {\n    console.error(`Fix tools entry: ${e.message}`);\n  }\n  throw e;\n}","preventionTips":["Always invoke tool factories: `tools: { foo: makeFooTool(opts) }`, never pass `makeFooTool` itself.","Type the tools map as `ToolsInput` so TypeScript flags bare functions at compile time.","Add a dev-time assertion over the tools object in app bootstrap."],"tags":["tools","configuration","type-error"],"backgroundTag":"invalid-tool-format","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}