RIED.TAXI

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

The description adds meaningful behavioral context beyond the annotations: cancellation is free of charge, must happen before pickup, requires customer_confirmed=true after explicit customer confirmation, and cannot be undone. These details are not present in the annotations or schema and materially shape how and when the tool should be used.

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 and front-loaded: the first sentence states the core behavior and key constraints, followed by a concise list of prerequisites and the irreversible nature of the action. There is no redundant or filler language.

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

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

Given the annotations, output schema presence, and the relatively simple cancellation semantics, the description covers all critical operational aspects: what happens, when it can happen, prerequisites, costs, and irreversibility. No essential information for invoking the tool 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?

The description reinforces which parameters are essential and adds the crucial semantic that customer_confirmed must be set to true only after the customer explicitly confirms. Schema descriptions already cover access_code, idempotency_key, and booking_reference, but the optional 'reason' parameter is not explained. The description partially compensates for the coverage gap by emphasizing the required confirmation flow.

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 action ('Cancels a booking') and identifies the specific resource. The addition of 'free of charge, any time before the pickup' distinguishes this cancellation operation from the sibling update/get/hold tools. An agent can immediately tell this tool is for canceling, not modifying or retrieving.

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 explicit usage context: cancellation is possible any time before pickup and requires customer confirmation before the flag is set true. It does not explicitly name alternative tools or list exclusions, but since no sibling is a cancellation tool, the primary use case 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 already declare read-only, idempotent, and non-destructive behavior, and the description adds valuable context beyond that: it checks the real calendar including temporary holds, depends on the whole day due to one car/driver, returns alternatives when unavailable, and clarifies that availability is not a reservation. This is rich behavioral disclosure with no 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?

Three sentences deliver the essential scope, caveats, and return behavior with no wasted words. The most important information about the real calendar and read-only nature 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 key behavioral and usage context: real calendar, capacity constraint, read-only semantics, and alternatives on failure. Since an output schema exists, return values are already specified; however, it does not clarify how optional addresses affect the drive-time calculation, which is a minor completeness gap.

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 only 40%, covering pickup_date and pickup_time, while passengers, pickup_address, and destination_address are undocumented in the schema. The description mentions driving to the pickup and back, which hints at address importance, but it does not explain any of the undocumented parameters or their role in the availability calculation.

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

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

The description clearly states the tool checks RIED.TAXI's real calendar for availability, which is a specific verb and resource. It distinguishes itself from booking/management siblings by emphasizing it is read-only and not a reservation, though it does not explicitly name alternative 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 gives clear context: availability is whole-day dependent and a free result is not a reservation, so an agent knows not to treat this as a booking action. It does not explicitly state when to prefer this over get_quote or hold_booking, but the read-only clarification provides useful boundary 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?

Annotations already flag idempotentHint=true and destructiveHint=false, but the description adds real context: retrying with the same idempotency_key never creates a second booking, the call blocks the day, and it returns a booking reference plus customer access code. It doesn't discuss permissions, failure modes, or what happens when a quote_id has expired.

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?

