# `Nous.Tools.DateTimeTools`
[🔗](https://github.com/nyo16/nous/blob/v0.17.1/lib/nous/tools/date_time_tools.ex#L1)

Built-in tools for date and time operations.

These tools provide common date/time functionality that AI agents often need:
- Get current date/time in various formats
- Parse and format dates
- Calculate date differences
- Check business days and weekends
- Timezone conversions

## Usage

    agent = Nous.new("lmstudio:qwen3-vl-4b-thinking-mlx",
      tools: [
        &DateTimeTools.current_date/2,
        &DateTimeTools.current_time/2,
        &DateTimeTools.current_datetime/2
      ]
    )

    {:ok, result} = Nous.run(agent, "What day is today?")

# `args`

```elixir
@type args() :: %{optional(String.t()) => term()}
```

Tool arguments exactly as the model produced them: JSON object keys stay
strings, values are unvalidated. Every function below reads what it needs
and falls back to a default for anything missing or of the wrong type.

# `ctx`

```elixir
@type ctx() :: Nous.RunContext.t() | nil
```

Run context. These tools are pure and ignore it, but they are registered
with `takes_ctx: true`, so it is always the first argument.

# `result`

```elixir
@type result() :: %{required(atom()) => term()}
```

Tool result: an atom-keyed map that echoes the inputs it used alongside the
computed fields, so the model can see what it actually asked for.

# `add_days`

```elixir
@spec add_days(ctx(), args()) :: result()
```

Add or subtract days from a date.

## Arguments

- date: Date in ISO8601 format (YYYY-MM-DD), defaults to today
- days: Number of days to add (positive) or subtract (negative)

# `current_date`

```elixir
@spec current_date(ctx(), args()) :: result()
```

Get the current date in the specified format.

## Arguments

- format: "iso8601" (default), "us" (MM/DD/YYYY), "eu" (DD/MM/YYYY), "full" (Monday, January 1, 2025)
- timezone: Optional timezone (e.g., "America/New_York", "Europe/London", "UTC")

# `current_datetime`

```elixir
@spec current_datetime(ctx(), args()) :: result()
```

Get the current date and time together.

## Arguments

- format: "iso8601" (default), "rfc3339", "unix", "human"
- timezone: Optional timezone

# `current_month`

```elixir
@spec current_month(ctx(), args()) :: result()
```

Get information about the current month.

## Arguments

- timezone: Optional timezone

# `current_time`

```elixir
@spec current_time(ctx(), args()) :: result()
```

Get the current time in the specified format.

## Arguments

- format: "24h" (default, HH:MM:SS), "12h" (hh:MM:SS AM/PM), "short" (HH:MM)
- timezone: Optional timezone

# `current_week`

```elixir
@spec current_week(ctx(), args()) :: result()
```

Get the start and end of the current week.

## Arguments

- timezone: Optional timezone
- week_start: Day to consider start of week (1=Monday default, 7=Sunday)

# `date_difference`

```elixir
@spec date_difference(ctx(), args()) :: result()
```

Calculate the difference between two dates.

## Arguments

- date1: First date in ISO8601 format (YYYY-MM-DD)
- date2: Second date in ISO8601 format (YYYY-MM-DD)
- unit: "days" (default), "weeks", "months", "years"

# `day_of_week`

```elixir
@spec day_of_week(ctx(), args()) :: result()
```

Get the day of the week for a given date.

## Arguments

- date: Date in ISO8601 format (YYYY-MM-DD), defaults to today

# `is_weekend`

```elixir
@spec is_weekend(ctx(), args()) :: result()
```

Check if a date is a weekend.

## Arguments

- date: Date in ISO8601 format (YYYY-MM-DD), defaults to today

# `parse_date`

```elixir
@spec parse_date(ctx(), args()) :: result()
```

Parse a human-readable date string.

## Arguments

- date_string: Date in various formats (ISO8601, MM/DD/YYYY, DD/MM/YYYY, etc.)
- format: Expected format hint ("iso8601", "us", "eu")

---

*Consult [api-reference.md](api-reference.md) for complete listing*