"Run this every weekday at 9 AM" seems straightforward until you need to write the cron expression. If you are building an AI assistant that helps users schedule tasks, you need tools to parse, validate, and explain cron expressions. This guide shows you how to add cron capabilities to your agent via MCP.
The Cron Confusion Problem
Cron expressions pack a lot of scheduling logic into five or six fields. Even experienced developers regularly look up the syntax:
Cron Expression Format
┌───────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌───────────── day of month (1-31)
│ │ │ ┌───────────── month (1-12)
│ │ │ │ ┌───────────── day of week (0-6, Sunday=0)
│ │ │ │ │
* * * * *LLMs know the format, but they make mistakes:
- Invalid expressions: "0 9 * * 7" (7 is not a valid day; use 0 or SUN for Sunday)
- Misinterpretation: Confusing "0 9 1-5 * *" (days 1-5 of month) with weekdays
- Timezone confusion: Not accounting for server timezone vs user timezone
- Wrong next run: Incorrectly calculating when the schedule triggers next
The Stakes: A wrong cron expression can mean a backup runs at 9 PM instead of 9 AM, or a report generates on the 1st of every month instead of every Monday. These errors are hard to catch until they cause real problems.
Parsing Cron Expressions
TinyFn parses cron expressions and provides human-readable descriptions:
MCP Tool Call
Tool: cron/parse
Input: {
"expression": "0 9 * * 1-5"
}
Result: {
"expression": "0 9 * * 1-5",
"valid": true,
"description": "At 9:00 AM, Monday through Friday",
"fields": {
"minute": "0",
"hour": "9",
"dayOfMonth": "*",
"month": "*",
"dayOfWeek": "1-5"
}
}Validating Expressions
The parser also catches invalid expressions:
MCP Tool Call - Invalid Expression
Tool: cron/parse
Input: {
"expression": "0 25 * * *"
}
Result: {
"expression": "0 25 * * *",
"valid": false,
"error": "Invalid hour value: 25 (must be 0-23)"
}Common Cron Expressions
| Expression | Description |
|---|---|
0 * * * * |
Every hour, on the hour |
0 9 * * * |
Every day at 9:00 AM |
0 9 * * 1-5 |
Weekdays at 9:00 AM |
0 0 1 * * |
First day of every month at midnight |
*/15 * * * * |
Every 15 minutes |
0 9,17 * * * |
Every day at 9 AM and 5 PM |
Calculating Next Run Times
Knowing when a cron job will run next is essential for verification:
MCP Tool Call
Tool: cron/next
Input: {
"expression": "0 9 * * 1-5",
"timezone": "America/New_York"
}
Result: {
"expression": "0 9 * * 1-5",
"description": "At 9:00 AM, Monday through Friday",
"timezone": "America/New_York",
"next_run": "2025-02-03T09:00:00-05:00",
"next_run_relative": "in 3 days"
}Multiple Upcoming Runs
MCP Tool Call
Tool: cron/next
Input: {
"expression": "0 9 * * 1-5",
"timezone": "America/New_York",
"count": 5
}
Result: {
"expression": "0 9 * * 1-5",
"description": "At 9:00 AM, Monday through Friday",
"next_runs": [
"2025-02-03T09:00:00-05:00",
"2025-02-04T09:00:00-05:00",
"2025-02-05T09:00:00-05:00",
"2025-02-06T09:00:00-05:00",
"2025-02-07T09:00:00-05:00"
]
}Scheduling Workflows
Here is how a scheduling assistant uses cron tools:
Example: Natural Language to Cron
User: "I need to run a report every Monday and Thursday at 2:30 PM"
Agent workflow:
1. Generate cron expression based on intent
2. Validate with TinyFn
3. Show next runs for confirmation
Agent generates: "30 14 * * 1,4"
Tool call:
- cron/parse { "expression": "30 14 * * 1,4" }
Result: {
"valid": true,
"description": "At 2:30 PM, on Monday and Thursday"
}
- cron/next { "expression": "30 14 * * 1,4", "count": 4 }
Result: {
"next_runs": [
"2025-02-03T14:30:00", // Monday
"2025-02-06T14:30:00", // Thursday
"2025-02-10T14:30:00", // Monday
"2025-02-13T14:30:00" // Thursday
]
}
Agent response:
"Here's your cron expression: `30 14 * * 1,4`
This means: 'At 2:30 PM, on Monday and Thursday'
Next runs:
- Mon, Feb 3 at 2:30 PM
- Thu, Feb 6 at 2:30 PM
- Mon, Feb 10 at 2:30 PM
- Thu, Feb 13 at 2:30 PM
Does this match what you need?"Explaining Existing Schedules
Example: Understanding Legacy Cron
User: "What does this cron expression do? 0 */4 * * *"
Tool call:
- cron/parse { "expression": "0 */4 * * *" }
Result: {
"valid": true,
"description": "At minute 0, every 4 hours",
"fields": {
"minute": "0",
"hour": "*/4",
"dayOfMonth": "*",
"month": "*",
"dayOfWeek": "*"
}
}
- cron/next { "expression": "0 */4 * * *", "count": 6 }
Result: {
"next_runs": [
"2025-01-31T16:00:00",
"2025-01-31T20:00:00",
"2025-02-01T00:00:00",
"2025-02-01T04:00:00",
"2025-02-01T08:00:00",
"2025-02-01T12:00:00"
]
}
Agent response:
"This cron expression runs **every 4 hours, at the top of the hour**.
Specifically, it runs at: 12 AM, 4 AM, 8 AM, 12 PM, 4 PM, and 8 PM every day.
Next 6 runs:
- Today at 4:00 PM
- Today at 8:00 PM
- Tomorrow at 12:00 AM
- Tomorrow at 4:00 AM
- Tomorrow at 8:00 AM
- Tomorrow at 12:00 PM"Automation Examples
DevOps Scheduling
Example: Backup Schedule
User: "Set up a backup that runs at 3 AM every day, but full backups
only on Sunday and incremental on other days"
Agent creates two schedules:
Full backup: "0 3 * * 0" (Sundays at 3 AM)
Incremental: "0 3 * * 1-6" (Mon-Sat at 3 AM)
Verified with TinyFn:
- cron/parse confirms both are valid
- cron/next shows correct scheduling
Agent response:
"Here's your backup schedule:
**Full Backup** (Sundays)
\`\`\`
0 3 * * 0
\`\`\`
Next run: Sunday, Feb 2 at 3:00 AM
**Incremental Backup** (Monday-Saturday)
\`\`\`
0 3 * * 1-6
\`\`\`
Next run: Tomorrow at 3:00 AM"Business Automation
Example: Report Generation
User: "Create a schedule for:
- Daily sales summary at 6 PM
- Weekly report every Friday at 5 PM
- Monthly report on the last day of the month at midnight"
Agent generates and validates:
Daily: "0 18 * * *"
Weekly: "0 17 * * 5"
Monthly: "0 0 L * *" (L = last day)
Each validated with cron/parse and cron/next
Agent response:
"Here are your report schedules:
**Daily Sales Summary**
\`0 18 * * *\` - Every day at 6:00 PM
Next: Today at 6:00 PM
**Weekly Report**
\`0 17 * * 5\` - Every Friday at 5:00 PM
Next: Friday, Feb 7 at 5:00 PM
**Monthly Report**
\`0 0 L * *\` - Last day of every month at midnight
Next: Feb 28 at 12:00 AM"MCP Setup
Add TinyFn cron tools to your AI agent:
mcp.json
{
"mcpServers": {
"tinyfn-cron": {
"url": "https://api.tinyfn.io/mcp/cron",
"headers": {
"X-API-Key": "your-api-key"
}
}
}
}Available Cron Tools
| Tool | Description |
|---|---|
cron/parse |
Parse and validate cron expression, get description |
cron/next |
Calculate next run time(s) for expression |
cron/validate |
Check if expression is valid |
Special Characters
| Character | Meaning | Example |
|---|---|---|
* |
Any value | * * * * * (every minute) |
, |
Value list | 0 9,17 * * * (9 AM and 5 PM) |
- |
Range | 0 9 * * 1-5 (Mon-Fri) |
/ |
Step | */15 * * * * (every 15 min) |
L |
Last | 0 0 L * * (last day of month) |
Add Cron Tools to Your Scheduling Agent
Get your free API key and give your agent accurate cron capabilities.
Get Free API Key