Four sentences, each earning its place: what it does, the precondition, the required inputs and idempotency guarantee, and the return values. The precondition is front-loaded ahead of parameter detail.

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 25-parameter mutation tool with an output schema available, the description covers the essential decision gate and the idempotency contract. What is missing is guidance on stale/invalid quote_ids and the fact that stops/child_seats must be empty, though the schema itself flags those.

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 56% across 25 parameters, so the schema does much of the work. The description reinforces four required parameters (quote_id, customer_confirmed, accepted_terms, idempotency_key) and adds the idempotency retry semantics, but says nothing about the many address, flight, or luggage parameters the agent must still fill.

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 ('Creates a REAL, CONFIRMED booking in RIED.TAXI's booking system and blocks the day'), and the 'CONFIRMED' plus 'blocks the day' framing distinguishes it from ried_taxi_hold_booking, which only reserves. An agent can identify the operation 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?

It gives an explicit gating condition – 'Only call after the customer has seen the complete trip and price and explicitly said yes' – which implies the get_quote → create sequence. It does not name hold_booking or update_booking as alternatives or state when to prefer them, so it stops just short of full routing 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?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description's 'Read-only' is redundant. It adds minor behavioral context like the access code being customer-received and the specific data fields returned, but these are largely covered by the output schema and parameter schema. 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 short, well-structured sentences with no fluff. The purpose is front-loaded, followed by requirements, and a final read-only note. Every sentence contributes directly to correct invocation.

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?

This is a simple single-booking lookup with only two parameters, both fully specified in the schema, and an output schema exists to describe return structure. The description covers the operation's purpose, required inputs, and read-only nature. Nothing an agent needs 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?

Schema description coverage is 100%, so both parameters (booking_reference and access_code) are already well-documented with formats and examples. The description adds only a slight clarification that the access code was received by the customer, which already appears in the schema ('given at booking time'). No significant additional meaning 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 clearly states a specific verb ('Returns'), a resource ('ONE booking'), and the scope of what is returned (status, pickup time, addresses, price, flight). It distinguishes itself from siblings like cancel/create/hold/update by focusing on retrieval only.

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 makes it clear this is for looking up a booking and is read-only, implying it is not for modifications. However, it does not explicitly name alternative tools (e.g., ried_taxi_update_booking) or state when not to use it. The context is clear but exclusions are only implicit.

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, and destructiveHint, so the bar for added context is lower. The description still adds substantial behavior beyond those annotations: quote_id is valid for 30 minutes, status values are enumerated, resolved pickup/destination should be shown to the customer, and ambiguous_place requires re-prompting with a postcode.

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 and front-loaded, starting with the core function and read-only safety. There is minor redundancy — 'Returns' opens two sentences and 'read-only' restates an annotation — but every sentence otherwise 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 tool with rich annotations and an output schema, the description covers the essential operational details: quote validity, status values, how to present resolved addresses, and how to handle ambiguous places. It does not explain what to do for manual_quote_required or not_offered, though those states are reasonably self-explanatory.

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 only 50%, and the description does not compensate for the undocumented parameters. It offers little input-side guidance beyond hinting that a postcode resolves ambiguity, while large_suitcases, flight_number, special_requirements, and passenger constraints remain unexplained in both schema and description.

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 verb ('Returns') and resource ('RIED.TAXI's current price for one journey'), and identifies the backend as the only valid price source. It also explicitly distinguishes the tool from booking or reserving, which separates it from sibling tools like ried_taxi_create_booking and ried_taxi_hold_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?

The read-only framing and 'never books or reserves anything' make it clear this tool is for price lookup, not booking. It also gives a concrete conditional instruction for ambiguous_place — ask the customer and resend with the postcode — though it does not explicitly name sibling alternatives or state when to use them.

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 a critical negative behavior: it does NOT block or reserve the day, and only a created booking blocks a day. It also describes the return payload (available=true/false with alternative dates, held=false). This adds real side-effect clarity that readOnlyHint/idempotentHint alone would not 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?

Three short sentences, each load-bearing: what it does, the side-effect caveat, the return shape, and the call-order guidance. The most decision-critical fact (it does not hold the day) is front-loaded in sentence two.

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 annotations covering the safety profile and an output schema present, the description still contributes the booking-model caveat and the sequencing with create_booking. An agent has everything needed to call this correctly in the booking flow.

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?

Three required params with schema coverage at 67%: pickup_date and pickup_time carry format/timezone descriptions, but quote_id is undocumented in both the schema and the description. The description adds no parameter-level meaning, so the baseline of 3 for largely schema-documented params 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 ("Re-checks that the quoted date is still free") with clear temporal scope ("right before the booking"), which differentiates it from the sibling check_availability. It does not name that sibling explicitly, so the agent must infer the distinction from timing rather than an explicit callout.

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 trigger ("when the customer wants to proceed") and the follow-on flow ("show the summary and create the booking right after their explicit yes"), which routes the agent through the booking sequence. It stops short of naming when to use check_availability instead, but the usage context 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 declare the destructive/idempotent/open-world profile, and the description goes well beyond them: it discloses the mandatory preview-then-apply confirmation workflow, the dual-path behavior (immediate vs. sent to Ronald with status change_requested), and the passenger ceiling. These are exactly the behavioral traits an agent needs to invoke it safely.

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 the action, then the required call sequence, then the immediate-vs-approval split. No filler sentences; each clause carries distinct 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 complex nested mutation tool with an output schema present (so return values needn't be described), the description covers workflow, confirmation gating, idempotency, approval routing, and limits. Nothing essential to 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?

At 50% schema coverage the description compensates meaningfully: it explains mode values, the customer_confirmed gate, the idempotency_key usage, passenger max of 5, and groups of changeable fields. It does not fully document every nested change field, so it falls short of a 5 but clearly adds value 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?

States a specific verb and resource ('Changes a booking') and the title disambiguates it as the RIED.TAXI update operation, making it clearly distinct from create/cancel/get siblings. It doesn't explicitly name or route to alternatives, so it stops short of a 5.

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 two-phase protocol (call mode='preview' first, show the customer, then mode='apply' with customer_confirmed=true and an idempotency_key) plus which change classes apply immediately vs. route for approval. When and how to use it is fully spelled out.

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