SzuruSzuru – rezerwacja czyszczenia tapicerki

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral context beyond them: the returned quote_id is valid for 30 minutes, side effects are none for the customer (the quote is stored only), and named error behaviors are documented (unsupported_addon, unsupported_postcode, below_min_order). This gives the agent a complete operational picture.

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 well-structured with front-loaded, capitalized section headings (PURPOSE, WHEN TO USE, WHEN NOT TO USE, REQUIRED, SIDE EFFECTS, CONSTRAINTS), making scanning easy. It is longer than a typical description, but almost every sentence carries operational value; only brief retellings of required parameters overlap with the schema.

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 quote-calculation tool with an output schema and rich annotations, the description covers all decision-critical points: prerequisites, alternatives, error conditions, quote expiry, side effects, and the constraint to report total_from exactly. Nothing an agent needs to call it correctly appears to be 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 coverage is 100%, so baseline is 3. The description still adds value: it clarifies that service ids come from list_upholstery_services, that add-ons are optional and matched with close spellings, that unknown add-ons trigger unsupported_addon with allowed_addons, and that the agent should ask the customer rather than guess unknown values. This goes beyond what the schema alone communicates.

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 precise verb+resource: 'Calculates the price of an order (unit prices, quantity discounts, add-ons, travel fee, minimum order) for a postal code.' It also explicitly distinguishes this tool from siblings by naming check_availability and contrasting it with booking, so an agent can route correctly without schema inspection.

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 provides explicit WHEN TO USE ('Whenever the customer asks how much a cleaning costs...', 'first step before check_availability') and WHEN NOT TO USE ('Not for checking dates and never as a booking - it reserves nothing') sections. This is exactly the when/when-not/alternatives guidance the dimension rewards.

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 cover the safety profile (destructiveHint, idempotentHint, readOnlyHint=false), and the description adds substance beyond them: notification side effects via SMS/e-mail, the irreversibility of the operation, and the repeated-call behavior. The auth requirement (customer_grant or signed-in customer) is also disclosed.

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?

Labeled sections (PURPOSE / WHEN TO USE / WHEN NOT TO USE / REQUIRED / SIDE EFFECTS) front-load the decision-critical information, and each line carries a distinct fact with 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?

An output schema exists so return values need not be described, and the description still covers everything an agent needs: preconditions, auth path, irreversible consequences, notification side effects, and idempotent retry behavior.

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 already 80%, so the baseline is 3, but the description adds real meaning: it distinguishes which fields are required vs optional and clarifies that customer_grant can be replaced by a signed-in customer. session_id is omitted from the description but is well documented in the schema itself.

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 the specific verb and resource ("Cancels the verified customer's existing booking") and immediately flags the irreversible nature. It is clearly distinguishable from reschedule_booking, which is explicitly named as the wrong tool for date changes.

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 WHEN TO USE precondition (customer explicitly confirmed the specific booking, reference and date read back) and an explicit WHEN NOT TO USE with the named alternative (reschedule_booking) plus a prohibition on unclear requests. Nothing is left to inference.

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 cover the read-only/no-destruction profile, and the description adds genuinely new behavior: no side effects, slot_id validity of ~15 minutes, the full error taxonomy (no_availability, date_in_past, date_out_of_range) and the instruction never to invent a slot. This is rich context beyond 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?

Labelled sections (PURPOSE/WHEN TO USE/WHEN NOT TO USE/REQUIRED/SIDE EFFECTS/RESULT) front-load the decision-relevant information and every sentence carries operational content. Dense but zero waste for a tool with this much branching logic.

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?

