MCP Server Capability Discovery Prompt Template

This prompt is for MCP server builders and agent framework developers who need to generate a structured, machine-readable capability manifest from raw server introspection data. The core job-to-be-done is runtime tool discovery: an agent must learn what tools are available, what parameters they accept, and what schemas govern their inputs and outputs, all without relying on stale, pre-validated registries. Use this prompt when an agent connects to a live MCP server and receives unstructured or semi-structured capability descriptions that must be normalized into a validated JSON manifest suitable for direct ingestion into the agent's tool registry.

The ideal user is an engineer wiring a dynamic tool ecosystem into a production agent. Required context includes the raw server response payload, the expected output schema for the manifest, and any known constraints such as required fields, enum values, or parameter type maps. The prompt is designed to handle sparse metadata, missing types, and ambiguous parameter definitions by inferring structure where possible and flagging gaps for human review. Do not use this prompt when the server already provides a perfectly structured OpenAPI spec or when the agent can rely on a static, pre-validated manifest that never changes—in those cases, a simpler schema validation or direct ingestion step is more appropriate and less prone to inference errors.

Before deploying this prompt into a production agent loop, pair it with a validation harness that checks the output manifest against a strict JSON Schema. Common failure modes include hallucinated endpoints that don't exist on the server, missing required parameters, and incorrect type coercions. Always log the raw server response alongside the generated manifest for debugging, and implement a staleness check that compares the generated manifest against the previous version to detect unexpected capability drift. For high-stakes agent actions, require human approval before registering newly discovered tools that modify external state.

This prompt template is designed to be sent to an LLM that has access to raw MCP server introspection data—typically the output of a list_tools or equivalent discovery endpoint. The model's job is to normalize that raw output into a structured capability manifest that downstream agent systems can consume reliably. The template uses square-bracket placeholders for all variable inputs, making it straightforward to wire into an application harness where those placeholders are resolved before the request is sent.

textCopy
You are a tool capability extraction system. Your task is to convert raw MCP server introspection output into a structured capability manifest.

## INPUT
Raw server introspection data:
[RAW_INTROSPECTION_DATA]

## OUTPUT SCHEMA
Return a JSON object with the following structure:
{
  "server_name": "string",
  "server_version": "string | null",
  "introspection_timestamp": "ISO 8601 string",
  "tools": [
    {
      "name": "string",
      "description": "string",
      "input_schema": { /* valid JSON Schema object */ },
      "output_schema": { /* valid JSON Schema object or null */ },
      "required_parameters": ["string"],
      "optional_parameters": ["string"],
      "constraints": {
        "rate_limit": "string | null",
        "requires_authentication": true | false,
        "side_effects": ["READ_ONLY" | "WRITE" | "DELETE" | "EXECUTE"],
        "idempotent": true | false | null
      },
      "examples": [
        {
          "description": "string",
          "input": {},
          "expected_output": {}
        }
      ],
      "confidence": "CONFIRMED" | "INFERRED" | "UNCERTAIN"
    }
  ],
  "warnings": ["string"]
}

## CONSTRAINTS
- If a field cannot be determined from the raw data, use null for scalar fields and empty arrays for list fields.
- Set confidence to CONFIRMED only when the raw data explicitly states the capability.
- Set confidence to INFERRED when you derive a capability from naming conventions or partial descriptions.
- Set confidence to UNCERTAIN when the raw data is ambiguous or contradictory.
- Do not invent tool names, parameters, or capabilities not present in the raw data.
- If the raw data contains no recognizable tools, return an empty tools array and include a warning.
- Preserve all schema types exactly as provided; do not coerce types.

## EXAMPLES
[FEW_SHOT_EXAMPLES]

## RISK LEVEL
[RISK_LEVEL]

To adapt this template, replace each square-bracket placeholder with the appropriate value before sending the request. [RAW_INTROSPECTION_DATA] should contain the full text or JSON output from the MCP server's discovery endpoint. [FEW_SHOT_EXAMPLES] is optional but strongly recommended for production use—include 2-3 examples of raw introspection data paired with correct manifest outputs to anchor the model's behavior. [RISK_LEVEL] should be set to LOW, MEDIUM, or HIGH based on the downstream consequences of a malformed manifest. For HIGH risk scenarios, add an explicit instruction requiring human review of any tool marked UNCERTAIN before registration. The output schema is designed to be directly consumable by a tool registry system; validate it against the schema before ingestion using a JSON Schema validator in your application harness. Do not skip the warnings field—it is your primary signal for detecting introspection gaps that need human attention.

The MCP Server Capability Discovery prompt is designed to be called as a pre-registration step whenever an agent or platform connects to a new MCP server. The typical integration point is a server onboarding workflow: the platform sends an initialize request to the server, receives the raw capability response, and passes that payload into this prompt as the [SERVER_RESPONSE] input. The prompt's output—a structured capability manifest—is then validated against a JSON Schema before being written to the tool registry. Do not use this prompt for periodic health checks; use the sibling MCP Server Health Check and Capability Refresh Prompt for ongoing monitoring.

Validation and retry logic must sit between the model output and the registry write. After receiving the manifest, validate that every tool entry contains a non-empty name, a valid input_schema conforming to JSON Schema draft-07, and a description field. If validation fails, retry the prompt once with the validation errors appended to the [CONSTRAINTS] block. If the second attempt also fails, log the failure, flag the server for manual review, and do not register partial capabilities. For production deployments, implement a circuit breaker: if three consecutive servers from the same provider fail validation, halt automatic registration for that provider and alert the platform team.

Model choice matters here. The prompt requires strict schema adherence and zero hallucinated endpoints. Use a model with strong JSON mode or structured output support (e.g., GPT-4o with response_format: json_schema, Claude 3.5 Sonnet with tool-use extraction, or a fine-tuned open-weight model validated against your schema). Avoid models known to inject plausible-but-fabricated API endpoints. Logging should capture the raw server response, the generated manifest, validation results, and the final registry write outcome. Store these as structured audit events with the server ID, timestamp, and model version. This audit trail is essential for debugging agent tool-call failures that trace back to incorrect capability registration.

Human review gates are required when the prompt flags [CONFIDENCE] below a threshold you define (e.g., any tool entry with confidence < 0.9) or when the server response contains ambiguous parameter types that the model had to infer. Route these manifests to a review queue rather than auto-registering. For RAG or retrieval-augmented workflows, you can supply the prompt with a [CONTEXT] block containing the server's OpenAPI spec or documentation if available; this grounds the capability extraction in source material and reduces hallucination risk. Do not wire this prompt directly into agent planning loops—it is a registration-time operation, not a runtime discovery call.

What to avoid: Do not call this prompt on every agent invocation. Cache the validated manifest in the tool registry and only re-run on server version changes or scheduled refreshes. Do not skip schema validation even if the model output looks correct—production MCP servers frequently return malformed or incomplete capability descriptions that pass visual inspection but break downstream tool selection. Finally, ensure your harness handles timeouts and partial responses from the MCP server gracefully; pass only complete, successful server responses into the prompt, and use a separate error-handling path for unreachable or degraded servers.