{"openapi":"3.0.3","info":{"title":"Toolcard","version":"0.1.8","description":"Cited checks for one MCP tool or a tools list, plus a called-or-ignored tally. Checks do not store the tool. Outcome reports store a name, a SHA-256, and called or ignored. Heuristics are not a certification."},"servers":[{"url":"https://agentghostedme.com"}],"paths":{"/v1/check":{"post":{"operationId":"checkTool","summary":"Check one MCP tool definition","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolDefinition"},"example":{"name":"getUser","description":"Get a user","inputSchema":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]}}}}},"responses":{"200":{"description":"Findings for this tool. stored is always false.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckResult"}}}},"400":{"description":"The body was not a usable tool object. The message says what to send."},"429":{"description":"Free cap hit. Retry-After is set. Paid keys are not offered yet."}}}},"/v1/check-server":{"post":{"operationId":"checkServer","summary":"Check every tool in a tools/list result","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolList"}}}},"responses":{"200":{"description":"Per-tool findings plus cross-tool findings. stored is always false. One list counts as one check.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerCheckResult"}}}},"400":{"description":"The body was not a usable tools list. The message says what to send."},"429":{"description":"Free cap hit. Retry-After is set. Paid keys are not offered yet."}}}},"/v1/outcomes":{"post":{"operationId":"reportOutcome","summary":"Report whether an agent called a tool","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutcomeReport"}}}},"responses":{"200":{"description":"This report_id was already stored. Nothing was added."},"201":{"description":"Stored. The body is the aggregate, not the raw row."},"400":{"description":"The report was rejected. The message says what to change."},"429":{"description":"Free cap hit."},"507":{"description":"The free outcome file is full."}}}},"/v1/outcomes/summary":{"get":{"operationId":"outcomeSummary","summary":"Aggregate called and ignored counts","responses":{"200":{"description":"Counts only. Tool names are not included."}}}},"/v1/rules":{"get":{"operationId":"rules","summary":"Rule ids, cutoffs, and sources","responses":{"200":{"description":"The rule list for this rules_version."}}}},"/v1/examples":{"get":{"operationId":"examples","summary":"Two sample checks computed live","responses":{"200":{"description":"One endpoint-shaped sample and one that does not trip these checks."}}}},"/v1/health":{"get":{"operationId":"health","summary":"Process health","responses":{"200":{"description":"ok, version, rules_version"}}}}},"components":{"schemas":{"ToolDefinition":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"inputSchema":{"type":"object"}}},"CheckResult":{"type":"object","properties":{"rules_version":{"type":"string"},"name":{"type":"string"},"shape":{"type":"string","enum":["endpoint-shaped","not-endpoint-shaped"]},"findings":{"type":"array","items":{"$ref":"#/components/schemas/Finding"}},"stored":{"type":"boolean"}}},"Finding":{"type":"object","required":["id","kind","message","source"],"properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["heuristic","spec"]},"message":{"type":"string"},"source":{"type":"object"},"resource":{"type":"string","description":"toolcard://answers URI for this finding. Omitted for missing-input-schema, input-schema-not-object, duplicate-name, overlapping-descriptions, and too-many-tools. Pass it to resources/read. Not an http URL."}}},"ToolList":{"type":"object","properties":{"tools":{"type":"array","items":{"$ref":"#/components/schemas/ToolDefinition"},"description":"Tools from a tools/list result or a server card. Wins over result.tools when both are present."},"result":{"type":"object","description":"JSON-RPC tools/list envelope. Used only when tools is omitted.","properties":{"tools":{"type":"array","items":{"$ref":"#/components/schemas/ToolDefinition"}}}}}},"ServerCheckResult":{"type":"object","properties":{"rules_version":{"type":"string"},"tool_count":{"type":"integer"},"tools":{"type":"array","items":{"$ref":"#/components/schemas/CheckResult"}},"findings":{"type":"array","items":{"$ref":"#/components/schemas/Finding"}},"stored":{"type":"boolean"}}},"OutcomeReport":{"type":"object","required":["name","result"],"properties":{"name":{"type":"string"},"result":{"type":"string","enum":["called","ignored"]},"description":{"type":"string"},"client":{"type":"string"},"report_id":{"type":"string"}}}}}}