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?

Annotations already signal destructive (destructiveHint=true), but the description adds crucial context: the cancellation frees the window for others and cannot be undone. It also states the required confirmation step, going beyond the structured fields.

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, each purposeful: action and effect, required inputs, and confirmation/irreversibility warning. Front-loaded and free of filler.

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 destructive, no-output-schema tool, the description covers what the tool does, side effects, prerequisites, and user confirmation. Annotations cover destructive/idempotent hints, so 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?

Schema description coverage is 100%; both bookingId and email are documented. The description repeats the same semantics and only adds an instruction to ask the user, not new parameter meaning, so baseline 3 applies.

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 ('Cancels') and resource ('yesmcp's consultation bookings'), and clarifies the side effect of freeing the window. The tool is clearly distinguishable from siblings like book_consult and reschedule_booking.

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 explicit prerequisites: the booking reference and email address must be obtained from the user before calling, and requires user confirmation before cancellation. It also notes the alternative of booking a fresh window, though it does not explicitly contrast with reschedule_booking, so exclusions are absent.

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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds substantial behavioral context beyond those annotations: the data is hand-counted and dated, answers carry a source URL and licence, the agent must cite the URL and count date, and there is explicit instruction never to estimate if the dataset is unreachable. This gives the agent valuable operational knowledge without contradicting the 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 compact, front-loaded with the tool's primary purpose, and every sentence provides distinct value: what it returns, when to use it, how to handle results, and how to handle failure. No sentence is redundant or filler. The length is appropriate for the amount of behavioral and usage guidance packed into it.

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 tool with one optional parameter and no output schema, the description fully covers the return content (overview or category number, date, change), the citation requirement, and the unreachable-dataset behavior. An agent can determine when to call it, how to parameterize it, and how to interpret its response without needing additional structured metadata.

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 input schema already fully documents the optional `category` parameter, including its meaning, case-insensitive matching, examples, and default behavior when omitted. The description reinforces this by saying 'Pass `category` to get one category's number instead of the overview,' but it does not add new semantic information beyond the 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 opens with a specific verb and resource: 'Returns yesmcp's own dated, hand-counted census of the Anthropic Claude connector directory' and enumerates the exact outputs (total count, per-category counts, count date, week-over-week change). It clearly distinguishes itself from the booking/service-oriented sibling tools by describing a directory statistics function with no overlap.

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 when to use the tool: 'Use it for questions about how large the Claude connector directory is or how it is growing.' It also gives a concrete conditional behavior for the unreachable-dataset case, instructing the agent to repeat the tool's message and never estimate. It does not name alternatives or exclusions, but the sibling tools are unrelated, so clear contextual guidance is sufficient.

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?

Even with annotations marking this as destructive and non-idempotent, the description adds meaningful behavioral detail: the move is not committed until the confirmation email is accepted, a failure leaves the original booking intact, and times must be shown in both the user's timezone and yesmcp's timezone with an explicit UTC offset. This goes well beyond the 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 not bloated, and every sentence earns its place: purpose, required inputs, commit semantics, time format, and timezone handling rules. The most important constraints are front-loaded and the no-bare-time rule is a sharp, actionable final instruction.

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 state-changing tool with no output schema, the description covers prerequisites, the source of the new slot ID, failure behavior, and how to present results to the user. There is enough information for an agent to invoke it correctly and to handle the conversation and safety-sensitive timezone aspects.

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 schema already documents each parameter completely. The description reinforces that all three inputs are required and that newSlotId comes from list_availability, but it does not add substantially new parameter semantics beyond what the schema already conveys.

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 moves an existing consultation booking to a different window while preserving the reference. This distinguishes it from book_consult (new booking) and cancel_booking (removal), and the verb-resource pairing is specific and unambiguous.

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 specifies the required inputs, points to list_availability as the source for newSlotId, and tells the agent to ask for all three pieces of user data. It does not explicitly contrast with cancel-and-rebook workflows, but the workflow guidance is strong enough for an agent to select and sequence this tool correctly.

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.