app/tools/clock.py

"""Current-time tool. Returns ISO-8601 UTC by default."""
from __future__ import annotations

from datetime import datetime, timezone, timedelta


def clock(timezone_offset_hours: float = 0.0) -> str:
    """Return the current time at the given UTC offset (in hours)."""
    try:
        offset = float(timezone_offset_hours)
    except (TypeError, ValueError):
        offset = 0.0
    tz = timezone(timedelta(hours=offset))
    now = datetime.now(tz)
    label = "UTC" if offset == 0 else f"UTC{offset:+g}"
    return f"{now.strftime('%Y-%m-%d %H:%M:%S')} {label}"


CLOCK_SCHEMA = {
    "name": "clock",
    "description": "Get the current wall-clock time. Optionally pass a UTC offset in hours.",
    "input_schema": {
        "type": "object",
        "properties": {
            "timezone_offset_hours": {
                "type": "number",
                "description": "Hours offset from UTC. Defaults to 0 (UTC).",
            }
        },
        "required": [],
    },
}