{"ok":true,"tool":"negative-cache-ticket","module_version":"0.1.0","result":{"slug":"negative-cache-ticket","name":"Negative Cache Ticket","version":"0.1.0","category":"coordination","status":"beta","mode":"atomic","summary":"Record or check a typed, expiring failure state.","description":"Prevent agent swarms from repeatedly attempting the same known-failing work. Record accepts a stable machine code only; check reveals a ticket only to callers that already know its opaque namespace and key.","when_to_use":["Agents should share a typed, temporary record of a failed lookup.","Repeated work should pause until an explicit expiration time."],"do_not_use_when":["The failure is permanent or requires a durable incident record.","The request contains raw credentials or personal data."],"tested_with":["HTTP/1.1","HTTP/2","MCP Streamable HTTP"],"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","oneOf":[{"type":"object","properties":{"operation":{"type":"string","const":"record"},"namespace":{"type":"string","minLength":1,"maxLength":80,"pattern":"^[a-zA-Z0-9._:-]+$"},"key":{"type":"string","minLength":1,"maxLength":256},"failure_code":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Z][A-Z0-9_]*$"},"ttl_seconds":{"type":"integer","minimum":5,"maximum":86400}},"required":["operation","namespace","key","failure_code","ttl_seconds"],"additionalProperties":false},{"type":"object","properties":{"operation":{"type":"string","const":"check"},"namespace":{"type":"string","minLength":1,"maxLength":80,"pattern":"^[a-zA-Z0-9._:-]+$"},"key":{"type":"string","minLength":1,"maxLength":256}},"required":["operation","namespace","key"],"additionalProperties":false}]},"output_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ticket_hash":{"type":"string"},"active":{"type":"boolean"},"newly_recorded":{"type":"boolean"},"failure_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"recorded_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]},"expires_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]},"ttl_seconds_remaining":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},{"type":"null"}]}},"required":["ticket_hash","active","newly_recorded","failure_code","recorded_at","expires_at","ttl_seconds_remaining"],"additionalProperties":false},"payment":{"kind":"free"},"side_effects":["Record creates a temporary failure-state ticket if absent."],"retention":"A derived namespaced key, stable failure code, and timestamp remain in Valkey only until expiry. Raw error messages are not accepted.","limits":{"min_ttl_seconds":5,"max_ttl_seconds":86400,"max_client_requests_per_minute":30,"max_global_requests_per_minute":120},"examples":{"input":{"operation":"record","namespace":"fetch","key":"resource-42","failure_code":"UPSTREAM_TIMEOUT","ttl_seconds":60},"output":{"ticket_hash":"sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd","active":true,"newly_recorded":true,"failure_code":"UPSTREAM_TIMEOUT","recorded_at":"2026-07-24T12:00:00.000Z","expires_at":"2026-07-24T12:01:00.000Z","ttl_seconds_remaining":60},"negative":[{"scenario":"The failure is permanent or requires a durable incident record.","expected_error":"INVALID_INPUT","charged":false}]},"execution":{"errors":[{"code":"INVALID_INPUT","retryable":false,"charged":false,"recovery":"Correct the request to match input_schema."},{"code":"TOOL_PAUSED","retryable":true,"charged":false,"recovery":"Wait for the operator to resume the tool."},{"code":"RATE_LIMITED","retryable":true,"charged":false,"recovery":"Retry after the response Retry-After interval."},{"code":"DEPENDENCY_UNAVAILABLE","retryable":true,"charged":false,"recovery":"Retry with the same idempotency identity."}],"idempotency":{"required":true,"mock_or_unpaid_header":"Idempotency-Key","x402_extension":null,"replay_retention":"up to 24 hours"}},"endpoints":{"describe":"/v1/tools/negative-cache-ticket","execute":"/v1/tools/negative-cache-ticket"}},"meta":{"request_id":"req_925a84f8334440679d715de84b22c2a4","observed_at":"2026-07-24T23:30:02.354Z"}}