Date and Timestamp Normalization for Tool Arguments Prompt Template

This prompt is designed for a single, high-leverage repair task: converting a malformed or ambiguous temporal argument from a failed tool call into a strict, predictable format that the target API or function actually accepts. The primary user is a scheduling system integrator, a log pipeline developer, or an agent platform engineer who has already received a validation error from a downstream tool. The prompt is not a general-purpose date parser, a natural-language understanding interface, or a user-facing chatbot. Its job is to act as a targeted repair step inside an automated retry loop, taking the original invalid value, the target tool's expected format, and a known reference timestamp, and returning a corrected, machine-readable string.

Use this prompt when a tool call has failed validation specifically because of a temporal argument—such as start_time, since, deadline, or range_start—and the error is due to format ambiguity, missing timezone offsets, relative date expressions like 'next Tuesday,' or locale-specific ordering. The prompt is most effective when the repair context is rich: you must supply the exact tool schema field definition, the raw invalid value, a reference timestamp to anchor relative expressions, and the expected output format (typically ISO 8601 or a tool-specific pattern). Do not use this prompt for general data cleaning, for normalizing dates that are already in a valid format, or for resolving semantic ambiguities that require business logic (e.g., 'end of quarter' without a fiscal calendar). It is a surgical repair tool, not a temporal reasoning engine.

Before wiring this into a production agent loop, ensure you have a clear retry budget and a fallback path. The prompt can resolve most format and timezone errors, but it will not invent missing information. If the original argument is 'sometime next month' and the tool requires a precise millisecond timestamp, the repair will fail or hallucinate. In such cases, the correct next step is to escalate to a human or to a clarification prompt, not to retry indefinitely. After implementing this prompt, validate every repaired output against the target schema before execution, and log both the original and repaired values for auditability. If the tool call affects billing, scheduling of physical resources, or compliance events, a human-in-the-loop review step is mandatory.

This prompt template is designed to be injected into an agent's repair loop when a tool call fails validation due to a temporal argument mismatch. It takes the original malformed argument, the tool's expected format specification, and an execution timestamp as context. The prompt instructs the model to normalize the value to the target format, resolve relative expressions, and handle timezone offsets. Use this template as a starting point, adapting the [TARGET_FORMAT] and [TOOL_SCHEMA] placeholders to your specific tool's contract.

textCopy
You are a precise date and timestamp normalization function. Your task is to repair a malformed temporal argument so it strictly conforms to the expected format for a tool call.

INPUT:
- Malformed Argument Value: [MALFORMED_VALUE]
- Target Parameter Name: [PARAMETER_NAME]
- Expected Format: [TARGET_FORMAT] (e.g., ISO 8601, Unix milliseconds, 'YYYY-MM-DD')
- Execution Timestamp (the current moment in ISO 8601): [EXECUTION_TIMESTAMP]
- Tool Schema Snippet: [TOOL_SCHEMA]
- Conversation Context (for resolving relative dates like 'tomorrow'): [CONVERSATION_CONTEXT]

INSTRUCTIONS:
1. Analyze the malformed value and identify the intended date, time, and timezone.
2. If the value is a relative expression (e.g., 'now', 'next Monday', 'in 2 hours'), resolve it using the Execution Timestamp as the anchor.
3. If a timezone offset is missing but implied by the context or schema, infer it. Default to UTC if no other information is available.
4. Convert the resolved value to the Expected Format.
5. Output ONLY the corrected value. Do not include any explanation, commentary, or surrounding text.

CORRECTED VALUE:

To adapt this template, replace the placeholders with data from your agent's runtime. [MALFORMED_VALUE] is the raw string from the model's tool call. [TARGET_FORMAT] should be a precise, machine-readable spec like ISO 8601 or YYYY-MM-DDThh:mm:ssZ. The [EXECUTION_TIMESTAMP] is critical for grounding relative dates and must be the actual time of the initial tool call attempt, not the repair attempt, to avoid time drift. The [CONVERSATION_CONTEXT] is optional but essential for resolving user-provided relative dates. After implementing, always validate the output against the target format with a strict parser before executing the tool call. For high-stakes scheduling or logging, log the original and normalized values together for auditability.

This prompt is designed to sit inside a tool-call repair loop—the middleware that catches a failed function call, extracts the invalid temporal argument, and attempts a targeted fix before the agent continues. The harness must provide the prompt with the original malformed value, the target tool's expected format specification (e.g., ISO 8601, Unix milliseconds, a custom pattern), the conversation context that produced the value, and an explicit reference timestamp that anchors relative expressions like 'next Tuesday' or 'end of month.' Without a reference timestamp, the model cannot resolve relative dates deterministically, and the repair will drift across executions.

Validation and retry flow: After the model returns a normalized value, the harness must validate it against the target format before passing it back to the tool. Use a strict parser—datetime.fromisoformat() for ISO 8601, dateutil.parser with a format constraint, or a regex validator for custom patterns. If validation fails, increment a retry counter and re-invoke the repair prompt with the validation error message appended to [CONSTRAINTS]. Set a hard retry budget (3 attempts is typical) and escalate to a human or a fallback default on exhaustion. Timezone handling is the most common failure mode: always log the timezone offset applied, and if the target system requires UTC, convert explicitly in the harness rather than trusting the model to do it. For high-stakes scheduling systems, add a human-in-the-loop gate when the normalized value differs from the original by more than a configurable threshold (e.g., 24 hours), as this often indicates a misinterpreted relative date.

Model choice and latency: This is a narrow, deterministic repair task. Use a fast, cheaper model (e.g., GPT-4o-mini, Claude Haiku) rather than a large reasoning model. The prompt's job is format conversion with context, not deep reasoning. Logging and observability: Record every repair attempt with the original value, the reference timestamp, the normalized output, the validation result, the retry count, and the final disposition (executed, escalated, defaulted). This audit trail is essential for debugging timezone drift, relative-date misinterpretation, and model inconsistency. What to avoid: Do not use this prompt for date extraction from unstructured text—that belongs in a data extraction pipeline. Do not skip the reference timestamp parameter; relative dates without an anchor produce non-deterministic and untestable outputs. Do not execute the repaired tool call without format validation, as even a syntactically plausible date can be semantically wrong.