Agent Capability Self-Assessment Prompt

This prompt is designed for agent framework developers who need their agents to produce a reliable, structured summary of their own capabilities before beginning a task. The core job-to-be-done is preventing capability hallucination at the planning stage. Instead of letting an agent optimistically assume it can perform an action and fail at runtime, this prompt forces introspection against its registered tool set. The ideal user is an AI platform engineer integrating dynamic tool ecosystems, such as Model Context Protocol (MCP) servers, where the available tools can change between sessions. The required context is a live, machine-readable tool registry or a system prompt that accurately lists every available tool with its full schema.

You should use this prompt at the boundary between tool discovery and task planning. For example, inject it as the first user turn after a dynamic tool registry refresh, or use it to generate a preamble that constrains the agent's subsequent planning steps. The output is a structured capability summary that includes explicit statements of what the agent cannot do and confidence levels for each claimed capability. This is not a prompt for single-step function calling or for agents with a static, well-known tool set. Do not use it when the tool list is trivially small or when the agent's task is so constrained that capability assessment adds latency without reducing risk. It is also inappropriate for agents that do not have access to a reliable, programmatic description of their tools—asking an agent to guess its own capabilities from vague system prompts will produce a confident hallucination, not a useful self-assessment.

The primary constraint is that this prompt is only as good as the tool registry it introspects. If the registry is stale, incomplete, or contains malformed schemas, the self-assessment will faithfully reproduce those errors. Always pair this prompt with a validated, recently refreshed tool manifest. In high-stakes deployments—such as agents with write access to production databases or customer-facing systems—the structured output from this prompt should be logged as an audit artifact and compared against a known capability baseline. A significant deviation in claimed capabilities between runs is a leading indicator of registry drift, a partial tool server outage, or a prompt injection attempt. The next step after generating the self-assessment is to feed it into the agent's planning prompt as a hard constraint, explicitly instructing the planner to never attempt actions outside the assessed capabilities.

This template is designed to be injected at session start or before a planning phase. It forces the agent to introspect its tool registry and produce a structured self-assessment rather than relying on implicit capability assumptions. The output is a machine-readable capability manifest that downstream planning prompts can reference. Use this when you need the agent to explicitly state what it can and cannot do before it attempts any multi-step task. Do not use this for agents with static, well-known tool sets where capability is already encoded in the system prompt.

textCopy
You are an agent with access to a set of registered tools. Before you plan or execute any task, you must produce a structured capability self-assessment based ONLY on the tools currently available to you.

## INPUT
- Tool Registry: [TOOL_REGISTRY]
- Task Domain (optional): [TASK_DOMAIN]

## INSTRUCTIONS
1. Examine every tool in the provided tool registry. For each tool, extract its name, primary function, required parameters, and return type.
2. Group tools by capability category (e.g., data retrieval, computation, file operations, external API calls).
3. For each capability category, state:
   - What you CAN do with high confidence (tool exists, schema is complete, no ambiguity).
   - What you CAN do with low confidence (tool exists but schema is incomplete, parameters are ambiguous, or the tool description is sparse).
   - What you CANNOT do that might be expected for [TASK_DOMAIN] (explicit gaps where no tool exists).
4. Assign a confidence score (0.0 to 1.0) to each capability claim.
5. Flag any tools with missing required metadata, conflicting schemas, or deprecation notices.

## OUTPUT SCHEMA
Return a JSON object with this exact structure:
{
  "assessment_timestamp": "ISO-8601",
  "tool_count": integer,
  "capabilities": [
    {
      "category": "string",
      "confidence": 0.0-1.0,
      "status": "high_confidence | low_confidence | gap",
      "tools_used": ["tool_name"],
      "description": "What this capability enables",
      "limitations": ["specific things you cannot do within this category"],
      "missing_metadata": ["fields missing from tool schemas"]
    }
  ],
  "explicit_gaps": [
    {
      "expected_capability": "string",
      "reason_unavailable": "no_tool | insufficient_schema | deprecated_tool | permission_denied",
      "suggested_workaround": "string or null"
    }
  ],
  "registry_health": {
    "deprecated_tools": ["tool_name"],
    "schema_conflicts": [{"tool": "name", "conflict": "description"}],
    "missing_required_fields": [{"tool": "name", "fields": ["field_name"]}]
  }
}

