Smarter Tool Call Results Cache

The one cache of tool call results.

An LLM’s tool call is answered by an MCP server, an Extension or the Smarter Project MCP server, and each caches the results it can with cached_tool_call(), so that the same call, from any LLMClient or conversation, is answered without running the tool again. The rules live here, once:

The key is the caller’s namespace, its key (plain values that identify the tool and everything else that can change its result), and the call’s arguments, as canonical JSON.
A result is JSON (ToolCall), so that it can be stored, and shared by every caller.
An error is never stored, whether the call raises it or returns it. A returned error is recognized by the call’s is_error check, is_error_result() by default.
A timeout of 0 or less runs the call without the cache.
The result says whether it came from the cache, for the caller’s signals and logs.

Each caller decides what may be cached at all: a tool that may change something, or whose result depends on who calls it, is called with a timeout of 0.

Example usage:

result = cached_tool_call(
    "mcpclient", (mcpclient.pk, mcpclient.fingerprint, "tool", "search"), {"query": "dns"}, 3600, run
)
result.value, result.cached

class smarter.lib.cache.tool_results.CachedToolResult(value, cached)[source]

Bases: object

The result of a tool call.

Parameters:

value (JsonValue) – The tool’s result.
cached (bool) – True if the result came from the cache, without running the tool.

__init__(value, cached)

cached: bool

value: JsonValue

smarter.lib.cache.tool_results.ERROR_KEY = 'error': The key of a tool’s result that is a JSON object when it is an error, e.g. an Extension tool’s or a budget refusal.

smarter.lib.cache.tool_results.ERROR_TEXT_PREFIX = 'Error:': How a tool’s result that is text begins when it is an error, e.g. an MCP tool’s.

smarter.lib.cache.tool_results.ToolCall

it takes no arguments, and returns the tool’s result as JSON.

It reports an error by raising, or by returning a result that its is_error check recognizes. Either way, the error is returned to the LLM and never cached.

Type:: A tool call, ready to run

alias of Callable[[], JsonValue]

smarter.lib.cache.tool_results.ToolCallErrorCheck

Whether a tool’s result is an error.

See is_error_result().

alias of Callable[[JsonValue], bool]

smarter.lib.cache.tool_results.ToolCallKeyPart = str | int | float | bool | None: A plain value that identifies a tool call, e.g. an id, a version or a tool’s name.

smarter.lib.cache.tool_results.cached_tool_call(namespace, key, arguments, timeout, call, is_error=<function is_error_result>)[source]

Return a tool call’s result, cached for timeout seconds, unless it is an error.

Parameters:

namespace (str) – The kind of tool, e.g. mcpclient, so that two kinds never share a key.
key (tuple[str | int | float | bool | None, ...]) – Plain values that identify the tool, and everything else that can change its result, e.g. an MCPClient’s id and fingerprint, and the tool’s name.
arguments (BaseModel | JsonValue) – The call’s arguments.
timeout (int) – Seconds to cache the result. 0 or less runs the call without the cache.
call (Callable[[], JsonValue]) – Runs the tool, and returns its result. See ToolCall.
is_error (Callable[[JsonValue], bool]) – Whether a result is an error, which is returned but not cached.

Return type:

CachedToolResult

Returns:

The result, and whether it came from the cache.

Raises:

Exception – Whatever call raises, which is not cached either.

smarter.lib.cache.tool_results.canonical_arguments(arguments)[source]

Return a tool call’s arguments in the form that is part of its cache key.

Parameters:: arguments (BaseModel | JsonValue) – Validated arguments, as a Pydantic model, or the LLM’s JSON arguments.
Return type:: str
Returns:: A model’s JSON, in the order of its fields, or the JSON with its keys sorted.

smarter.lib.cache.tool_results.is_error_result(value)[source]

Return whether a tool’s result is an error, by the conventions that Smarter’s tools follow.

Parameters:: value (JsonValue) – The tool’s result.
Return type:: bool
Returns:: True for text that begins with ERROR_TEXT_PREFIX, a JSON object with an ERROR_KEY, or that object serialized as text.