{"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/766dce6b1394ebb56a3090748d5a0240a5aefb36/packages/agent/src/primitives.ts#L170-L206","documentation":"Thrown at execution time (not build time) when a tool built with a Standard Schema input receives arguments that fail validation: standard.validate(value) returned issues, so execute() refuses to hand unvalidated input to your implementation, throwing cave_tool_input_schema_mismatch:<toolName>. This is the runtime guard that your tool's execute only ever sees schema-valid values. The tool name is embedded after the colon so a multi-tool run can identify the offender.","triggerScenarios":"The model emits arguments that don't match the advertised schema (missing required field, wrong type, extra field with additionalProperties: false); a caller invoking definition.execute(rawArgs) directly with hand-built args; drift between the JSON Schema sent to the provider and the Standard Schema used to validate.","commonSituations":"Provider-side schema stripping (some APIs ignore parts of the schema); prompts that don't show the model the expected shape; tool schemas tightened in code while cached conversations still send the old shape.","solutions":["Compare the failing arguments against the tool's input schema and fix whichever is wrong — usually the prompt/example or the schema's required/typing.","If you call execute() yourself, validate first or catch this error and correct the arguments.","In a custom runner, catch it and return the mismatch message to the model as a tool error so it can retry with corrected arguments."],"exampleFix":"// before (custom runner lets the throw escape)\nconst out = await def.execute(modelArgs);\n\n// after (surface to the model for self-correction)\ntry {\n  const out = await def.execute(modelArgs);\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith(\"cave_tool_input_schema_mismatch:\")) {\n    return { error: `arguments rejected by schema for ${e.message.split(\":\")[1]}; fix and retry` };\n  }\n  throw e;\n}","handlingStrategy":"try-catch","validationCode":"// Validate before calling execute when driving tools manually.\nconst result = await standard.validate(args);\nif (result.issues) {\n  // fix args or reject before execute() throws cave_tool_input_schema_mismatch:<name>\n}","typeGuard":null,"tryCatchPattern":"try {\n  const out = await def.execute(args, signal);\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith(\"cave_tool_input_schema_mismatch:\")) {\n    const toolName = e.message.split(\":\")[1];\n    return { error: `invalid arguments for ${toolName}; correct and retry` };\n  }\n  throw e;\n}","preventionTips":["Keep the JSON Schema advertised to the provider in lockstep with the Standard Schema used to validate.","Show the model a concrete example of valid arguments in the tool description.","Treat a mismatch as recoverable feedback for the model, not a crash."],"tags":["validation","tool-input","runtime","schema"],"backgroundTag":"schema-validation-failed","analyzedSha":"766dce6b1394ebb56a3090748d5a0240a5aefb36","analyzedAt":"2026-08-18T03:14:35.516Z","schemaVersion":2},"datasetVersion":"2026-08-21T13:17:26.733Z"}