{"record":{"id":"584bddd94f505a51","repo":"JuliusBrussee/caveman","slug":"cave-tool-input-schema-mismatch","errorCode":"cave_tool_input_schema_mismatch","errorMessage":"cave_tool_input_schema_mismatch:${options.name}","messagePattern":"cave_tool_input_schema_mismatch:(.+?)","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/agent/src/primitives.ts","lineNumber":188,"sourceCode":"  }\n  const definition = {\n    kind: \"tool\",\n    name: options.name,\n    description: options.description,\n    input,\n    effect: options.effect,\n    result,\n    ...(typeof options.result === \"object\" ? { artifact: options.result } : {}),\n    ...(options.allowRepeat === undefined ? {} : { allowRepeat: options.allowRepeat }),\n    timeoutMs,\n    ...(options.runtime === undefined ? {} : { runtime: options.runtime }),\n    async execute(value: unknown, signal?: AbortSignal) {\n      if (standard === undefined) {\n        return options.execute(value as never, signal);\n      }\n      const validated = await standard.validate(value);\n      if (validated.issues) {\n        throw new Error(`cave_tool_input_schema_mismatch:${options.name}`);\n      }\n      return options.execute(validated.value, signal);\n    },\n  } as const;\n  Object.defineProperty(\n    definition,\n    Symbol.for(\"@caveman-ai/agent:tool-implementation-source\"),\n    {\n      value: Function.prototype.toString.call(options.execute),\n      enumerable: false,\n      configurable: false,\n      writable: false,\n    },\n  );\n  return Object.freeze(definition);\n}\n\nfunction standardToolSchema(","sourceCodeStart":170,"sourceCodeEnd":206,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/3ee70a102609e550bd2e68004bf5990a9341c851/packages/agent/src/primitives.ts#L170-L206","documentation":"At execution time, a tool defined with a Standard Schema input validates the incoming arguments via standard.validate(value). If validation returns issues, execute() throws an error whose message is cave_tool_input_schema_mismatch:<toolName> — meaning the model/caller supplied arguments that do not conform to the tool's declared input schema.","triggerScenarios":"Calling toolDefinition.execute(value) with a value that fails the Standard Schema validation — missing required properties, wrong types, additional/unexpected fields the schema rejects.","commonSituations":"A language model hallucinating malformed tool arguments; a caller bypassing the provider layer and invoking execute() directly with hand-built payloads; schema tightened after callers were built against an older, looser schema.","solutions":["Log and inspect the failing value against the tool's input schema; fix the argument payload to satisfy the schema","Validate arguments with the same Standard Schema on the caller side before invoking execute()","If the schema changed, regenerate/repair callers (prompts, client code) to match the new required fields and types"],"exampleFix":"// before\nawait myTool.execute({ query: 123 }); // query must be a string\n// after\nconst parsed = mySchema.safeParse({ query: 123 });\nif (!parsed.success) throw new Error(\"bad tool args: \" + parsed.error.message);\nawait myTool.execute({ query: \"cave docs\" });","handlingStrategy":"try-catch","validationCode":"const check = await standard[\"~standard\"].validate(args);\nif (check.issues) {\n  throw new Error(`tool args invalid for ${toolName}: ` + JSON.stringify(check.issues));\n}\nawait toolDef.execute(args, signal);","typeGuard":null,"tryCatchPattern":"try {\n  await toolDef.execute(args, signal);\n} catch (err) {\n  if (err instanceof Error && err.message.startsWith(\"cave_tool_input_schema_mismatch:\")) {\n    const toolName = err.message.split(\":\")[1];\n    // re-validate args against tool input schema, repair or reject the call\n  } else throw err;\n}","preventionTips":["Validate arguments with the same Standard Schema before invoking execute()","Keep the model's tool schema description and the validation schema generated from one source","When tightening schemas, update callers/prompts in the same change and add regression tests"],"tags":["schema","validation","tool-execution","arguments"],"backgroundTag":"schema-validation-failed","analyzedSha":"3ee70a102609e550bd2e68004bf5990a9341c851","analyzedAt":"2026-09-20T15:53:39.229Z","contentChangedAt":"2026-09-20T15:53:39.229Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}