Tool Result Expiry and Refresh Prompt Template

This prompt is for infrastructure teams building AI agents that call external tools returning time-sensitive data. It solves the problem of an agent naively reusing a cached tool result that has become stale, or wasting resources by refreshing data that is still valid. Use this prompt when your agent's tool results have a known shelf life, when the cost of a stale decision exceeds the cost of a refresh call, or when you need an auditable decision trail for why a result was reused or refreshed.

Deploy this prompt when you have already instrumented your tool layer to return structured metadata alongside each result. The prompt expects a [TOOL_OUTPUT] that includes a timestamp, a declared TTL, and a unique result identifier. It is designed for high-stakes operational domains—such as incident response, financial reconciliation, or deployment verification—where acting on data that is even a few minutes old can cause cascading failures. Do not use this prompt for user-facing chat memory or personalization; those workflows require session-scoped eviction strategies, not per-result expiry logic. This prompt also assumes your agent has a deterministic cache layer available as a fallback, and that the model's role is to reason about the decision to refresh, not to implement the cache itself.

Before integrating this prompt, ensure your evaluation harness can measure two distinct failure modes: false staleness (refreshing a result that was still valid, wasting latency and cost) and missed expiry (reusing a result that had expired, leading to incorrect downstream actions). If you cannot instrument both metrics, you are not ready to tune this prompt. The next section provides the copy-ready template. Wire it into your agent's pre-tool-call reasoning step, not as a post-hoc audit log.

This prompt template is designed to be injected into your agent's tool-response processing layer. It receives a tool result, the current time, and any relevant caching policy, then outputs a structured annotation that includes an expiry timestamp, a refresh decision, and the reasoning behind that decision. The template uses square-bracket placeholders that you must replace with values from your application's state manager, tool registry, or context window before sending the request to the model.

textCopy
You are a tool-result freshness evaluator. Your job is to annotate a tool result with expiry metadata and decide whether the result should be refreshed or reused.

## INPUT
- Current time: [CURRENT_TIMESTAMP]
- Tool name: [TOOL_NAME]
- Tool call arguments: [TOOL_ARGUMENTS]
- Tool result: [TOOL_RESULT]
- Caching policy for this tool: [CACHING_POLICY]
- Prior refresh history for this tool call signature: [REFRESH_HISTORY]

## TASK
1. Determine the expiry timestamp for this result based on the caching policy, the nature of the data, and any time-sensitivity hints in the result itself.
2. Decide whether the result should be REFRESHED or REUSED.
3. Provide a concise reason for your decision.

## CONSTRAINTS
- If the caching policy specifies a TTL, use it as the maximum expiry window unless the result contains explicit server-provided expiry headers.
- If the result contains an error, timeout, or partial data, mark it as REFRESH with an immediate expiry.
- If the result is older than the TTL at the current time, mark it as REFRESH.
- If the refresh history shows more than [MAX_CONSECUTIVE_REFRESHES] consecutive refreshes for the same arguments, mark as REUSED and flag for human review.
- Never invent expiry times. If no policy or data-driven hint exists, default to [DEFAULT_TTL_SECONDS] seconds from the result's retrieval time.

## OUTPUT SCHEMA
Return a single JSON object with no additional text:
{
  "tool_name": "string",
  "result_retrieved_at": "ISO8601 timestamp",
  "expires_at": "ISO8601 timestamp or null if already expired",
  "decision": "REFRESH | REUSE",
  "reason": "string (max 200 characters)",
  "requires_human_review": boolean
}

To adapt this template, replace each square-bracket placeholder with values from your tool execution harness. [CACHING_POLICY] should be a structured description of the tool's TTL, invalidation conditions, and scope boundaries—ideally sourced from your tool registry. [REFRESH_HISTORY] should include timestamps and outcomes of recent calls with the same tool and arguments, enabling the model to detect refresh loops. [MAX_CONSECUTIVE_REFRESHES] and [DEFAULT_TTL_SECONDS] are configuration constants you should set based on your system's tolerance for stale data and redundant tool calls. If your application cannot provide a structured caching policy, replace that placeholder with a static rule set such as "financial data expires in 60 seconds; static reference data expires in 3600 seconds."

