Agent Tool Health Self-Check Prompt Template

This prompt is for agent developers and platform reliability engineers who need their agents to assess tool health before execution. It produces a structured self-check that evaluates tool availability, recent failure patterns, and degraded-mode readiness. Use this when your agent must decide whether to proceed with a tool call, switch to a fallback, or halt and escalate. The prompt acts as a pre-flight gate, forcing the agent to reason explicitly about the risk of a tool call before committing to an operation that might fail, time out, or corrupt state.

You should use this prompt when building agents that interact with external APIs, databases, or services where failures are routine and costly. Ideal contexts include multi-step agent workflows where a single tool failure can cascade, high-traffic systems where retry storms risk overwhelming degraded backends, and regulated environments where failed writes or partial commits create audit problems. The prompt requires the agent to have access to recent tool interaction history, including error codes, latency metrics, and any circuit breaker state. Without this context, the self-check becomes speculative and loses its value as a reliability gate.

This is not a replacement for external monitoring, circuit breakers, or health checks in the application layer. It is a prompt-level health gate that gives the agent explicit reasoning before it commits to a tool call. Do not use this prompt when the agent has no access to recent failure data, when the tool is stateless and idempotent with negligible failure cost, or when the latency overhead of the self-check itself exceeds the tool call timeout. In high-frequency loops where every millisecond counts, move health gating to the application layer and keep the agent's prompt focused on execution. After reading this section, you should understand whether your agent's reliability requirements justify a prompt-level health gate, and proceed to the prompt template to adapt it for your tool ecosystem.

This prompt template is designed to be injected into your agent's execution loop immediately before it invokes an external tool. It forces the agent to assess the current health of the target tool by examining recent failure patterns, latency signals, and the readiness of any pre-configured fallback or degraded modes. The output is a structured health card that downstream logic can use to decide whether to proceed, switch to a fallback, or abort the operation. Replace every square-bracket placeholder with runtime values from your observability layer, such as a tool's recent error rate or its circuit breaker state.

textCopy
You are an agent about to execute a tool call. Before proceeding, perform a structured health self-check on the target tool. Your goal is to prevent cascading failures by detecting degradation early.

**Tool to Assess:** [TOOL_NAME]
**Tool Description:** [TOOL_DESCRIPTION]
**Current Circuit Breaker State:** [CIRCUIT_BREAKER_STATE]
**Recent Error Rate (last 5 min):** [RECENT_ERROR_RATE]
**P95 Latency (ms, last 5 min):** [RECENT_P95_LATENCY]
**Available Fallback Tools (in priority order):** [FALLBACK_TOOL_LIST]
**Retry Budget Remaining:** [RETRY_BUDGET_REMAINING]
**Degraded Mode Policy:** [DEGRADED_MODE_POLICY]

**Instructions:**
1.  **Analyze Signals:** Evaluate the provided metrics against standard health thresholds (e.g., error rate > 5%, latency > 2x baseline).
2.  **Classify Health Status:** Assign one of the following statuses: `HEALTHY`, `DEGRADED`, `UNHEALTHY`, or `UNKNOWN`.
3.  **Recommend Action:** Based on the status, recommend one of: `PROCEED`, `USE_FALLBACK`, `SHED_LOAD`, or `ALERT_AND_ABORT`.
4.  **Select Fallback:** If the recommendation is `USE_FALLBACK`, specify which tool from the `[FALLBACK_TOOL_LIST]` is the best candidate and explain why.
5.  **Justify Decision:** Provide a concise, evidence-based rationale for your classification and recommendation.

**Output Format:**
Produce a JSON object with the following schema:
{
  "tool_name": "string",
  "health_status": "HEALTHY | DEGRADED | UNHEALTHY | UNKNOWN",
  "recommended_action": "PROCEED | USE_FALLBACK | SHED_LOAD | ALERT_AND_ABORT",
  "selected_fallback": "string | null",
  "rationale": "string"
}

To adapt this template, start by integrating it into your agent's middleware or pre-tool-call hook. The placeholders like [RECENT_ERROR_RATE] and [CIRCUIT_BREAKER_STATE] must be populated by a real-time observability system, not hardcoded. For high-risk tools where an incorrect health assessment could cause data loss or a significant user-facing outage, always route the UNKNOWN status to a human-in-the-loop review queue. The primary failure mode for this prompt is an agent that hallucinates metrics when the observability system fails to provide them; prevent this by strictly validating the input placeholders before the prompt is assembled.

The self-check prompt is not a standalone diagnostic; it is a pre-flight gate that runs before the agent commits to a tool call. Wire it into the agent's execution loop as a synchronous step after tool selection but before argument assembly and invocation. The agent should call this prompt with the target tool's recent call history, current latency metrics, and any circuit breaker state. The output is a structured health assessment that the agent's control logic uses to decide whether to proceed, switch to a fallback tool, or enter a degraded mode. This harness must treat the self-check as a blocking decision point—if the check fails or times out, the agent must not silently proceed with the tool call.

Validation and retry logic: Parse the model's output against a strict schema that includes tool_status (one of healthy, degraded, unavailable), confidence (0.0–1.0), evidence_summary (string), and recommended_action (one of proceed, retry_with_backoff, use_fallback, abort). If parsing fails or confidence is below a configured threshold (start with 0.7), retry the self-check once with the same input plus the parse error or low-confidence flag. If the second attempt also fails, treat the tool as degraded and log the self-check failure as an observability event. Model choice: Use a fast, cheap model for self-checks (e.g., a small Haiku-class model) because latency added here directly impacts the user experience. Reserve larger models for the actual tool-use reasoning. Tool use and RAG: The self-check prompt itself should not call tools. Feed it pre-computed metrics—error counts, latency p95, circuit breaker state, and recent failure signatures—from the agent's telemetry store. Do not ask the model to query live monitoring systems.

Observability and logging: Log every self-check decision with the tool name, input metrics, model output, parse result, and final action taken. Attach a trace span that links the self-check to the subsequent tool call or fallback. This trace is essential for tuning thresholds and detecting when the self-check itself becomes a bottleneck. Human review gates: For high-risk tools (write operations, financial transactions, clinical actions), add a rule that any self-check result of degraded or unavailable must escalate to a human reviewer before the agent proceeds with a fallback. The harness should queue the decision context—tool name, health assessment, proposed fallback—into a review interface rather than blocking the agent indefinitely. What to avoid: Do not run self-checks on every tool call if the tool is stateless and idempotent; cache the health assessment for a short TTL (5–30 seconds, tuned to your tool's failure dynamics). Do not let the self-check prompt grow into a general diagnostic—keep it focused on go/no-go decisions. If the agent's control logic starts second-guessing the self-check output, the prompt's thresholds or evidence requirements need recalibration, not ad-hoc overrides in code.