yesmcp

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

The description discloses important behavior beyond the readOnly and idempotent annotations: it returns the closest playbook when an exact match is absent, explicitly instructs the agent to label that as adjacent guidance and not invent specifics, and describes the intake-question flow. This is exactly the kind of non-obvious behavior an agent needs to know before calling.

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 dense but every clause earns its place: purpose, playbook contents, fallback rule, no-invention guardrail, and the two-step intake workflow. It front-loads the core action and keeps all critical usage constraints in one coherent block.

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?

The tool's complexity is well covered: the description explains the scenario, the fallback, the intake flow, and how to handle partial answers. The output schema exists to explain return values, so the description does not need to redundantly describe them. Nothing essential is missing for correct invocation.

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 coverage is 100%, so the baseline is 3. The description adds meaningful parameter context: `businessType` should be in the user's own words, `answers` is the response to previously returned intake questions, and any subset of answers is acceptable. This goes beyond the schema by explaining the intended calling pattern.

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 states a specific verb and resource ('returns yesmcp's curated playbook') for a business type, and immediately clarifies what the playbook contains. It also distinguishes the tool from the booking-oriented sibling tools by focusing on scenario guidance rather than scheduling or service listing.

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 gives clear workflow guidance: call without `answers` to get intake questions, then call again with answers. It also explains fallback behavior when no exact playbook exists. It does not explicitly name alternative sibling tools, but the context is clear enough that an agent would not confuse this with a booking tool.

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 (readOnlyHint=false, openWorldHint=true, idempotentHint=false) already signal a non-idempotent write with external effects, and the description goes far beyond them. It discloses the commit-on-email-acceptance semantics ('if it fails, nothing is stored and the window stays open'), the exact data collected and the purpose of each field, and the timezone/display obligations. 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 long but earns its length: every paragraph maps to a distinct obligation (purpose, prerequisites, privacy disclosure, commit semantics, timezone handling). It is front-loaded with the core purpose before the procedural rules. Minor redundancy exists between the disclosure obligation and the 'only call once the user has given you those three values knowingly' consent requirement, which overlap thematically.

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?

With no output schema, the description carries the return-value burden and partially meets it by specifying the time format of returned times. It covers preconditions, failure behavior, privacy, and consent thoroughly. The main gap is the success-response shape (e.g., whether a booking reference or confirmation details are returned), which an agent would have to discover at runtime.

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 coverage is 100% and each of the 4 parameters already has a meaningful schema description (e.g., topic limited to one or two sentences, slotId 'exactly as returned by list_availability'). The description adds the rationale for why each value is collected — name/email to hold the slot and send confirmation, topic to prepare — but introduces no new format or syntax details, so it holds at the baseline of 3.

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 opening verb+resource — 'Books one of yesmcp's consultation windows for the user' — is specific and unambiguous. The requirement that slotId come from list_availability further clarifies the mechanism, but no sibling (notably booking_widget) is explicitly named, so the differentiation is implied rather than stated.

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 gives unusually explicit when-to-use guidance: the slotId must come from list_availability first, the user must knowingly provide three values, the agent must disclose what data is stored before calling, and it must ask for the user's timezone before confirming anything. What it lacks is an explicit when-not-to-use clause or named alternatives (e.g., use cancel_booking or reschedule_booking for changes).

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 and idempotentHint, and the description reinforces this by stating opening the calendar stores nothing. It also adds valuable context beyond annotations: the widget performs the booking through book_consult, so the agent understands the composed behavior and that all booking rules remain in effect.

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, front-loads the core behavior, and every sentence adds unique value: what the widget does, when to prefer it, and how it relates to book_consult. No wasted words.

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?

With zero parameters, rich annotations, an output schema, and a description covering purpose, usage, delegation, and side-effect behavior, the context is complete for an agent to select and invoke this tool correctly.

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 tool has zero parameters, so parameter explanation is unnecessary. The baseline of 4 applies; no additional semantic burden exists for the description to carry.

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 opens an interactive booking calendar in chat and describes what the user can do with it. It distinguishes itself from list_availability by explicitly saying to prefer this tool when booking or viewing times in an interactive-capable client.

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?

It gives explicit guidance: prefer this over list_availability when the user wants to book or see times and the client can render interactive tools. It also clarifies that booking rules from book_consult still apply, so the agent knows the widget is not an exception path.

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?

The description discloses the exact return payload, including prompts, mappings, expected outputs, the review-access token, and currently open reviewer windows. It also explicitly states 'it changes nothing,' reinforcing the read-only, non-destructive, and idempotent annotations with additional behavioral context.

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 with no filler. It front-loads the primary return value, then adds the token/window context, and closes with audience and safety. 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?

For a zero-parameter, read-only walkthrough tool, the description is complete: it explains what is returned, who it is for, and that it has no side effects. Annotations already cover safety, and no output schema is needed given the detailed description of the return content.

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 input schema has zero parameters and 100% schema coverage, so there are no parameter semantics to document. The baseline for zero-parameter tools is 4, and the description appropriately focuses on output rather than inputs.

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 names a specific verb ('Returns'), a distinct resource (yesmcp's demo sequence), and details the content: prompts, mapped tool calls, expected returns, token, and open reviewer windows. This clearly differentiates it from sibling tools like book_consult, directory_census, and cancel_booking, which represent actual connector actions rather than a walkthrough.

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 explicitly states the intended audience: directory reviewers and anyone wanting a guided tour of the connector. It also reassures that the tool 'changes nothing,' providing clear context for safe use, though it does not explicitly name alternatives or state 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 already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context by warning that the catalog may not be published yet and instructing the agent to return that status and the contact link, which is not visible from 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?

Two sentences with no filler: the first states the core purpose and the second provides essential handling instructions. The most important 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?

For a simple, read-only, zero-parameter tool, the description covers the return content, the fallback behavior, and the constraint not to embellish. Nothing essential is missing.

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 tool has zero parameters, so the description has no parameter details to add. According to the baseline for zero-parameter tools, this is fully adequate.

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 states a specific verb and resource: 'Returns yesmcp's real services catalog' and identifies the content areas: offerings, engagement process, and timeline expectations. This makes the tool's purpose immediately distinguishable from the siblings.

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 gives clear operational guidance: answer only from the tool's output, do not add unsupported claims, and handle the 'not published yet' case with a specific response. It doesn't explicitly contrast with sibling tools, but it clearly implies when this tool should drive the answer.

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 mark the tool read-only, idempotent, and non-destructive. The description adds genuinely new behavioral facts: UTC-offset formatting, the never-show-bare-time rule, the next-available-window fallback, and the review_access switch to seeded test data. 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 dense but front-loaded with the core behavior, then covers workflow, formatting, edge cases, and test mode. Every sentence carries operational weight, and the timezone example makes the format unambiguous without padding.

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?

With no output schema, the description provides the essential runtime contract: slotId availability, timezone display rules, the empty-result fallback, and the reviewer test-mode switch. An agent has enough to correctly call the tool and interpret what it returns.

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 a small amount of meaning for review_access (token source and 'do not use for real users') but nothing substantive for from, to, or limit, so it does not rise above baseline.

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 first sentence states a specific verb and resource: 'Lists yesmcp's genuinely bookable consultation windows.' It further scopes the tool to 'only real, future, unclaimed slots' and names the dependent sibling (book_consult), so an agent can clearly distinguish it from booking or cancellation tools.

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 explicitly says 'Use it before book_consult' and explains the slotId handoff, giving clear when-to-use context. It also adds timezone-handling instructions and a reviewer-specific mode, so an agent knows exactly when and how to invoke the tool.

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 mark destructiveHint=true and readOnlyHint=false; the description adds more context: cancellation is irreversible, a reschedule is only committed after the new confirmation email, and failures leave the original time intact. It also gives the timezone format, which is crucial behavioral information.

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 efficiently written and front-loads the outcome. Each sentence adds value, including the timezone instruction and failure semantics. It's slightly long, but every clause serves a clear purpose.

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?

It covers all necessary items an agent needs to call this tool safely: the required user inputs, the newSlotId source, confirmation before cancellation, and time inconsistency. With a moderate 4‑parameter tool and no output schema, the description is sufficiently complete.

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 input schema has 100% description coverage and already documents bookingId, email, action, and newSlotId. The description adds a little extra (like the need to ask the user for email and booking reference), but doesn't fundamentally change parameter understanding beyond the schema, so the baseline 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?

States a clear, specific action: 'Cancels an existing yesmcp consultation booking (`action: cancel`) or moves it to a different window keeping the same reference (`action: reschedule`)'. It identifies the exact resource and distinguishes the two modes, making it easy to tell apart from siblings like book_consult or list_availability.

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?

It explains the prerequisites: ask for the booking reference and email before calling, and state that rescheduling uses a newSlotId from list_availability. It also tells the agent to confirm before cancelling. It stops short of explicitly saying to use a book_consult for a fresh window, but the contextual clues are strong.

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 carry readOnly/idempotent/non-destructive safety. The description adds genuine context beyond them: the interactive carousel behavior, the in-widget booking flow routed through book_consult with 'every booking rule applies,' and the concrete claim that 'browsing stores nothing.' 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?

Three sentences with no waste: core function, booking interaction, then routing and read-only note. Every sentence earns its place and key facts are 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?

For a 0-parameter widget with an output schema and safety annotations, the description covers what it shows, when to select it over get_services, how its booking interaction behaves, and its storage footprint. Nothing needed for correct invocation is missing.

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 tool has zero parameters and schema coverage is trivially 100%, so there is nothing for the description to explain about inputs. This meets the baseline-4 expectation for a parameterless tool.

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?

States a specific verb and resource — 'Shows yesmcp's services' — and adds the rendering format (interactive card carousel) with the content areas covered. Explicitly contrasts with get_services, so an agent can distinguish it from siblings without opening schemas.

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?

Gives an explicit routing rule: 'Prefer this over get_services when the user asks what yesmcp does or offers and this client can render interactive tools.' It names the alternative, states the condition, and implies the inverse (use get_services when interactive rendering is unavailable).

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