plumbing-booking

Verify Returning Customer and Retrieve History

customer_lookup

Destructive

For a returning customer: first call with phone and confirmed:true to request a code. Next call with the returned challenge_id and customer-supplied code. Saved details and recent service history are returned only after successful verification. If lookup fails, offer the new-customer form or office assistance. Never claim a match from the initial response.

Input Schema

Name	Required	Description
`code`	No	The 6-digit verification code the customer received by SMS; send it together with challenge_id. Keep it separate from booking codes.
`phone`	Yes	Phone number on the customer account, any common US format; the verification code is texted to it.
`confirmed`	Yes	True only after the customer agreed to receive a verification code at this number.
`challenge_id`	No	The challenge_id returned by the first call; send it together with code on the second call.

Output Schema

Name	Required	Description
`status`	Yes
`history`	No
`message`	Yes
`success`	Yes
`customer`	No
`next_step`	Yes
`record_id`	No	Saved office lead reference, when applicable.
`request_id`	Yes	Public operation receipt for support; never a provider customer ID.
`challenge_id`	No
`history_status`	No
`review_sandbox`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedOct 21, 2026

addedInput schema / properties / challenge_id / description

Added value: +"The challenge_id returned by the first call; send it together with code on the second call."

addedInput schema / properties / code / description

Added value: +"The 6-digit verification code the customer received by SMS; send it together with challenge_id. Keep it separate from booking codes."

addedInput schema / properties / confirmed / description

Added value: +"True only after the customer agreed to receive a verification code at this number."

addedInput schema / properties / phone / description

Added value: +"Phone number on the customer account, any common US format; the verification code is texted to it."

Changed10 schema fields changedSep 14, 2026

changedOutput schema / properties / customer / additionalProperties
```
Previous value: -{}New value: +false
```

addedOutput schema / properties / customer / properties

Added value: +{
+  "addresses": {
+    "items": {
+      "additionalProperties": false,
+      "properties": {
+        "city": {
+          "type": "string"
+        },
+        "country": {
+          "type": "string"
+        },
+        "state": {
+          "type": "string"
+        },
+        "street": {
+          "type": "string"
+        },
+        "street_line_2": {
+          "type": "string"
+        },
+        "zip": {
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    "type": "array"
+  },
+  "email": {
+    "type": "string"
+  },
+  "firstName": {
+    "type": "string"
+  },
+  "lastName": {
+    "type": "string"
+  },
+  "phone": {
+    "type": "string"
+  }
+}

addedOutput schema / properties / customer / required
```
Added value: +[
+  "phone",
+  "addresses"
+]
```
changedOutput schema / properties / history / items / additionalProperties
```
Previous value: -{}New value: +false
```

addedOutput schema / properties / history / items / properties

Added value: +{
+  "description": {
+    "type": "string"
+  },
+  "scheduledStart": {
+    "type": "string"
+  },
+  "workStatus": {
+    "type": "string"
+  }
+}

addedOutput schema / properties / history / items / required
```
Added value: +[
+  "description",
+  "workStatus"
+]
```
addedOutput schema / properties / next_step
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / record_id

Added value: +{
+  "description": "Saved office lead reference, when applicable.",
+  "type": "string"
+}

addedOutput schema / properties / request_id

Added value: +{
+  "description": "Public operation receipt for support; never a provider customer ID.",
+  "format": "uuid",
+  "type": "string"
+}

changedOutput schema / required

Previous value: -[
-  "success",
-  "status",
-  "message"
-]New value: +[
+  "request_id",
+  "next_step",
+  "success",
+  "status",
+  "message"
+]

AddedSep 13, 2026

TDQS

A4.5/5.0

Behavior4/5

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

Beyond the annotations, the description discloses the crucial behavioral fact that sensitive data is only returned after successful verification and that the first response must not be treated as a match. It does not explain the destructive/openWorld annotation implications (e.g. SMS cost, rate limits, why the tool is flagged destructive), leaving a modest gap.

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?

Four tight sentences, front-loaded with the primary workflow and followed by the failure and guardrail rules. Every sentence carries operational information, though the final two sentences could be merged without loss.

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?

With a full output schema and 100% parameter coverage, the description covers the workflow, guardrails, and fallback. The only omission is guidance on repeated attempts or code expiry, which matters for a destructive-flagged, non-idempotent tool.

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 100%, so field meanings are already documented, but the description adds real value by mapping parameters to call order: phone+confirmed on the first call, challenge_id+code on the second. That sequencing is not inferable from the schema alone.

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 concrete two-step verification workflow for looking up a returning customer, naming both the action (request code, then verify) and the resource (customer details and service history). It clearly distinguishes this tool from siblings like search_service_history or open_customer_portal, which the agent could otherwise confuse with a lookup.

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?

It gives explicit sequencing ('first call' / 'next call'), the precondition ('For a returning customer'), and a failure path ('offer the new-customer form or office assistance'), plus a guardrail ('Never claim a match from the initial response'). This tells the agent both when to use the tool and how to behave on the negative path.

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

All plumbing-booking 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.

Resources

Need Help?