metrecept-opensource

Cache: Prewarm cache

metrecept_prewarm_cache

Refresh an about-to-expire Anthropic prompt-cache breakpoint with a one-token call so the next real turn reads the cache instead of paying for a fresh cache write.

Instructions

Refresh an about-to-expire Anthropic prompt-cache breakpoint for a session with a one-token call, so the next real turn reads the cache instead of paying a fresh cache write. Use it from an idle timer when a long Claude conversation is about to sit past the cache TTL. Not for the gateway's own exact-replay cache (it never touches it): use metrecept_create_chat_completion. Not for OpenAI or other vendors, whose prompt caching is automatic. Sends your transcript and your upstream key exactly like a chat call; nothing is stored. Unbilled by the gateway (returns billed:false, billed_usd 0; the vendor still charges its own tokens) and audit-logged. Errors: 400 prewarm_unsupported_model for non-claude models, 400 cache_autopilot_disabled when the gateway has cache autopilot off, 401/402 for a missing upstream key. Requires a Metrecept API key (METRECEPT_API_KEY env on stdio, or Authorization: Bearer on remote HTTP); results are scoped to that key's tenant only.

Input Schema

Name	Required	Description
`model`	Yes	Anthropic model id, must start with "claude" (e.g. "claude-sonnet-4-5"); other vendors cache automatically and are refused.
`messages`	Yes	The conversation's current transcript (system, user and assistant turns in order). The cached prefix is computed from it; nothing is stored.
`session_id`	Yes	Session id of the conversation to keep warm; the same id the client sends on its real chat turns.
`upstream_api_key`	No	Optional Anthropic key for this call (else the configured upstream key env); forwarded, never stored.

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.4.1Oct 25, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does: discloses that it sends transcript and upstream key, that nothing is stored, that it is unbilled by the gateway (returns billed:false, billed_usd 0) while the vendor still bills, that it is audit-logged, and lists specific error codes (400 prewarm_unsupported_model, 400 cache_autopilot_disabled, 401/402).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the action and the when-to-use, then progressively less essential details (billing, errors, auth). Dense but nearly every clause carries operational value; only the auth/tenant sentence is slightly redundant given the schema's upstream_api_key note.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Output schema exists, so return values need no explanation; the description nevertheless covers auth (METRECEPT_API_KEY / Bearer), tenant scoping, billing semantics, storage behavior, and enumerated errors — everything an agent needs to invoke and interpret the tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all four parameters are already documented in the schema. The description restates the claude-prefix constraint on model and the transcript/key-forwarding nature of messages, adding little beyond the schema; baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource+mechanism: refresh an about-to-expire Anthropic prompt-cache breakpoint via a one-token call. It also names exactly which caches it does NOT operate on (the gateway's exact-replay cache) and points to the sibling tool for that path.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit trigger ('from an idle timer when a long Claude conversation is about to sit past the cache TTL') plus named exclusions: not for the gateway's exact-replay cache (use metrecept_create_chat_completion) and not for OpenAI/other vendors. An agent can decide between it and siblings without inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.