Capability Description Generation Prompt for Tool Providers

Tool providers and internal platform teams use this prompt to convert raw technical artifacts—such as code annotations, OpenAPI specifications, or sparse README files—into structured capability descriptions that agents can consume. The primary job-to-be-done is generating a registry-ready manifest that includes tool names, input/output schemas, parameter constraints, usage examples, and explicit failure modes. This is a critical step when onboarding new tools into an agent ecosystem, normalizing documentation across a multi-vendor tool fleet, or generating capability contracts that prevent agent hallucination about what a tool can actually do. The ideal user is an integration developer or platform engineer who has access to source material but needs a consistent, machine-readable contract before registering the tool with an agent framework.

This prompt is designed for static, offline generation of tool descriptions. It expects you to provide the raw source material directly in the prompt context, such as a full OpenAPI spec, a block of annotated code, or a documentation page. The output is a structured JSON manifest that you should validate against your registry schema before ingestion. Do not use this prompt for runtime tool discovery from a live server; for that workflow, use the MCP Server Capability Discovery Prompt Template instead, which handles server introspection and dynamic schema extraction. This prompt also assumes you have the complete source material available—it will not fill gaps by inventing endpoints or parameters, and it will explicitly flag areas where the source documentation is insufficient.

Before using this prompt, ensure you have gathered all relevant source artifacts and identified the target agent framework's capability schema. If the source material is ambiguous or incomplete, the prompt will produce a manifest with confidence annotations and flags for human review. After generation, always run the output through a schema validator and a manual review step for high-risk or security-sensitive tools. The next step is to register the validated manifest in your agent's tool registry and run a capability hallucination test to confirm the agent only claims capabilities that are explicitly present.

The following prompt template is designed to be copied directly into your AI harness. It takes raw source material—such as code annotations, API specifications, or minimal documentation—and produces a rich, structured capability description suitable for registration in an agent tool registry. Replace every square-bracket placeholder with your actual inputs before use. The template enforces a strict output schema, requires explicit failure mode descriptions, and demands confidence annotations for any inferred or uncertain metadata. This is not a conversational prompt; it is a production artifact meant to be version-controlled, tested, and wired into an automated tool-onboarding pipeline.

textCopy
You are a tool capability description generator for an agent ecosystem. Your output will be consumed by an automated tool registry that agents query at runtime. Accuracy and honesty are critical: a hallucinated capability or missing constraint will cause silent agent failures in production.

## INPUT

### Source Material
[SOURCE_MATERIAL]

### Available Context
- Tool name (if known): [TOOL_NAME]
- Provider or vendor: [PROVIDER]
- Intended agent domain: [AGENT_DOMAIN]
- Existing registry schema: [REGISTRY_SCHEMA]

## OUTPUT SCHEMA

Return a single JSON object conforming to this structure:

{
  "tool_id": "<unique identifier, snake_case>",
  "display_name": "<human-readable name>",
  "version": "<semver string or 'unknown'>",
  "description": "<1-3 sentence summary of what the tool does>",
  "capabilities": [
    {
      "capability_id": "<unique capability key>",
      "name": "<short capability name>",
      "description": "<what this capability accomplishes>",
      "inputs": {
        "required": [{"name": "<param>", "type": "<type>", "description": "<description>"}],
        "optional": [{"name": "<param>", "type": "<type>", "description": "<description>"}]
      },
      "outputs": {
        "type": "<return type>",
        "schema": "<JSON Schema or description>"
      },
      "side_effects": ["<list of side effects, e.g., 'writes to database', 'sends email'>"],
      "constraints": ["<list of constraints, e.g., 'max 100 results', 'requires authentication'>"],
      "failure_modes": [
        {
          "condition": "<when this failure occurs>",
          "symptom": "<what the agent will observe>",
          "recommended_action": "<what the agent should do>"
        }
      ],
      "confidence": "<confirmed | inferred | uncertain>"
    }
  ],
  "global_constraints": ["<constraints applying to all capabilities>"],
  "authentication_required": true,
  "rate_limits": {"requests_per_second": null, "description": "<known rate limit info or 'unknown'>"},
  "deprecation": {"is_deprecated": false, "replacement_tool_id": null, "sunset_date": null},
  "metadata_confidence": "<overall confidence: high | medium | low>",
  "missing_information": ["<list of fields or behaviors that could not be determined from source material>"],
  "human_review_required": true
}

