Tool Contract Schema Definition Prompt Template

This prompt is for AI platform engineers and integration developers who need to produce a complete, machine-readable tool contract from a natural language description or an incomplete API specification. The job-to-be-done is translating a human-written summary of a tool's purpose, arguments, and outputs into a strict schema that an LLM agent can consume reliably. Without a well-formed schema, agents hallucinate parameters, omit required fields, or misinterpret return types—failures that are silent, hard to debug, and compound across multi-step tool sequences. Use this prompt when you are onboarding a new internal API, wrapping a third-party service, or standardizing a collection of ad-hoc tools into a consistent agent interface.

The ideal user has access to the tool's source documentation, knows its authentication pattern, and understands which operations are read-only versus mutating. Required context includes the tool's functional purpose, a list of arguments with their types and constraints, the expected output shape, and any side effects or error conditions. You should not use this prompt when the tool's behavior is undefined, when you lack access to the actual API specification, or when you are trying to reverse-engineer a schema from observed traffic alone—schema generation requires authoritative source material, not guesswork. This prompt is also insufficient for tools that require complex, stateful multi-turn negotiation; it produces a single-invocation contract, not a conversation protocol.

Before running this prompt, gather the raw tool description, argument details, and output examples. After generation, you must validate the output schema against the actual tool behavior using the companion Tool Output Contract Validation Prompt. For high-risk tools that mutate data, initiate transactions, or access sensitive systems, route the generated schema through human review and pair it with an Action Permission, Scope, and Safety Boundaries prompt. Do not deploy an agent-facing tool schema without first testing it against at least five happy-path and three edge-case invocations.

This prompt template converts a natural-language description of a tool's purpose and behavior into a rigorous, machine-readable schema. It is designed for AI platform engineers who need to bootstrap tool contracts that agents can consume reliably. The template enforces a consistent output structure that includes argument definitions, constraints, output shapes, error codes, and side-effect declarations. Use it when you have a clear functional description of a tool but need a formal schema to register it in an agent framework, MCP server, or internal tool registry.

textCopy
You are a tool contract schema generator. Your task is to produce a complete, validated tool schema from a natural-language description. The schema must be precise enough for an LLM agent to call the tool correctly and interpret its output without ambiguity.

## INPUT

Tool Name: [TOOL_NAME]
Tool Description: [TOOL_DESCRIPTION]
Intended Use: [INTENDED_USE]
Risk Level: [RISK_LEVEL]

## OUTPUT SCHEMA

Return a JSON object with the following structure:

{
  "tool_name": "string",
  "description": "string (1-3 sentences, unambiguous, includes side effects)",
  "risk_level": "read_only | side_effect | destructive",
  "arguments": [
    {
      "name": "string",
      "type": "string (json schema type)",
      "required": true,
      "description": "string (what this argument does, with example values)",
      "constraints": {
        "min_length": null,
        "max_length": null,
        "pattern": null,
        "enum": null,
        "minimum": null,
        "maximum": null,
        "format": null
      },
      "default": null,
      "sensitive": false
    }
  ],
  "output": {
    "type": "object",
    "properties": {},
    "description": "string (what a successful response contains)"
  },
  "error_responses": [
    {
      "code": "string",
      "description": "string",
      "retryable": true,
      "user_message": "string"
    }
  ],
  "idempotency": {
    "supported": false,
    "key_field": null,
    "description": "string"
  },
  "execution_estimate_ms": {
    "p50": null,
    "p95": null,
    "p99": null
  },
  "pagination": {
    "style": "none | cursor | offset | page",
    "parameters": {}
  },
  "deprecation": {
    "status": "active",
    "replacement_tool": null,
    "sunset_date": null
  }
}

## CONSTRAINTS

[CONSTRAINTS]

## EXAMPLES

[EXAMPLES]

## INSTRUCTIONS

1. Infer argument types, constraints, and required fields from the description.
2. Mark any argument that could contain PII, credentials, or tokens with `sensitive: true`.
3. Generate at least 3 error responses covering: invalid input, server error, and rate limiting.
4. If the tool mutates data, set `risk_level` to `side_effect` or `destructive` and explain why.
5. If the description mentions pagination, define the pagination style and parameters.
6. If the description mentions idempotency keys, populate the idempotency block.
7. Provide realistic execution time estimates if the description implies latency characteristics.
8. Do not invent capabilities not present in the description.
9. If the description is ambiguous, flag the ambiguity in a `notes` field at the top level.

Adapt this template by replacing the square-bracket placeholders with your specific context. The [CONSTRAINTS] block is where you inject domain-specific rules, such as 'all date fields must use ISO 8601 format' or 'user_id must be a UUID v4.' The [EXAMPLES] block should contain 1-3 concrete input/output pairs that demonstrate the tool's behavior, including at least one error case. After generating the schema, run it through a validation step that checks for missing required fields, ambiguous descriptions, type inconsistencies, and unmarked sensitive data. For high-risk tools, route the generated schema through a human review gate before registering it in production.

The Tool Contract Schema Definition prompt is not a one-off assistant; it is a pipeline component that should be integrated into your tool registration or CI/CD workflow. The goal is to produce a machine-readable JSON schema that an agent can consume reliably. This means the prompt's output must pass structural validation before it ever reaches an agent's context window. A typical harness wraps the LLM call in a function that accepts a raw tool description (from an OpenAPI spec, a README, or a developer's notes) and returns a validated tool contract object or a structured error for human review.

The implementation should follow a strict validate → retry → escalate loop. First, parse the LLM's JSON output and validate it against a canonical tool contract schema (requiring fields like name, description, parameters with JSON Schema types, and returns with success and error shapes). If validation fails, feed the specific validation errors back into a retry prompt with the original input and the malformed output, asking the model to repair only the invalid fields. Limit retries to 2 attempts. If the output still fails, log the full trace—including the raw input, both attempts, and the validator errors—and route to a human review queue. For high-risk tools (those with [RISK_LEVEL] set to high or destructive), always require human approval before registration, even if validation passes.

Model choice matters here. Use a model with strong JSON mode and schema-following capabilities (e.g., GPT-4o, Claude 3.5 Sonnet) and enable structured output mode if available, passing the target tool contract schema directly to the API rather than relying solely on the prompt's [OUTPUT_SCHEMA] instructions. Log every registration attempt with the tool name, schema version, validation status, and the LLM's usage metadata for cost tracking. Avoid registering tool contracts that contain unresolved placeholders, ambiguous type descriptions like 'string or number', or error codes without retry hints. These are the most common failure modes that cause silent agent failures in production, and the harness is your last line of defense before a bad contract poisons an agent's tool selection logic.