siyuan-note/siyuan · warning

invalid capability arguments: %w

Error message

invalid capability arguments: %w

What it means

Each capability carries a JSON-Schema-backed validator; validateCapabilityCall runs ValidateInputContext on the model's decoded arguments (kernel/agent/tools.go:69-71) and surfaces failures as 'invalid capability arguments: <cause>'. This is the argument gate before confirmation/snapshot and before the handler runs — bad input never becomes a write operation. The message goes back to the model as an IsError tool result so it can fix its arguments.

Source

Thrown at kernel/agent/tools.go:70

	}
	return t, validator, nil
}

func validateCapabilityCall(ctx context.Context, registration *capabilityRegistration, args map[string]any) error {
	if registration == nil {
		return fmt.Errorf("capability was not exposed in this model round")
	}
	if !capabilityStillExecutable(registration, args) {
		return fmt.Errorf("capability is disabled or no longer available: %s", registration.ID)
	}
	if ctx.Err() != nil {
		return fmt.Errorf("capability execution was cancelled before it started")
	}
	if registration.Validator == nil {
		return fmt.Errorf("capability validator unavailable: %s", registration.ID)
	}
	if err := registration.Validator.ValidateInputContext(ctx, args); err != nil {
		return fmt.Errorf("invalid capability arguments: %w", err)
	}
	if !registration.isBrowser() &&
		(registration.Tool == nil || registration.Tool.ContextHandler == nil && registration.Tool.Handler == nil) {
		return fmt.Errorf("capability handler unavailable: %s", registration.ID)
	}
	return nil
}

// executeTool 执行单次工具调用。
func executeTool(ctx context.Context, tc openai.ToolCall, sessionID string) executedToolResult {
	tool, validator := tools.LookupToolWithValidator(tc.Function.Name)
	if tool == nil {
		return executedToolResult{Text: "unknown tool: " + tc.Function.Name, IsError: true}
	}
	return executeCapability(ctx, tc, sessionID, &capabilityRegistration{
		ID:        tools.CapabilityIDForTool(tool),
		ModelName: tool.Name,
		Source:    tool.Source,

View on GitHub (pinned to afa823b6b4)

Solutions

  1. Return the error text to the model unchanged — it contains the schema violation and the model usually corrects itself next round
  2. When integrating MCP tools, mirror the server's inputSchema exactly and respect additionalProperties:false
  3. Validate arguments client-side against the tool's inputSchema before dispatch if you pre-compose calls
  4. Keep tool schemas backward-compatible (add optional fields, never change types) across plugin versions

Example fix

// before: guessed argument type
{"query": 1234}

// after: match inputSchema
{"query": "1234"}
Defensive patterns

Strategy: validation

Validate before calling

// Client-side schema gate before dispatch (ajv-style)
// const valid = ajv.compile(tool.inputSchema); if (!valid(args)) return correctionHint;

Type guard

const matchesSchema = (args: unknown, schema: any) => {
  try { ajv.validate(schema, args); return !ajv.errors; } catch { return false; }
};

Try / catch

null

Prevention

When it happens

Trigger: Model emits tool arguments violating the tool's inputSchema: missing required fields, wrong types (string where number expected), unknown enum values, or extra properties on strict schemas. Notably, _sessionID/_toolCallID are injected only for native tools (kernel/agent/tools.go:103-110) — strict additionalProperties:false MCP servers reject payloads that include them, which is why they are withheld from non-native tools (issue #17927).

Common situations: Weak models mis-formatting arguments; schema drift after a plugin/MCP tool update while a session spans versions; clients pre-filling arguments from stale schemas; enum/boolean confusion ("true" vs true).

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

AI-assisted analysis of siyuan-note/siyuan@afa823b6b4 (2026-08-18). Data as JSON: /api/errors/64def5b3c7c4733a. Report an issue: GitHub.