Rudko — vertebrologist (Chernivtsi, Ukraine)

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

Beyond annotations (readOnlyHint=false), the description adds crucial behavioral context: it is a real-world side effect ('REAL action'), requires explicit user consent via Telegram OAuth scoped to booking:write, and enforces a one-appointment-per-day limit. These are not captured in the annotations or schema.

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 extremely concise—two short sentences with zero waste. It front-loads the critical warning ('REAL action') and packs essential details (consent, format, constraint) into a compact structure. Every word 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 real-world side-effecting tool, the description covers the essential aspects: action, consent/auth, parameter formats, and a key constraint. It lacks an explanation of the response/return value or failure modes, but given no output schema, the description provides sufficient context for an agent to invoke correctly in most cases.

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 0% schema description coverage, the description compensates by giving exact formats: 'date (YYYY-MM-DD), time (HH:MM)'. This adds concrete meaning to the parameters. It does not specify additional constraints like timezone or business hours, but the format guidance is valuable.

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 a specific action: 'creates a real appointment with the vertebrologist on the user's behalf.' This is a strong verb+resource pair, and it distinguishes itself from sibling tools by emphasizing 'REAL action (not a simulation)' and the booking scope.

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 the tool: when a real booking is needed and user consent has been obtained. It also notes constraints ('One appointment per day') and the OAuth requirement. However, it does not explicitly list when not to use it or mention alternatives like 'reschedule' or 'cancel'.

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 adds rich behavioral context: immediate execution, no confirmation step, return values on success/failure, and clearance on OAuth consent. However, it directly contradicts the annotation destructiveHint:false by stating it 'cancels the user's appointment IMMEDIATELY'—a destructive state change. This is an annotation contradiction.

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 lengthier than strictly necessary but front-loads the critical behavior ('REAL action... IMMEDIATELY — no confirmation step') and each sentence earns its place by covering return values, auth, and an alternative. Minor redundancy like 'REAL action' and the repetition in the second sentence prevents a 5.

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 one required parameter and no output schema, the description covers operation semantics, input source, response shape, auth prerequisites, and the alternate tool. The main gap is the internal inconsistency with destructiveHint:false, which undermines a fully coherent context for the agent.

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 schema provides no description for booking_id (0% coverage), so the description compensates by explaining it comes from list_current_bookings and is used to target the correct appointment. It also ties the parameter to the return value and error reasons, adding practical meaning beyond the raw 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?