## CONSTRAINTS
- Do not invent capabilities. If a tool is not in the registry, you cannot perform its function.
- If a tool description is ambiguous, mark it as low_confidence and explain the ambiguity.
- If [TASK_DOMAIN] is provided, explicitly list capabilities expected in that domain that you lack.
- Do not omit gaps to appear more capable. Explicit gaps are required output.
- If the tool registry is empty, return an assessment with tool_count: 0 and populate explicit_gaps with all capabilities you would normally expect to need.

## EXAMPLES
[FEW_SHOT_EXAMPLES]

## RISK LEVEL
[RISK_LEVEL]

Adapt this template by replacing the square-bracket placeholders. [TOOL_REGISTRY] should contain the serialized tool definitions available to the agent—typically JSON Schema function definitions or MCP tool manifests. [TASK_DOMAIN] is optional; provide it when you want the agent to assess its capabilities against a specific problem space like 'customer support triage' or 'database migration.' [FEW_SHOT_EXAMPLES] should include one well-populated capability assessment and one sparse-registry example showing how gaps are reported. [RISK_LEVEL] controls whether the agent should be more conservative in claiming capabilities; set to 'high' for regulated domains where overclaiming is dangerous. After adapting, validate that the output schema matches your downstream planning prompt's expected input format. Run this prompt against a known tool registry first and compare the output to a manually verified capability list before deploying to production.

The Agent Capability Self-Assessment Prompt is not a one-off chat interaction. It is a structured introspection call that should be wired into the agent's initialization sequence and periodically re-executed when the tool registry changes. The prompt expects a complete tool manifest as input and returns a structured capability summary. This output becomes a first-class artifact in the agent's context window, used by planning, tool selection, and refusal logic. Treat the self-assessment as a cached, versioned artifact rather than a transient thought.

Wire this prompt into your agent harness as a synchronous preflight step before any user task begins. Pass the current tool registry—including tool names, descriptions, parameter schemas, and any known constraints—into the [TOOL_REGISTRY] placeholder. The model returns a JSON object containing capabilities, gaps, confidence_scores, and explicit_limitations. Validate the output against a schema that requires: (1) every claimed capability references at least one registered tool, (2) confidence scores are numeric values between 0.0 and 1.0, and (3) the explicit_limitations array is non-empty (an agent that claims no limitations is a red flag). If validation fails, retry once with the validation errors injected into the [CONSTRAINTS] field. After two failures, fall back to a conservative capability set derived directly from tool descriptions without model inference.

Cache the validated capability summary with a hash of the tool registry input. On subsequent agent invocations, compare the current registry hash against the cached hash. If they match, reuse the cached assessment to avoid unnecessary latency and cost. If the registry has changed—tools added, removed, or schemas modified—re-execute the prompt. Log every assessment run with the registry version, model used, latency, and validation status. For high-stakes deployments where capability hallucination could cause downstream harm (e.g., agents with write access to production systems), route the capability summary through a human review queue before it enters the agent's active context. The review should confirm that no claimed capability lacks a corresponding tool and that limitations are honestly stated.

Model choice matters here. Use a model with strong instruction-following and structured output capabilities. GPT-4o, Claude 3.5 Sonnet, and Gemini 1.5 Pro are all suitable. Avoid smaller or older models that may conflate general world knowledge with actual tool access. If you are running this prompt in a local or air-gapped deployment with an open-weight model, add few-shot examples to the [EXAMPLES] placeholder showing the desired output shape for a small tool registry. Test the harness with a deliberately incomplete or malformed registry to confirm the agent correctly identifies gaps rather than papering over them. The most common production failure is an agent that claims capabilities it does not possess because the self-assessment prompt was skipped, cached indefinitely, or run against a stale registry.

Do not treat this prompt as a substitute for programmatic capability enumeration. The tool registry itself is the source of truth; the self-assessment is a derived summary for the agent's reasoning convenience. If your agent framework can deterministically compute capabilities from tool schemas without a model call, prefer that approach and reserve this prompt for cases where tool descriptions are sparse, inconsistent, or written in natural language that requires interpretation. When you do use the prompt, log the raw output alongside the validated version so you can audit capability drift over time and catch cases where the model begins to over-claim or under-claim capabilities as tool registries evolve.