Timeplex K-Beauty Booking

search_shops

Read-onlyIdempotent

Search Korean beauty and wellness shops by shop name, service type, or location. Use this tool when a user wants to find a beauty salon, hair salon, nail salon, skincare or facial shop, spa, massage shop, or other K-beauty business in Korea, including requests for appointment or booking options. Results indicate whether each shop is bookable through Timeplex: bookable=true means real-time availability can be checked and the customer can proceed to booking through this MCP; bookable=false means it needs request_booking (Timeplex concierge arranges it manually). Shops fall into two categories: hair (hair salons) and beauty (everything else — massage, spa, nail, skincare, facial, waxing, scrub, etc.). Each shop result carries its category. If the user named a specific shop that is not registered, the response sets shop_name_not_found — tell the user that shop is not on Timeplex and offer the registered shops in the result as alternatives. Each result carries the shop address, so you can answer area questions ("shops in Seoul") without extra calls. Always reply to the user in the language they used, and start the reply with the response's reply_header line.

Input Schema

TableJSON Schema

Name	Required	Description
`query`	No	Shop name, service, or natural-language search term (optional). If no shop name matches, it is also interpreted as a service/category search.
`location`	No	Area filter (optional), in English or Korean — "Seoul", "Gangnam", "Hongdae", "Busan", "Jeju", "강남", "홍대"… Matched against the shop address. Shops with no address registered are excluded when this is set.
`service_type`	No	Shop category (optional). Accepts broad categories ("hair", "beauty") and specific ones ("massage", "spa", "head spa", "nail", "skincare", "facial", "esthetic", "waxing", "scrub"), in English, Korean, Japanese or Chinese (アカスリ, ヘッドスパ, マッサージ, 搓澡, 头皮护理, 按摩…). Leave empty to search all categories.

Output Schema

TableJSON Schema

Name	Required	Description
`note`	No	Follow-up guidance for the agent
`count`	Yes
`shops`	Yes	Matching shops.
`categories`	No
`reply_header`	No
`filter_applied`	No	How the inputs were interpreted (category/service_type/location/query)
`reply_header_usage`	No
`shop_name_not_found`	No	Set when the user named a specific shop that is not registered on Timeplex. Tell the user that shop is not on Timeplex — do not treat it as a category with zero results, and do not submit it with request_booking.
`available_service_types`	No	business_type values currently registered

Schema Changelog

Changes observed during successful MCP inspections. Dates show when Glama detected each change.

Changed2 schema fields changedAug 24, 2026

addedOutput schema / properties / shops / items / properties / business_type / description
```
Added value: +"Filter code. Use business_type_label when naming the shop to the user."
```

addedOutput schema / properties / shops / items / properties / business_type_label

Added value: +{
+  "description": "Display label the shop selected (spa = 스파·헤드스파 / spa & head spa). null when unset.",
+  "properties": {
+    "en": {
+      "type": "string"
+    },
+    "ko": {
+      "type": "string"
+    }
+  },
+  "type": [
+    "object",
+    "null"
+  ]
+}

Changed1 schema field changedAug 24, 2026

changedInput schema / properties / service_type / description

Previous value: -"Shop category (optional). Accepts broad categories (\"hair\", \"beauty\") and specific ones (\"massage\", \"spa\", \"head spa\", \"nail\", \"skincare\", \"facial\", \"esthetic\", \"waxing\", \"scrub\"), in English or Korean. Leave empty to search all categories."New value: +"Shop category (optional). Accepts broad categories (\"hair\", \"beauty\") and specific ones (\"massage\", \"spa\", \"head spa\", \"nail\", \"skincare\", \"facial\", \"esthetic\", \"waxing\", \"scrub\"), in English, Korean, Japanese or Chinese (アカスリ, ヘッドスパ, マッサージ, 搓澡, 头皮护理, 按摩…). Leave empty to search all categories."

Changed1 schema field changedAug 24, 2026

addedOutput schema / properties / shop_name_not_found

