Date and time tool
Use resolve_datetime for calendar calculations during a conversation.
Overview
The tool lets an Assistant:
- Find which day of the week a date falls on.
- Convert relative dates such as "in three weeks" or "in two months" into a calendar date.
- Calculate the time until or since an appointment, delivery, or deadline.
How it works
The Assistant supplies a date, a date and time, or "now". It can add days, weeks, or months, with negative values moving into the past. The tool returns:
- the resulting date (and time),
- its day of the week,
- how far it is from now, in days, and in days and hours when a time is given.
Example: on Monday 12 October 2026, the caller asks for an appointment "in three weeks". The Assistant calls the tool with add_weeks: 3 and gets back Monday 2 November 2026, 21 days from now.
Adding months keeps the same day of the month when possible. If that day does not exist, the result is the last day of the month. For example, 31 January + 1 month is 28 February in a non-leap year or 29 February in a leap year.
Timezone
"Now" and every date are in the Assistant's timezone, set on the Assistant, e.g. Europe/Paris. If no timezone is set, the service's TIMEZONE setting is used, falling back to Europe/Paris.
Full example
Step 1: fetch the tool definition
Code
Note the id of the returned definition.
Step 2: attach the tool to the Assistant
Code
Code
Attach one resolve_datetime tool per Assistant. The API rejects a second instance with 400 DUPLICATE_TOOL_NAME.