# TOOL.CACHE.SET

> Store or replace an entry in a tool cache namespace, with optional TTL and token usage.

URL: https://docs.hotkv.com/commands/tool-cache-set/

```
TOOL.CACHE.SET namespace key value [TTL seconds] [MODEL model [INPUT n] [OUTPUT n] [CACHEREAD n] [CACHEWRITE5M n] [CACHEWRITE1H n]]
```

- Group: Keyed caches
- Complexity: O(1)
- HotKV Cloud: Performance and Scale plans
- On-Premise: requires the tool-cache license feature

The tool cache memoizes the results of deterministic tool or function calls an agent makes, keyed by a deterministic string built from the call (for example the tool name and its arguments). `TOOL.CACHE.SET` stores `value` under `key` (the deterministic input string) in
`namespace`. If the key is already cached, its value, usage and expiry are
replaced. The namespace must exist (see [TOOL.CACHE.CREATE](https://docs.hotkv.com/commands/tool-cache-create/index.md)).

## Options

| Option | Effect |
| --- | --- |
| `TTL seconds` | Time to live for this entry. `0` or omitted uses the namespace's default TTL. |
| `MODEL model` | The model that produced the response. Required when you pass any token count below. |
| `INPUT n` | Uncached input tokens the original call used. |
| `OUTPUT n` | Output tokens the original call used. |
| `CACHEREAD n` | Provider cache-read tokens the original call used. |
| `CACHEWRITE5M n` | Tokens the original call wrote to a 5-minute provider cache. |
| `CACHEWRITE1H n` | Tokens the original call wrote to a 1-hour provider cache. |

Options come in name and value pairs after `value`, in any order.

The usage options record what the original, uncached model call consumed.
Every later hit on the entry adds those tokens to the namespace's
`usage_saved_*` counters, and when the model has a price (built in, or set
with [LLMSTATS.PRICE](https://docs.hotkv.com/commands/llmstats-price/index.md)) it also adds the cost those
tokens would have had to `usage_saved_cost_usd`. Token counts are
non-negative integers. Passing a token count without `MODEL` is rejected.

## Return value

| Case | RESP2 | RESP3 |
| --- | --- | --- |
| Entry stored | Simple string `OK` | Same |

Errors:

- `ERR namespace not found` if the namespace does not exist.
- `ERR syntax error` if an option has no value.
- `ERR unknown option` for any other option name.
- `ERR invalid TTL` if `TTL` is not a non-negative integer.
- `ERR usage token counts (INPUT, OUTPUT, CACHEREAD, CACHEWRITE5M, CACHEWRITE1H) need MODEL` if you pass a token count without `MODEL`.
- `ERR invalid INPUT`, `ERR invalid OUTPUT`, `ERR invalid CACHEREAD`, `ERR invalid CACHEWRITE5M` or `ERR invalid CACHEWRITE1H` if a token count is not a non-negative integer.
- `ERR wrong number of arguments for 'tool.cache.set' command` if the argument count is wrong.
- `NOLICENSE tool-cache requires a HotKV license. Contact sales@hotkv.com` if your license does not include the `tool-cache` feature.

## Examples

```
127.0.0.1:6379> TOOL.CACHE.SET sqltool "SELECT 1" "[[1]]"
OK
127.0.0.1:6379> TOOL.CACHE.SET sqltool "SELECT 2" "[[1]]" TTL 120
OK
```

## Compatibility

HotKV-only command. Redis and Valkey have no equivalent.

## See also

[TOOL.CACHE.CREATE](https://docs.hotkv.com/commands/tool-cache-create/index.md), [TOOL.CACHE.GET](https://docs.hotkv.com/commands/tool-cache-get/index.md), [TOOL.CACHE.DEL](https://docs.hotkv.com/commands/tool-cache-del/index.md), [TOOL.CACHE.STATS](https://docs.hotkv.com/commands/tool-cache-stats/index.md), [TOOL.CACHE.FLUSH](https://docs.hotkv.com/commands/tool-cache-flush/index.md), [TOOL.CACHE.DROP](https://docs.hotkv.com/commands/tool-cache-drop/index.md), [TOOL.CACHE.LIST](https://docs.hotkv.com/commands/tool-cache-list/index.md), [AI features guide](https://docs.hotkv.com/ai-features/index.md)