Capability Contract Generation Prompt from OpenAPI Specs

This prompt is designed for integration developers and AI platform engineers who need to onboard third-party REST APIs into an agent ecosystem. The core job-to-be-done is converting a raw OpenAPI specification into a structured, normalized tool capability contract that an agent can register, reason about, and call. The ideal user is someone building a tool registry, bootstrapping an MCP server from existing services, or generating consistent tool descriptions across a multi-vendor API surface. You should have the OpenAPI spec in hand and a clear understanding of the target agent framework's tool contract schema before using this prompt.

Use this prompt early in the tool onboarding pipeline, before any agent attempts to discover or invoke the API. It is a static generation step, not a runtime resolution step. The prompt expects a complete or partial OpenAPI document as input and produces a manifest that includes input/output JSON schemas, error contracts, and invocation constraints such as rate limits or required authentication scopes. This is not a replacement for runtime schema validation, authentication configuration, or network-level security controls. You will still need to wire the generated contract into a tool execution harness that handles token management, retry logic, and response validation.

Do not use this prompt when the API lacks an OpenAPI spec and you only have unstructured documentation. In that case, use a documentation extraction prompt first to produce a structured capability description. Do not use this prompt for real-time tool discovery against a live server; that requires a dynamic introspection prompt that queries the server directly. Finally, do not treat the generated contract as a security boundary. The prompt translates what the spec declares, but it cannot verify that the API actually enforces the described constraints. Always pair the generated contract with runtime validation and, for high-risk operations, a human-in-the-loop approval gate.

This prompt template converts an OpenAPI specification into a structured capability contract that an agent framework can use to register and call a tool. It extracts endpoints, input/output schemas, error contracts, authentication requirements, and invocation constraints. The output is designed to be machine-readable for tool registration pipelines and human-auditable for integration review. Use this prompt when onboarding a new REST API into an agent ecosystem, refreshing capability descriptions after an API version change, or generating tool manifests for MCP server publication.

textCopy
You are a tool capability contract generator. Your task is to convert the provided OpenAPI specification into a structured capability contract suitable for agent tool registration.

