{"record":{"id":"1e8f917ff45b3027","repo":"JuliusBrussee/caveman","slug":"cave-tool-input-schema-mismatch-options-name","errorCode":null,"errorMessage":"cave_tool_input_schema_mismatch:${options.name}","messagePattern":"cave_tool_input_schema_mismatch:(.+?)","errorType":"validation","errorClass":"Error","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/27d5a3981a347890211bb1bf2439e5c821a63bc9/packages/agent/src/primitives.ts#L170-L206","documentation":"When a tool is defined with a Standard Schema input, every execute() call first runs standard.validate(value) on the incoming arguments. If validation reports issues, the call aborts before your execute logic with cave_tool_input_schema_mismatch:<toolname> — a runtime guard against the model producing arguments that fit the advertised JSON Schema but not your actual validator (or drift between the two).","triggerScenarios":"The model calls the tool with arguments that fail your Standard Schema validator: wrong types, missing required fields, extra fields when the schema is strict, or enum values outside the allowed set. Triggered per call, not at definition time, and the tool name is appended to the message.","commonSituations":"Schema drift where inputJSONSchema (what the model sees) is looser than the Standard Schema (what validates), models hallucinating fields, number-vs-string confusion for IDs, or strict object schemas rejecting model-added properties.","solutions":["Reproduce: log the raw tool arguments right before the tool call and run them through your schema locally","Align inputJSONSchema and the Standard Schema so they accept the same shapes; regenerate the JSON Schema from the validator instead of hand-writing it (or drop inputJSONSchema and let conversion do it)","Relax the validator where the model legitimately varies (optional fields, coercion of numeric strings) or tighten the advertised schema so the model stops sending bad shapes","In the agent loop, catch this error per tool call and feed the failure back to the model as a corrective tool result so it can retry with fixed arguments"],"exampleFix":"// before\ninput: schema.object({ id: schema.integer() }),\ninputJSONSchema: { type: \"object\", properties: { id: {} } }, // advertises anything, validator requires integer -> mismatch\n\n// after\ninput: schema.object({ id: schema.integer() }),\n// let the factory derive the JSON Schema from the validator (omit inputJSONSchema),\n// so the model sees the same integer requirement it will be validated against","handlingStrategy":"try-catch","validationCode":"const probe = await schema[\"~standard\"].validate(sampleArgs);\nif (probe.issues) {\n  // fix the schema or the advertised inputJSONSchema before shipping the tool\n  console.warn(\"tool args fail validation:\", probe.issues);\n}","typeGuard":null,"tryCatchPattern":"try {\n  await toolDef.execute(args, signal);\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith(\"cave_tool_input_schema_mismatch:\")) {\n    return { error: `invalid arguments for ${toolName}: ${JSON.stringify(args)}` }; // feed back to model\n  }\n  throw e;\n}","preventionTips":["Derive the advertised JSON Schema from the validator instead of maintaining two schemas","Test each tool with realistic model-produced arguments before deploying","Catch mismatch errors in the agent loop and return them as corrective tool results so the model retries"],"tags":["runtime","schema-mismatch","llm-output","validation","tool-calls"],"backgroundTag":null,"analyzedSha":"27d5a3981a347890211bb1bf2439e5c821a63bc9","analyzedAt":"2026-08-15T09:26:11.751Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}