Kirah Local Services

Reschedule booking

reschedule_booking

Destructive

Atomically moves one grant-authorized booking to a real open time after explicit user confirmation. Reusing idempotency_key makes retries safe. Failure leaves the original booking unchanged; success returns a rotated grant.

Input Schema

TableJSON Schema

Name	Required	Description
`grant`	Yes	The capability token from this booking's create_booking response (confirmation.grant). Required: without it there is no way to establish that you are the agent that made this booking. It must carry the `booking:reschedule` scope. Tampered, wrong-booking, wrong-tenant, revoked and insufficiently-scoped grants all answer invalid_grant, indistinguishably; an authentic grant past the appointment start answers expired_grant. These are the GRANT codes, not the payment page's invalid_token/expired_token — through contract 2.11 this action answered the latter, whose prose wrongly told callers their payment link was broken.
`tenant`	Yes	The tenant to operate on: the provider.tenant_slug value from the tenant's /.well-known/kirah.json manifest (the tenant's full domain, e.g. <slug>.kirah.ai).
`start_iso`	Yes	The exact ISO 8601 instant to move the appointment to. Natural-language times are not accepted. You may supply it DIRECTLY — calling get_reschedule_options first is optional, not required — because the instant is validated against real availability by the same slot engine create_booking uses. A time that is not genuinely open answers slot_taken with the original booking untouched; a time further ahead than this business books answers beyond_booking_horizon.
`booking_ref`	Yes	The reference create_booking returned for the booking you want to MOVE. It must be the SAME booking the supplied grant was issued for; a mismatch answers invalid_grant, indistinguishably from a forged grant. A successful move does not change it.
`provider_id`	No	OPTIONAL. Move the booking to a different provider. Omit it and the booking keeps the provider it is already on — the customer booked a person, not a room. An explicit provider is honored only when that provider exists in this tenant's catalog (else unknown_provider) AND performs the booked service (else provider_service_mismatch). The service and its duration never change.
`agent_metadata`	No
`idempotency_key`	Yes	REQUIRED — unlike create_booking, this action cannot derive one, because "move booking X to time T" is byte-identical whether it is a retry or a deliberate second move. Omitting it answers missing_idempotency_key. Reuse the SAME key when retrying the SAME move: the replay returns the original result with idempotent_replay:true and moves nothing. The same key with a different start_iso or provider_id answers idempotency_conflict.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`demo`	No
`grant`	No
`detail`	No
`reason`	No
`end_iso`	No
`missing`	No
`outcome`	Yes
`notified`	No
`start_iso`	No
`policy_fee`	No
`request_id`	No
`booking_ref`	No
`booking_url`	No
`demo_notice`	No
`intake_form`	No
`payment_url`	No
`confirmation`	No
`service_name`	No
`deposit_cents`	No
`provider_name`	No
`status_reason`	No
`appointment_id`	No
`policy_message`	No
`retry_after_sec`	No
`cancel_fee_cents`	No
`already_cancelled`	No
`idempotent_replay`	No

TDQS

A4.5/5.0

Behavior5/5

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

The description adds significant behavioral detail beyond the annotations: atomicity, idempotent retries via idempotency_key, failure leaving the original booking unchanged, and success returning a rotated grant. These are not available from annotations alone and materially improve an agent's understanding of side effects and retry behavior.

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?

The main description is three tight sentences that front-load the core action, then cover atomicity, idempotency, failure behavior, and success behavior. Every sentence earns its place, and the extensive parameter details live where they belong in 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?

The tool is complex with 7 parameters and nested objects, but the schema descriptions are comprehensive, an output schema exists, and annotations convey read-only vs destructive intent. The description covers the behavioral guarantees an agent needs, including the crucial requirement of explicit user confirmation, so nothing critical is missing.

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 high at 86%, so the baseline is 3. The top-level description itself adds little parameter-specific meaning beyond idempotency_key reuse, while the input schema already provides rich semantics for grant, start_iso, booking_ref, provider_id, and idempotency_key, including error codes and constraints.

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?

The description states a specific verb and resource: "Atomically moves one grant-authorized booking to a real open time." It distinguishes this from siblings like create_booking, cancel_booking, and get_reschedule_options by emphasizing that this acts on an existing booking with a grant and after explicit user confirmation.

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?

The description clearly implies the booking already exists and requires a grant, which establishes when this tool is appropriate. The start_iso parameter adds explicit guidance that get_reschedule_options is optional, not required. It does not explicitly enumerate when not to use it versus cancel_booking or create_booking, but the context is clear enough.

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

All Kirah Local Services tools Inspect

Try in Browser

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.1/5.0

Disambiguation4/5

Each booking lifecycle tool is clearly distinct, and the search/availability tools are generally separated by scope. The closest pair is find_available_services and get_availability, but their descriptions sufficiently distinguish cross-business availability checks from per-service calendar lookups.

Naming Consistency5/5

All tool names follow a consistent snake_case verb_noun pattern, such as create_booking, get_availability, list_services, and reschedule_booking. The verbs are predictable and communicate the action clearly.

Tool Count5/5

Ten tools is a well-scoped size for a local services booking server. Each tool addresses a distinct part of the workflow without unnecessary redundancy or bloat.

Completeness4/5

The tool set covers the core booking journey: discovery, availability, booking creation, status checks, rescheduling, and cancellation. A minor gap is the lack of a list-bookings endpoint, though payment is explicitly handled outside MCP, so core functionality remains intact.

Resources

Need Help?