Black Car Service — Bay Area Ride Quotes

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

Annotations only declare the safety profile (destructive, non-idempotent, open-world); the description adds substantive behavior beyond them — live price/availability recheck, no vehicle hold, no payment or SMS side effects, and the critical retry semantics that constrain how an agent may re-invoke a non-idempotent call. It also restates the security boundary 'never request payment credentials'.

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?

Six short sentences, each carrying a distinct constraint: trigger, return value, required inputs, revalidation, explicit non-effects, retry rule, security rule. The precondition and result come first; 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?

For a non-idempotent, destructive creation tool with no output schema, the description covers everything an agent needs: the precondition gate, the returned checkout link, which side effects do and do not occur, and the retry discipline. Nothing material is left to inference.

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 still adds value by tying booking_token to its origin in quote_ride and mandating that the same token and contact details be reused across retries — semantics the schema repeats but does not fully motivate. customer_confirmed's intent is reinforced but not extended much beyond the schema's const/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?

States a specific verb and resource — 'create a pending reservation and return its secure website checkout link' — with the triggering condition (customer-confirmed quote_ride estimate) front-loaded. This clearly separates it from quote_ride (estimate), complete_booking (payment/confirm) and get_booking_status (read).

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 the customer explicitly confirms a quote_ride estimate and trip'), explicit when-not ('does not hold a vehicle, confirm payment, charge a card, or enroll SMS'), and explicit retry policy (reuse the same token and contacts; do not bypass uncertain outcomes with a new token). No alternatives need to be 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?

Adds substantial context beyond annotations: the result set is exactly available/unavailable/unknown, an 'available' answer is tentative and is not a hold or reservation, and hourly rides require hours. The 'not a hold' framing is especially useful given readOnlyHint=false and idempotentHint=false, clarifying that no operational state is created. Only missing piece is why it is not flagged read-only despite sounding like a pure check.

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?

Dense and front-loaded: eligibility constraint, input parity, return values, no-hold caveat, then the hours rule. Every sentence carries information, though the opening sentence partially restates the title and could be tightened.

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?

No output schema exists, and the description compensates by enumerating the three possible results and the tentative nature of a positive answer, along with geo preconditions and the follow-up booking step. Remaining gaps are minor for a pre-check tool (e.g., what 'unknown' implies for the caller, whether retrying helps).

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 67% and the description fills meaningful gaps: it restates the conditional hours rule (1–24, hourly only, omit otherwise), points to quote_ride for identical route/time/passenger inputs, and imposes geographic constraints on pickup/destination that the schema itself does not encode. It does not add format or DST detail beyond the schema's own pickup_at 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?

States a specific verb and resource ('Check a requested Bay Area SUV pickup time against current scheduling constraints') and immediately distinguishes itself from quote_ride (input parity) and from booking (not a hold or reservation). An agent can tell it apart from book_ride and get_booking_status 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 real usage boundaries: geo eligibility (both endpoints CA or NV, one endpoint in the nine-county Bay Area) and the terminal step ('complete the request at https://.../book'), plus input parity with quote_ride. It does not explicitly say when to prefer quote_ride instead (pricing) or how it relates to book_ride/complete_booking beyond the URL, so it stops short of a full when/when-not/alternatives statement.

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: retries reuse the SAME checkout_url and never create another reservation (concrete idempotency semantics), the token must be scoped to the returned Stripe business profile for that amount, and customer_action verify_in_agent_wallet must be resolved in the issuing wallet before retrying. Consistent with destructiveHint=true and idempotentHint=true, and adds the failure/next-action path 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?

