Skip to main content

Time Tools

Date and time operations for AI agents.

Provider: Built-in
Authentication: None required
Category: Utilities
Credit Cost: 0 credits (free)

Overview​

Time tools provide date and time manipulation without external APIs. Use these for timestamp operations, date formatting, and time calculations in your workflows.

Available Tools​

Get Current Time​

Get the current date and time in various formats.

Tool ID: get_current_time
Credit Cost: 0 credits (free)

Parameters: None required - returns current time

Response:

{
  "timestamp": "2025-11-22T10:30:45Z",
  "unix_timestamp": 1700649045,
  "iso_format": "2025-11-22T10:30:45.123456",
  "readable": "Friday, November 22, 2025 10:30:45 AM"
}

Example Usage:

# Python
response = client.call_tool(name="get_current_time")
# Returns current timestamp in multiple formats
// TypeScript
const response = await client.callTool({
  name: "get_current_time"
});
// Use response.timestamp for ISO format
// Use response.unix_timestamp for Unix epoch
# cURL
curl -X POST https://api.joinreeva.com/mcp/server_123 \
  -H "Authorization: Bearer mcpk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "get_current_time"
    },
    "id": 1
  }'

Use Cases:

  • Timestamp log entries
  • Record event times
  • Calculate elapsed time
  • Schedule tasks and reminders
  • Add metadata to documents

Format Date​

Format date strings with custom patterns.

Tool ID: format_date
Credit Cost: 0 credits (free)

Parameters:

  • date_string (string, required): Date to format (ISO format recommended)
    • Examples: "2025-11-22", "2025-11-22T10:30:00Z"
  • format_str (string, optional): Python strftime format string
    • Default: "%Y-%m-%d"
    • See format codes below

Response:

{
  "original": "2025-11-22T10:30:00Z",
  "formatted": "November 22, 2025",
  "format_used": "%B %d, %Y"
}

Format Codes:

  • %Y - Year with century (2025)
  • %m - Month as number (01-12)
  • %d - Day of month (01-31)
  • %B - Full month name (November)
  • %b - Abbreviated month name (Nov)
  • %A - Full weekday name (Friday)
  • %a - Abbreviated weekday name (Fri)
  • %H - Hour 24-hour format (00-23)
  • %I - Hour 12-hour format (01-12)
  • %M - Minute (00-59)
  • %S - Second (00-59)
  • %p - AM/PM

Example Usage:

# Python - Format for display
response = client.call_tool(
    name="format_date",
    arguments={
        "date_string": "2025-11-22T10:30:00Z",
        "format_str": "%B %d, %Y"
    }
)
# Returns: {"formatted": "November 22, 2025"}
// TypeScript - Format with time
const response = await client.callTool({
  name: "format_date",
  arguments: {
    date_string: "2025-11-22T10:30:00Z",
    format_str: "%A, %B %d, %Y at %I:%M %p"
  }
});
// Returns: {"formatted": "Friday, November 22, 2025 at 10:30 AM"}

Common Format Patterns:

# US Format
"%m/%d/%Y"  # 11/22/2025

# European Format
"%d/%m/%Y"  # 22/11/2025

# Full readable
"%A, %B %d, %Y"  # Friday, November 22, 2025

# ISO with time
"%Y-%m-%d %H:%M:%S"  # 2025-11-22 10:30:45

# Short format
"%b %d, %Y"  # Nov 22, 2025

Use Cases:

  • Display dates in user-friendly format
  • Localize date formatting
  • Convert between date formats
  • Generate readable timestamps
  • Format dates for reports

Days Between​

Calculate the number of days between two dates.

Tool ID: days_between
Credit Cost: 0 credits (free)

Parameters:

  • start_date (string, required): Starting date (ISO format)
  • end_date (string, required): Ending date (ISO format)

Response:

{
  "start_date": "2025-11-01",
  "end_date": "2025-11-22",
  "days_between": 21,
  "is_future": true
}

Example Usage:

# Python - Calculate project duration
response = client.call_tool(
    name="days_between",
    arguments={
        "start_date": "2025-01-01",
        "end_date": "2025-12-31"
    }
)
# Returns: {"days_between": 364}
// TypeScript - Days until deadline
const response = await client.callTool({
  name: "days_between",
  arguments: {
    start_date: "2025-11-22",
    end_date: "2025-12-25"
  }
});
// Returns: {"days_between": 33}

Use Cases:

  • Calculate age from birthdate
  • Compute project timelines
  • Track days until deadlines
  • Measure time between events
  • Subscription duration calculations

Notes:

  • Returns absolute difference (always positive)
  • Excludes time portion (only dates)
  • Works with past and future dates
  • Includes start date, excludes end date in count

Common Patterns​

