findtime.io MCP Server

Request a booking

request_booking

Destructive

Requests an available slot for the signed-in guest using an optionId from a recent availability response, guest name, and guest zone. The guest email comes from the authenticated identity; typed email is ignored. An idempotencyKey identifies this request and prevents duplicate sends when reused on retry. The host approves or declines; nothing is booked before approval. Successful results contain guestTrackingToken for this request. guestHistoryToken is a newly issued link to this guest's requests to the host, or null when no new link was issued. Without confirm: true, the operation changes nothing and returns a read-back with status needs_confirmation. confirm: true executes the same operation after the person has confirmed that read-back. Other statuses include no_match for option_expired or slot_taken, existing_request for an overlapping request, rate_limited, and needs_sign_in. Every result has a status listed in the output schema. 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>",
      "optionId": "<optionId>",
      "guestName": "<guestName>"
    },
    "name": "request_booking"
  }
}

Input Schema

Name	Required	Description
`notes`	No	Optional note to the host.
`handle`	Yes	The host's findtime.io handle, or their findtime.io/b/<handle> link.
`invite`	No	The invite value from the personal link used for the availability request.
`confirm`	No	true indicates the person confirmed the read-back returned by the same operation with confirmation omitted.
`subject`	No	Optional meeting subject.
`optionId`	Yes	An exact optionId from the most recent availability response.
`passcode`	No	The page passcode, if the host gave the guest one.
`guestName`	Yes	The guest's name as the host will see it.
`guestZone`	No	The guest's IANA time zone, such as America/Los_Angeles.
`_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.
`idempotencyKey`	No	Unique request identifier. The same value identifies retries of this request.

Output Schema

Name	Required	Description	Default
`hint`	No
`error`	No
`reason`	No
`status`	Yes
`options`	No
`request`	No
`summary`	No
`nextStep`	No
`readBack`	No
`duplicate`	No
`guestHistoryToken`	No
`retryAfterSeconds`	No
`guestTrackingToken`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedNov 2, 2026
- changedOutput schema / properties / guestHistoryToken / type
```
Previous value: -"string"New value: +[
+  "string",
+  "null"
+]
```
First observedNov 2, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Goes well beyond annotations: discloses approval gating ('nothing is booked before approval'), idempotencyKey retry semantics, and a full status taxonomy including no_match, existing_request, rate_limited, needs_sign_in, temporarily_unavailable. Slight tension with idempotentHint:false (the key implies dedup), though the annotation refers to MCP state semantics, not a true contradiction.

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?

Dense but well-structured: it front-loads the core action, then handles idempotency, approval semantics, and the status enumeration. It's longer than minimal but nearly every sentence carries operational meaning.

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 mutating, open-world tool with an output schema, the description covers the critical gaps: confirmation protocol, approval gating, idempotency, and status meanings. An agent has everything needed to call it and interpret results correctly.

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 bar is the baseline 3, but the description adds meaning beyond schema: guest email derives from identity, optionId must come from a recent availability response, and confirm:true's prerequisite of a prior read-back. This clarifies non-obvious parameter relationships.

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

Purpose5/5

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

States a specific verb and resource ('Requests an available slot') and clarifies the trigger inputs (optionId, guest name, guest zone). Clearly distinct from sibling approve_booking_request, decline_booking_request, and cancel_booking.

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

Usage Guidelines4/5

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

Explicitly defines the two-step protocol: without confirm:true it does nothing and returns needs_confirmation, with confirm:true it executes. Also clarifies the email comes from auth and typed email is ignored. Doesn't explicitly route to alternatives like get_booking_status for polling, but the when-to-use guidance is strong.

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.