Skip to main content
Glama
Sign In

HandledIQ: find and book home service

by com.handlediq
OverviewDiscussionsAdmin

Find a shop near the person

find_help

Finds up to 3 shops on HandledIQ near a US ZIP code that do what the person needs, soonest open time first: each with its own book prices (all in, US dollars), their terms, its soonest open times, its service record and a quote_id for hold_time. Use it when the person needs home service at a US house: heating and cooling, plumbing, electrical, roofing, pest control, junk removal, demolition and more. An empty list means no shop on HandledIQ takes that work near that ZIP yet. Sends nothing to anyone.

Input Schema

NameRequiredDescriptionDefault
dayNoOptional. The first day that works for the person, YYYY-MM-DD.
zipYesThe house's 5-digit US ZIP code.
needYesWhat the person needs, in a line, like: AC not cooling, a roof leak, ants in the kitchen, or a couch to haul away.
assistantYesYour own name, as the person you act for knows you, like ChatGPT, Claude or Muse. It goes in the text the shop sends them.
budget_dollarsNoOptional. The most the person wants to pay, in dollars.
include_signed_recordsNoOptional. true adds each shop's signed record and the keys to check it with verify_record, a few thousand characters per shop. Leave it out unless the person asks for proof.

Output Schema

NameRequiredDescriptionDefault
zipYes
nextYes
shopsYes
check_recordsNoOnly with include_signed_records: how to check each signed_record, every shop's key by its issuer's address.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changed
    • addedOutput schema / properties / shops / items / properties / soonest / properties / time_zone
      Added value: +{
+  "description": "The shop's time zone, like: America/Chicago.",
+  "type": "string"
+}
    • addedOutput schema / properties / shops / items / properties / soonest / properties / when / description
      Added value: +"The time in the shop's own time zone (time_zone), like: Today, 8 to 10 AM or Thu, Oct 22, 8 to 10 AM. Today is the shop's today."
    • addedOutput schema / properties / shops / items / properties / times / items / properties / time_zone
      Added value: +{
+  "description": "The shop's time zone, like: America/Chicago.",
+  "type": "string"
+}
    • addedOutput schema / properties / shops / items / properties / times / items / properties / when / description
      Added value: +"The time in the shop's own time zone (time_zone), like: Today, 8 to 10 AM or Thu, Oct 22, 8 to 10 AM. Today is the shop's today."
  2. Changed3 schema fields changed
    • changedInput schema / properties / assistant / description
      Previous value: -"Your own name, as the person you act for knows you, like Muse. It goes in the text the shop sends them."New value: +"Your own name, as the person you act for knows you, like ChatGPT, Claude or Muse. It goes in the text the shop sends them."
    • addedInput schema / properties / include_signed_records
      Added value: +{
+  "description": "Optional. true adds each shop's signed record and the keys to check it with verify_record, a few thousand characters per shop. Leave it out unless the person asks for proof.",
+  "type": "boolean"
+}
    • changedOutput schema / properties / check_records / description
      Previous value: -"How to check each signed_record: every shop's key, by its issuer's address."New value: +"Only with include_signed_records: how to check each signed_record, every shop's key by its issuer's address."
  3. Changed3 schema fields changed
    • addedOutput schema / properties / shops / items / properties / currency
      Added value: +{
+  "description": "Every amount is US dollars.",
+  "enum": [
+    "USD"
+  ],
+  "type": "string"
+}
    • addedOutput schema / properties / shops / items / properties / terms
      Added value: +{
+  "description": "The terms every price here comes with: all in with no fees, paid after the work, and free to cancel within cancel_free_days of booking, before the visit.",
+  "properties": {
+    "all_in": {
+      "type": "boolean"
+    },
+    "cancel_free_days": {
+      "type": "integer"
+    },
+    "fees_cents": {
+      "type": "integer"
+    },
+    "pay": {
+      "enum": [
+        "after_the_work"
+      ],
+      "type": "string"
+    },
+    "words": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "all_in",
+    "fees_cents",
+    "pay",
+    "cancel_free_days",
+    "words"
+  ],
+  "type": "object"
+}
    • changedOutput schema / properties / shops / items / required
      Previous value: -[
-  "shop",
-  "business_id",
-  "quote_id",
-  "prices",
-  "soonest",
-  "door"
-]New value: +[
+  "shop",
+  "business_id",
+  "quote_id",
+  "currency",
+  "prices",
+  "terms",
+  "soonest",
+  "door"
+]
  4. First observed

TDQS

A3.7/5.0
Behavior2/5

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

The description makes an explicit side-effect claim ('Sends nothing to anyone'), yet the annotations declare readOnlyHint=false, which tells the agent the call may modify state. Those two signals pull in opposite directions, and the annotation set also looks boilerplate (idempotentHint=false and openWorldHint=false for a pure lookup). The rich disclosure of what is returned (prices, terms, open times, service record, quote_id) is genuinely useful, but the read-only conflict is a real defect.

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?

Front-loaded with the core behavior (what is found, how many, in what order) before the when-to-use sentence. The first sentence is a long run-on and 'and more' is vague, but every sentence carries information and nothing is padded.

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 an output schema present the description needn't enumerate return fields, yet it still covers the empty-result case, the US-household domain, and the no-notification behavior. It stops short of naming the follow-up tools (hold_time, get_quote) as next steps, which would have completed the workflow picture.

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%, so every parameter (need, zip, assistant, day, budget_dollars, include_signed_records) is already documented in the schema. The description adds little parameter-level detail beyond restating the ZIP/US-house scope and hinting at quote_id, so the baseline of 3 applies.

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?

States a specific verb and resource ('Finds up to 3 shops on HandledIQ near a US ZIP code that do what the person needs') plus ordering and scope. It is clearly distinguishable from siblings like get_quote, request_service, and booking_status, which all operate on an already-selected shop.

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?

Gives a concrete when-to-use condition ('the person needs home service at a US house: heating and cooling, plumbing, electrical...') and an edge case ('An empty list means no shop... takes that work near that ZIP yet'). It does not name alternatives or when-not-to-use, but the entry-point role is clear from context.

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

All HandledIQ: find and book home service toolsInspect
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