Kirah Local Services

Search Kirah businesses

search_businesses

Read-only

Searches Kirah's eligible public business directory by service need or exact Kirah Agent Address, with optional coarse location, price and demo-mode filters. Demo results are explicitly labeled.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`limit`	No
`query`	No	The consumer's need in plain words (e.g. 'lower back tightness', 'prenatal massage'). Matched deterministically against real service catalogs, expanded by the discovery ontology.
`cursor`	No	Opaque next_cursor value from a previous search_businesses response with the SAME query/filters: resumes after that tenant in the stable ordering. A cursor that does not decode, or that names a tenant not present in the current ordering, is invalid_cursor.
`location`	No	Optional place text ('City, ST', ZIP, bare city/state) OR explicit coordinates 'lat,lng'. With resolvable coordinates, radius_miles applies as real distance; otherwise matching is city/ZIP/metro-market text equality.
`tenant_mode`	No	The authoritative eligibility filter for demo tenants. include_demos (default) returns real and demo businesses together; every demo is flagged demo:true and carries a clear notice. real_only excludes every demo business; demos_only returns ONLY demo businesses. A discovery-disabled, inactive, or otherwise ineligible tenant never appears in any mode — not even when its catalog uniquely matches the query.	include_demos
`include_demo`	No	Back-compat alias: true is equivalent to tenant_mode 'include_demos' and false to 'real_only'. When omitted, tenant_mode defaults to include_demos. Every demo result carries demo:true and a demo_notice. Supplying both include_demo and tenant_mode with disagreeing demo-inclusion is invalid_tenant_mode.
`radius_miles`	No	Radius in miles (default 25) — OPERATIVE when the location resolves to coordinates (2.6); otherwise answered with a truthful distance_note instead of a fabricated distance.
`agent_address`	No	Exact public locator `<handle>@kirah.ai`; case-insensitive ASCII only. A locator, never authentication or owner authority. Reserved, malformed, unlisted, disabled, non-bookable, and tenant_mode-ineligible addresses do not resolve. Exact mode never fuzzy-matches a near miss.
`max_price_cents`	No	Only services with a parseable price at or under this amount are returned; unpriced services are excluded when this is set.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedSep 1, 2026

addedInput schema / properties / location

Added value: +{
+  "description": "Optional place text ('City, ST', ZIP, bare city/state) OR explicit coordinates 'lat,lng'. With resolvable coordinates, radius_miles applies as real distance; otherwise matching is city/ZIP/metro-market text equality.",
+  "maxLength": 120,
+  "type": "string"
+}

addedInput schema / properties / radius_miles

Added value: +{
+  "description": "Radius in miles (default 25) — OPERATIVE when the location resolves to coordinates (2.6); otherwise answered with a truthful distance_note instead of a fabricated distance.",
+  "maximum": 500,
+  "minimum": 1,
+  "type": "integer"
+}