Before deploying this prompt into a production agent loop, validate the model's output against your expected schema. A common failure mode is the model returning an expiry timestamp that is already in the past when the decision is REUSE, or returning REUSE for an error response. Add a post-processing validator that rejects any annotation where decision is REUSE but expires_at is earlier than result_retrieved_at, and any annotation where the tool result contains an error string but decision is not REFRESH. For high-risk domains where stale data could cause incorrect actions—such as financial transactions or clinical data lookups—route any requires_human_review: true annotation to a review queue and log the full annotation alongside the original tool result for auditability.

The Tool Result Expiry and Refresh prompt is not a standalone artifact—it is a decision module that sits between your tool execution layer and the agent's reasoning context. In practice, you will invoke this prompt every time a tool result is about to be passed into the model's context window, or when the agent explicitly requests a tool call that might be served from cache. The harness is responsible for: (1) attaching expiry metadata to every tool result as it arrives, (2) calling the expiry/refresh prompt with the current time, the cached result, and the tool's refresh cost, (3) parsing the structured decision output, and (4) either injecting the cached result, triggering a refresh call, or blocking the agent with a staleness warning.

The prompt expects a specific input shape. Your harness must assemble a JSON object containing: current_timestamp (ISO-8601), tool_name, cached_result (the full payload from the prior call), result_timestamp (when the result was originally fetched), ttl_seconds (the declared time-to-live for this tool's results), refresh_cost (a numeric or categorical estimate of latency/token/dollar cost to refresh), and dependency_state (a map of upstream tool results this result depends on, with their own timestamps). The output schema must be enforced: a JSON object with decision (one of USE_CACHED, REFRESH, BLOCK_STALE), confidence (0-1), reasoning (a short string for logs), and suggested_next_refresh_check (ISO-8601). Use structured output mode or a JSON schema validator in your model API call. If the model returns an invalid decision value or missing fields, your harness must default to BLOCK_STALE and log the parse failure—never silently inject unvalidated cached data into the agent's context.

Retry logic is critical here. If the harness decides to REFRESH and the subsequent tool call fails (timeout, 5xx, rate limit), do not retry the expiry prompt itself. Instead, implement a fallback chain: first, check if the cached result is within a grace period (e.g., 2x TTL for read-only data). If within grace, inject the cached result with a stale_flag: true annotation so the agent can reason about data freshness. If beyond grace, escalate to BLOCK_STALE and surface the failure to the agent with a clear message: 'Tool [tool_name] result is expired and refresh failed. Provide a partial response or ask the user for guidance.' Log every decision—USE_CACHED, REFRESH, BLOCK_STALE, and fallback—with the tool name, timestamps, TTL, and decision reasoning. This log becomes your audit trail for debugging agent errors caused by stale data.

Model choice matters. For low-latency, high-throughput agents, use a fast classifier model (e.g., a small fine-tuned model or a rapid-inference endpoint) for the expiry decision, reserving larger models for the agent's core reasoning. The expiry prompt is a classification task with a constrained output schema, so it benefits from models with strong instruction-following and JSON mode support. If you are using the same model for both the agent and the expiry check, be aware of context window pressure: the expiry prompt's input includes the full cached result, which may be large. Consider compressing cached results before passing them to the expiry prompt, or using a separate, smaller context window for expiry decisions.

Testing this harness requires a dedicated eval suite. Build test cases for: (1) a result well within TTL—expect USE_CACHED with high confidence; (2) a result just past TTL but with low refresh cost—expect REFRESH; (3) a result far past TTL with high refresh cost and stale dependencies—expect BLOCK_STALE; (4) a result with a dependency that updated more recently than the result itself—expect REFRESH even if within TTL; (5) malformed input (missing timestamp, invalid TTL)—expect the harness to reject and log before calling the model. Run these evals on every prompt or model version change. In high-risk domains (finance, healthcare, safety-critical operations), add a human-review gate for any BLOCK_STALE decision before the agent's response reaches the user. The harness should also emit a metric—stale_result_blocks_total—so you can monitor whether your TTLs are tuned correctly or causing excessive blocking.