RED-220418: Document per-Gateway result cache and handle settings

content/develop/ai/context-engine/context-gateway/api-reference.md

@@ -67,7 +67,7 @@ The result is the tool's result.
 
 ### Result handle tools
 
-Listed in both modes when the deployment turns on result handles.
+Listed in both modes when result handles are on for the Gateway.
 
 | Tool | Arguments | Result |
 | --- | --- | --- |

content/develop/ai/context-engine/context-gateway/concepts.md

@@ -83,7 +83,9 @@ In `search` mode the agent calls `search_tools` and receives complete tool defin
 
 ## Tool policies
 
-A **tool policy** sets optional behavior for one tool of one Upstream. Both behaviors need a Gateway database, selected with the Gateway's `databaseId`, and both are off until the deployment turns them on.
+A **tool policy** sets optional behavior for one tool of one Upstream. Both behaviors need a Gateway database, selected with the Gateway's `databaseId`.
+
+Each Gateway also turns the result cache and result handles on or off for all of its tools with its `resultCache` and `resultHandles` settings, `enabled` or `disabled`. A Gateway created with a `databaseId` starts with both enabled, and a Gateway without one has both disabled. A feature serves a Gateway only when the Gateway's setting is `enabled` and the deployment turns the feature on.
 
 ### Result cache
 
@@ -98,7 +100,7 @@ All callers with access to a Gateway share its cache entries.
 
 ### Result handles
 
-A result handle holds a large tool result in the Gateway database. When the deployment turns on result handles, every eligible result over 32 kibibytes (KiB) becomes a handle, on every Gateway with a `databaseId`. The agent receives a small stub with the handle and reads the result in pages, queries, counts, or aggregates.
+A result handle holds a large tool result in the Gateway database. When result handles are on for a Gateway, every eligible result over 32 kibibytes (KiB) becomes a handle. The agent receives a small stub with the handle and reads the result in pages, queries, counts, or aggregates.
 
 A tool opts out with a `resultHandle` policy of `capture: never`, or sets its own handle lifetime with `ttlSeconds`. An agent can also hold a result of any size with `run_tool_as_handle`.
 
@@ -114,6 +116,7 @@ A handle is bound to the caller that created it, and it survives a rotation of t
 | Namespace | The prefix that makes an Upstream's tool names unique within a Gateway. |
 | Catalog | The stored list of an Upstream's tools. |
 | Tool policy | Per-tool settings for the result cache and result handles. |
+| `resultCache`, `resultHandles` | Per-Gateway settings that turn the result cache and result handles on or off. |
 | Gateway database | The Redis database that holds cached results and result handles. |
 
 ## Next steps

content/develop/ai/context-engine/context-gateway/developer-guide.md