changedOutput schema / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "businesses": {
-        "items": {
-          "additionalProperties": false,
-          "properties": {
-            "agent_address": {
-              "description": "Canonical public Kirah Agent Address for this business when its authoritative domain is a safe single-label *.kirah.ai domain. Locator only; never authentication. Absent for custom domains and reserved/invalid handles in migration-free v1.",
-              "type": "string"
-            },
-            "agent_bookable": {
-              "type": "boolean"
-            },
-            "agent_discoverable": {
-              "description": "Present for V1-enrolled tenants; true because the row passed current owner discovery consent.",
-              "type": "boolean"
-            },
-            "authority_mode": {
-              "description": "Present for V1-enrolled tenants; null when discoverable but not agent-bookable.",
-              "enum": [
-                "instant",
-                "approval_required",
-                null
-              ],
-              "type": [
-                "string",
-                "null"
-              ]
-            },
-            "demo": {
-              "description": "true = a DEMONSTRATION business (present on every result; demo results also carry demo_notice).",
-              "type": "boolean"
-            },
-            "demo_notice": {
-              "type": "string"
-            },
-            "location": {
-              "additionalProperties": false,
-              "properties": {
-                "city": {
-                  "type": [
-                    "string",
-                    "null"
-                  ]
-                },
-                "match": {
-                  "description": "The coarse place relationship used for this result.",
-                  "enum": [
-                    "postal",
-                    "city",
-                    "market",
-                    "region"
-                  ],
-                  "type": "string"
-                },
-                "postal_code": {
-                  "type": [
-                    "string",
-                    "null"
-                  ]
-                },
-                "region": {
-                  "type": [
-                    "string",
-                    "null"
-                  ]
-                }
-              },
-              "type": "object"
-            },
-            "matched_services": {
-              "items": {
-                "additionalProperties": false,
-                "properties": {
-                  "duration_minutes": {
-                    "type": "integer"
-                  },
-                  "id": {
-                    "type": "string"
-                  },
-                  "match_evidence": {
-                    "description": "Grounded explanations (which query/ontology terms matched which catalog text).",
-                    "items": {
-                      "type": "string"
-                    },
-                    "maxItems": 4,
-                    "type": "array"
-                  },
-                  "match_type": {
-                    "description": "exact = a direct query term matched the service name or category. ontology = only a discovery-ontology expansion term matched the name or description. description = a direct query term matched ONLY the description. Ranking always tiers exact above ontology above description, regardless of score — a service whose description merely mentions a term never outranks a service actually named for it.",
-                    "enum": [
-                      "exact",
-                      "ontology",
-                      "description"
-                    ],
-                    "type": "string"
-                  },
-                  "name": {
-                    "type": "string"
-                  },
-                  "price_cents": {
-                    "type": [
-                      "integer",
-                      "null"
-                    ]
-                  },
-                  "price_label": {
-                    "type": "string"
-                  }
-                },
-                "required": [
-                  "id",
-                  "name",
-                  "match_type"
-                ],
-                "type": "object"
-              },
-              "maxItems": 3,
-              "minItems": 0,
-              "type": "array"
-            },
-            "score": {
-              "description": "The tenant's top matched service's integer score — used for cross-business ranking together with match_type tier. Zero in exact agent_address resolution mode when matched_services is empty.",
-              "type": "integer"
-            },
-            "service_match": {
-              "description": "True when matched_services contains a grounded query match. False only for exact agent_address resolution with no matching/supplied service query.",
-              "type": "boolean"
-            },
-            "tenant_name": {
-              "type": "string"
-            },
-            "tenant_slug": {
-              "description": "The stable identifier for every tenant-scoped action (the tenant's full domain).",
-              "type": "string"
-            }
-          },
-          "required": [
-            "tenant_slug",
-            "tenant_name",
-            "demo",
-            "score",
-            "service_match",
-            "matched_services"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      },
-      "demo_notice": {
-        "description": "Present when any demo result is included.",
-        "type": "string"
-      },
-      "is_exhaustive": {
-        "description": "True only when the roster scan did not hit its internal candidate cap AND every matching tenant (from any cursor position forward) fit within this page. NEVER fabricated: hitting the roster cap always yields false, even with no cursor and few matches.",
-        "type": "boolean"
-      },
-      "location_precision": {
-        "description": "The public surface reports coarse matching precision only.",
-        "enum": [
-          "city_zip_market",
-          "none"
-        ],
-        "type": "string"
-      },
-      "next_cursor": {
-        "description": "Present only when more matching tenants exist beyond this page. Opaque; pass back verbatim as `cursor` with the SAME query/filters to resume.",
-        "type": "string"
-      },
-      "outcome": {
-        "enum": [
-          "ok"
-        ],
-        "type": "string"
-      },
-      "resolution": {
-        "additionalProperties": false,
-        "properties": {
-          "agent_address": {
-            "type": "string"
-          },
-          "exact": {
-            "enum": [
-              true
-            ],
-            "type": "boolean"
-          },
-          "found": {
-            "type": "boolean"
-          },
-          "type": {
-            "enum": [
-              "agent_address"
-            ],
-            "type": "string"
-          }
-        },
-        "required": [
-          "type",
-          "agent_address",
-          "exact",
-          "found"
-        ],
-        "type": "object"
-      }
-    },
-    "required": [
-      "outcome",
-      "location_precision",
-      "businesses",
-      "is_exhaustive"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "detail": {
-        "description": "A short user-safe explanation.",
-        "type": "string"
-      },
-      "outcome": {
-        "description": "A stable failure category.",
-        "enum": [
-          "validation_error",
-          "rate_limited",
-          "internal_error"
-        ],
-        "type": "string"
-      },
-      "reason": {
-        "description": "A stable machine-readable reason.",
-        "type": "string"
-      },
-      "retry_after_sec": {
-        "minimum": 1,
-        "type": "integer"
-      }
-    },
-    "required": [
-      "outcome",
-      "reason",
-      "detail"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "businesses": {
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "agent_address": {
+              "type": "string"
+            },
+            "agent_bookable": {
+              "type": "boolean"
+            },
+            "agent_discoverable": {
+              "type": "boolean"
+            },
+            "authority_mode": {
+              "enum": [
+                "instant",
+                "approval_required",
+                null
+              ],
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "demo": {
+              "type": "boolean"
+            },
+            "demo_notice": {
+              "type": "string"
+            },
+            "listed": {
+              "enum": [
+                true
+              ],
+              "type": "boolean"
+            },
+            "location": {
+              "additionalProperties": false,
+              "properties": {
+                "city": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "distance_miles": {
+                  "type": "number"
+                },
+                "match": {
+                  "enum": [
+                    "postal",
+                    "city",
+                    "market",
+                    "region",
+                    "coordinates"
+                  ],
+                  "type": "string"
+                },
+                "postal_code": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "region": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                }
+              },
+              "type": "object"
+            },
+            "matched_services": {
+              "items": {
+                "additionalProperties": false,
+                "properties": {
+                  "duration_minutes": {
+                    "type": "integer"
+                  },
+                  "id": {
+                    "type": "string"
+                  },
+                  "match_evidence": {
+                    "items": {
+                      "type": "string"
+                    },
+                    "maxItems": 4,
+                    "type": "array"
+                  },
+                  "match_type": {
+                    "enum": [
+                      "exact",
+                      "ontology",
+                      "description"
+                    ],
+                    "type": "string"
+                  },
+                  "name": {
+                    "type": "string"
+                  },
+                  "price_cents": {
+                    "type": [
+                      "integer",
+                      "null"
+                    ]
+                  },
+                  "price_label": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "id",
+                  "name",
+                  "match_type"
+                ],
+                "type": "object"
+              },
+              "maxItems": 3,
+              "minItems": 0,
+              "type": "array"
+            },
+            "resolution": {
+              "enum": [
+                "exact_agent_address"
+              ],
+              "type": "string"
+            },
+            "score": {
+              "type": "integer"
+            },
+            "service_match": {
+              "type": "boolean"
+            },
+            "tenant_name": {
+              "type": "string"
+            },
+            "tenant_slug": {
+              "type": "string"
+            },
+            "url": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "tenant_slug",
+            "tenant_name",
+            "demo",
+            "listed",
+            "matched_services",
+            "score",
+            "service_match",
+            "agent_bookable"
+          ],
+          "type": "object"
+        },
+        "maxItems": 10,
+        "type": "array"
+      },
+      "demo_businesses_excluded": {
+        "minimum": 1,
+        "type": "integer"
+      },
+      "demo_businesses_excluded_is_exhaustive": {
+        "type": "boolean"
+      },
+      "demo_exclusion_note": {
+        "type": "string"
+      },
+      "demo_notice": {
+        "type": "string"
+      },
+      "distance_note": {
+        "type": "string"
+      },
+      "is_exhaustive": {
+        "type": "boolean"
+      },
+      "location_precision": {
+        "enum": [
+          "coordinates",
+          "city_zip_market",
+          "none"
+        ],
+        "type": "string"
+      },
+      "next_cursor": {
+        "type": "string"
+      },
+      "outcome": {
+        "enum": [
+          "ok"
+        ],
+        "type": "string"
+      },
+      "resolution": {
+        "additionalProperties": false,
+        "properties": {
+          "agent_address": {
+            "type": "string"
+          },
+          "exact": {
+            "enum": [
+              true
+            ],
+            "type": "boolean"
+          },
+          "found": {
+            "type": "boolean"
+          },
+          "type": {
+            "enum": [
+              "agent_address"
+            ],
+            "type": "string"
+          }
+        },
+        "required": [
+          "type",
+          "agent_address",
+          "exact",
+          "found"
+        ],
+        "type": "object"
+      }
+    },
+    "required": [
+      "outcome",
+      "location_precision",
+      "businesses",
+      "is_exhaustive"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "detail": {
+        "type": "string"
+      },
+      "outcome": {
+        "enum": [
+          "validation_error",
+          "rate_limited",
+          "internal_error"
+        ],
+        "type": "string"
+      },
+      "reason": {
+        "type": "string"
+      },
+      "retry_after_sec": {
+        "type": "integer"
+      }
+    },
+    "required": [
+      "outcome",
+      "reason",
+      "detail"
+    ],
+    "type": "object"
+  }
+]

