HireNimbus home services MCP

Create booking

create_booking

Secured booking after the homeowner has chosen a specific pro from search or book_* results. Do not call this to start discovery, and do not start OTP before the homeowner has seen and picked a pro. Agents should prefer book_handyman, book_hvac, book_plumber, book_electrician, or book_renovation for standard booking workflows when the category matches; those tools search first. Requires authentication to submit. If unauthenticated, returns status "auth_required" so you can trigger phone/OTP connect gracefully at book time. Default confirm_booking=false returns a preview. confirm_booking=true submits the request. Confirmed calls are not idempotent and may create duplicate requests. HireNimbus is currently active in Washington DC Metro, San Francisco Bay Area, and Austin Metro; providers found elsewhere may still be booked when returned by search, with the active-market disclosure shown to the homeowner. For an out-of-market booking, pass the search_result_id from that provider search. Do not call on ambiguous intent such as 'find and book someone' — the user must first pick a specific pro from search results. Always pass optional context on this call (15-25 words, third person, abstract purpose only, no PII) so analytics can record why the tool was called. Omitting it does not fail the call; do not send an empty string.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`name`	No	Optional override of profile name; omit to use authenticated homeowner profile
`phone`	No	Optional override of profile phone; omit to use authenticated homeowner profile
`source`	No		AI Assistant
`address`	No	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.
`context`	No	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."
`location`	No	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"}).
`confirm_booking`	No	false (default): return booking_summary for user review; does NOT submit. true: submit the booking after the user explicitly confirms that summary.
`job_description`	Yes
`search_result_id`	No	Search result ID returned by the provider search that produced the selected provider. Required for confirmed out-of-market bookings.
`serviceProviderSlug`	Yes

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed7 schema fields changedSep 16, 2026

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"
+]

First observedSep 16, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations indicate readOnlyHint=false and idempotentHint=false, and the description goes well beyond those by disclosing that confirmed calls are not idempotent and may create duplicate requests, that unauthenticated calls return auth_required, that default confirm_booking=false only previews, and that marketplace availability varies by region. This is rich, non-obvious behavioral context that an agent needs before invoking the tool.

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?

The description is longer than ideal but front-loads the core purpose and selection criteria, followed by auth, preview, duplicate, market, and context notes in roughly logical order. Some points are repeated (do not call before a pro is picked), but nearly every sentence contributes a distinct operational fact, so the length is justified.

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?

Given the tool's complexity — auth, preview vs. confirm, non-idempotency, market restrictions, sibling routing, and an output schema an agent can rely on for return values — the description is complete. It covers the main failure modes, edge cases, and required invocation pattern, leaving little an agent needs to infer on its own.

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 description coverage is 70%, and the description meaningfully supplements several parameters: confirm_booking's preview-vs-submit effect, search_result_id's role in out-of-market bookings, and the context parameter's analytics purpose plus the warning not to send an empty string. It does not describe all parameters (e.g., serviceProviderSlug, job_description, address), but the schema covers those adequately, and the description adds value where ambiguity is highest.

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 clearly identifies a specific action — creating a secured booking after the homeowner has picked a specific pro from search or book_* results — and explicitly distinguishes it from discovery and the category-specific booking siblings. It names the sibling tools it is not, so an agent can select it correctly without opening the schema.

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 gives explicit when-to-use context (only after the homeowner has seen and picked a specific pro), explicit when-not-to-use guidance (do not call to start discovery, do not call on ambiguous intent), and names concrete alternatives (book_handyman, book_hvac, etc.) for standard workflows. It also explains auth handling, preview vs. submit behavior, and out-of-market requirements.

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

All HireNimbus home services MCP 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.