@@ -28,7 +28,7 @@ Platform teams create the Gateway and register its Upstreams through the Control
 |:-------|:------------|:------------------|
 | Python | Your application or agent uses Python. | Install [`redis-iris`](https://pypi.org/project/redis-iris/) and follow the [quickstart](/content/develop/ai/context-engine/context-gateway/quickstart.md). `ContextGateway` lists, searches, and calls tools, and its `service` property administers Gateways. |
 | CLI | You work from a shell, a script, or continuous integration. | The `iris context-gateway` commands ship in the same [`redis-iris`](https://pypi.org/project/redis-iris/) package. |
-| TypeScript | Your application or agent uses JavaScript or TypeScript. | Install [`@redis-iris/context-gateway`](https://www.npmjs.com/package/@redis-iris/context-gateway). `ContextGatewayClient` opens MCP sessions, and `ContextGatewayService` calls the Control Plane. |
+| TypeScript | Your application or agent uses JavaScript or TypeScript. | Install [`@redis-iris/context-gateway`](https://www.npmjs.com/package/@redis-iris/context-gateway) with the `alpha` tag. `ContextGateway` opens MCP sessions, and `ContextGatewayService` calls the Control Plane. |
 | HTTP | You need language-independent access or don't want a package dependency. | No package required. Send MCP requests to the Gateway endpoint as shown in [MCP](/content/develop/ai/context-engine/context-gateway/mcp.md). |
 
 The `redis-iris` package requires Python 3.11 or later. The TypeScript client requires Node.js 22 or later.
@@ -50,7 +50,7 @@ In `full` mode, `tools/list` returns every tool under its qualified name. In `se
 
 ## Work with large results
 
-When the deployment turns on result handles, a large result comes back as a stub with a handle. Read the parts you need with the handle tools, then release it. See [Read result handles](/content/develop/ai/context-engine/context-gateway/mcp.md#read-result-handles).
+When result handles are on for the Gateway, a large result comes back as a stub with a handle. Read the parts you need with the handle tools, then release it. See [Read result handles](/content/develop/ai/context-engine/context-gateway/mcp.md#read-result-handles).
 
 ## References
 

content/develop/ai/context-engine/context-gateway/manage-gateways.md

@@ -32,7 +32,7 @@ Create a Gateway and save its `id` and `mcpEndpoint`. The Gateway serves Model C
 
 *Example set `iris_gateway_manage`, step `gateway-create`, in Python (Iris), cURL (Iris), and CLI (Iris).*
 
-To use the result cache or result handles, select a Gateway database with `databaseId`. Your administrator names the available databases.
+To use the result cache or result handles, select a Gateway database with `databaseId`. Your administrator names the available databases. A Gateway created with a `databaseId` has `resultCache` and `resultHandles` enabled unless you send them as `disabled`. Sending `enabled` without a `databaseId` returns `400`.
 
 ## List and inspect Gateways and Upstreams
 
@@ -42,10 +42,26 @@ List the deployment's Gateways and a Gateway's Upstreams, and read one by ID. Ev
 
 ## Change a Gateway
 
-Update a Gateway's `toolExposureMode` to `full` or `search`, its display name, or its `databaseId`. Agents see a new mode on their next request. See [Tool exposure modes](/content/develop/ai/context-engine/context-gateway/concepts.md#tool-exposure-modes).
+Update a Gateway's `toolExposureMode` to `full` or `search`, its display name, its `databaseId`, or its `resultCache` and `resultHandles` settings. Agents see a new mode on their next request. See [Tool exposure modes](/content/develop/ai/context-engine/context-gateway/concepts.md#tool-exposure-modes).
 
 *Example step `gateway-update-mode`.*
 
+### Turn the result cache and result handles on or off
+
+Set `resultCache` or `resultHandles` to `enabled` or `disabled` on a Gateway update. Every Gateway response returns both settings. A Gateway's setting takes effect only when the deployment also turns the feature on. See [Result cache and result handles](/content/operate/iris/context-gateway/self-managed/configuration.md#result-cache-and-result-handles).
+
+```json
+{"revision": "<revision>", "resultCache": "enabled", "resultHandles": "disabled"}
+```
+
+| Change | What to send |
+| --- | --- |
+| Remove the Gateway database | `"databaseId": null` with `"resultCache": "disabled"` and `"resultHandles": "disabled"` in the same request. Without them, the update returns `400`. |
+| Add a Gateway database to a Gateway that had none | `databaseId` with `"resultCache": "enabled"`, `"resultHandles": "enabled"`, or both. Adding a database alone keeps both settings as they were, which is `disabled` for a Gateway created without one. |
+| Stop caching or handles for a Gateway | `"disabled"` for that setting. The Gateway stops reading and writing cache entries, or stops creating handles and removes the handle tools from `tools/list`. Stored entries and handles stay until their TTL. |
+
+*Example step `gateway-update-features`.*
+
 ## Register an MCP server
 
 Register an MCP server as an Upstream with a namespace, its endpoint, and its credential. Any MCP server that serves Streamable HTTP works, including third-party and in-house servers. The Gateway discovers the server's tools during registration.
@@ -77,7 +93,7 @@ Disable an Upstream to take its tools away from agents without deleting it. Its
 
 ## Set tool policies
 
-Set a tool's policies with `toolPolicies` on an Upstream update. The result cache is opt-in for each tool. Result handles are on for every eligible result once the deployment turns them on, so a tool policy only opts a tool out or changes its handle lifetime.
+Set a tool's policies with `toolPolicies` on an Upstream update. The result cache is opt-in for each tool. Result handles are on for every eligible result while they are on for the Gateway, so a tool policy only opts a tool out or changes its handle lifetime.
 
 | Policy | Member | Effect |
 | --- | --- | --- |
@@ -89,6 +105,7 @@ Set a tool's policies with `toolPolicies` on an Upstream update. The result cach
 
 - Cache only tools whose data changes more slowly than the time to live (TTL). All callers with access to the Gateway share its cache entries.
 - A tool whose definition says `readOnlyHint: false` or `destructiveHint: true` is never cached.
+- A new or changed `resultCache` policy returns `400` while the Gateway's `resultCache` is `disabled`, including on a Gateway without a `databaseId`. A stored policy sent back unchanged is kept.
 - When you move an Upstream to a new endpoint, the response lists any policies it removed in `droppedToolPolicies`.
 
 ## Rotate an Upstream credential

content/develop/ai/context-engine/context-gateway/mcp.md

@@ -74,7 +74,7 @@ This client connects, lists tools, and calls one in either mode.
 
 ## Read result handles
 
-When the deployment turns on result handles, the Gateway lists these tools in both modes:
+When result handles are on for the Gateway, it lists these tools in both modes:
 
 | Tool | What it does |
 | --- | --- |

content/develop/ai/context-engine/context-gateway/quickstart.md

@@ -28,7 +28,7 @@ This walkthrough needs no agent framework or model-provider key.
 
 Follow one tab throughout the page. The Python package and command-line interface (CLI) are alpha prereleases pinned to the version used here. Both require Python 3.11 or later. The cURL and CLI examples use Bash and jq.
 
-<!-- TODO: Update the pin to redis-iris 0.1.0a5 when it publishes. In a5 the SDK's data-plane client is renamed from ContextGatewayClient to ContextGateway. Recheck the client property sentence below. -->
+<!-- TODO: Move the pin when a redis-iris release depends on redis-context-gateway 0.1.0a5, where the SDK's data-plane client is renamed from ContextGatewayClient to ContextGateway. Recheck the client property sentence below. -->
 
 **Python and CLI**
 
@@ -39,7 +39,7 @@ python -m pip install redis-iris==0.1.0a4
 ```
 
 > [!NOTE]
-> For TypeScript, use the generated client [@redis-iris/context-gateway](https://www.npmjs.com/package/@redis-iris/context-gateway). It opens Model Context Protocol (MCP) sessions with `ContextGatewayClient` and calls the Control Plane with `ContextGatewayService`. See the [developer guide](/content/develop/ai/context-engine/context-gateway/developer-guide.md).
+> For TypeScript, use the generated client [@redis-iris/context-gateway](https://www.npmjs.com/package/@redis-iris/context-gateway). Install it with `npm install @redis-iris/context-gateway@alpha`. It opens Model Context Protocol (MCP) sessions with `ContextGateway` and calls the Control Plane with `ContextGatewayService`. See the [developer guide](/content/develop/ai/context-engine/context-gateway/developer-guide.md).
 
 **HTTP**
 

content/operate/iris/context-gateway/self-managed/_index.md

@@ -55,7 +55,7 @@ Use separately managed Redis deployments for metadata, credentials, and customer
 | Gateway MCP | `/v1/gateways/{gatewayId}/mcp` | The Streamable HTTP MCP endpoint for one Gateway. |
 | Protected resource metadata | `/.well-known/oauth-protected-resource/v1/gateways/{gatewayId}/mcp` | Names the identity provider for MCP client sign-in. |
 | Control Plane | `/v1/gateways` | Administration of Gateways and Upstreams. |
-| Health | `/v1/health/live`, `/v1/health/ready` | Liveness and readiness on both planes. |
+| Health | `/health/liveness`, `/health/readiness` | Liveness and readiness on both planes. |
 | Identity Service | `/v1/api-keys` | Administration of agent keys. |
 
 ## Get started

content/operate/iris/context-gateway/self-managed/api-examples.md

@@ -51,7 +51,7 @@ export OPERATIONS_ID="$(jq -er '.id' operations.json)"
 jq '{id, mcpEndpoint, toolExposureMode}' front-desk.json operations.json
 ```
 
-Result handles also need `result_handles.enabled` on the Data Plane. See [Result cache and result handles](/content/operate/iris/context-gateway/self-managed/configuration.md#result-cache-and-result-handles).
+The `search` mode Gateway has a `databaseId`, so it starts with `resultCache` and `resultHandles` enabled. Result handles also need `result_handles.enabled` on the Data Plane. See [Result cache and result handles](/content/operate/iris/context-gateway/self-managed/configuration.md#result-cache-and-result-handles).
 
 <!-- TODO: Run every step against a deployed chart before review. -->
 

content/operate/iris/context-gateway/self-managed/configuration.md

@@ -118,7 +118,9 @@ dataplane:
 | `result_handles.max_capture_bytes` | `8388608` | Results above this size come back whole. |
 | `result_handles.preview_items`, `preview_bytes` | `3`, `2048` | The size of a handle stub's preview. |
 
-The result cache still needs a policy for each tool. Result handles apply to every eligible result on every Gateway with a `databaseId`, unless a tool's policy opts out. Both need the Gateway's `databaseId` to name a registered database.
+These settings turn each feature on for the deployment. Each Gateway then has its own `resultCache` and `resultHandles` settings, and a feature serves a Gateway only when both the deployment and the Gateway turn it on. Both need the Gateway's `databaseId` to name a registered database.
+
+The result cache still needs a policy for each tool. Result handles apply to every eligible result on a Gateway that has them on, unless a tool's policy opts out. See [Turn the result cache and result handles on or off](/content/develop/ai/context-engine/context-gateway/manage-gateways.md#turn-the-result-cache-and-result-handles-on-or-off).
 
 ## Trust a private CA
 

content/operate/iris/context-gateway/self-managed/deploy.md

@@ -90,7 +90,7 @@ Check each value in `gateway-values.yaml` before you install. If one is wrong, y
 | `publicBaseURL` is the Data Plane origin that MCP clients reach | `mcpEndpoint` in Gateway responses points to an address clients cannot reach, and identity provider sign-in fails | Set the public origin, including `https://`. |
 | `identityService.allowInsecureTransport` is `true` for an `http://` Identity Service URL | The Data Plane cannot check agent keys | Set it, or use an `https://` URL. |
 | The admin, internal, and runtime tokens come from three different Secrets or keys | Rendering fails, or the Identity Service cannot check keys | Create three distinct token files. |
-| `license` points to a valid license | `/v1/health/ready` answers `503` | Mount the license file as issued. |
+| `license` points to a valid license | `/health/readiness` answers `503` | Mount the license file as issued. |
 | Both component `image.repository` and `image.tag` are set | Pods `ImagePullBackOff` | Set both to the release images. |
 {{< /table-scrollable >}}
 
@@ -134,8 +134,8 @@ kubectl -n <namespace-name> port-forward svc/ids-iris-identity-service 9200:9200
 Then check readiness on both planes:
 
 ```bash
-curl -sS http://localhost:9100/v1/health/ready
-curl -sS http://localhost:8083/v1/health/ready
+curl -sS http://localhost:9100/health/readiness
+curl -sS http://localhost:8083/health/readiness
 ```
 
 ## 6. Create a Gateway

content/operate/iris/context-gateway/self-managed/operations.md

@@ -13,13 +13,13 @@ hideListLinks: true
 
 ## Check service health
 
-Both planes serve `/v1/health/live` and `/v1/health/ready` without a credential. Readiness answers `503` while a token source cannot be read or is empty, or the license is not valid. The response does not name the failed check, so read the plane's logs.
+Both planes serve `/health/liveness` and `/health/readiness` without a credential. Readiness answers `503` while a token source cannot be read or is empty, or the license is not valid. The response does not name the failed check, so read the plane's logs.
 
 With the ports forwarded as in [Deploy](/content/operate/iris/context-gateway/self-managed/deploy.md#5-verify-pods-and-health):
 
 ```bash
-curl -sS http://localhost:9100/v1/health/ready
-curl -sS http://localhost:8083/v1/health/ready
+curl -sS http://localhost:9100/health/readiness
+curl -sS http://localhost:8083/health/readiness
 ```
 
 `iris context-gateway health` probes both planes, and `iris context-gateway service diagnose <gateway-id>` reports a Gateway's setup, including Upstreams with empty catalogs.
@@ -51,6 +51,7 @@ A cache hit carries `resultCache` in the call's invocation metadata. Every other
 | Bypass `reason` | What to check |
 | --- | --- |
 | `not_opted_in` | The tool has no result cache policy. |
+| `disabled` | The Gateway's `resultCache` is `disabled`. |
 | `no_database` | The Gateway has no `databaseId`. |
 | `unknown_database` | The Gateway's database is not registered on the Data Plane. Declare it on both planes. |
 | `vetoed_by_annotation` | The tool's definition says it is not read-only, or that it is destructive. |
@@ -88,6 +89,8 @@ Upgrade both planes together and roll forward, not back. An older Data Plane can
 
 After an upgrade, refresh an Upstream's catalog when the release notes ask for it.
 
+Gateways stored before the per-Gateway `resultCache` and `resultHandles` settings read as `enabled` when they have a `databaseId` and `disabled` otherwise, so their behavior does not change. Scripts that remove or add a Gateway's `databaseId`, or set `resultCache` tool policies, may need the changes in [Turn the result cache and result handles on or off](/content/develop/ai/context-engine/context-gateway/manage-gateways.md#turn-the-result-cache-and-result-handles-on-or-off).
+
 ```bash
 helm upgrade gateway redis-ai/redis-context-gateway \
   --version <new-chart-version> \