Skip to main content
Glama

HireNimbus home services MCP

Create booking

create_booking

Creates a service request for a provider slug and job description. Optional inputs include profile overrides, location, search result identifier, and confirmation flag. Requires authentication. Unauthenticated requests return status "auth_required". confirm_booking=false returns a preview with status "confirmation_required"; confirm_booking=true submits the request. Confirmed submissions are not idempotent; repeated confirmed submissions create separate requests. Returns booking status, identifiers, links, and notification statuses.

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": {
      "serviceProviderSlug": "<serviceProviderSlug>",
      "job_description": "<job_description>"
    },
    "name": "create_booking"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameNoOptional name override; the authenticated homeowner profile supplies the value otherwise
phoneNoOptional phone override; the authenticated homeowner profile supplies the value otherwise
sourceNoAI Assistant
addressNoOptional street-level address override. The authenticated homeowner profile address is used otherwise. Accepted fields are address1, address2, city, region, postalCode, and country; formattedAddress is output only.
contextNoOptional analytics context for a brief, non-identifying summary of the request purpose. The value is recorded as Agent Intent.
locationNoOptional geocoding hint when address lacks coordinates; the profile address is used otherwise. Accepted forms: lat+lng, zip, or text (e.g. {"text": "Alexandria, VA"}).
confirm_bookingNofalse (default) returns booking_summary without submitting. true submits the booking.
job_descriptionYes
search_result_idNoSearch result identifier associated with the selected provider. Required for confirmed out-of-market bookings.
serviceProviderSlugYes

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed12 schema fields changed
    • changedInput schema / $defs / BookingLocationInput / description
      Previous value: -"Optional geocoding hint when the address lacks coordinates. Provide one style only."New value: +"Optional geocoding hint for addresses without coordinates, in one supported form."
    • changedInput schema / $defs / BookingLocationInput / properties / lat / description
      Previous value: -"Latitude; use together with lng or lon"New value: +"Latitude; paired with lng or lon"
    • changedInput schema / $defs / BookingLocationInput / properties / lng / description
      Previous value: -"Longitude; use together with lat"New value: +"Longitude; paired with lat"
    • changedInput schema / $defs / BookingLocationInput / properties / lon / description
      Previous value: -"Alias for lng when paired with lat"New value: +"Longitude alias; paired with lat"
    • changedInput schema / $defs / HomeownerAddressInput / description
      Previous value: -"Street-level address override for booking tools. Omit to use the authenticated profile address."New value: +"Optional street-level address override; the authenticated profile address is used otherwise."
    • changedInput schema / properties / address / description
      Previous value: -"Optional street-level address override. Omit to use the authenticated homeowner profile address. When overriding, pass only structured fields (address1, address2, city, region, postalCode, country) — never formattedAddress."New value: +"Optional street-level address override. The authenticated homeowner profile address is used otherwise. Accepted fields are address1, address2, city, region, postalCode, and country; formattedAddress is output only."
    • changedInput schema / properties / confirm_booking / description
      Previous value: -"false (default): return booking_summary for user review; does NOT submit. true: submit the booking after the user explicitly confirms that summary."New value: +"false (default) returns booking_summary without submitting. true submits the booking."
    • changedInput schema / properties / context / description
      Previous value: -"Always include this argument on every call — do not omit it (analytics / Agent Intent). Write 15-25 words in third person explaining why this tool is being called. Abstract purpose only: never names, phones, emails, street addresses, IDs, or other PII. Example: \"Homeowner wants vetted local plumbers for a leaking kitchen faucet within the previously confirmed ZIP.\""New value: +"Optional analytics context for a brief, non-identifying summary of the request purpose. The value is recorded as Agent Intent."
    • changedInput schema / properties / location / description
      Previous value: -"Optional geocoding hint when address lacks coordinates. Omit in normal flows (profile address is used). When needed, pass exactly one of: lat+lng, zip, or text (e.g. {\"text\": \"Alexandria, VA\"})."New value: +"Optional geocoding hint when address lacks coordinates; the profile address is used otherwise. Accepted forms: lat+lng, zip, or text (e.g. {\"text\": \"Alexandria, VA\"})."
    • changedInput schema / properties / name / description
      Previous value: -"Optional override of profile name; omit to use authenticated homeowner profile"New value: +"Optional name override; the authenticated homeowner profile supplies the value otherwise"
    • changedInput schema / properties / phone / description
      Previous value: -"Optional override of profile phone; omit to use authenticated homeowner profile"New value: +"Optional phone override; the authenticated homeowner profile supplies the value otherwise"
    • changedInput schema / properties / search_result_id / description
      Previous value: -"Search result ID returned by the provider search that produced the selected provider. Required for confirmed out-of-market bookings."New value: +"Search result identifier associated with the selected provider. Required for confirmed out-of-market bookings."
  2. Changed7 schema fields changed
    • addedInput schema / properties / context / anyOf
      Added value: +[
      +  {
      +    "type": "string"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • addedInput schema / properties / context / default
      Added value: +null
    • changedInput schema / properties / context / description
      Previous value: -"Explain in 15-25 words, in third person, why this tool is called and how it supports the user's goal. For analytics only. You MUST describe only the abstract purpose of the tool call. NEVER include, repeat, paraphrase, or infer personal, sensitive, or identifying information from the user request or tool results, including names, emails, phone numbers, IPs, IDs, or credentials. You MUST generalize specific entities into roles such as \"a user\", \"the customer\", or \"an account\". Example: \"Retrieving a customer's recent orders to investigate a billing issue and help support determine the appropriate resolution.\""New value: +"Always include this argument on every call — do not omit it (analytics / Agent Intent). Write 15-25 words in third person explaining why this tool is being called. Abstract purpose only: never names, phones, emails, street addresses, IDs, or other PII. Example: \"Homeowner wants vetted local plumbers for a leaking kitchen faucet within the previously confirmed ZIP.\""
    • addedInput schema / properties / context / examples
      Added value: +[
      +  "Homeowner wants vetted local plumbers for a leaking kitchen faucet within the previously confirmed ZIP.",
      +  "Homeowner is comparing HVAC pros after a no-cool air conditioner at the confirmed job site."
      +]
    • addedInput schema / properties / context / title
      Added value: +"Context"
    • removedInput schema / properties / context / type
      Removed value: -"string"
    • changedInput schema / required
      Previous value: -[
      -  "serviceProviderSlug",
      -  "job_description",
      -  "context"
      -]New value: +[
      +  "serviceProviderSlug",
      +  "job_description"
      +]
  3. First observed

TDQS

A3.9/5.0
Behavior5/5

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

Beyond the annotations, the description discloses the auth precondition and the concrete 'auth_required' failure status, the 'confirmation_required' preview status, and — importantly — spells out the consequence of idempotentHint=false ('repeated confirmed submissions create separate requests'), which the hint alone does not convey. It also previews return contents (status, identifiers, links, notification statuses).

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?

Five tight sentences, purpose and required inputs front-loaded, followed by the preview/confirm contract and the non-idempotency warning. The optional-input enumeration sentence is the only mildly redundant part since the schema covers it.

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 10-parameter, open-world, non-idempotent create operation, the description covers auth, the two-phase confirm flow, side-effect duplication risk, and return shape, which is ample. The one omission is guidance on this tool's position relative to the trade-specific book_* siblings; output schema coverage means return values needn't be explained further.

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?

At 70% schema description coverage the schema already documents most fields in detail (address, location forms, search_result_id's out-of-market requirement). The description only enumerates the optional groups ('profile overrides, location, search result identifier, and confirmation flag'), adding categorization but no semantics beyond the schema.

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 description opens with a specific verb and resource ('Creates a service request') and names the two required inputs (provider slug, job description), so the tool's action is unambiguous. It does not, however, distinguish itself from the trade-specific siblings (book_plumber, book_hvac, etc.), leaving the agent to infer that this is the generic path.

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 context is implied through the confirm_booking preview-vs-submit flow and the authentication requirement, which tells the agent how to stage a call. It never says when to prefer this generic tool over book_plumber/book_hvac/book_handyman or when to prefer find_* + get_provider_details first, which is the main selection decision an agent faces here.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.