First observedAug 23, 2026

TDQS

A3.6/5.0

Behavior3/5

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

Annotations already establish readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context about eligibility and explicitly labeled demo results, but it does not disclose behaviors like exact-no-fuzzy matching or the nuanced tenant-mode exclusions; those are left to the schema.

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?

Two concise sentences lead with the core purpose and then highlight the most important behavioral caveat, demo labeling. Every phrase earns its place, with no redundant restatement of schema details.

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?

Given the rich input schema, output schema, and annotations, the description is largely complete for selection purposes. It could be improved by naming the intended alternative to search_services and by surfacing a couple of key edge behaviors, but an agent can reasonably call the tool correctly from this definition.

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 89%, so the schema carries most parameter meaning. The description adds a useful high-level grouping—service need, exact address, location, price, and demo-mode filters—but does not materially extend what the parameter descriptions already provide.

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 states a specific verb and resource: searching Kirah's eligible public business directory, and names the two principal lookup modes (service need or exact agent address). It does not explicitly distinguish itself from siblings like search_services, so it falls short of full sibling differentiation.

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?

The description implies when to use the tool: when looking up businesses by a service need or by an exact Kirah address, with optional location/price/demo filters. It gives no explicit guidance about when a sibling such as search_services or list_services would be more appropriate.

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

All Kirah Local Services 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?