Parameter Schema Design Prompt Template

Use this prompt when you need to generate a precise, model-friendly JSON Schema definition for a tool's input arguments. This is a design-time prompt for platform engineers and API developers who are authoring the contract between the model and a function. The goal is to produce type definitions, enum constraints, and field descriptions that maximize correct argument generation and minimize type coercion errors, hallucinated parameters, and missing required fields. Run this prompt before registering a tool with a model, after you have a clear functional specification for what the tool does but before you write the final schema by hand.

This prompt is not for runtime argument validation or for repairing malformed calls after they occur. If you are already in production and seeing tool_call argument errors, you need the 'Tool Call Validation and Pre-Execution Guardrails' or 'Error Handling and Tool Call Recovery' playbooks instead. Do not use this prompt to generate schemas for tool outputs—that requires the 'Tool Output Schema Definition Prompt' in the same content group. The ideal user has the tool's functional spec, knows which parameters are required versus optional, understands the expected data types, and can provide 2-3 examples of valid argument sets. You should not use this prompt when the tool's behavior is still undefined, when you lack clarity on which fields the model should fill versus the system should inject, or when you are adapting an existing OpenAPI spec—use the 'OpenAPI-to-Tool Schema Conversion Prompt' for that workflow.

Before running this prompt, gather the tool's purpose statement, a list of all parameters with their types and constraints, and at least two example argument sets that represent common and edge-case usage. After generating the schema, you must validate it against the 'Tool Schema Review Rubric Prompt' and test it with a model using the eval harness described in the implementation section. The most common failure mode is producing a schema that is syntactically valid but semantically ambiguous—for example, using generic descriptions like 'the ID' instead of 'the unique customer identifier from the CRM system.' Always review generated schemas for field descriptions that a model could misinterpret, and run at least 20 test calls across different model providers before considering the schema production-ready.

This prompt template is designed for platform engineers and API developers who need to generate precise, model-friendly JSON Schema definitions for tool arguments. A well-authored parameter schema acts as the contract between the model and your system, directly reducing argument generation errors, hallucinated fields, and type mismatches in production. Use this template when you have a clear understanding of your tool's inputs but need the model to produce a compliant, constrained schema definition that includes types, enums, descriptions, and required-field flags.

textCopy
You are a JSON Schema designer for AI-callable tools. Your task is to produce a strict, well-documented JSON Schema for the input parameters of a tool described below.

## Tool Description
[TOOL_DESCRIPTION]

## Parameter Requirements
[PARAMETER_REQUIREMENTS]

## Constraints
- Every field must have a `type`, a `description` that explains what the field represents and how the model should populate it, and an explicit `nullable` designation.
- Use `enum` for any field with a known, finite set of valid values. Include a `description` for each enum value.
- Mark fields as `required` only if the tool cannot execute without them. For optional fields, provide a safe `default` value where applicable.
- Use `$ref` and `definitions` for reusable object structures to avoid duplication.
- Add `examples` for complex fields to guide correct model usage.
- Annotate fields that accept PII, credentials, or sensitive data with a `x-sensitive: true` extension.
- The root schema must include `additionalProperties: false` to prevent hallucinated arguments.

## Output Format
Return ONLY a valid JSON object conforming to JSON Schema Draft 2020-12. Do not wrap the output in markdown fences or add explanatory text.

## Output Schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": { ... },
  "required": [ ... ],
  "additionalProperties": false
}

To adapt this template, replace [TOOL_DESCRIPTION] with a clear, plain-language explanation of what your tool does, its side effects, and when it should be selected. Replace [PARAMETER_REQUIREMENTS] with a structured list of the inputs your tool expects, including their expected types, valid ranges, and any business logic constraints. For high-risk tools that mutate state or access sensitive data, add a [RISK_LEVEL] placeholder and require a human review step before the generated schema is deployed. After generation, always validate the output against a JSON Schema validator and run a set of test tool calls to confirm the model correctly populates required fields, respects enum constraints, and does not hallucinate additional properties.

The parameter schema design prompt is not a one-off utility; it is a code-generation step in a tool-authoring pipeline. The prompt takes a natural-language description of a tool's arguments and produces a JSON Schema definition. The output must be treated as generated code: it requires validation, testing, and review before it becomes the contract between the model and your system. Wire this prompt into a workflow where the generated schema is immediately validated against the JSON Schema specification, checked for required-field completeness, and tested against a set of known argument-generation scenarios before it reaches production tool definitions.

Build a harness that calls the prompt, parses the JSON output, and runs a series of automated checks. First, validate that the output is syntactically valid JSON Schema using a standard schema validator. Second, verify that every field marked as required in the natural-language description appears in the required array. Third, test the schema against a small set of hand-crafted argument payloads—both valid and invalid—to confirm that type constraints, enum values, and format rules behave as expected. If any check fails, route the output to a repair prompt or flag it for human review. For high-stakes tools that mutate state or access sensitive data, always require a human to approve the generated schema before it is registered with the model's tool catalog.

Log every generated schema along with the input description, the model and version used, the validation results, and the reviewer's decision. This audit trail is essential for debugging tool-call failures later: when a model passes malformed arguments, you need to trace back to whether the schema itself was ambiguous or incorrectly constrained. Store schemas in a version-controlled registry, not as ad-hoc strings in application config. When you update a schema, run the old and new versions through the same validation harness and compare argument-generation accuracy on a golden test set before deprecating the old version. Avoid the common failure mode of deploying a 'small schema fix' that silently breaks argument generation for previously working inputs.