findtime.io MCP Server

Find a host's open times

find_host_slots

Read-only

Lists a findtime.io host's open times as numbered options in the guest's and host's zones, with explicit dates and abbreviations across clock changes. Accepts structured handle, durationMinutes, askerZone, and ISO dates or date ranges; startUtc and endUtc specify an instant window, and exactStart checks one time. Relative date phrases are not supported. today contains the current date in askerZone. optionId values correspond to the numbered list and expire after about 15 minutes. A slot option is not a booking; every request requires host approval. Every result has a status. ok contains the answer. needs_clarification contains a question and candidate retry arguments. no_match reasons include host_not_found, host_busy_in_window with nearest alternatives, outside_booking_window, duration_not_offered, and host_not_taking_requests. temporarily_unavailable indicates a temporary service failure.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "handle": "<handle>"
    },
    "name": "find_host_slots"
  }
}

Input Schema

Name	Required	Description
`now`	No	Optional ISO current timestamp for clock-drift diagnostics. Does not control date resolution.
`dates`	No	ISO dates in askerZone (2026-10-28), or ranges (2026-10-28..2026-10-30). Defaults to the next 7 days.
`hours`	No	Clock windows in askerZone to keep, such as 09:00-12:00.
`limit`	No	Options per answer, 10 at most.
`order`	No	spread (default) takes times across days; earliest or latest first.
`cursor`	No	Pagination cursor from more.cursor in the previous answer. Other arguments remain unchanged.
`endUtc`	No	End of an exact window, an ISO instant with offset.
`handle`	Yes	The host's findtime.io handle, or their findtime.io/b/<handle> link.
`invite`	No	The invite value from a personal link the host sent the guest (?invite=...).
`passcode`	No	The page passcode, if the host gave the guest one.
`startUtc`	No	Start of an exact window, an ISO instant with offset. Paired with endUtc instead of dates.
`weekdays`	No	Weekdays to keep: monday..sunday, or 1-7 with Monday 1.
`askerZone`	No	The guest's IANA time zone, such as America/Los_Angeles. Without it, times are in the host's zone and the answer asks where the guest is.
`_endUserId`	No	Optional opaque per-call end-user attribution token populated by the MCP host, not the LLM. Accepts a non-PII hash or token, excluding raw email addresses, names, or platform user IDs.
`exactStart`	No	An exact start time such as 2026-10-28T10:00 in askerZone, or an ISO instant with offset. Returns that option, or the nearest open times that day.
`meetingType`	No	Meeting type id from the host profile. Defaults to the host's main one.
`excludeHours`	No	Clock windows in askerZone to skip, such as 12:00-13:00.
`durationMinutes`	No	Meeting length. If the host offers several and you leave this out, the answer asks which.
`excludeWeekdays`	No	Weekdays to skip.

Output Schema

Name	Required	Description	Default
`days`	No
`hint`	No
`host`	No
`more`	No
`error`	No
`exact`	No
`reason`	No
`status`	Yes
`window`	No
`nearest`	No
`options`	No
`summary`	No
`evidence`	No
`nextStep`	No
`question`	No
`expiresAt`	No
`guestZone`	No
`candidates`	No
`meetingType`	No
`durationMinutes`	No
`allowedDurations`	No
`retryAfterSeconds`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 2, 2026

TDQS

A3.9/5.0

Behavior5/5

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

Annotations only declare readOnly/openWorld/non-idempotent/non-destructive; the description adds material behavior beyond that: optionId values expire after ~15 minutes, results are enveloped by status with ok/needs_clarification/no_match/temporarily_unavailable, needs_clarification carries candidate retry arguments, and no_match enumerates concrete reasons like host_busy_in_window with nearest alternatives. It also flags that slots are not bookings, which is the key downstream consequence.

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

Conciseness4/5

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

Front-loaded with purpose before behavior, and most sentences carry distinct information (expiry, status envelope, no_match reasons). The one wasted clause is the parameter enumeration ('Accepts structured handle, durationMinutes, askerZone...'), which duplicates schema content an agent will already read.

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

Completeness4/5

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

For a 19-parameter, open-world read tool with an output schema, the description covers the non-obvious parts an agent would otherwise get wrong: retry loop via needs_clarification, cursor pagination semantics, and the approval step after slot selection. What's missing is routing context against sibling tools, which matters given how many adjacent availability tools exist.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents all 19 parameters, and the description largely restates them ('structured handle, durationMinutes, askerZone, and ISO dates or date ranges', 'startUtc and endUtc specify an instant window'). The genuinely additive notes are that `today` holds the current date in askerZone and that optionId values map to the numbered list, but neither is a parameter. Baseline 3 is appropriate.

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: 'Lists a findtime.io host's open times as numbered options in the guest's and host's zones.' That is far more than a restatement of the name and conveys the output shape. It never names the sibling it is not (e.g., find_meeting_time, get_overlap_hours, rank_recurring_slot), so an agent must infer the boundary between single-host availability lookup and multi-party overlap search.

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

Usage Guidelines3/5

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

Usage is implied rather than stated: 'A slot option is not a booking; every request requires host approval' hints that request_booking is the follow-up, and 'Relative date phrases are not supported' excludes a class of input. There is no explicit when-to-use-this-vs-alternative guidance, despite several siblings (find_meeting_time, are_they_awake, rank_recurring_slot) that plausibly overlap.

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

All findtime.io MCP Server 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.