{"ok":true,"tool":"freshness-lease","module_version":"0.1.0","result":{"slug":"freshness-lease","name":"Freshness Lease","version":"0.1.0","category":"coordination","status":"beta","mode":"atomic","summary":"Coordinate one renewable freshness owner without exposing identity.","description":"Atomically grants a short renewable lease for refreshing an opaque resource. Only the current holder can renew or release it; status reveals activity and TTL but never the holder.","when_to_use":["One agent should own a renewable refresh responsibility for a short period.","Peers need to see lease activity and expiry without learning the holder."],"do_not_use_when":["The underlying refresh itself must execute exactly once.","A permanent ownership record is required."],"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":{"namespace":{"type":"string","minLength":1,"maxLength":80,"pattern":"^[a-zA-Z0-9._:-]+$"},"key":{"type":"string","minLength":1,"maxLength":256},"action":{"type":"string","const":"acquire"},"holder":{"type":"string","minLength":1,"maxLength":128},"ttl_seconds":{"type":"integer","minimum":1,"maximum":3600}},"required":["namespace","key","action","holder","ttl_seconds"],"additionalProperties":false},{"type":"object","properties":{"namespace":{"type":"string","minLength":1,"maxLength":80,"pattern":"^[a-zA-Z0-9._:-]+$"},"key":{"type":"string","minLength":1,"maxLength":256},"action":{"type":"string","const":"release"},"holder":{"type":"string","minLength":1,"maxLength":128}},"required":["namespace","key","action","holder"],"additionalProperties":false},{"type":"object","properties":{"namespace":{"type":"string","minLength":1,"maxLength":80,"pattern":"^[a-zA-Z0-9._:-]+$"},"key":{"type":"string","minLength":1,"maxLength":256},"action":{"type":"string","const":"status"}},"required":["namespace","key","action"],"additionalProperties":false}]},"output_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"action":{"type":"string","enum":["acquire","release","status"]},"lease_hash":{"type":"string"},"active":{"type":"boolean"},"acquired":{"type":"boolean"},"renewed":{"type":"boolean"},"released":{"type":"boolean"},"held_by_caller":{"anyOf":[{"type":"boolean"},{"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"}]}},"required":["action","lease_hash","active","acquired","renewed","released","held_by_caller","expires_at"],"additionalProperties":false},"payment":{"kind":"free"},"side_effects":["Acquire creates or renews a temporary lease.","Release removes a lease only when called by its current holder."],"retention":"Only hashes of the namespace, key, and holder remain in Valkey until the lease TTL expires. Raw identifiers are never returned.","limits":{"max_ttl_seconds":3600,"max_key_bytes":256,"max_client_requests_per_minute":30,"max_global_requests_per_minute":120},"examples":{"input":{"action":"acquire","namespace":"index:example.invalid","key":"sitemap-refresh","holder":"agent-a","ttl_seconds":45},"output":{"action":"acquire","lease_hash":"sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc","active":true,"acquired":true,"renewed":false,"released":false,"held_by_caller":true,"expires_at":"2026-07-24T12:00:45.000Z"},"negative":[{"scenario":"The underlying refresh itself must execute exactly once.","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/freshness-lease","execute":"/v1/tools/freshness-lease"}},"meta":{"request_id":"req_f2c11e9a28b3434cab5653af1dc6c0c3","observed_at":"2026-07-25T00:58:03.219Z"}}