Covers the request modes, required inputs, side effects, success and failure shapes, and the ordering constraint relative to calculate_quote. With an output schema present, the description correctly focuses on routing and error semantics rather than restating return fields.

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, but the description adds meaning the schema does not: how wanted.type selects behavior (asap/date/range/preferred) and the fallback when type is omitted (date->date, from/to->range, nothing->asap), plus the customer_grant requirement for rescheduling. It stops short of documenting preferred_time ordering semantics.

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+resource (returns real, currently free appointment slots) and distinguishes the two calling modes by quote_id (new booking) vs booking_reference (reschedule). An agent can tell it apart from create_booking/reschedule_booking without opening a schema.

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 WHEN TO USE (after calculate_quote, when the customer asks when we can come) and WHEN NOT TO USE (never to book - reserves nothing), plus the sequencing relative to a named sibling. Nothing is left to inference.

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/idempotentHint/non-destructive, so 'SIDE EFFECTS: none' is partly redundant. What the description adds beyond structured data is the failure path — success=false, error='unsupported_postcode', available=false — plus the directive to stop the customer at that point rather than continue to quote or booking. That is genuine behavioral guidance, though it overlaps with the existing output 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 labeled PUrpose/WHEN/REQUIRED/RESULT structure is front-loaded and scannable, and each block earns its place. Minor redundancy: 'SIDE EFFECTS: none (read-only)' duplicates the annotations, and 'REQUIRED: postal_code' duplicates the schema.

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 single-parameter eligibility check with an output schema, annotations, and a named sibling, nothing an agent needs is missing: input format, exclusions, expected result shape, and the escalation rule on failure are all present.

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 schema already documents the NN-NNN pattern with an example and notes that session_id is ignored. The description's 'REQUIRED: postal_code (NN-NNN)' restates the schema without adding format, validation, or edge-case meaning, so the 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?

The description opens with a precise verb and resource: 'Checks whether SzuruSzuru serves a Polish postal code.' It names the sibling calculate_quote explicitly, so an agent can separate this read-only eligibility check from the quoting tool without inspecting either schema.

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 WHEN TO USE ('when the customer asks whether we come to their town/postal code') and WHEN NOT TO USE ('not needed before calculate_quote — calculate_quote checks the area itself', 'never use it to reserve anything'). The alternative tool and the condition selecting it are spelled out, not inferred.

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?

Goes well beyond the annotations by disclosing side effects (technician scheduled, SMS/e-mail sent to customer), the idempotency mechanism, and named error modes (missing_required_fields, verification_failed with attempts_left). The annotations confirm idempotentHint/destructiveHint, and the prose adds the operational detail they cannot carry.

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?

Front-loaded with labeled sections (PURPOSE, WHEN TO USE/NOT, REQUIRED, SIDE EFFECTS, RESULT) that let an agent skim in priority order. Length is justified by a two-step, side-effecting, idempotent booking flow.

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 mutation tool with output schema present, the description supplies everything needed: prerequisites, failure modes, idempotency guarantees, and what success returns. No gaps remain 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 description coverage is 100%, so the schema already documents all four parameters, including the retry semantics of idempotency_key. The description restates required vs optional but adds no syntax or format detail beyond the schema, so the 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 and resource ('Creates the real, confirmed SzuruSzuru booking') and explicitly frames it as step 2 of 2 tied to prepare_booking, which cleanly separates it from the sibling that produces the confirmation_id.

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?

