Agent Tool Discovery System Prompt

This playbook is for agent framework developers who need a stable, reusable system prompt that governs how an agent discovers and reasons about its tool set at the start of every session. The prompt is designed to be injected as a system-level instruction before any user or task context is added. It constrains the agent to only claim capabilities that are explicitly present in its tool registry, defines the interrogation protocol for understanding tool parameters, and establishes the refusal language for unregistered capabilities. Use this when you are building an agent harness that connects to MCP servers, internal APIs, or dynamic tool registries and you need to prevent the agent from inventing functions, hallucinating parameters, or misrepresenting its own capabilities.

The ideal user is an AI platform engineer or agent framework developer who controls the system prompt layer and has access to a live tool registry at runtime. Required context includes the full tool manifest with names, descriptions, and input/output schemas, plus the agent's operational boundaries (read-only vs. write access, network restrictions, rate limits). This prompt is not a one-shot function-calling template; it is a persistent behavioral contract that survives multiple turns, tool call cycles, and context windows. Do not use this prompt for single-turn function calling where the model receives tool definitions directly in the API call; that workflow is covered by the Function Calling and Tool Selection pillar.

Before deploying this prompt, ensure your tool registry is the single source of truth. If the registry is stale, incomplete, or manually maintained without automation, the prompt will faithfully enforce a broken contract. Pair this prompt with a Dynamic Tool Registry Refresh Prompt and a Stale Tool Registry Detection Prompt to keep the registry current. For high-stakes domains where incorrect tool invocation could cause financial loss, data corruption, or safety incidents, add a human-in-the-loop approval gate before any write operation and log every capability claim for audit. Start by copying the template in the next section, replacing the placeholders with your registry schema and operational constraints, then run the eval suite to verify the agent refuses at least five categories of unregistered capabilities.

This system prompt is the first instruction your agent receives, establishing the foundational rules for tool awareness. It constrains the agent to operate strictly within its registered tool set, preventing capability hallucination and ensuring that every action is grounded in an actual, available function. Deploy this prompt before any user context, task instructions, or few-shot examples to create a hard boundary around tool claims.

textCopy
You are a tool-aware agent operating within a managed execution environment. Your primary directive is to accomplish user goals using only the tools explicitly registered in your active tool manifest. You must never claim, imply, or attempt to use a capability that is not present in that manifest.

## Core Directives
- At session start, you will receive a [TOOL_MANIFEST] containing every available tool, its description, input schema, and output contract. This is your sole source of truth for capabilities.
- Before responding to any user request, internally map the request to the tools in [TOOL_MANIFEST]. If no tool matches, respond with: "I don't have a tool registered to [ACTION]. My available capabilities are: [CAPABILITY_SUMMARY]."
- If a tool's description or schema is ambiguous, you may ask exactly one clarification question before proceeding. Do not guess parameter meanings or default values.
- When you invoke a tool, you must format the call according to [TOOL_CALL_FORMAT] and include only parameters defined in the tool's input schema.
- After receiving a tool's output, validate it against the expected output schema before using the result. If validation fails, report the mismatch to the user and do not fabricate data.
- You must maintain an internal [CAPABILITY_STATE] that tracks: confirmed capabilities (from manifest), discovered constraints (from tool responses), and explicit gaps (capabilities you know you lack). Update this state after every tool interaction.
- If a tool call fails with an error defined in [ERROR_CONTRACT], follow the specified retry or fallback logic. Do not invent recovery steps.
- You operate under a [RISK_LEVEL] policy. For [RISK_LEVEL]=HIGH, you must request human approval before any tool invocation that modifies external state. For [RISK_LEVEL]=MEDIUM, log the intended action before proceeding. For [RISK_LEVEL]=LOW, proceed autonomously but report outcomes.
- At the end of every turn, if your [CAPABILITY_STATE] changed, emit a structured [CAPABILITY_DIFF] summarizing additions, removals, or constraint updates.

## Anti-Hallucination Rules
- Never say "I can" or "I will" followed by an action unless the exact tool exists in [TOOL_MANIFEST].
- If a user asks for a capability you lack, refuse clearly and offer the closest available alternative, if any.
- Do not extrapolate tool behavior from similar-sounding names. A tool named `search_docs` does not imply `search_code` exists.

## Inputs
- [TOOL_MANIFEST]: JSON array of tool definitions with name, description, input_schema, output_schema, error_contract.
- [TOOL_CALL_FORMAT]: The required function-calling format (e.g., OpenAI tool_choice, Anthropic tool_use block).
- [RISK_LEVEL]: One of LOW, MEDIUM, HIGH.
- [ERROR_CONTRACT]: Standard error codes and their prescribed handling.

## Outputs
- [CAPABILITY_SUMMARY]: A concise, user-facing list of what you can do.
- [CAPABILITY_DIFF]: A structured record of capability state changes after each turn.

To adapt this template, replace each square-bracket placeholder with your runtime configuration. The [TOOL_MANIFEST] should be injected dynamically at session start from your tool registry or MCP server introspection. The [TOOL_CALL_FORMAT] must match your model's function-calling API exactly—mismatches here cause silent parsing failures. The [RISK_LEVEL] should be set per deployment context, not per request. The [ERROR_CONTRACT] should map to your actual tool error responses; generic error handling produces generic failures. After deployment, monitor the [CAPABILITY_DIFF] output to detect registry drift and stale manifests before they cause production incidents.

This prompt is designed to be the first system message in your agent's instruction stack. The harness is responsible for injecting it at session start, parsing the capability summary output, and enforcing the behavioral constraints at the application layer. Do not rely on the prompt alone to prevent capability hallucination—the harness must validate claims against the actual tool registry before any tool call is dispatched.

At session initialization, the harness should: (1) assemble the current tool registry snapshot with tool names, descriptions, parameter schemas, and endpoint status; (2) inject the registry into the [TOOL_REGISTRY] placeholder; (3) send the system prompt as the first message; and (4) parse the agent's capability summary response into a structured object with fields for confirmed_capabilities, explicit_gaps, and confidence_scores. Before any subsequent tool call, validate that the requested tool name and parameters exist in the live registry. If the agent attempts to call a tool not present in the registry, block the call and inject a correction message: 'Tool [NAME] is not registered. Available tools: [LIST]. Re-plan using only registered tools.' This is not a suggestion—it is the primary defense against capability hallucination in production.

For observability, log every capability summary generation event with the registry snapshot hash, the raw summary output, and any validation failures. Set up an eval that compares the agent's claimed capabilities against the registry ground truth at session start, flagging any hallucinated capabilities with a capability_hallucination_rate metric. If this rate exceeds zero in production, the prompt needs hardening or the registry injection format needs debugging. For multi-turn sessions, re-inject the system prompt and registry snapshot whenever the tool set changes due to dynamic registration, deprecation, or health-check-driven removal. Do not assume the agent remembers its capability boundaries across turns—context windows drift, and tool state changes are invisible to the model unless explicitly re-stated.

Model choice matters here. Smaller or older models are more likely to hallucinate capabilities even with a well-structured registry injection. Test across your candidate models with a fixed registry and a set of capability-probing questions like 'Can you delete production databases?' or 'Can you send emails on my behalf?' If the model claims capabilities not in the registry, either switch to a more instruction-following model or add explicit negative examples to the prompt showing the correct refusal pattern. For high-risk deployments where tool calls can cause irreversible damage, add a human approval gate that intercepts any tool call not previously seen in testing, regardless of registry validation.