Skip to main content
Glama

Immersive Commons

by com.immersivecommons
OverviewDiscussionsAdmin

Read, cancel or reschedule one booking with its cancel token

ic_scheduling_manage_booking

The way OUT of a booking, and it is first-class on purpose: an agent that has to ask its human to click a link in an email simply ghosts, and no-shows are the failure mode that actually burns members' time. NO TOKEN REQUIRED — the booking's own cancel_token IS the credential, exactly as a form's claim token is for an account-less submitter. Putting the exit behind an IC account nobody was issued is how a person ends up emailing a human to be removed. Authorization has not been skipped, it has MOVED into the resource: the token is checked in constant time and a WRONG token gives the SAME answer as a missing booking (not_found), so this cannot be used to discover which booking ids exist. action:read returns the booking's current state. action:cancel is idempotent — cancelling an already-cancelled booking is a SUCCESS, not an error, so a retry after a dropped response does not look like a failure. action:reschedule NEEDS start. A refused move leaves the original booking untouched: the release and the new booking are one transaction, so an error means nothing changed and you may try another slot. Confirm cancel and reschedule with your human first; both are visible to the member immediately. booking.id in a reschedule response is NEW and is the one to keep; cancel_token is unchanged. Reading the OLD id with the same token returns the LIVE booking (booking.id is the new id) plus superseded{id,start,end,rescheduled_by} naming the booking you asked for, so a saved manage link keeps working after the owner moves the meeting. Args: { booking_id, cancel_token, action, start?, reason?, idempotency_key? }. Returns: { ok, booking{id,status,start,end,cancel_token,cancelled_by,rescheduled_by,rescheduled_to}, superseded?{id,start,end,rescheduled_by}, member, meeting_type, location_url, ics, calendar{status} } or { ok:false, error_kind } from not_found | slot_taken | outside_window | too_soon | rate_limited | validation | transient. No auth required.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
startNoRequired for action:reschedule. An ISO-8601 slot start from a FRESH ic_scheduling_get_availability call — the old response is stale the moment anyone else books.
actionYesread is safe and repeatable. cancel and reschedule change a real person's calendar — confirm with your human first.
reasonNoOptional, for action:cancel. The member sees it; it is the difference between a cancellation and a ghosting.
booking_idYesThe booking's id, from the confirm response's booking.id.
cancel_tokenYesFrom booking.cancel_token on the confirm response, or the manage link inside the .ics your human saved. It is the only credential for this booking.
idempotency_keyNo8-128 chars of [A-Za-z0-9._:-]. Required by the service on a reschedule; minted here if you omit it. Bring your own and reuse it on retry.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.2/5.0
Behavior5/5

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

Goes well past the annotations: token-as-credential model, constant-time comparison, wrong-token and missing-booking both returning not_found (enumeration defense), cancel idempotency so a retry after a dropped response is a success, reschedule atomicity so a refused move leaves the original untouched, and the new booking.id plus superseded payload behavior for stale manage links. This is exactly the behavioral context a mutation tool needs.

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

Conciseness3/5

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

Information-dense but front-loaded with rhetorical framing ('an agent that has to ask its human to click a link in an email simply ghosts') before the operational facts. Every paragraph carries real content, yet the prose is long and capitalized emphasis is overused, which slows an agent scanning for the essentials.

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?

There is no output schema, and the description compensates fully by enumerating the success payload (booking, superseded, member, meeting_type, location_url, ics, calendar) and the full error_kind list. For a 6-param, three-action tool with no output schema, nothing an agent needs to call it or interpret a failure 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 already 100%, but the description adds meaning on top: reschedule's start must come from a fresh availability call because old responses go stale, the service requires idempotency_key on reschedule and mints one if omitted, reason is member-visible, and the full arg list is restated. It doesn't add much beyond the schema on booking_id/cancel_token, which the schema already documents.

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?

The title and body make clear this is read/cancel/reschedule for a single booking keyed by its cancel_token, and the action enum semantics are spelled out, so it is distinguishable from ic_scheduling_get_availability and the other siblings. The opening sentence is metaphor ('The way OUT of a booking') rather than a plain verb+resource statement, so the purpose takes a few lines to land.

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?

Gives real routing guidance: cancel/reschedule must be confirmed with the human first, reschedule needs a start from a FRESH ic_scheduling_get_availability call (implying the alternative of re-querying availability), and idempotency_key should be brought and reused on retry. No explicit when-not-to-use case beyond that, so it stops short of a 5.

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

All Immersive Commons toolsInspect
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