Timeplex K-Beauty Booking

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

The description adds significant behavioral context beyond the readOnlyHint annotation. It reveals that the response contains a 'status_url' used for cancellation, explains that cancellation happens outside the MCP, and includes the language instruction. These details are not available in annotations and help the agent understand the tool's side effects and workflow constraints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences long, with the core purpose stated first, followed by a crucial cancellation workflow note, and ending with a language instruction. Every sentence adds unique value and there is no unnecessary text, making it highly efficient and scannable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Although there is no output schema, the description adequately covers the key return contents: booking status, payment status, cancellation eligibility, refund terms, and the status_url. For a simple lookup tool with one parameter, this is complete enough for an agent to understand what the tool provides. Minor improvement could be listing the exact fields, but the current description is sufficient.

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

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

The single required parameter res_no is described in the schema as 'Reservation number', and the description mentions 'reservation number' without adding further meaning, format, or examples. With 100% schema coverage, the baseline is 3; the description adds no extra semantic benefit beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Look up booking and payment status by reservation number'. The verb 'look up' and the specific resource 'booking and payment status' with the identifier 'reservation number' make the action unambiguous. It also specifies included details (cancellation eligibility, refund terms), which distinguishes it from sibling tools that handle searches, booking creation, or service listings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Excellent usage guidance: the description explicitly tells the agent when to NOT use this tool ('To actually cancel... cancelling is done there, not through this MCP') and provides an alternative action (hand the customer the status_url). It also includes the instruction 'Reply in the user's language', which is a clear behavioral directive for the agent.

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

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

Annotations already declare readOnlyHint=true (safe read) and openWorldHint=false. The description adds value by detailing the returned data (service menu + staff/seats) and translation behavior. It does not disclose additional behavioral traits like rate limits or authentication needs, but given annotation coverage, the description is adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with no fluff. The first sentence states purpose and output, the second adds usage guidance for lang. Information is front-loaded and every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given there is no output schema, the description reasonably covers the return structure (name, price, duration; staff/seats). It also accounts for the optional lang behavior. A minor gap: staff/seats content is vague, but overall sufficient for a simple get tool with well-documented params and read-only annotations.

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

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

Schema description coverage is 100%: both slug and lang have clear descriptions. The description's mention of translation adds minimal new meaning beyond the schema. With high schema coverage, the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'Get' and clearly identifies the resource: a shop's service menu (including name, price, duration) and staff/seats. It also adds the translation capability, making the purpose precise. This distinguishes it well from siblings like search_shops (search) and request_booking (booking flow).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides contextual guidance for the lang parameter (pass lang for translation) and implies the slug comes from search_shops (via schema). However, it does not explicitly state when to use this tool versus alternatives, nor does it offer exclusion criteria or when not to use it.

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

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

Annotations are not very informative (all false). The description compensates fully by explaining the complete behavioral flow: the request is not automatically confirmed; instead, concierge staff contact the shop and later reply with a link. This sets correct expectations for an async, human-involved process, which is critical for an AI agent to manage user expectations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences: first states the core purpose and condition, second outlines the concierge workflow, third tells the agent what to do with the result. Each sentence earns its place, no fluff, and the key information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (2 params, simple schema, no output schema), the description is complete. It covers purpose, condition, workflow, and output handling. The async nature and human involvement are clearly communicated. No gaps for an agent to misunderstand.

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

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

Schema description coverage is 100% and the description adds clear meaning: it explains that 'venue_name' is the shop name the customer wants to book, and 'lang' is the customer's language for the booking process. The description's workflow mention (concierge contacts shop) implies these parameters will be used in that process, adding value beyond the schema's basic parameter descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: submitting a booking request for a shop not yet onboarded to Timeplex. It specifies the condition (bookable=false) and the workflow (concierge contacts shop, then replies to customer with a link). This distinguishes it from siblings like search_availability (which checks availability) and start_booking (which likely handles already-onboarded shops).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use this tool ('shop not onboarded yet'), but does not explicitly tell when not to use it or mention alternatives. The sibling tools hint at alternatives (e.g., start_booking for onboarded shops), but the description could directly state that this tool is only for bookable=false shops.

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

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

