Skip to main content
Glama

mcp

by com.crisphive

confirmJobRequest

Confirm a booking on behalf of the customer

Fires the customer-actor confirm_booking action from the BUSINESS surface (audited as business_on_behalf). Two uses: (1) LIVE — staff confirm a slot for a customer who booked by phone; (2) SANDBOX — the customer magic-token surface is live-only (a sandbox job's link can never reach a real customer), so this is the ONLY way to drive a sandbox test job past booking (book → quote → confirm → assign → complete). Body carries the customer-chosen scheduled_at (business-local naive datetime). DECISION TABLE — every 409 this endpoint returns, and the correct NEXT STEP (branch on error_code, never on the HTTP status): • JOB_REQUEST_STAGE_CONFLICT — the job changed since you read it (NOTE: every FAILED confirm attempt also bumps status_version by design). Next: re-GET the job, retry with the fresh status_version. • JOB_REQUEST_ACTION_NOT_PENDING — the job is no longer at the confirm step (usually: already confirmed). Next: re-GET and show current status; do not retry. • JOB_REQUEST_NO_TECHNICIAN_AVAILABLE — the TIME is infeasible for everyone (outside working hours / the customer window, or nobody qualifies). Next: pick another time via booking-windows / time-segments. NOT an emergency case — displacement cannot conjure capacity. • JOB_REQUEST_TECH_INFEASIBLE — the FORCED technician can never take the job then; data.reason says why: cannot_arrive_in_time (commute/shift-start — data.earliest_feasible_at (RFC3339 UTC) is the first same-day time they CAN be on site → offer it) | missing_required_skills | not_available_today | not_lead_tier. Next: keep the tech and reschedule to earliest_feasible_at+, OR keep the time and drop technician_id (auto-pick) / choose another tech from time-segments. NOT an emergency case. • JOB_REQUEST_P0_REQUIRES_DISPLACEMENT — the ONLY code that routes to the EMERGENCY flow: the job is P0, the tech qualifies, but the lane is genuinely occupied. Next: POST emergency/candidates → preview → commit (the commit auto-confirms). Caveat: if the occupying jobs are themselves P0 the preview will reject with EMERGENCY_RESCHEDULE_SLOT_OCCUPIED (P0 never displaces P0) — then pick another tech/time.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
idYesJob request ID
scheduled_atNoChosen start time — business-local naive datetime, no offset (the business_time.datetime value from the time-segments picker). The server converts to UTC using the job's business timezone.
technician_idNoTechnicianID (BUSINESS confirm only — ignored on the customer surface): force-assign the job to this technician instead of the ranked auto-pick. Ranking is bypassed; feasibility (hours/time-off/geo/skills), the TierLead rule and the double-booking guard still apply — an infeasible forced tech rejects the confirm (P0 gets the displacement hint).
status_versionNoOptimistic-lock fence: the status_version from your last read. Omitted/0 = fence on the row's current version (no race protection).
idempotency_keyNoUnique key making retries safe: a repeat send with the same key replays the original response (header Idempotent-Replayed: true) instead of re-running the operation. Reusing a key with a different body returns 422 IDEMPOTENCY_KEY_REUSE. (sent as the Idempotency-Key header)
arrival_window_minutesNoArrivalWindowMinutes = width (phút) của arrival-window ô khách bấm ở slot-picker (chính là time_slot_step_minutes, mặc định 30). Persist để post-confirm detail render lại đúng window. Optional; bounds ([5, 240], khớp slot-picker step) validate ở usecase — single authority, một error code (JOB_REQUEST_INVALID_INPUT).

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
dataNoThe response payload. Omitted on error unless the error carries structured data.
errorsNoField-level validation details; present only for VALIDATION_ERROR responses.
messageNoHuman-readable message ("Success" or an error description), localized via the X-Locale header.
error_codeNo0 on success; a stable string error code on failure (e.g. CUSTOMER_NOT_FOUND).

TDQS

A4.7/5.0
Behavior5/5

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

Annotations only provide generic hints (readOnlyHint=false, idempotentHint=false, etc.), so the description carries the behavioral burden. It reveals important operational details: the action is audited as business_on_behalf, the customer magic-token surface is live-only, every FAILED confirm attempt bumps status_version by design, and the P0 displacement flow has a caveat that P0 never displaces P0. No contradiction with annotations.

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 description is long but justifiably dense: it front-loads the core purpose, then uses a structured decision table to organize complex error-handling guidance. Every section earns its place, and the bulleted format makes the branching logic easy for an agent to follow.

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 an endpoint with six parameters, six error modes, and an output schema, the description is exceptionally complete. It explains the two surfaces, the sandbox limitation, the exact meaning of each 409 code, and the correct next action for each. Since an output schema exists, not describing the return structure is acceptable and does not create a gap.

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% and the schema already provides rich parameter details including formatting, examples, and edge-case behavior. The description adds only light reinforcement such as noting the body carries the customer-chosen scheduled_at and connecting technician_id to feasibility rules, but it does not meaningfully extend beyond the schema.

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 names a specific verb and resource ('Confirm a booking on behalf of the customer') and identifies the exact action being fired ('customer-actor confirm_booking action from the BUSINESS surface'). It clearly distinguishes itself from siblings like createJobRequest and quoteJobRequest by scoping the operation to confirmation on behalf of a customer.

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?

The description explicitly lists two use cases — LIVE staff confirmation and SANDBOX testing — and states this is the ONLY way to drive a sandbox job past booking. The decision table goes further by giving concrete next steps for every 409 error code, including alternatives like re-GET, choosing another time, dropping technician_id, and routing to the emergency flow.

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

All mcp toolsInspect
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

A3.7/5.0
Disambiguation4/5

Most tools target a distinct resource and action, and the heavy use of noun-qualified names (listJobRequestBookingWindows vs listMatchingSlots vs listNearbyTechnicians) keeps close concepts separable. A few availability/skill-listing endpoints could be misselected on first pass, but their descriptions are specific enough to recover.

Naming Consistency4/5

The dominant pattern is clear camelCase verb_noun: createCustomer, getTechnician, listSkills, replaceTechnicianBuddies, previewJobRequestMove. Slight irregularities exist (quoteJobRequest and confirmJobRequest are action-style rather than resource-CRUD, and listJobRequestChanges vs listJobRequests mixes singular/plural), but the overall convention is predictable.

Tool Count2/5

43 tools is well above the 25+ threshold for 'too many', even for a broad field-service domain. The emergency flow alone has three dedicated endpoints and the many replaceTechnician* tools could plausibly be consolidated without hurting clarity.

Completeness2/5

Customer, technician, and job-request reading/creation are well covered, plus a rich scheduling/move/emergency surface. However, the job lifecycle is incomplete: there is no update, cancel, delete, assign, or complete endpoint, and reference entities like vehicles, job types, service areas, and skills lack write operations.

Resources