Zovo Focus Timer

Plan focus session

plan_focus_session

Read-onlyIdempotent

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).

Input Schema

Name	Required	Description
`date`	No	Date of the session as YYYY-MM-DD, e.g. 2026-10-02. Defaults to today in time_zone.
`label`	No	Topic used for calendar event titles, e.g. "Study: organic chemistry". Default "Focus".
`breaks`	No	Fixed breaks the plan must avoid, e.g. [{"start":"12:00","end":"12:45","label":"Lunch"}].
`rounds`	No	Maximum number of pomodoros to schedule, e.g. 6. Without an end time the plan runs until this many are done.
`end_time`	No	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.
`time_zone`	No	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.
`start_time`	No	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.
`work_minutes`	No	Focus block length in minutes, e.g. 25 (default) or 50.
`long_break_every`	No	Long break after this many focus blocks, e.g. 4 (default). 0 = never. Leave unset unless the user asks.
`available_minutes`	No	Total time available in minutes, e.g. 180 for "I have 3 hours". Used with start_time or end_time. Max 1440.
`long_break_minutes`	No	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.
`short_break_minutes`	No	Break between focus blocks in minutes, e.g. 5 (default) or 10.

Output Schema

Name	Required	Description	Default
`mode`	Yes
`label`	Yes
`notes`	Yes
`phases`	Yes
`totals`	Yes
`summary`	Yes
`schedule`	Yes
`settings`	Yes
`downloads`	Yes
`phase_count`	No
`spare_minutes`	Yes
`phases_truncated`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedOct 22, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description still adds substantial behavior: it shortens or drops the standard long break to fit a whole block and says so, resolves ambiguous bare hours (5 after 14:00 read as 5pm, with a note), and defaults to America/New_York when date and zone are absent. It also enumerates the artifacts produced (clock times per block, total focus minutes, spare time, .ics, live timer).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two dense sentences with the invocation trigger front-loaded before the mechanics and the limits. Despite covering a dozen parameters and an output contract, nothing reads as filler or repetition of the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 12-parameter, all-optional planning tool with an output schema, the description still covers the invocation scenario, the scheduling algorithm's key trade-off, output artifacts, and hard limits. Nothing an agent needs in order to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents the 12 parameters thoroughly and baseline would be 3. The description adds genuine meaning on top: the long-break shortening/dropping policy unless long-break settings were supplied, and the 24-hour cap tying to available_minutes' 1440 maximum.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('fits the most whole focus blocks between the start and end time') and grounds it in concrete user phrasings like "I have 3 hours to study until 5pm". It never names its sibling show_focus_timer, and since it also returns 'a live timer for the plan', the boundary between planning and the timer tool is left implicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Opens with an explicit trigger ('Use this when the user wants pomodoros fitted into a time window') and follows with three realistic utterance examples, then states exclusions: one window up to 24 hours, no calendar read/write, no multi-day study plans such as finals week. An agent knows both when to call it and when not to.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Zovo Focus Timer tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?