## CONSTRAINTS

1. Never invent capabilities not present in the source material. If a parameter, behavior, or constraint is not explicitly stated, mark it as 'inferred' or 'uncertain' and include it in `missing_information`.
2. For every capability, describe at least one realistic failure mode. If the source material does not document error behavior, infer common failure modes from the capability type and mark confidence as 'inferred'.
3. If the source material is too sparse to produce a reliable description, set `human_review_required` to `true` and explain what is missing in `missing_information`.
4. Use the existing registry schema in [REGISTRY_SCHEMA] to align field names, types, and required metadata. If no schema is provided, use the output schema above.
5. Do not wrap the JSON in markdown fences or add commentary outside the JSON object.

## EXAMPLES

[EXAMPLES]

## RISK LEVEL

[RISK_LEVEL]

To adapt this template, start by replacing [SOURCE_MATERIAL] with the raw input you have—code annotations, an OpenAPI spec fragment, or a paragraph of documentation. If you have a registry schema that agents already query, supply it in [REGISTRY_SCHEMA] to ensure field alignment. The [EXAMPLES] placeholder should contain one or two high-quality input-output pairs that demonstrate the desired level of detail and honesty. The [RISK_LEVEL] placeholder accepts a value like low, medium, or high and should influence how aggressively the model marks items for human review. After generation, always validate the output JSON against your registry schema before ingestion. A single malformed capability description can break agent tool selection across your entire fleet.

Before wiring this into a production pipeline, build a validation step that checks for required fields, non-empty failure modes, and the presence of missing_information entries when confidence is low. For high-risk domains—finance, healthcare, infrastructure automation—require human approval on any capability description where metadata_confidence is low or human_review_required is true. Run regression tests against a golden set of known tool descriptions to catch schema drift or hallucination regressions before they reach your agent runtime.

This prompt is designed to sit inside an automated tool onboarding pipeline, not a one-off chat interface. The typical integration point is a CI/CD step that triggers when a tool provider pushes new code annotations, updates an OpenAPI spec, or modifies a sparse tool.yaml manifest. The harness should extract the source material, populate the [SOURCE_ARTIFACT] and [SOURCE_TYPE] placeholders, invoke the model, validate the output against the expected capability description schema, and either auto-register the tool or route it for human review based on confidence signals and schema compliance.

Start by building a thin orchestration layer that handles the full lifecycle: artifact extraction (parse code annotations via AST walkers, load OpenAPI specs, or read existing markdown docs), prompt assembly (inject the extracted content into the template along with the [OUTPUT_SCHEMA] that defines required fields like tool_name, description, parameters, return_type, constraints, failure_modes, and usage_examples), model invocation (use a model with strong structured output support such as gpt-4o or claude-3.5-sonnet with JSON mode enabled), schema validation (validate the response against your capability contract schema using a library like jsonschema or pydantic, flagging missing required fields, malformed parameter definitions, or empty descriptions), and confidence routing (if the prompt includes a [CONFIDENCE] field in the output, route low-confidence generations to a human review queue; otherwise, gate on schema validation failures). For retries, implement a single automatic retry on validation failure with the validation errors injected back into the prompt as [PREVIOUS_ERRORS] so the model can self-correct. Stop after two failed attempts and escalate to the review queue.

Log every generation with the source artifact hash, the full prompt, the raw model output, validation results, and the final registration decision. This audit trail is essential for debugging capability hallucinations and stale descriptions later. When wiring this into a registry update pipeline, always compare the newly generated description against the existing registered version using a semantic diff. If the change is structural (new required parameters, removed endpoints, breaking schema changes), flag for human approval even if validation passed. Avoid auto-registering tools without this diff check—silent capability drift is the most common failure mode in production tool ecosystems. For MCP server integrations, pair this prompt with a health check step that verifies the described capabilities against live server introspection before finalizing registration.