Front-loaded with the core action, then prerequisites, then constraint and retry semantics; every sentence carries operational information. It is dense (six sentences) but not padded — only the final clause about 'confirmed result' borders on restating what should be obvious.

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 does communicate that only a confirmed result counts and that a customer_action may require wallet-side handling before retry. Return-shape detail (what fields a confirmed result carries) is thin, but the critical agent-facing behavior for a money-moving tool is covered.

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%, and the description still adds meaning: the total must be the exact one from get_booking_status that the customer approved, and the token must be issued to the returned Stripe profile for that amount. It does not explicitly discuss checkout_url or customer_confirmed, but the schema covers both well.

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 — charges the exact approved USD total via a Stripe shared payment token, then verifies confirmation — which is clearly distinct from siblings book_ride (creates the reservation) and get_booking_status (reads status). An agent can route to it 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?

Gives an explicit prerequisite sequence ('First call get_booking_status and obtain explicit customer approval of that total and the booking terms') and an explicit prohibition ('Never accept card numbers, CVC, or saved-card IDs'). It also names a sibling as the required prior step, leaving nothing 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 readOnly, idempotent, non-destructive, so the safety floor is set; the description still adds real value by specifying that no charge occurs and by warning that a pending reservation or payment authorization must not be read as confirmation. The privacy constraint on the URL is additional operational context not present in the annotations. Return field meanings ('total', 'payment options') are named but their shape is not described.

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 short, front-loaded sentences with the resource and result fields first, then constraints. Minor redundancy: 'Keep the checkout URL private' repeats what the parameter schema already states.

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?

No output schema exists, so the description must convey the return surface, and it does by naming total, payment options and confirmation status. For a one-parameter read-only lookup with full annotation coverage, this is nearly sufficient; only the result format and any not-found/expired behavior are unaddressed.

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 the parameter's own description already covers exactness and privacy, so the description mostly restates it. It does add provenance ('returned by book_ride'), which is useful for constructing the value correctly, but no format or failure-mode guidance beyond that. 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 specific verb (read) and a concrete set of returned facts (current total, payment options, confirmation status) tied to a specific resource (the checkout_url from book_ride). The provenance 'returned by book_ride' and the disclaimer 'does not charge or change the booking' cleanly separate it from book_ride and complete_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?

Clearly establishes the trigger condition (use the exact URL produced by book_ride) and an explicit negative condition (this is not the tool that charges or modifies a booking). It also warns against inferring confirmation from pending states, which guides interpretation. It stops short of naming complete_booking as the alternative for actually finishing payment, so not a full 5.

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 substantial behavioral context beyond the annotations: the quote excludes extras and gratuity, geographic eligibility does not guarantee service, dates begin tomorrow in America/Los_Angeles, and no hold or payment is created. This is exactly the sort of side-effect and scope disclosure annotations alone (readOnlyHint=false, openWorldHint=true) cannot 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?

Purpose is front-loaded in the first sentence and every subsequent clause carries a real constraint. The middle sentence packs geography, eligibility caveat, and the date rule into one long run-on, which costs a little readability but no filler is present.

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 burden of describing what comes back, but it only says the price excludes extras and gratuity. It never states the response shape (fare amount, currency, itemization, quote validity/expiry), which is a meaningful gap for an estimation 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?

Goes well beyond the 67%-covered schema: it explains which endpoints must resolve to CA/NV and the Bay Area (applying to pickup_address and dropoff_address), the 1–6 passenger ceiling, the tomorrow-start date rule with timezone, and the conditional rule that hours applies only to hourly trips. These are business rules the schema cannot express.

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?

A specific verb ("Estimate") plus a specific resource ("Black Car Service SUV fares") scoped to a region and a set of ride types. The closing sentence ("No availability check, hold, reservation, or payment is performed") cleanly separates it from book_ride and check_ride_availability without needing to name them.

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 states the eligibility conditions for using the tool (CA/NV endpoints, at least one in the nine-county Bay Area, pickup from tomorrow) and, crucially, what it does NOT do (no availability check, hold, reservation, or payment), which implicitly routes the agent to check_ride_availability or book_ride. It stops short of naming those siblings as alternatives, so it falls short of a 5.

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