Contains dedicated WHEN TO USE and WHEN NOT TO USE sections, including the specific precondition (prepare_booking succeeded and the customer typed the SMS code) and explicit exclusions ('never to check price or availability, never without a code').

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 readOnly/idempotent/non-destructive, so the bar is lower; the description still adds the 90-day retention window, the verification_required error contract with its remediation chain, and the data-isolation guarantee ('Never shows other customers' data'). 'SIDE EFFECTS: none (read-only)' duplicates the annotation, which keeps it short of a 5.

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?

Labeled blocks (PURPOSE / WHEN TO USE / WHEN NOT TO USE / REQUIRED / SIDE EFFECTS) front-load the decision-relevant information, and every line carries a distinct fact with 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 an output schema present, return values need no explanation, and annotations cover the safety profile. The remaining gaps an agent would care about, auth path and error recovery, are both stated, so nothing material 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 coverage is 100%, so the schema already documents all three parameters including session_id recovery and the booking_reference pattern. The description only restates the booking_reference list-vs-single switch, adding no syntax or format detail beyond the schema; baseline 3 is correct.

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?

Opens with a specific verb+resource ('Lists the verified customer's bookings') and scopes it to a 90-day window plus the single-booking alternative via booking_reference. The listed return fields (reference, services, date, status, can_reschedule, can_cancel) make the distinction from create_booking/cancel_booking/reschedule_booking 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?

Explicit WHEN TO USE ('customer asks about existing booking(s)') and WHEN NOT TO USE ('not for new bookings'), plus a named recovery path: on verification_required run start_phone_verification -> verify_phone_code. This routes the agent to siblings with the exact triggering condition.

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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data; the description's 'SIDE EFFECTS: none (read-only)' largely restates it. It does add value by disclosing the breadth of returned content, but that overlaps the output 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?

Labelled sections (PURPOSE / WHEN TO USE / WHEN NOT TO USE / REQUIRED / SIDE EFFECTS) make it scannable and front-loaded. One clause, the side-effects note, duplicates the annotations rather than adding new information.

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 an output schema is present, the description need not detail return values, and it still supplies purpose, routing conditions, the required parameter source, and a safety note. An agent has everything needed to select and invoke it 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?

Schema description coverage is 100%, so both the service id and the ignored session_id are already documented in the schema exactly as the description repeats them. Baseline 3 is correct when the schema carries the full parameter burden.

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 the details of ONE service') and enumerates exactly what is returned (unit, quantity, add-ons, description, FAQ). This lets an agent distinguish it from siblings like list_upholstery_services or calculate_quote without opening any schema.

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 WHEN TO USE ('when the request is ambiguous') and WHEN NOT TO USE ('not for prices of an order (use calculate_quote) or availability') sections name both the condition and the alternative sibling tools. Nothing is left to inference.

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 cover readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is largely pre-declared. The description nonetheless adds a useful domain constraint not present in structured data: prices come only from this catalog and calculate_quote, never estimated. It does not add much beyond that (no pagination or ordering behavior), so it sits just above 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?

Labeled sections (PURPOSE / WHEN TO USE / WHEN NOT TO USE / REQUIRED / SIDE EFFECTS / CONSTRAINTS) make it scannable, and the purpose is front-loaded before the routing rules. Every sentence carries a distinct instruction; 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?

Output schema exists, so return-value explanation is unnecessary, yet the description still names the key returned fields. Required params (none), side effects, filtering option and the pricing constraint are all covered, leaving no gap for an agent to call it 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?

Schema description coverage is 100%, so both parameters (category enum with its meaning, session_id being ignored) are fully documented in the schema. The description adds no parameter syntax or format detail beyond that, so the baseline 3 is correct.

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 (Lists) and resource (SzuruSzuru services) with scope: the service domain, region, and the exact fields returned (service ids, unit prices in PLN, units, add-on names). An agent can distinguish it from calculate_quote and the other siblings without opening any schema.

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 WHEN TO USE (find service id / exact add-on names before calculate_quote, or answer what is offered) and WHEN NOT TO USE with named alternatives for each excluded case (calculate_quote for order pricing, check_service_area for coverage, check_availability for dates). Nothing is left to inference.

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 destructiveHint=false, idempotentHint=true and openWorldHint=false, but the description adds material behavior beyond them: the 10-minute hold, the outbound SMS side effect to the customer's phone, the idempotency contract (same confirmation_id, no duplicate SMS), and the missing_required_fields error shape. This is a genuinely informative mutation contract.

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?

Labeled sections (PURPOSE/WHEN TO USE/WHEN TO NOT USE/REQUIRED/SIDE EFFECTS/NEXT) put the highest-value facts first with zero filler. Long but every clause carries operational information.

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 stateful two-step booking flow, it supplies preconditions, side effects, error contract, idempotency and the explicit next step (collect SMS code, call create_booking). With an output schema present it correctly avoids describing return values, and nothing needed to call it correctly 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 86%, so the schema already documents quote_id, slot_id, customer fields and terms_accepted. The description mainly restates the required list rather than adding new meaning (e.g. it does not explain the phone-optional-when-signed-in rule that the schema itself carries). 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 precise verb and resource ('Step 1 of 2 of booking... Holds the chosen slot for 10 minutes and sends a 6-digit SMS code'), and explicitly negates the closest sibling with 'Does NOT create a booking.' An agent can distinguish it from create_booking without inspecting either schema.

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 preconditions (customer confirmed this slot, gave name/address/phone, accepted terms) and a WHEN TO NOT USE clause covering price/date questions and vague 'maybe' intent, plus a 'never guess' instruction. Routing against siblings like calculate_quote and check_availability is unambiguous.

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?

Adds real context beyond the annotations: notifies the customer by SMS/e-mail, price/services are unchanged, and repeated calls return the same result (reinforcing idempotentHint=true consistently with destructiveHint=true). It does not state whether the old slot is released or the notification timing, which keeps it short of a 5.

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?

Labeled sections (PURPOSE / WHEN TO USE / WHEN NOT / REQUIRED / SIDE EFFECTS) front-load the decision-relevant facts and every line carries information. Slightly longer than strictly necessary, but nothing is 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 an output schema present, return values need no explanation, and the description covers prerequisites, safety-relevant side effects, and idempotency. It stops short of stating what happens to the vacated slot and the exact auth/permission requirement, the only meaningful gaps.

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 80%, so the baseline is 3; the description rises above it by tying slot_id to check_availability(booking_reference), tying customer_grant to a signed-in alternative, and naming idempotency_key's optional status and retry semantics. It does not add format details beyond those already in 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?

States a specific verb+resource ('moves the verified customer's existing booking to a new slot') plus a scope constraint ('price and services stay the same'). This clearly distinguishes it from create_booking and cancel_booking without needing to open either schema.

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 WHEN TO USE section requires the prior check_availability(booking_reference) call and explicit customer confirmation, and WHEN NOT TO USE excludes new bookings and service/price changes. Alternative routing is unambiguous.

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 only declare non-read-only, non-idempotent, non-destructive; the description goes further by disclosing side effects (sends exactly one SMS), concrete rate limits (1/min, 3 per 30 min per phone), and the exact error and recovery field (rate_limited with retry_after). That is behavior an agent must 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?

Labeled sections (PURPOSE / WHEN TO USE / WHEN NOT TO USE / REQUIRED / SIDE EFFECTS) front-load the routing decision and compress rate-limit detail into one line. Every sentence carries operational weight.

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?

An output schema exists, so return values need not be explained. The description covers the remaining agent-facing gaps: correct trigger conditions, exclusions, required input, and failure/backoff behavior.

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 both parameters are fully documented in the schema itself. The description only restates that confirmation_id is required and cites its source, adding little beyond the structured field, 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 precise verb+resource: re-sending the SMS code of a prepared booking. This clearly separates it from prepare_booking (initial send) and verify_phone_code (code entry), so an agent can route correctly without opening the schema.

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 WHEN TO USE (SMS from prepare_booking did not arrive) and WHEN NOT TO USE (not after a wrong code, not to start a new booking), with the corrective action spelled out for the wrong-code case. No inference required.

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 only give the generic flags (readOnly=false, destructive=false, openWorld=false, idempotent=false); the description goes well beyond them by disclosing the single-SMS side effect and the 60-second dedupe window that returns the same verification_id without a new SMS. It also discloses the anti-enumeration property (identical response whether or not the number is known), which is real behavioral information an agent needs.

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 labeled PURPOSE / WHEN / WHEN NOT / REQUIRED / SIDE EFFECTS structure is front-loaded and highly scannable with no filler prose. The 'REQUIRED: phone' line duplicates the schema's required field, so it isn't perfectly waste-free, but the size is appropriate.

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?

An output schema exists, so return-value explanation is unnecessary; what remains — purpose, selection criteria, the SMS side effect, dedupe behavior, and privacy semantics — is fully covered for a two-parameter 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?

Schema description coverage is 100% and both parameters are documented in the schema, so the baseline is 3. The description restates only that phone is required and says nothing about session_id or the server's session-recovery behavior beyond what the schema already explains.

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 concrete verb+resource (send an SMS code to a Polish mobile number) and the business goal (proving ownership before acting on EXISTING bookings). It also differentiates itself from the sibling prepare_booking, so an agent can distinguish it without opening either schema.

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 WHEN TO USE (customer asks about an existing booking and no customer_grant exists) and WHEN NOT TO USE (new booking -> prepare_booking sends its own code), naming the alternative directly. This is the full when/when-not/alternative pattern.

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 non-read-only, non-destructive, non-idempotent behavior, and the description adds context beyond them: the grant's 60-minute validity, 'no side effects besides issuing the grant', and exactly which downstream tools consume the grant. It stops short of failure modes (expired/invalid code) and retry limits, so not a 5.

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?

Labeled PURPOSE / WHEN TO USE / WHEN NOT TO USE / REQUIRED / SIDE EFFECTS blocks front-load the routing decision and the object handoff; every sentence carries information, with 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?

An output schema exists so return values need not be described, and the description closes the loop by telling the agent which tools to feed the grant into. For a two-required-parameter verification tool, nothing needed to call it correctly 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%, so all three parameters already document their format and provenance. The description only restates the two required names and adds no semantics beyond the schema, which matches the baseline-3 rule when the schema does the heavy lifting.

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: exchanges the SMS code for a customer_grant that grants access to the customer's bookings. It also pins the input's origin (start_phone_verification) and the grant's 60-minute lifetime, which no sibling tool shares.

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 WHEN TO USE (right after the customer types the code from start_phone_verification) and WHEN NOT TO USE, naming prepare_booking/create_booking as the conflicting path so the agent can disambiguate the two code flows.

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