Null and Empty Value Handling Prompt for Optional Arguments

This prompt is for backend and platform engineers who need to validate tool call arguments generated by an LLM before those arguments are dispatched to an internal or external API. Its specific job is to resolve ambiguity in optional fields: it decides whether a field that is empty, null, or missing should be omitted from the final payload, explicitly set to null, or replaced with a safe default value. This decision is made by comparing the generated argument against the target tool's API contract, which you provide as part of the input. The goal is to prevent the 400 Bad Request errors and silent state corruption that occur when an LLM guesses incorrectly about how an API handles absent versus null optional parameters.

Use this prompt when your application constructs tool call payloads from LLM outputs and the downstream API has strict, documented behavior for optional fields. It is most valuable when the API contract distinguishes between 'field not present' and 'field present with a null value'—a common source of bugs in REST and GraphQL APIs. The prompt requires you to supply the raw generated arguments, the complete API schema for the target tool (including which fields are optional, their types, and any default values), and a set of business rules that might override the schema (e.g., 'if the user's role is viewer, the access_level field must be omitted'). You should not use this prompt for simple APIs where all optional fields can be safely omitted, or for workflows where the LLM's output is already guaranteed to be schema-valid by a prior step. In those cases, a simpler required-field check or a direct schema validation prompt is more efficient.

This prompt is a pre-execution guardrail, not a repair tool. It assumes the tool call arguments have already passed a basic schema conformance check and that the only remaining ambiguity is how to handle optional fields that are empty, null, or missing. If the input arguments contain hard validation errors—such as a required field that is missing, a string where an integer is expected, or an enum value that is not in the allowed set—this prompt will not fix them. Instead, it will flag those issues and recommend that the payload be sent to a dedicated repair prompt or rejected outright. The output is a structured decision for each optional field: omit, send_null, or set_default, along with a corrected payload and an audit trail explaining each choice. For high-risk write operations, you should route the corrected payload to a human approval step before execution, not rely solely on this automated normalization.

Before integrating this prompt, confirm that your downstream API documentation clearly specifies null handling for every optional field. If the API's behavior is undocumented or inconsistent, the prompt's decisions will be based on inference rather than contract, which increases the risk of errors. In those cases, pair this prompt with a test harness that sends the corrected payload to a sandbox or staging endpoint and validates the response. Also, log every normalization decision so that when an API changes its null-handling behavior, you can trace which past tool calls might be affected. This prompt is a precision instrument for a specific failure mode; use it when optional-field ambiguity is the known bottleneck, not as a general-purpose argument cleaner.

This prompt template is designed to sit between argument construction and tool execution. It receives a partially filled tool call payload and the target tool's API contract, then normalizes every optional field according to the contract's declared nullability, default values, and omission rules. The goal is to prevent 400 errors, unintended null writes, and default-value surprises before the call leaves your system.

textCopy
You are a tool call argument normalizer. Your job is to inspect a proposed tool call payload and enforce the correct handling of optional fields based on the tool's API contract.

## INPUT
Tool Name: [TOOL_NAME]
Tool Description: [TOOL_DESCRIPTION]
Parameter Schema (JSON Schema subset): [PARAMETER_SCHEMA]
Proposed Arguments (JSON): [PROPOSED_ARGUMENTS]

## RULES
1. For each field in the parameter schema, determine whether it is required or optional based on the schema's `required` array.
2. For each optional field:
   - If the field is absent from the proposed arguments and the schema declares a `default`, insert the default value.
   - If the field is absent and no default is declared, omit the field entirely (do not send `null`).
   - If the field is present but set to `null`, `""`, `[]`, or `{}`:
     - If the schema explicitly allows `null` (type array includes `"null"`), keep it as `null`.
     - If the schema does not allow `null` and no default is declared, omit the field.
     - If the schema does not allow `null` but a default is declared, replace with the default.
3. For required fields, never omit them. If a required field is missing, null, or empty, flag it as an error—do not guess.
4. Do not add fields that are not declared in the parameter schema.
5. Preserve all valid, non-empty values exactly as provided.

## OUTPUT SCHEMA
Return a JSON object with exactly these keys:
- `normalized_arguments`: The corrected arguments object ready for tool dispatch.
- `changes`: An array of change records, each with `field`, `action` (one of: "omitted", "set_default", "kept_null", "flagged_missing_required"), and `reason`.
- `valid`: Boolean. `true` if all required fields are present and non-empty after normalization, `false` otherwise.
- `errors`: Array of error strings for missing required fields or schema violations that cannot be repaired.

## EXAMPLES
[EXAMPLES]

## CONSTRAINTS
[CONSTRAINTS]

Adapt this template by replacing the placeholders. [PARAMETER_SCHEMA] should be a JSON Schema subset that includes at minimum type, properties, and required for each parameter. [PROPOSED_ARGUMENTS] is the raw output from your argument-filling prompt or agent step. [EXAMPLES] should include at least two few-shot demonstrations: one where an empty optional string is correctly omitted, and one where a null-allowed field is preserved. [CONSTRAINTS] can specify additional business rules such as "never default limit to more than 100" or "always omit callback_url in staging environments." After generating the normalized payload, always validate it against the original schema with a deterministic JSON Schema validator before dispatch. For high-risk write operations, route the changes array to a human review queue or an audit log rather than silently applying defaults.

The null and empty value handling prompt operates as a pre-execution gate within your tool-calling pipeline. It should be invoked after the model generates a tool call payload but before that payload is dispatched to the downstream API. The harness receives the raw tool call arguments, the tool's JSON Schema or API contract, and any business-level defaults configuration. Its job is to normalize optional fields—deciding whether to omit them entirely, send them as explicit null, or substitute a configured default—so that the downstream API receives a payload that matches its expectations and avoids 400 errors from malformed optional parameters.

To wire this into an application, implement a middleware function that intercepts the tool call object. Pass the arguments block, the tool_schema (including which fields are optional and their types), and a defaults_map (key-value pairs for fallback values) into the prompt. The prompt returns a structured JSON object with normalized_arguments, a transformations array explaining each decision (e.g., 'omitted empty string for optional field X', 'substituted default for null field Y'), and a confidence score. Your harness should validate this output against the original schema to confirm no required fields were accidentally dropped. If the confidence score falls below a configured threshold (e.g., 0.85), route the payload to a human review queue or a clarification prompt instead of executing the tool call.

For production resilience, wrap the normalization step in a retry loop with exponential backoff. Log every transformation decision alongside the original and normalized payloads for auditability—this is critical when debugging why a downstream API rejected a call. If the normalization prompt itself fails or times out, fall back to a deterministic rule-based normalizer that strips empty strings from optional fields and applies your defaults map directly. Avoid executing tool calls with un-normalized optional arguments, as even a single empty string where an API expects omission can cascade into state corruption or confusing user-facing errors. Finally, integrate the transformations output into your observability stack so that support engineers can trace exactly which fields were modified and why.