# How to Pass System Facts (Date and Locale) to the Needle Agent

> Discover how the Needle agent automatically passes system facts like date and locale to the LLM runtime. Learn about the built-in system_facts tool for seamless integration.

- Repository: [Cactus Compute, Inc./needle](https://github.com/cactus-compute/needle)
- Tags: how-to-guide
- Published: 2026-08-22

---

**The Needle agent receives system facts like the current date and locale through a built-in `system_facts` tool registered via the `@tool` decorator in [`needle/agent/tools.py`](https://github.com/cactus-compute/needle/blob/main/needle/agent/tools.py), which automatically exposes these values to the LLM runtime without manual wiring.**

The **Needle** framework from `cactus-compute/needle` provides a streamlined way to inject real-time system context into LLM-driven workflows. By leveraging the automatic tool registration system, developers can pass critical environmental data—such as timestamps and localization settings—directly to the agent's context payload with minimal configuration.

## Built-in System Facts Tool

The core functionality resides in **[`needle/agent/tools.py`](https://github.com/cactus-compute/needle/blob/main/needle/agent/tools.py)**, where the **`system_facts`** function is defined and decorated with **`@tool`**. This decorator registers the function's JSON schema with the agent runtime, making it discoverable by the LLM during prompt processing.

### How system_facts Works

When invoked, the function gathers system data using Python's standard library:

- **`datetime.datetime.now(tz=datetime.timezone.utc).isoformat()`** generates an ISO-8601 timestamp
- **`locale.getdefaultlocale()`** or **`locale.getlocale()`** retrieves the active system locale string

The function returns a dictionary structured as:

```json
{
    "date": "2026-08-22T14:35:12+00:00",
    "locale": "en_US"
}

```

Because the **`@tool`** decorator handles schema registration, the agent automatically understands the function signature (`def system_facts() -> dict`) and can invoke it when context is required.

## Using System Facts in Agent Workflows

### Implicit Tool Invocation

The most common pattern involves letting the LLM decide when to fetch system facts. When you initialize a **`Needle`** agent and submit a prompt requiring temporal or regional context, the runtime automatically selects the `system_facts` tool:

```python
from needle import Needle

agent = Needle(model="gpt-4o-mini")

response = agent.run(
    "Give me a short report that includes the current date and formats the heading "
    "according to the system locale."
)

print(response)

```

The internal flow follows four steps:
1. **Prompt parsing** – the LLM identifies requirements for "date" and "locale"
2. **Tool selection** – the runtime matches the request to `system_facts` in [`needle/agent/tools.py`](https://github.com/cactus-compute/needle/blob/main/needle/agent/tools.py)
3. **Execution** – the function fetches live system data
4. **Response generation** – the agent merges the returned dictionary into the final context

### Direct Tool Access

You can also invoke the tool manually for debugging or custom preprocessing:

```python
from needle.agent.tools import system_facts

info = system_facts()
print(f"Today's date: {info['date']}")
print(f"System locale: {info['locale']}")

```

## Customizing System Facts

### Creating Custom Wrappers

For scenarios requiring specific timezones or non-default locales, extend the pattern by creating your own decorated function. The agent will expose this alongside the built-in tool:

```python
from needle.agent.tools import tool
import datetime
import locale

@tool
def custom_system_facts(tz: str = "UTC", loc: str = "fr_FR") -> dict:
    """Return date and locale, optionally overriding defaults."""
    now = datetime.datetime.now(datetime.timezone.utc).astimezone(
        datetime.timezone(datetime.timedelta(hours=int(tz)))
    )
    locale.setlocale(locale.LC_ALL, loc)
    return {"date": now.isoformat(), "locale": locale.getlocale()[0]}

```

This approach allows you to pass **custom system information** to the agent while maintaining the same automatic discovery mechanism used by the default implementation.

## Summary

- The **`system_facts`** tool in [`needle/agent/tools.py`](https://github.com/cactus-compute/needle/blob/main/needle/agent/tools.py) automatically exposes date and locale data via the **`@tool`** decorator
- System facts are retrieved using standard library modules `datetime` and `locale`, returning ISO-8601 timestamps and locale strings
- The agent runtime in [`needle/agent/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/agent/__init__.py) handles tool discovery and invocation without manual registration
- You can override default behavior by creating custom functions decorated with **`@tool`** and passing specific timezone or locale parameters

## Frequently Asked Questions

### How does the Needle agent discover the system_facts tool?

The agent discovers the tool through the **`@tool`** decorator defined in [`needle/agent/tools.py`](https://github.com/cactus-compute/needle/blob/main/needle/agent/tools.py). During initialization in [`needle/agent/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/agent/__init__.py), the runtime scans for decorated functions and registers their JSON schemas, making them available for LLM tool selection without explicit configuration.

### Can I override the default timezone or locale?

Yes. While the built-in `system_facts` uses UTC and the system default locale, you can create a custom function decorated with **`@tool`** that accepts `tz` and `loc` parameters. This custom tool will be automatically exposed to the agent alongside the default implementation.

### What format does the date field return?

The date field returns an **ISO-8601 formatted string** generated by `datetime.datetime.now(tz=datetime.timezone.utc).isoformat()`, including timezone offset (e.g., `2026-08-22T14:35:12+00:00`).

### Where is the tool registration handled?

Tool registration occurs in **[`needle/agent/tools.py`](https://github.com/cactus-compute/needle/blob/main/needle/agent/tools.py)** where the `@tool` decorator is defined and applied to `system_facts`. The agent bootstrap process in **[`needle/agent/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/agent/__init__.py)** loads these registered tools into the runtime context, while **[`needle/cli.py`](https://github.com/cactus-compute/needle/blob/main/needle/cli.py)** serves as the entry point for command-line invocation.