Annotations already declare readOnlyHint=true, confirming no state changes. The description adds valuable detail: when a time is given, the tool judges bookability and returns nearby alternatives if unavailable. This beyond-annotations info helps the agent understand conditional behavior. No contradictions found.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the core purpose, and the second sentence covers a key conditional behavior. No filler, every word earns its place. Highly concise and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 4 parameters, no output schema, and read-only annotations, the description covers the main function and conditional behavior. However, it does not explain the return format (relevant since there's no output schema) or the meaning of the 'slug' parameter (which lacks a schema description). The 'items' parameter behavior is left to the schema. Some gaps remain for a fully self-contained description.

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

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

With 75% schema description coverage, the schema already documents date, time, and items. The tool description adds extra meaning for the 'time' parameter: it judges exact slot bookability and returns alternatives. This augments the schema description. The undocumented 'slug' parameter in schema is not explained in the description, but overall the description adds value beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool checks available time slots for a date, with additional behavior when a time is provided. The verb 'check' and resource 'availability' are specific, and the tool implicitly distinguishes from siblings like get_booking_status or request_booking. However, it does not explicitly name sibling tools or contrast use cases.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description offers minimal guidance on when to use this tool versus alternatives. It implies a use case (checking availability for a date, optionally with a specific time), but does not state when not to use it (e.g., for existing bookings use get_booking_status) or mention any prerequisites or behavior for edge cases.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds value by disclosing behavioral traits: that results carry category, address, and a reply_header for response formatting. However, it does not mention pagination or result limits, which would round out transparency for a search tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is clear and front-loaded with the core purpose, but is somewhat verbose with extended booking logic and response instructions. A slightly shorter version could retain all key points while being more direct.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the context (3 optional params, no enums, no output schema, 5 sibling tools), the description provides ample guidance: it explains result structure, user language handling, and how to use the bookable flag. No output schema means the description must cover return content, and it does so by mentioning address, category, and reply_header.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining that search results include addresses (making location queries more useful) and that bookable vs. request_booking distinction enriches the query interpretation. It also clarifies that query can serve as a category fallback, which the schema does not express.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly defines the tool's purpose: finding Korean beauty & wellness shops on Timeplex. It specifies verb ('Find'), resource ('Korean beauty & wellness shops'), and platform context ('on Timeplex'), while distinguishing it from sibling tools by noting that search results provide shop addresses and booking indicators.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit when-to-use guidance: it explains the difference between bookable=true (available through MCP) and false (requires request_booking), categorizes shops into hair and beauty, and includes a user-language instruction. It also tells agents they can answer area questions without extra calls, implicitly differentiating from search_availability or get_shop_services.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the description's job is to add context beyond that. It does so richly: explains the tool 'creates and changes nothing — it only builds a link' (consistent with readOnlyHint), clarifies that the link requires customer action (email, name, phone, payment), discloses that payment does not guarantee the slot (whoever pays first gets it, and shop owner confirms), and states the response format (link_markdown, never raw URL). No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is comprehensive and front-loads the core purpose ('Build a link...'). However, it is quite long and contains some repetition (e.g., the instruction to 'never withhold the link' and details about what the customer must do). Some redundant guidance could be trimmed without losing clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 4 parameters with 75% schema coverage, annotations covering safety, and no output schema, the description is remarkably complete. It covers when to call, parameter optionality, behavioral nuances (no mutation), customer-facing instructions, and error-prone scenarios (raw URL exposure, waiting for date). The lack of an output schema is compensated by the explicit instruction to use link_markdown in the reply.

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

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

Schema documentation coverage is 75%, meaning most parameters already have descriptions. The description still adds value beyond the schema: clarifies that date, time, and items are all optional ('if the customer has not picked a date or time yet, still call it with just the shop'), explains the items array constraints per shop type (hair: exactly one; massage: multiple allowed), and ties parameter usage to the customer's conversation context. A slight deduction because the slug parameter is not explained beyond 'slug' in the schema and the description does not elaborate much on how to obtain it—though it could be inferred from context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool's purpose: 'Build a link that lets the customer continue the booking.' It clearly defines what the tool does and does not do: 'This creates and changes nothing — it only builds a link.' This distinguishes it from 'request_booking' (a sibling) which likely submits the booking or performs mutations, and from search tools like 'search_availability' which find available slots.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides exceptionally detailed usage guidance: when to call it ('once a shop is known, call it right away'), when not to ask questions ('never ask shall I create a link?'), how to handle missing data ('still call it with just the shop'), and what to tell the customer ('slot is not held until payment'). Also warns against common mistakes ('never expose the raw URL').

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