JuliusBrussee/caveman · error · Error

cave_tool_input_schema_mismatch:${options.name}

Error message

cave_tool_input_schema_mismatch:${options.name}

What it means

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).

Source

Thrown at packages/agent/src/primitives.ts:188

  }
  const definition = {
    kind: "tool",
    name: options.name,
    description: options.description,
    input,
    effect: options.effect,
    result,
    ...(typeof options.result === "object" ? { artifact: options.result } : {}),
    ...(options.allowRepeat === undefined ? {} : { allowRepeat: options.allowRepeat }),
    timeoutMs,
    ...(options.runtime === undefined ? {} : { runtime: options.runtime }),
    async execute(value: unknown, signal?: AbortSignal) {
      if (standard === undefined) {
        return options.execute(value as never, signal);
      }
      const validated = await standard.validate(value);
      if (validated.issues) {
        throw new Error(`cave_tool_input_schema_mismatch:${options.name}`);
      }
      return options.execute(validated.value, signal);
    },
  } as const;
  Object.defineProperty(
    definition,
    Symbol.for("@caveman-ai/agent:tool-implementation-source"),
    {
      value: Function.prototype.toString.call(options.execute),
      enumerable: false,
      configurable: false,
      writable: false,
    },
  );
  return Object.freeze(definition);
}

function standardToolSchema(

View on GitHub (pinned to 27d5a3981a)

Solutions

1. Reproduce: log the raw tool arguments right before the tool call and run them through your schema locally
2. 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)
3. 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
4. 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

Example fix

// before
input: schema.object({ id: schema.integer() }),
inputJSONSchema: { type: "object", properties: { id: {} } }, // advertises anything, validator requires integer -> mismatch

// after
input: schema.object({ id: schema.integer() }),
// let the factory derive the JSON Schema from the validator (omit inputJSONSchema),
// so the model sees the same integer requirement it will be validated against

const probe = await schema["~standard"].validate(sampleArgs);
if (probe.issues) {
  // fix the schema or the advertised inputJSONSchema before shipping the tool
  console.warn("tool args fail validation:", probe.issues);
}

try {
  await toolDef.execute(args, signal);
} catch (e) {
  if (e instanceof Error && e.message.startsWith("cave_tool_input_schema_mismatch:")) {
    return { error: `invalid arguments for ${toolName}: ${JSON.stringify(args)}` }; // feed back to model
  }
  throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• ${field} is not an array (got ${typeof value})
• tool message requires tool_call_id
• option not found
• cave_harness_adapter_version_invalid
• cave_harness_model_invalid

AI-assisted analysis of JuliusBrussee/caveman@27d5a3981a (2026-08-15). Data as JSON: /api/errors/1e8f917ff45b3027. Report an issue: GitHub.