Required vs Optional Field Decision Prompt

This playbook is for API designers and platform engineers who are authoring tool schemas and need to decide which parameters must be required versus optional with safe defaults. The core job is to produce a field-by-field classification rationale and a schema that minimizes argument generation errors in production. You should use this prompt when you have a tool definition with multiple parameters and you need a systematic, documented decision for each field's required/optional status before the schema is published to a model.

The ideal user is someone who understands the tool's business logic but needs help applying consistent rules for required fields, default values, and missing-argument behavior. Required context includes the tool's purpose, the full parameter list with types, the operational constraints (e.g., idempotency requirements, side effects, permission scopes), and any existing user-facing documentation. Without this context, the prompt will produce generic classifications that don't account for the tool's real failure modes.

Do not use this prompt when the tool schema is still in early exploration, when parameter semantics are undefined, or when you need runtime argument validation logic rather than schema design decisions. This prompt is also inappropriate for tools that have no optional parameters or for schemas where all fields are already locked by an external contract. In those cases, use the Parameter Schema Design Prompt Template or the Tool Call Validation and Pre-Execution Guardrails playbook instead.

The output of this prompt is a structured classification document, not executable code. You will need to translate the rationale into your actual JSON Schema, OpenAPI definition, or model-specific tool format. Before shipping, validate the schema against the test cases this prompt produces for missing-argument behavior and over-eager defaulting. If the tool has write side effects, require human review of the final schema before deployment.

This template is designed to be copied directly into your prompt management system or codebase. It instructs the model to analyze a set of API parameters and produce a structured classification rationale, a recommended schema, and a set of test cases. The prompt uses square-bracket placeholders for all dynamic inputs, making it safe to template and reuse across different API endpoints and services. Before using it, ensure you have a clear list of parameters, their current types, and the business context for the operation they perform.

textCopy
You are an API design analyst. Your task is to review a list of parameters for a given API operation and classify each as REQUIRED or OPTIONAL. For optional parameters, you must also propose a safe default value.

## INPUT PARAMETERS
[PARAMETER_LIST]

## BUSINESS CONTEXT
[OPERATION_CONTEXT]

## CONSTRAINTS
- A parameter should be REQUIRED if the operation cannot complete meaningfully or safely without it.
- A parameter should be OPTIONAL if a safe, sensible default exists that preserves the operation's intent.
- Defaults must never trigger a destructive action, send a notification, or mutate state in a way the user did not explicitly request.
- Prefer defaults that result in a no-op or the most common, least-privileged behavior.

## OUTPUT_SCHEMA
Return a valid JSON object with the following structure:
{
  "classifications": [
    {
      "parameter_name": "string",
      "classification": "REQUIRED | OPTIONAL",
      "rationale": "string",
      "proposed_default": "any | null",
      "risk_notes": "string | null"
    }
  ],
  "test_cases": [
    {
      "scenario": "string (e.g., 'All optional fields omitted')",
      "provided_args": {},
      "expected_behavior": "string",
      "failure_mode": "string"
    }
  ]
}

## RISK_LEVEL
[RISK_LEVEL]

If RISK_LEVEL is "HIGH", flag any parameter whose misclassification could cause data loss, a security incident, or a compliance violation. For these parameters, add a `requires_human_review: true` field to the classification object.

To adapt this template, replace the placeholders with your specific data. [PARAMETER_LIST] should be a structured list, such as a markdown table or JSON array, containing each parameter's name, current type, and a brief description. [OPERATION_CONTEXT] is a natural language description of what the API does and who uses it. [RISK_LEVEL] should be set to "LOW", "MEDIUM", or "HIGH" to control the strictness of the review. For high-risk operations, the generated output will flag items for human review, which you must enforce in your deployment pipeline before the schema is finalized. The next step is to take the generated test cases and turn them into automated integration tests in your harness.

This prompt is designed to be called programmatically, not just used in a chat interface. The primary integration point is a function that takes a raw API endpoint specification (OpenAPI fragment, JSON Schema, or a structured list of parameters) and returns a classification rationale plus an updated schema. The harness should validate the output against a strict JSON Schema before accepting it, because a malformed classification can silently break downstream code generation or documentation. Treat the model output as a proposal that requires deterministic validation, not as a final artifact.

The implementation should follow a three-stage pipeline: pre-processing, model invocation, and post-validation. In pre-processing, extract the parameter list from the source spec and normalize it into the [PARAMETER_LIST] format the prompt expects. This means each parameter must have a name, type, current_required boolean, and a description. If the source spec lacks descriptions, flag them as missing rather than guessing. During model invocation, use a low-temperature setting (0.0–0.2) because classification tasks benefit from deterministic behavior. Set response_format to JSON mode if the provider supports it, and always include a max_tokens ceiling to prevent runaway outputs. For high-throughput API reviews, batch multiple endpoints into separate calls rather than cramming them into one prompt, which reduces hallucination risk.

Post-validation is the critical safety layer. Validate the model output against a schema that requires: (1) every input parameter appears in the output with a required boolean and a default_value (or explicit null), (2) the rationale field is present and non-empty for each parameter, (3) no new parameters are invented, and (4) required fields do not have defaults that would mask missing-input errors in production. If validation fails, retry once with the validation error message appended to the prompt as feedback. If the second attempt also fails, log the failure and route the endpoint for human review. For regulated or safety-critical APIs, always require human approval on the final classification before it reaches a production schema. Log every classification decision with the model version, timestamp, and validator result so that audit trails exist for governance reviews.

Model choice matters here. Smaller, faster models (like GPT-4o-mini or Claude Haiku) handle this classification task well when the parameter list is under 20 fields and descriptions are clear. Switch to a frontier model when the API has nested objects, polymorphic types, or parameters with complex interdependencies where a wrong default could cause data loss. Avoid using this prompt on endpoints with more than 50 parameters in a single call; split them into logical groups first. The harness should also track cost: if you are reviewing thousands of endpoints, cache results keyed by a hash of the parameter list to avoid redundant model calls when the same schema appears across multiple endpoints.