{"openapi":"3.0.3","info":{"title":"Agent Tool-Call Validator & Repairer API","version":"1.0.0","description":"Validates and repairs LLM tool/function calls across OpenAI, Anthropic, Gemini, and MCP formats against JSON Schemas."},"servers":[{"url":"https://api.tinplate.dev","description":"Production Edge Gateway"}],"components":{"schemas":{"ToolCallValidateResponseData":{"type":"object","properties":{"valid":{"type":"boolean","example":true},"verdict":{"type":"string","enum":["allow","repaired","reject"],"example":"repaired","description":"'allow' if valid with zero repairs, 'repaired' if valid after healing/coercion, 'reject' if invalid."},"provider_format":{"type":"string","enum":["openai","anthropic","gemini","mcp","flat","raw_string","unknown"],"example":"openai"},"tool_name":{"type":"string","nullable":true,"example":"search_invoices"},"call_id":{"type":"string","nullable":true,"example":null},"normalized_arguments":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"example":{"customer_id":"cust_99","limit":10,"status":"paid","include_line_items":false}},"mcp_call":{"type":"object","nullable":true,"properties":{"method":{"type":"string","enum":["tools/call"]},"params":{"type":"object","properties":{"name":{"type":"string"},"arguments":{"type":"object","additionalProperties":{"nullable":true}}},"required":["name","arguments"]}},"required":["method","params"]},"repairs":{"type":"array","items":{"type":"string"},"example":["normalized_tool_name:Search-Invoices->search_invoices","stripped_markdown_fence","quoted_unquoted_keys","converted_single_quoted_strings","removed_trailing_commas","coerced_integer:$.limit","coerced_enum_case:$.status","stripped_unknown_property:$.extra_hallucinated","applied_default:$.include_line_items"]},"schema_errors":{"type":"array","items":{"type":"string"},"example":[]},"llm_retry_feedback":{"type":"string","nullable":true,"example":null,"description":"Deterministic correction message to feed back to the LLM when `valid` is false."}},"required":["valid","verdict","provider_format","tool_name","call_id","normalized_arguments","mcp_call","repairs","schema_errors","llm_retry_feedback"]},"ToolCallValidateRequest":{"type":"object","properties":{"tool_call":{"anyOf":[{"type":"string","minLength":1,"maxLength":262144},{"type":"object","additionalProperties":{"nullable":true}}],"example":{"type":"function","function":{"name":"Search-Invoices","arguments":"```json\n{customer_id: 'cust_99', limit: '10', status: 'PAID', extra_hallucinated: true,}\n```"}},"description":"Raw LLM tool call (OpenAI function/tool_call, Anthropic tool_use, Gemini functionCall, MCP tools/call, or raw string)."},"tools":{"type":"array","items":{"$ref":"#/components/schemas/ToolDefinition"},"minItems":1,"maxItems":128,"example":[{"name":"search_invoices","description":"Search customer invoices","parameters":{"type":"object","required":["customer_id","limit"],"additionalProperties":false,"properties":{"customer_id":{"type":"string","minLength":3},"limit":{"type":"integer","minimum":1,"maximum":100},"status":{"type":"string","enum":["draft","open","paid","void"]},"include_line_items":{"type":"boolean","default":false}}}}],"description":"List of allowed tool definitions with their JSON Schemas."},"coerce_types":{"type":"boolean","default":true,"example":true,"description":"Coerce safe LLM type mismatches ('10' -> 10, 'true' -> true, stringified JSON arrays/objects, enum casing)."},"strip_unknown_properties":{"type":"boolean","default":true,"example":true,"description":"Remove hallucinated keys not declared in `properties` when `additionalProperties: false`."},"apply_defaults":{"type":"boolean","default":true,"example":true,"description":"Populate missing properties that declare a `default` value in the JSON Schema."},"fuzzy_match_tool_name":{"type":"boolean","default":true,"example":true,"description":"Match tool names across snake_case, camelCase, and kebab-case differences."}},"required":["tool_call","tools"]},"ToolDefinition":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":256,"example":"search_invoices","description":"Canonical tool/function name (or nested inside `function.name` for OpenAI format)."},"type":{"type":"string","maxLength":64},"description":{"type":"string","maxLength":4096},"parameters":{"type":"object","additionalProperties":{"nullable":true},"description":"JSON Schema for tool arguments (OpenAI/Gemini style)."},"inputSchema":{"type":"object","additionalProperties":{"nullable":true},"description":"JSON Schema for tool arguments (MCP camelCase style)."},"input_schema":{"type":"object","additionalProperties":{"nullable":true},"description":"JSON Schema for tool arguments (Anthropic snake_case style)."},"function":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":256},"description":{"type":"string","maxLength":4096},"parameters":{"type":"object","additionalProperties":{"nullable":true}},"strict":{"type":"boolean"}},"required":["name"],"description":"OpenAI Chat Completions wrapped `{ type: 'function', function: { name, parameters } }` definition."}}},"ResponseMeta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","format":"uuid"},"ms":{"type":"integer","minimum":0},"version":{"type":"string","example":"1.0.0"}}},"ErrorEnvelope":{"type":"object","required":["ok","error","meta"],"properties":{"ok":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"invalid_input"},"message":{"type":"string","example":"Request body failed validation"}}},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}}},"parameters":{}},"paths":{"/v1/tool-call-validator":{"post":{"tags":["17_TOOL_CALL_VALIDATOR"],"summary":"Validate, heal, and normalize an LLM tool or MCP call against tool JSON Schemas","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolCallValidateRequest"}}}},"responses":{"200":{"description":"Validation verdict, normalized arguments, canonical MCP call, and repair log","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/ToolCallValidateResponseData"},"meta":{"$ref":"#/components/schemas/ResponseMeta"}},"required":["ok","data","meta"]}}}},"400":{"description":"Invalid input or malformed JSON request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid authentication credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request payload exceeds subscribed plan byte cap","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}