Timestamp Everything​

# Add timestamps to log entries
current_time = client.call_tool(name="get_current_time")

log_entry = {
    "event": "user_login",
    "timestamp": current_time["iso_format"],
    "user_id": "123"
}

Date Range Validation​

# Check if project is within timeline
project_start = "2025-01-01"
project_end = "2025-06-30"

duration = client.call_tool(
    name="days_between",
    arguments={
        "start_date": project_start,
        "end_date": project_end
    }
)

if duration["days_between"] > 180:
    print("⚠️ Project exceeds 6-month limit")
else:
    print("✅ Project timeline approved")

Formatted Notifications​

# Create readable notification
current_time = client.call_tool(name="get_current_time")

formatted = client.call_tool(
    name="format_date",
    arguments={
        "date_string": current_time["timestamp"],
        "format_str": "%B %d, %Y at %I:%M %p"
    }
)

notification = f"Report generated on {formatted['formatted']}"
# "Report generated on November 22, 2025 at 10:30 AM"

Deadline Tracking​

# Calculate days until deadline
current = client.call_tool(name="get_current_time")
deadline = "2025-12-31"

days_left = client.call_tool(
    name="days_between",
    arguments={
        "start_date": current["iso_format"].split("T")[0],
        "end_date": deadline
    }
)

if days_left["days_between"] < 7:
    urgency = "🔴 URGENT"
elif days_left["days_between"] < 30:
    urgency = "🟡 Soon"
else:
    urgency = "🟢 On track"

print(f"{urgency}: {days_left['days_between']} days remaining")

Best Practices​

Timestamp Format​

  • Use ISO 8601 format for storage (2025-11-22T10:30:00Z)
  • Convert to readable format only for display
  • Include timezone information when relevant
  • Use UTC for consistency across systems

Date Calculations​

  • Always validate date inputs
  • Be aware of leap years
  • Consider timezone differences for user-facing dates
  • Use days_between for date arithmetic

Performance​

  • Time tools are extremely fast (< 1ms)
  • Safe for high-frequency operations
  • No external dependencies or rate limits
  • Process in bulk without performance impact

Integration Examples​

Example 1: Event Logging System​

# Complete logging with timestamps
def log_event(event_type, details):
    timestamp = client.call_tool(name="get_current_time")
    
    formatted_time = client.call_tool(
        name="format_date",
        arguments={
            "date_string": timestamp["iso_format"],
            "format_str": "%Y-%m-%d %H:%M:%S"
        }
    )
    
    log_entry = {
        "timestamp": timestamp["unix_timestamp"],
        "formatted_time": formatted_time["formatted"],
        "event_type": event_type,
        "details": details
    }
    
    # Save to database
    database.insert("logs", log_entry)

Example 2: Subscription Management​

# Calculate subscription status
subscription_start = "2025-01-01"
subscription_end = "2025-12-31"
current = client.call_tool(name="get_current_time")

days_remaining = client.call_tool(
    name="days_between",
    arguments={
        "start_date": current["iso_format"].split("T")[0],
        "end_date": subscription_end
    }
)

total_days = client.call_tool(
    name="days_between",
    arguments={
        "start_date": subscription_start,
        "end_date": subscription_end
    }
)

percentage_used = (
    (total_days["days_between"] - days_remaining["days_between"]) 
    / total_days["days_between"] * 100
)

print(f"Subscription: {percentage_used:.1f}% used")
print(f"Days remaining: {days_remaining['days_between']}")

Example 3: Report Generation​

# Generate dated report
current = client.call_tool(name="get_current_time")

report_date = client.call_tool(
    name="format_date",
    arguments={
        "date_string": current["iso_format"],
        "format_str": "%B %d, %Y"
    }
)

report = {
    "title": f"Monthly Report - {report_date['formatted']}",
    "generated_at": current["iso_format"],
    "period_start": "2025-11-01",
    "period_end": "2025-11-30",
    "data": gather_report_data()
}

save_report(report)

Troubleshooting​

"Invalid date format" Error​

Cause: Date string not in expected format

Solutions:

  • Use ISO 8601 format: YYYY-MM-DD or YYYY-MM-DDTHH:MM:SSZ
  • Check for typos in date string
  • Ensure date components are valid (e.g., month 1-12)
  • Include timezone for full timestamps

"Invalid format string" Error​

Cause: Format string contains invalid codes

Solutions:

  • Check format codes against documentation
  • Test format strings before deploying
  • Use common patterns provided above
  • Verify % symbols are properly used

Unexpected Days Calculation​

Cause: Including/excluding time component

Solutions:

  • Strip time component if only comparing dates
  • Be aware of timezone differences
  • Remember calculation is inclusive/exclusive
  • Verify date order (start before end)

See Also​