Zovo Focus Timer

Use this when the user wants a timer now: a pomodoro timer (25/5, 50/10, pomodoro timer for studying), a countdown timer ("10-minute timer"), or an interval timer (work/rest repeats, e.g. 45 s on, 15 s off). Returns the full phase plan (focus blocks, short and long breaks, totals) and shows a live timer with a progress ring, play, pause, skip and reset controls, and an optional chime. With a clock time for the first block and a time zone (IANA name such as Europe/Warsaw, a city, or an abbreviation such as EST), each phase also gets wall-clock times that stay correct across daylight-saving changes. Limits: up to 24 hours and 96 rounds; no phone notifications, alarms when the chat is closed, or music. Do not use for reminders about future appointments, questions about how long something takes (e.g. boiling an egg), or unit conversions.

{
  "type": "object",
  "properties": {
    "mode": {
      "type": "string",
      "enum": [
        "pomodoro",
        "countdown",
        "interval"
      ],
      "description": "Timer type: \"pomodoro\" (focus blocks with short and long breaks, e.g. 25/5), \"countdown\" (one countdown, e.g. 10 minutes), or \"interval\" (repeating work/rest, e.g. 45 s on, 15 s off)."
    },
    "work_minutes": {
      "description": "Length of each focus or work block in minutes, e.g. 25 for a classic pomodoro or 50 for 50/10. For countdown this is the countdown length, e.g. 10. Decimals allowed: 0.5 = 30 seconds. Default 25 for pomodoro.",
      "type": "number"
    },
    "short_break_minutes": {
      "description": "Break between blocks in minutes, e.g. 5 (pomodoro default) or 10 for 50/10. For interval mode this is the rest, e.g. 0.25 = 15 seconds. 0 = no break.",
      "type": "number"
    },
    "long_break_minutes": {
      "description": "Longer break taken after every long_break_every blocks, in minutes, e.g. 15 (pomodoro default).",
      "type": "number"
    },
    "rounds": {
      "description": "Number of focus blocks, e.g. 4 (pomodoro default). Ignored for countdown.",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "long_break_every": {
      "description": "Take the long break after this many blocks, e.g. 4 (pomodoro default). 0 = never.",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "label": {
      "description": "What the user is focusing on, shown on the timer, e.g. \"Biology chapter 3\" or \"Presentation practice\".",
      "type": "string",
      "maxLength": 60
    },
    "start_time": {
      "description": "Optional clock time the session starts, as HH:MM (24-hour) or 9:30 am, e.g. 14:00. When given, every phase gets wall-clock start and end times.",
      "type": "string",
      "maxLength": 20
    },
    "time_zone": {
      "description": "Optional time zone for start_time: an IANA name (e.g. Europe/Warsaw, America/New_York), a city (e.g. Warsaw), or an abbreviation (e.g. EST, CET). Makes the clock times correct across daylight-saving changes.",
      "type": "string",
      "maxLength": 64
    },
    "date": {
      "description": "Optional date of start_time as YYYY-MM-DD, e.g. 2026-10-02. Defaults to today in time_zone.",
      "type": "string",
      "maxLength": 10
    },
    "sound": {
      "description": "Play a short chime when each phase ends. Default true.",
      "type": "boolean"
    },
    "auto_advance": {
      "description": "Start the next phase automatically when one ends. Default true; false pauses after each phase until the user presses Start.",
      "type": "boolean"
    }
  },
  "required": [
    "mode"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "mode": {
      "type": "string"
    },
    "label": {
      "type": "string"
    },
    "summary": {
      "type": "string"
    },
    "settings": {
      "type": "object",
      "properties": {
        "work_minutes": {
          "type": "number"
        },
        "short_break_minutes": {
          "type": "number"
        },
        "long_break_minutes": {
          "type": "number"
        },
        "rounds": {
          "type": "number"
        },
        "long_break_every": {
          "type": "number"
        },
        "auto_advance": {
          "type": "boolean"
        },
        "sound": {
          "type": "boolean"
        }
      },
      "required": [
        "work_minutes",
        "short_break_minutes",
        "long_break_minutes",
        "rounds",
        "long_break_every",
        "auto_advance",
        "sound"
      ],
      "additionalProperties": false
    },
    "totals": {
      "type": "object",
      "properties": {
        "focus_minutes": {
          "type": "number"
        },
        "break_minutes": {
          "type": "number"
        },
        "fixed_break_minutes": {
          "type": "number"
        },
        "free_minutes": {
          "type": "number"
        },
        "total_minutes": {
          "type": "number"
        },
        "focus_blocks": {
          "type": "number"
        }
      },
      "required": [
        "focus_minutes",
        "break_minutes",
        "fixed_break_minutes",
        "free_minutes",
        "total_minutes",
        "focus_blocks"
      ],
      "additionalProperties": false
    },
    "schedule": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "date": {
              "type": "string"
            },
            "date_label": {
              "type": "string"
            },
            "time_zone": {
              "type": [
                "string",
                "null"
              ]
            },
            "start": {
              "type": "string"
            },
            "end": {
              "type": "string"
            },
            "start_local": {
              "type": "string"
            },
            "starts_at_ms": {
              "type": [
                "number",
                "null"
              ]
            }
          },
          "required": [
            "date",
            "date_label",
            "time_zone",
            "start",
            "end",
            "start_local",
            "starts_at_ms"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ]
    },
    "phases": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string"
          },
          "minutes": {
            "type": "number"
          },
          "round": {
            "type": "number"
          },
          "label": {
            "type": "string"
          },
          "start": {
            "type": "string"
          },
          "end": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "minutes"
        ],
        "additionalProperties": false
      }
    },
    "phase_count": {
      "type": "number"
    },
    "phases_truncated": {
      "type": "boolean"
    },
    "notes": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "spare_minutes": {
      "type": [
        "number",
        "null"
      ]
    },
    "downloads": {
      "type": "object",
      "properties": {
        "ics": {
          "type": "string"
        }
      },
      "additionalProperties": false
    }
  },
  "required": [
    "mode",
    "label",
    "summary",
    "settings",
    "totals",
    "schedule",
    "phases",
    "notes",
    "spare_minutes",
    "downloads"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

Use this when the user wants pomodoros fitted into a time window: "I have 3 hours to study until 5pm", "plan pomodoros from 9:00 to 12:30 with a lunch break", "how many 50/10 blocks fit before my 3pm meeting". Fits the most whole focus blocks between the start and end time around fixed breaks (if the standard long break would cost a block, it shortens or drops it and says so, unless the user gave long-break settings) and returns clock times for every block, total focus minutes, spare time, an .ics calendar file with one event per focus block, and a live timer for the plan. Limits: one window of up to 24 hours; it does not read or change the user's calendar and does not build multi-day study plans (e.g. finals week).

{
  "type": "object",
  "properties": {
    "start_time": {
      "description": "When the session starts, as HH:MM or 9:00 am, e.g. 09:00. Needed unless end_time is given with available_minutes or rounds.",
      "type": "string",
      "maxLength": 20
    },
    "end_time": {
      "description": "When the session must end, e.g. 17:00 or 5pm (for \"until 5pm\"). Earlier times mean the next day; equal start and end times are refused. A bare hour such as 5 after a 14:00 start is read as 5pm, with a note; use 05:00 for next-day 5am.",
      "type": "string",
      "maxLength": 20
    },
    "available_minutes": {
      "description": "Total time available in minutes, e.g. 180 for \"I have 3 hours\". Used with start_time or end_time. Max 1440.",
      "type": "number"
    },
    "rounds": {
      "description": "Maximum number of pomodoros to schedule, e.g. 6. Without an end time the plan runs until this many are done.",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "work_minutes": {
      "description": "Focus block length in minutes, e.g. 25 (default) or 50.",
      "type": "number"
    },
    "short_break_minutes": {
      "description": "Break between focus blocks in minutes, e.g. 5 (default) or 10.",
      "type": "number"
    },
    "long_break_minutes": {
      "description": "Long break in minutes, e.g. 15. Leave unset unless the user asks for one: by default it is 15 and may be shortened when that fits an extra focus block.",
      "type": "number"
    },
    "long_break_every": {
      "description": "Long break after this many focus blocks, e.g. 4 (default). 0 = never. Leave unset unless the user asks.",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "breaks": {
      "description": "Fixed breaks the plan must avoid, e.g. [{\"start\":\"12:00\",\"end\":\"12:45\",\"label\":\"Lunch\"}].",
      "maxItems": 8,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "start": {
            "type": "string",
            "maxLength": 20,
            "description": "Break start as a clock time, e.g. 12:00 or 12 pm."
          },
          "end": {
            "description": "Break end as a clock time, e.g. 12:45.",
            "type": "string",
            "maxLength": 20
          },
          "minutes": {
            "description": "Break length in minutes if no end is given, e.g. 45.",
            "type": "number"
          },
          "label": {
            "description": "Name shown in the plan, e.g. \"Lunch\".",
            "type": "string",
            "maxLength": 40
          }
        },
        "required": [
          "start"
        ]
      }
    },
    "label": {
      "description": "Topic used for calendar event titles, e.g. \"Study: organic chemistry\". Default \"Focus\".",
      "type": "string",
      "maxLength": 60
    },
    "time_zone": {
      "description": "Time zone of the clock times: an IANA name (e.g. Europe/Warsaw), a city (e.g. New York), or an abbreviation (e.g. EST). With a zone, calendar events use absolute timestamps. With an explicit date and no zone, events use floating local time. If both date and zone are omitted, today's date and clock times use America/New_York, with a note.",
      "type": "string",
      "maxLength": 64
    },
    "date": {
      "description": "Date of the session as YYYY-MM-DD, e.g. 2026-10-02. Defaults to today in time_zone.",
      "type": "string",
      "maxLength": 10
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "mode": {
      "type": "string"
    },
    "label": {
      "type": "string"
    },
    "summary": {
      "type": "string"
    },
    "settings": {
      "type": "object",
      "properties": {
        "work_minutes": {
          "type": "number"
        },
        "short_break_minutes": {
          "type": "number"
        },
        "long_break_minutes": {
          "type": "number"
        },
        "rounds": {
          "type": "number"
        },
        "long_break_every": {
          "type": "number"
        },
        "auto_advance": {
          "type": "boolean"
        },
        "sound": {
          "type": "boolean"
        }
      },
      "required": [
        "work_minutes",
        "short_break_minutes",
        "long_break_minutes",
        "rounds",
        "long_break_every",
        "auto_advance",
        "sound"
      ],
      "additionalProperties": false
    },
    "totals": {
      "type": "object",
      "properties": {
        "focus_minutes": {
          "type": "number"
        },
        "break_minutes": {
          "type": "number"
        },
        "fixed_break_minutes": {
          "type": "number"
        },
        "free_minutes": {
          "type": "number"
        },
        "total_minutes": {
          "type": "number"
        },
        "focus_blocks": {
          "type": "number"
        }
      },
      "required": [
        "focus_minutes",
        "break_minutes",
        "fixed_break_minutes",
        "free_minutes",
        "total_minutes",
        "focus_blocks"
      ],
      "additionalProperties": false
    },
    "schedule": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "date": {
              "type": "string"
            },
            "date_label": {
              "type": "string"
            },
            "time_zone": {
              "type": [
                "string",
                "null"
              ]
            },
            "start": {
              "type": "string"
            },
            "end": {
              "type": "string"
            },
            "start_local": {
              "type": "string"
            },
            "starts_at_ms": {
              "type": [
                "number",
                "null"
              ]
            }
          },
          "required": [
            "date",
            "date_label",
            "time_zone",
            "start",
            "end",
            "start_local",
            "starts_at_ms"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ]
    },
    "phases": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string"
          },
          "minutes": {
            "type": "number"
          },
          "round": {
            "type": "number"
          },
          "label": {
            "type": "string"
          },
          "start": {
            "type": "string"
          },
          "end": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "minutes"
        ],
        "additionalProperties": false
      }
    },
    "phase_count": {
      "type": "number"
    },
    "phases_truncated": {
      "type": "boolean"
    },
    "notes": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "spare_minutes": {
      "type": [
        "number",
        "null"
      ]
    },
    "downloads": {
      "type": "object",
      "properties": {
        "ics": {
          "type": "string"
        }
      },
      "additionalProperties": false
    }
  },
  "required": [
    "mode",
    "label",
    "summary",
    "settings",
    "totals",
    "schedule",
    "phases",
    "notes",
    "spare_minutes",
    "downloads"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}