States a specific verb ('cancels'), resource ('the user's appointment'), and required input ('by booking_id'), while explicitly distinguishing itself from the sibling 'reschedule' with 'To change the time instead, prefer reschedule.' This leaves no ambiguity about the operation.

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 when-to-use instructions: 'If the user said cancel, cancel; do NOT re-ask' and also names the alternative for changing the time ('prefer reschedule'). Clear exclusions and alternatives are fully stated.

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=true, and the description reinforces this with 'Read-only (does not book)'. It adds contextual details about the specific doctor and location, plus the behavior of returning all nearest available days when no date is provided. No contradictions 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 extremely concise, front-loading the core purpose and then covering optional behavior in one short clause. Every word adds value, and there is no redundancy or unnecessary elaboration.

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 availability tool with one optional parameter and no output schema, the description provides sufficient context: the purpose, location, parameter behavior, and read-only guarantee. It does not describe the exact response format, but this is not critical given the tool's simplicity and the lack of an output schema.

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 schema covers the single 'date' parameter with a basic format description, but the description adds crucial semantics by explaining what happens when the date is omitted ('all nearest available days'). This goes beyond the schema's minimal 'YYYY-MM-DD (optional)' label and helps the agent understand the parameter's optionality impact.

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 identifies the tool as providing free appointment slots for a specific doctor (vertebrologist) and location (Chernivtsi), and explicitly distinguishes it from booking by stating 'does not book'. This makes the purpose specific and differentiates it from sibling tools like book, cancel, and reschedule.

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 explains the optional date parameter and the behavior when omitted ('all nearest available days'), giving clear context on when to use the tool. The explicit 'Read-only (does not book)' implies that booking actions should be handled by other tools, though it does not name specific alternatives.

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 readOnlyHint annotation already tells the agent this is a safe read operation. The description adds useful context about the content (e.g., the one-appointment-per-day rule), but it doesn't disclose other behavioral details like response format or whether information is dynamic. It doesn't contradict 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 a single, compact sentence that front-loads the subject and lists key information. It is efficient, though the list format could be slightly clearer with separators or a more structured layout.

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-param read-only tool with no output schema, the description adequately covers what the agent can expect in the response. It includes specific details like the one-appointment rule and booking instructions, making it suitably complete for its simple scope.

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 zero parameters in the schema, the baseline is 4. The description adds meaning by explaining what the tool returns, but since there are no params, there is nothing more to elaborate. It appropriately doesn't invent parameter details.

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: providing info about the vertebrologist, listing specific content areas (specialty, treats, address, slot length, rules, booking). This distinguishes it from sibling tools like book or get_availability, which are action-oriented or availability-focused.

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 context is clear: this tool is for static doctor information, not for actions like booking or cancellation. However, it doesn't explicitly name alternatives or say when not to use it, so it falls short of full explicit guidance.

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?

Beyond the readOnlyHint annotation, the description adds that cancelled appointments are included and differentiated via a status field, that results are ordered nearest first, and that authorization is required. This gives the agent actionable behavioral context beyond what the annotation conveys.

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 four short sentences, each providing essential information: purpose, cancellation behavior, use case, and auth requirement. There is no redundancy or filler, and the main purpose 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?

The description covers the returned fields, ordering, cancellation inclusion, use case, and authorization. It doesn't explicitly state that past appointments are excluded, though 'current/upcoming' implies it, and the auth requirement is not detailed. Overall sufficient for a simple zero-parameter list tool.

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 there is no schema to elaborate on. Per the rubric, a baseline of 4 is appropriate when no parameters exist, and the description adds no unnecessary parameter detail.

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 lists the user's current/upcoming appointments with specific fields (booking_id, date, time, status) and ordering (nearest first). It distinguishes from sibling tools like list_past_bookings through the 'current/upcoming' scope and the explicit mention of cancelled appointments.

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 usage context by stating 'Needed to reschedule/cancel.' It also implies exclusion of past bookings via 'current/upcoming,' but does not explicitly name alternative tools or provide when-not-to-use guidance.

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 declaring readOnlyHint, the description adds valuable behavioral context: ordering (most recent first), inclusion of cancelled appointments (shown via status field), pagination with default limit (20), and the authorization requirement. These details go beyond what the annotations alone convey.

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 four concise sentences, each providing essential information: main purpose with fields, pagination, cancelled appointment behavior, and authorization. It is front-loaded with the primary purpose and contains no 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?

With no output schema, the description adequately covers return fields, ordering, pagination, cancellation behavior, and authorization requirements. For a simple read-only list tool, this is complete and leaves no major gaps for an agent to infer.

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 provides no descriptions for limit and offset (0% coverage). The description fully compensates by explaining 'limit (default 20) and offset for pagination', giving both purpose and default value for each parameter.

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 resource ('the user's past appointments'), includes key fields (booking_id, date, time, status), and specifies ordering ('most recent first'). It distinguishes itself from the sibling tool 'list_current_bookings' by focusing on past appointments, and also notes that cancelled appointments are included.

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 implies usage context by explicitly saying 'past appointments' and mentioning pagination, but it does not explicitly name an alternative or state when not to use it. The distinction from 'list_current_bookings' is clear via the word 'past', providing clear context without formal exclusions.

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 adds behavioral context beyond the annotations: the atomic guarantee (if target slot is taken, user keeps current slot), no confirmation required, and that OAuth consent is pre-provisioned and should never be re-prompted. This enriches the bare readOnlyHint/idempotentHint/destructiveHint annotations with actionable details.

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 information-dense and front-loaded with the main purpose and atomic guarantee. It includes necessary usage guidance and parameter formats. However, the phrase 'that atomic guarantee is the whole point of same-day move' is slightly redundant, and the 'REAL action:' prefix feels unnecessary. Still, 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 its complexity, the description covers all critical aspects: same-day vs different-day behavior (cross-referencing book), atomicity, consent/confirmation expectations, and parameter formats. No output schema is present, but the description sufficiently addresses what the agent needs to know to invoke the 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 input schema has zero per-parameter descriptions, so the description fully compensates by specifying formats: date (YYYY-MM-DD), from (HH:MM current), to (HH:MM new). It also explains that 'from' is the current slot and 'to' is the new one, which is essential for correct invocation.

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 the user's appointment to another free slot on the same day, with the key detail of atomicity. This specific verb and resource scope distinguishes it from the sibling tool 'book', which is explicitly mentioned for different-day moves.

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?

Explicit guidance is given: use this for same-day rescheduling, and use 'book' for different days. It also clarifies no confirmation is needed and that consent is already handled via OAuth, so the agent knows when and how to invoke the tool without hesitation.

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