Added value: +{
+  "description": "Set when the user named a specific shop that is not registered on Timeplex. Tell the user that shop is not on Timeplex — do not treat it as a category with zero results, and do not submit it with request_booking.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

Changed4 schema fields changedAug 23, 2026

changedInput schema / properties / query / description

Previous value: -"Shop name, partial match (optional). If no name matches, it is also interpreted as a shop category."New value: +"Shop name, service, or natural-language search term (optional). If no shop name matches, it is also interpreted as a service/category search."

changedInput schema / properties / service_type / description

Previous value: -"Shop category (optional). Accepts broad categories (\"hair\", \"beauty\") and specific ones (\"massage\", \"spa\", \"head spa\", \"nail\", \"skin care\", \"esthetic\", \"waxing\", \"scrub\"), in English or Korean. Leave empty to search all categories."New value: +"Shop category (optional). Accepts broad categories (\"hair\", \"beauty\") and specific ones (\"massage\", \"spa\", \"head spa\", \"nail\", \"skincare\", \"facial\", \"esthetic\", \"waxing\", \"scrub\"), in English or Korean. Leave empty to search all categories."

addedOutput schema / properties / shops / items / properties / address / description
```
Added value: +"null = newly joined shop that has not registered an address yet"
```

addedOutput schema / properties / shops / items / properties / area_match

Added value: +{
+  "description": "Present only when a location filter was applied: true = address matched the area; false = no address registered yet (newly onboarding) — confirm the area with the shop",
+  "type": "boolean"
+}

Changed1 schema field changedAug 22, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "available_service_types": {
+      "description": "business_type values currently registered",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "categories": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "count": {
+      "type": "integer"
+    },
+    "filter_applied": {
+      "description": "How the inputs were interpreted (category/service_type/location/query)",
+      "type": "object"
+    },
+    "note": {
+      "description": "Follow-up guidance for the agent",
+      "type": "string"
+    },
+    "reply_header": {
+      "type": "string"
+    },
+    "reply_header_usage": {
+      "type": "string"
+    },
+    "shops": {
+      "description": "Matching shops.",
+      "items": {
+        "properties": {
+          "address": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "bookable": {
+            "description": "true = bookable via this MCP; false = use request_booking",
+            "type": "boolean"
+          },
+          "business_type": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "category": {
+            "enum": [
+              "hair",
+              "beauty"
+            ],
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          },
+          "slug": {
+            "description": "Shop id for the other tools",
+            "type": "string"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "shops",
+    "count"
+  ],
+  "type": "object"
+}

First observedAug 18, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, so safety is known. The description goes beyond by detailing the bookable flag semantics, the hair/beauty categorization, the shop_name_not_found response behavior, address inclusion for area questions, and the instruction to use reply_header and match user language. This adds substantial behavioral context without contradicting annotations.

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 typical but every sentence carries actionable information. It front-loads the purpose and follows with usage context, behavioral details, and response handling. The structure is logical, though it could be slightly more concise without losing value.

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?

For a search tool with an output schema, the description covers all critical aspects: matching semantics, fallback behavior, bookability implications, error handling, location filtering, and response formatting. Given its complexity (3 optional params, category logic, internationalization), nothing essential is missing. The output schema presumably defines the result structure, so the description doesn't need to repeat it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but the description enriches parameter understanding: it explains query falls back to service/category search, location matches against address and excludes shops without addresses, and service_type accepts broad and specific categories in multiple languages. These nuances are not present in the schema and materially improve correct usage.

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 opens with a specific verb and resource: 'Search Korean beauty and wellness shops by shop name, service type, or location.' It enumerates the types of businesses covered (salon, spa, nail, etc.) and differentiates itself from booking tools by stating it finds shops and indicates bookability. This clearly distinguishes it from siblings like request_booking or search_availability.

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?

Explicitly says 'Use this tool when a user wants to find a beauty salon, hair salon, nail salon, skincare or facial shop, spa, massage shop, or other K-beauty business in Korea, including requests for appointment or booking options.' It also explains the branching: bookable=true leads to booking through this MCP, bookable=false requires request_booking. It even covers the not-found case with shop_name_not_found and instructs to offer alternatives. This is exemplary guidance.

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

All Timeplex K-Beauty Booking tools Inspect

Try in Browser

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.5/5.0

Disambiguation5/5

Each tool targets a distinct step in the booking workflow: searching shops, retrieving services, checking availability, initiating a booking, and handling manual requests for non-bookable shops. Their purposes and usage conditions are clearly separated with specific guidance on when to use each, eliminating ambiguity.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern in snake_case: get_shop_services, request_booking, search_availability, search_shops, start_booking. The verbs (get, request, search, start) and nouns (shop_services, booking, availability, shops) are all lowercase and underscore-separated, providing a predictable and readable naming scheme.

Tool Count5/5

With exactly 5 tools, the server is well-scoped for its purpose. It covers the essential phases of finding a shop, inspecting services, checking availability, and initiating bookings, without unnecessary expansion. This count is typical for a focused domain-specific MCP and each tool earns its place.

Completeness4/5

The tool set covers the primary booking flow comprehensively: search_shops, get_shop_services, search_availability, and start_booking handle the standard online-booking path, while request_booking covers shops that require manual concierge intervention. Minor gaps exist (e.g., no tool for canceling or modifying bookings), but since start_booking only generates a booking link and actual reservation management happens on the booking page, the surface is reasonably complete for its stated purpose.

Resources

Need Help?