## INPUT
OpenAPI Specification:
```yaml
[OPENAPI_SPEC]

OUTPUT SCHEMA

Return a JSON object with the following structure: { "tool_name": "string (unique, kebab-case identifier derived from the API's primary function)", "display_name": "string (human-readable name, 3-8 words)", "description": "string (2-4 sentences describing what the tool does, its primary use case, and any critical limitations)", "version": "string (semver from the OpenAPI info.version field)", "base_url": "string (the base URL for all endpoints)", "authentication": { "type": "string (one of: none, api_key, bearer, oauth2, basic, mTLS)", "location": "string (one of: header, query, body, null if type is none)", "parameter_name": "string (the header or query parameter name, null if not applicable)", "description": "string (how to obtain and use credentials)" }, "endpoints": [ { "operation_id": "string (from the OpenAPI operationId or generated from method+path)", "method": "string (GET, POST, PUT, DELETE, PATCH)", "path": "string (the URL path template)", "summary": "string (1-sentence description of what this endpoint does)", "description": "string (detailed description including side effects, idempotency, and rate limits if known)", "parameters": [ { "name": "string", "location": "string (path, query, header, cookie)", "type": "string (JSON Schema type)", "required": true, "description": "string", "default": "any (null if no default)", "enum": ["array of allowed values or null"], "pattern": "string (regex constraint or null)", "minimum": "number or null", "maximum": "number or null" } ], "request_body": { "required": true, "content_type": "string (application/json, multipart/form-data, etc.)", "schema": {}, "description": "string" }, "responses": { "success": { "status_code": 200, "content_type": "string", "schema": {}, "description": "string (what a successful response contains)" }, "errors": [ { "status_code": 400, "condition": "string (what causes this error)", "response_body_pattern": "string (identifiable field or message pattern)", "recovery_hint": "string (what the agent should do when this error occurs)" } ] }, "idempotency": "string (one of: idempotent, non_idempotent, conditional)", "side_effects": ["array of strings describing state changes this endpoint causes"], "rate_limit": { "requests_per_minute": "number or null", "description": "string (any known rate limit details from the spec or documentation)" } } ], "global_constraints": { "required_headers": ["array of headers that must be sent with every request"], "timeout_ms": "number (recommended timeout in milliseconds, default 30000)", "max_retries": "number (recommended max retries for transient errors, default 3)", "retry_on_status": [429, 503], "pagination": { "style": "string (one of: offset, cursor, page, link_header, none)", "parameter_details": "string (how to paginate through results)" } }, "capability_bounds": { "read_only": true, "requires_confirmation": ["array of operation_ids that need human approval before execution"], "max_objects_per_request": "number or null", "known_limitations": ["array of strings describing known gaps or constraints"] }, "examples": [ { "scenario": "string (description of a common use case)", "endpoint": "string (operation_id)", "request": {}, "expected_response": {}, "notes": "string (any important behavior to note)" } ] }

CONSTRAINTS

• Extract all information from the provided OpenAPI spec only. Do not invent endpoints, parameters, or behaviors not present in the spec.
• If the spec is missing information for a required field, use null and add a note in the description field indicating what is unknown.
• For error recovery hints, infer reasonable agent actions from the status code and any error response schema. If no error schema exists, provide a generic recovery hint based on the status code class.
• Mark endpoints as requiring confirmation if they perform destructive actions (DELETE, write operations that modify critical resources, or operations with irreversible side effects).
• Generate at least one example per endpoint if the spec provides sufficient detail. If not, generate examples for the most commonly used endpoints.
• Use the operationId from the spec when available. Generate a stable operationId from the method and path when missing.
• For the tool_name, derive a concise kebab-case identifier from the API title or primary resource. Avoid generic names like "api-tool" or "rest-client".
• If the spec contains webhook definitions or callback objects, include them as endpoints with a note in the description that they are server-initiated.

RISK LEVEL: [RISK_LEVEL]

• If RISK_LEVEL is "high": Mark all write operations as requiring_confirmation. Set max_retries to 1. Add a constraint that the agent must log the full request payload before execution.
• If RISK_LEVEL is "medium": Mark only DELETE and bulk-update operations as requiring_confirmation. Use default retry settings.
• If RISK_LEVEL is "low": Only mark operations with irreversible side effects as requiring_confirmation. Allow default retry behavior.

OUTPUT FORMAT

Return ONLY the JSON object. No markdown fences, no commentary, no additional text.

To adapt this template, replace [OPENAPI_SPEC] with the raw YAML or JSON of your OpenAPI specification. Set [RISK_LEVEL] to high, medium, or low based on the sensitivity of the system the tool will access. For internal read-only APIs, use low. For APIs that modify production data, customer records, or infrastructure, use high. The output contract is designed to be consumed by a tool registration pipeline—validate the JSON against the schema before registering the tool with an agent framework. If the OpenAPI spec is large, consider splitting it by tag or resource group and running this prompt once per group to stay within context limits.

Before deploying the generated contract, run it through a validation step that checks for missing required fields, malformed schemas, and hallucinated endpoints not present in the source spec. Pair this prompt with the Tool Manifest Validation Prompt for Agent Registration to catch structural errors. For high-risk integrations, require a human reviewer to confirm the authentication configuration, the list of endpoints marked as requiring confirmation, and the error recovery hints before the tool is registered in production. Never register a tool contract generated from an untrusted or user-supplied OpenAPI spec without validation and review.

This prompt is designed to sit inside a tool ingestion pipeline, not a one-off chat interface. The typical flow: an integration developer uploads an OpenAPI spec (JSON or YAML), your application extracts the relevant paths and schemas, injects them into the prompt's [OPENAPI_SPEC] placeholder, calls the model, and then validates the output before writing it to the tool registry. The prompt expects a complete or partial OpenAPI document—if you're feeding it a single endpoint, wrap it in the minimal openapi, info, and paths structure so the model has the version and server context it needs to generate accurate base URLs and error shapes.

Validation is the critical gate. Before any generated contract enters your agent's tool registry, run a schema validator against the expected JSON output structure. At minimum, confirm that tool_name is a non-empty string, input_schema is valid JSON Schema, output_schema is valid JSON Schema, and error_contracts is an array of objects with status_code and description fields. Reject contracts where the model hallucinated endpoints not present in the source spec—cross-reference source_path and source_method against the input OpenAPI document. For high-stakes production systems, add a human review step for contracts that touch write operations (POST, PUT, PATCH, DELETE) or carry [RISK_LEVEL] of high. The review UI should display the original OpenAPI snippet alongside the generated contract so reviewers can spot capability inflation quickly.

Retry logic should be narrow. If validation fails due to malformed JSON, retry once with the validation errors injected into the [CONSTRAINTS] block. If the model invents endpoints or parameters not in the spec, do not retry—log the failure, flag the spec for manual review, and move on. Retrying hallucination-prone outputs without additional grounding typically produces different hallucinations, not corrections. For model choice, prefer models with strong JSON Schema adherence and large context windows if you're processing multi-endpoint specs in a single call. If you're processing specs endpoint-by-endpoint, smaller context windows work fine. Logging should capture the input spec hash, the generated contract, validation results, and the reviewer decision (approved/rejected/modified) for audit trails. This is especially important if your tool registry feeds autonomous agents—you need to trace every capability claim back to its source spec and generation run.

Tool use integration is straightforward here because this prompt is itself a tool-contract generator. The output feeds directly into your agent's tool registration system. If you're using MCP servers, the generated contract maps cleanly to MCP tool definitions: tool_name becomes the MCP tool name, input_schema becomes the tool's inputSchema, and output_schema and error_contracts become part of the tool's description or annotations. For non-MCP agent frameworks, adapt the output fields to your framework's tool registration format. What to avoid: don't skip validation, don't auto-register contracts that touch destructive operations without review, and don't batch-process hundreds of endpoints without rate limiting and cost tracking. A single large OpenAPI spec can generate significant token usage, so implement cost controls—process endpoints in chunks, track cumulative spend, and set per-spec generation budgets that trigger human review if exceeded.