Tool Schema Introspection Prompt for MCP Clients

This prompt is for MCP client developers and AI platform engineers who need to extract structured, machine-readable JSON Schema definitions from raw tool descriptions returned by MCP servers. The core job is normalization: taking sparse, inconsistent, or ambiguous metadata—where parameter types might be missing, descriptions vague, or constraints implied—and producing a clean, validated schema that an agent can reliably use for function calling. You should use this prompt when you are building the integration layer between an MCP server and an agent's tool registry, and the server's native descriptions are insufficient for strict, schema-driven tool selection.

The ideal user is actively wiring a dynamic tool discovery pipeline. They have already received a raw tool listing from an MCP server's tools/list or equivalent endpoint, and they have that payload ready as the [RAW_TOOL_DESCRIPTIONS] input. Required context includes the server's stated API version, any known type system conventions (e.g., whether the server uses OpenAPI-style types or custom type strings), and the target output schema standard you are normalizing to (typically JSON Schema Draft 2020-12). Do not use this prompt for generating tool descriptions from scratch, for validating a hand-written manifest against a spec, or for runtime tool selection logic—those are separate playbooks. This prompt is specifically for the introspection and normalization step.

There are clear boundaries where this prompt is the wrong tool. If the MCP server already returns fully compliant JSON Schema for every tool and parameter, you do not need normalization; you need a validation pass. If you are trying to infer what a tool does from its name alone, you risk capability hallucination—use the Capability Hallucination Prevention System Prompt instead. If you are comparing two tool registries for drift, use the Runtime Tool Schema Change Detection Prompt. This prompt assumes you have raw, server-authored descriptions and need to convert them into a strict, typed contract. It does not perform semantic enrichment beyond what is present in the input; it clarifies, structures, and flags gaps, but it does not invent missing capabilities.

Before using this prompt, ensure you have a clear [OUTPUT_SCHEMA] defined—the exact JSON Schema structure you expect each normalized tool to conform to. This becomes your contract. Also prepare a set of [CONSTRAINTS] that encode your platform's rules: required fields, banned type fallbacks (e.g., never default to string when a type is missing), and enumeration rules for parameter categories. The prompt works best when you provide a few [EXAMPLES] of correctly normalized schemas alongside their raw inputs, establishing the transformation pattern. After generation, always validate the output against your [OUTPUT_SCHEMA] programmatically; the prompt includes a validation instruction, but you must implement the actual schema validator in your harness. For high-stakes tool registrations—where a malformed schema could cause an agent to call a destructive API with wrong arguments—route the normalized output through a human review step before registration.

This prompt template is designed to be sent to an LLM that has received a raw tool description payload from an MCP server. The model's job is to introspect that payload, identify gaps in metadata, missing types, and ambiguous parameter definitions, and produce a clean, standards-compliant JSON Schema object for each tool. Use this template as the core instruction block in your MCP client's tool registration pipeline.

textCopy
You are a tool schema normalization engine. Your input is a raw tool description from an MCP server. Your output must be a valid, strictly typed JSON Schema (Draft 2020-12) representation for each tool.

Follow these rules:
1. For every input parameter, infer the most specific JSON Schema type possible (e.g., 'string', 'integer', 'boolean', 'object', 'array'). If a type is missing or ambiguous, use your best inference and set a 'x-inferred' property to true in the schema.
2. Generate a human-readable 'description' for every parameter and for the tool itself. If the source description is missing, write a concise description based on the parameter name and context.
3. Identify all required parameters. If the source does not specify required fields, mark parameters that appear essential for the tool's operation as required and note this inference in the 'x-inferred-required' property.
4. For enum parameters, extract all possible values. If values are not provided, set the 'enum' field to an empty array and add a note to the description.
5. Normalize all parameter names to camelCase.
6. Output a single JSON object with a 'tools' array. Each element in the array must have 'name', 'description', and 'inputSchema' keys. The 'inputSchema' must be a valid JSON Schema object.
7. If the input contains multiple tools, process all of them.
8. Do not hallucinate parameters or capabilities not present in the source text. If you are unsure about a property, omit it rather than guessing.

[RAW_TOOL_DESCRIPTION]

To adapt this template, replace the [RAW_TOOL_DESCRIPTION] placeholder with the actual text or JSON payload received from the MCP server's tools/list or equivalent endpoint. For production systems, you should wrap this prompt in a validation harness that parses the output, checks it against the JSON Schema meta-schema, and flags any x-inferred properties for human review. If the tool will be used in a high-stakes domain, route any schema with inferred required parameters or missing enum values to a human-in-the-loop review queue before registering the tool with an agent.

This prompt is designed to be called programmatically by an MCP client after receiving a raw tool description from a server. The client should treat the prompt as a normalization layer that sits between the server's tools/list response and the agent's tool registry. Do not expose raw server output directly to the agent's context; always pass it through this introspection prompt first to produce a validated, normalized JSON Schema representation. The prompt expects two inputs: the raw tool description text and a target output schema that defines the required fields. Wire the prompt into a dedicated ToolSchemaNormalizer service that is invoked during tool registration, not during agent execution, to avoid adding latency to time-sensitive tool calls.

Validation and retry logic is mandatory. After receiving the model's JSON output, validate it against the expected JSON Schema using a server-side validator such as ajv. If validation fails, retry the prompt once with the validation errors appended to the [CONSTRAINTS] field. If the second attempt also fails, log the raw server response, the failed model output, and the validation errors as a structured incident, then fall back to a minimal safe schema that includes only the tool name and a generic object type with no parameters. This prevents a single malformed tool description from blocking agent startup. For high-risk production deployments, add a human review queue for tools that fail normalization twice, especially if they originate from untrusted third-party MCP servers.

Model choice matters. Use a model with strong JSON Schema generation capabilities and strict mode support, such as GPT-4o with response_format set to json_schema or Claude 3.5 Sonnet with structured output enabled. Avoid models that are prone to hallucinating fields when given sparse input. Set temperature=0 to maximize determinism. For the [OUTPUT_SCHEMA] placeholder, provide the exact JSON Schema you expect the model to populate, including required fields like name, description, inputSchema (with type, properties, and required), and outputSchema. The prompt template includes a [CONFIDENCE_THRESHOLD] parameter; set this to 0.7 by default and flag any tool where the model's self-reported confidence falls below this threshold for manual review. Log every normalization result with the tool name, server origin, confidence score, and whether fallback was triggered for auditability and debugging.