{"record":{"id":"64def5b3c7c4733a","repo":"siyuan-note/siyuan","slug":"invalid-capability-arguments-w","errorCode":null,"errorMessage":"invalid capability arguments: %w","messagePattern":"invalid capability arguments: %w","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"kernel/agent/tools.go","lineNumber":70,"sourceCode":"\t}\n\treturn t, validator, nil\n}\n\nfunc validateCapabilityCall(ctx context.Context, registration *capabilityRegistration, args map[string]any) error {\n\tif registration == nil {\n\t\treturn fmt.Errorf(\"capability was not exposed in this model round\")\n\t}\n\tif !capabilityStillExecutable(registration, args) {\n\t\treturn fmt.Errorf(\"capability is disabled or no longer available: %s\", registration.ID)\n\t}\n\tif ctx.Err() != nil {\n\t\treturn fmt.Errorf(\"capability execution was cancelled before it started\")\n\t}\n\tif registration.Validator == nil {\n\t\treturn fmt.Errorf(\"capability validator unavailable: %s\", registration.ID)\n\t}\n\tif err := registration.Validator.ValidateInputContext(ctx, args); err != nil {\n\t\treturn fmt.Errorf(\"invalid capability arguments: %w\", err)\n\t}\n\tif !registration.isBrowser() &&\n\t\t(registration.Tool == nil || registration.Tool.ContextHandler == nil && registration.Tool.Handler == nil) {\n\t\treturn fmt.Errorf(\"capability handler unavailable: %s\", registration.ID)\n\t}\n\treturn nil\n}\n\n// executeTool 执行单次工具调用。\nfunc executeTool(ctx context.Context, tc openai.ToolCall, sessionID string) executedToolResult {\n\ttool, validator := tools.LookupToolWithValidator(tc.Function.Name)\n\tif tool == nil {\n\t\treturn executedToolResult{Text: \"unknown tool: \" + tc.Function.Name, IsError: true}\n\t}\n\treturn executeCapability(ctx, tc, sessionID, &capabilityRegistration{\n\t\tID:        tools.CapabilityIDForTool(tool),\n\t\tModelName: tool.Name,\n\t\tSource:    tool.Source,","sourceCodeStart":52,"sourceCodeEnd":88,"githubUrl":"https://github.com/siyuan-note/siyuan/blob/afa823b6b4e4f183511e0bc0a3be93caa94c7c97/kernel/agent/tools.go#L52-L88","documentation":"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.","triggerScenarios":"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).","commonSituations":"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).","solutions":["Return the error text to the model unchanged — it contains the schema violation and the model usually corrects itself next round","When integrating MCP tools, mirror the server's inputSchema exactly and respect additionalProperties:false","Validate arguments client-side against the tool's inputSchema before dispatch if you pre-compose calls","Keep tool schemas backward-compatible (add optional fields, never change types) across plugin versions"],"exampleFix":"// before: guessed argument type\n{\"query\": 1234}\n\n// after: match inputSchema\n{\"query\": \"1234\"}","handlingStrategy":"validation","validationCode":"// Client-side schema gate before dispatch (ajv-style)\n// const valid = ajv.compile(tool.inputSchema); if (!valid(args)) return correctionHint;","typeGuard":"const matchesSchema = (args: unknown, schema: any) => {\n  try { ajv.validate(schema, args); return !ajv.errors; } catch { return false; }\n};","tryCatchPattern":"null","preventionTips":["Mirror MCP inputSchema exactly; respect additionalProperties:false","Return the wrapped validation message to the model — it self-corrects next round","Keep tool schemas backward-compatible across plugin versions"],"tags":["agent","capability","json-schema","arguments"],"backgroundTag":"schema-validation-failed","analyzedSha":"afa823b6b4e4f183511e0bc0a3be93caa94c7c97","analyzedAt":"2026-08-18T17:04:10.865Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}