Fold Laundry

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

Annotations already declare idempotentHint=true and destructiveHint=true; the description adds real behavior beyond that — weekly pickup Orders auto-generate on the chosen day until term end, and the re-call no-op semantics. It does not explain why destructiveHint is set (what gets altered/consumed), leaving one gap.

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-loads the operation and required inputs, then layers precondition, side effect, and idempotency. Dense but every sentence carries a distinct fact; slightly long for a single tool but nothing is pure 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?

Covers precondition, required inputs, cross-tool constraint on pickup day, post-activation side effects, and idempotency — with no output schema present, the description fully explains the observable consequences an agent needs to reason about.

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, but the description adds meaning beyond the schema: the phone is for pickup-day reminders, and the pickup day must match a campus availablePickupDays value (a cross-tool constraint the schema only repeats). Dorm building/room purpose is left to 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 ('Activate a paid Semester Pass') and implicitly distinguishes itself from siblings like get_semester_pass and buy_semester_pass by scoping to the activation step. The parenthetical about PENDING_ACTIVATION status further pins down exactly what operation this is.

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?

Clear precondition: 'Only callable on a pass in PENDING_ACTIVATION status (i.e. payment has cleared)', and it routes the pickup day to list_campuses' availablePickupDays. It stops short of explicitly naming the prerequisite sibling (buy_semester_pass) or stating when-not to use it, so no explicit alternative naming.

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 the mutation profile (destructiveHint=true, idempotentHint=false); the description adds the state precondition and the response contents (new total and discount applied). It does not say whether an existing promo is overwritten, which matters for a destructive, non-idempotent call — that is the only real gap.

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, no waste: purpose first, then the eligibility precondition, then the return value. Every sentence carries information an agent needs.

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 covers the return shape itself (new total, discount applied) along with preconditions and inputs. For a three-parameter mutation, that is sufficient 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 coverage is 100%, so the baseline would be 3, but the description contradicts the schema: it says "Requires order code, email, and the promo code" while email is optional and only needed when the customer has no connected Fold account. That error could push an agent to demand an unnecessary parameter. The added promo-code length hint (4–12 alphanumeric) is useful but does not offset the inaccuracy.

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?

Specific verb + resource ("Apply a promo / discount code to an existing order") plus a state scope (DRAFT or SCHEDULED, before pickup). No sibling tool handles promo codes, so no differentiation is needed to disambiguate it from the list.

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?

Explicitly states the eligibility window (only DRAFT or SCHEDULED orders, before pickup) so the agent knows when the call will succeed and when it must not be attempted. No alternative tool exists for this capability, so the guidance is complete.

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=true and openWorldHint=true, so the bar is lower, yet the description adds real substance: 'This creates a real order', no card link/charge for hotel billing, monthly Folio placement, hotel contract pricing, and the $49.99 order minimum. What it omits is reversibility — nothing about cancellation, cutoff times, or what happens after scheduling, which matters for a destructive mutation.

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 prerequisite is front-loaded and every clause carries operational content, but the middle is a dense run-on of billing and pricing details that could be split into shorter statements. No filler, though density costs some scannability.

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 an 11-parameter, 7-required mutation with no output schema, the description covers authentication context, billing modes, pricing tiers, minimums, and return timing. Gaps remain around order lifecycle (cancellation/reschedule via siblings, what the response contains), which an agent would need before committing a destructive real order.

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 55% schema coverage the description does heavy lifting: it defines the default and business meaning of billTo (statement vs card link), the four returnPreference modes with timing and +$30 express pricing, and why guest contact fields are required even for hotel billing. It adds nothing for services (WASH_AND_FOLD/DRY_CLEANING/HANG_DRY) or notes, leaving some required parameters to 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 ('Schedules laundry pickup for a guest by room number at that hotel') and scopes it to a named audience (front-desk staff at a Fold partner hotel). It also implicitly separates itself from book_hotel_pickup by pointing to that sibling for guest-billed orders.

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 (login must belong to the hotel's Fold business account), lays out the billTo decision with consequences for each branch, and points to book_hotel_pickup as the alternative for guest-rate pricing. returnPreference values are explained with timing windows and surcharges, so the agent can choose correctly.

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

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

Goes well beyond the annotations: discloses that no Fold account is needed, that the card is NOT charged at scheduling time (only after intake), that the guest must visit the Stripe URL, that the server enforces cut-offs on its own clock, and that it will never silently add a surcharge or shift the day. This is exactly the mutation-safety context a destructiveHint tool 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-loads purpose, account requirement, and return values, then organizes pricing and tier rules under clear headers and bullets. It is long, and the return-tier block restates the schema's returnPreference description nearly verbatim, which is the main wasted payload.

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 11 parameters, no output schema, and a destructive mutation, the description covers everything an agent needs: the booking prerequisite (hotel Place ID from search_hotels, stated in schema), payment flow, what is returned (FHL code + Stripe URL), pricing/minimums, tier cut-offs, and retry behavior. The only residual gap is sibling differentiation, scored elsewhere.

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 lacks: how pricing interacts with services (wash & fold flat vs per-garment dry cleaning), the $49.99 minimum, the $9.99 hotel service charge, and which surcharges do/don't count toward the minimum. That informs real parameter choices, though the return-tier text largely duplicates the returnPreference schema 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 ('Schedule a laundry pickup for a hotel guest') plus a concrete side effect (creates an order, returns FHL tracking code + Stripe setup URL). However, a sibling named 'book_for_hotel_guest' exists and the description never distinguishes the two, leaving the agent to guess which hotel booking tool to call.

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 strong operational guidance for the return-time tiers (which to pick given drop-off time) and explicitly tells the agent how to handle server refusals (confirm the $30 express surcharge with the guest before retrying, fall back to next_day after noon). It does not address when to use this tool versus the near-identical book_for_hotel_guest sibling, so exclusivity is missing.

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?

Volunteers behavior well beyond the annotations: it creates a real order, delivery is next-evening only, invalid pickupWindow results in nothing being scheduled and returns the valid windows, and an idempotencyKey changes retry semantics. The idempotentHint=false annotation is consistent with the stated behavior (duplicates without a key), so 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?

Dense but front-loaded — the precondition and the 'real order' consequence come before the option details. A few clauses (access notes, gate code) are slightly packed, but no sentence 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?

For a 10-parameter, all-optional, destructive booking tool with no output schema, it covers defaults, failure mode, reuse semantics and delivery timing. Minor gaps: no mention of pricing/estimate confirmation, auth failure handling, or a pointer to reschedule_order/cancel_order after booking.

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 cross-parameter meaning the schema cannot: omitted addressId falls back to the default, sameAsLastOrder/sameAsOrderCode prefill service, address and window, and any explicitly passed value overrides the prefill. That override precedence is genuinely additive.

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 concrete verb and resource ('Schedules a pickup') and immediately scopes it to signed-in customers with a connected Fold account and saved address/card, which separates it from guest and hotel booking siblings. The title's '(signed in)' plus the account precondition make the target persona unmistakable.

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 clear preconditions (connected Fold account, saved address, market-valid window) and explains defaulting behavior and the sameAsLastOrder shortcut. It stops short of naming the alternatives (book_residential_pickup / book_hotel_pickup) or saying when a not-signed-in agent should route elsewhere, so exclusion guidance is 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?

Goes well beyond the annotations (destructiveHint=true, idempotentHint=false) by disclosing that a guest account is created without a password, that the card is not charged until after intake, the $39.99 minimum, and the exact return payload (FOLD-XXXXX order code plus Stripe setup URL). It also explains the retry-safe idempotencyKey behavior, which materially refines the idempotentHint=false signal.

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 purpose and eligibility, then behavior, then return values and cost. Every sentence carries distinct information — no repetition of the title or restatement of schema fields.

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 17-parameter mutation with no output schema, the description supplies the missing pieces an agent needs: what is created (guest account), what is returned (order code + Stripe URL), when money moves, the order minimum, and the service-area gate. Nothing critical to a correct first call is absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description adds real meaning on top by clarifying that zipCode must be a Fold-served ZIP (check_service_zip first) and that pickupWindow labels come from that tool. It does not add guidance for the many optional fields (notes, deliveryNotes, line2), leaving those to 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 the specific verb and resource (schedule a laundry pickup) and immediately scopes it to residential/non-hotel addresses, explicitly including Airbnb and vacation rentals. This cleanly separates it from the hotel-pickup siblings without needing 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?

"For any non-hotel address in the service area" is an explicit when-to-use plus an implicit when-not (hotels), and it routes the agent to check_service_zip for ZIP validation and to pickupWindows/deliveryWindows as the source of window labels. Alternatives and preconditions are both named.

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 the annotations: it returns a Stripe Checkout URL that the purchaser must visit, the student receives a separate activation email, and pricing varies by campus/term with priceCents echoed. It does not explain why destructiveHint is set or any auth/permission requirements, keeping 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?

Four sentences, front-loaded with the action and scope, each contributing distinct information (campuses, purchaser/student roles, checkout flow, pricing source). Slightly dense but 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 an 11-parameter purchase tool with no output schema, it covers the end-to-end flow and what is returned (checkout URL, priceCents echo) plus the list_campuses dependency. Minor gaps remain around failure/retry behavior and the significance of the destructive annotation.

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 100% schema coverage the baseline is 3, but the description adds meaningful meaning by explaining the two-party model (purchaser vs student) and the list_campuses dependency for campus/term IDs, which helps an agent map its inputs correctly.

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 ('Buy a Fold Semester Pass') and immediately scopes it to four named campuses and a college-student use case. It clearly distinguishes itself from siblings like get_semester_pass and activate_semester_pass by describing the purchase-and-checkout action.

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?

Explicitly routes the agent to list_campuses for campusId, termId, and pricing, and clarifies the purchaser-vs-student split. However, it never states when NOT to use this tool or how it differs from adjacent actions such as apply_promo_code or book_my_pickup, so it lacks explicit 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?

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds real context beyond them: the pickup cutoff that makes the call fail, the fallback return flow, and the reassurance that the saved card is not charged. It also states the returned state, which matters for a mutation with no 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?

Three tight sentences, with the core action and the blocking precondition front-loaded. No filler; each clause carries a distinct operational fact.

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 covers the return value ('new state', card-not-charged confirmation) and the failure path, which is what an agent needs. The one gap is the slight mismatch over whether email is mandatory, left unresolved between description and 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?

Schema coverage is 100%, so the schema already documents all three parameters, and the baseline is 3. The description's 'requires the order code and the email' mildly conflicts with the schema, where only orderCode is required and email is waived for connected accounts — a nuance an agent could misread rather than one the description clarifies.

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 ('Cancel a Fold order') with no ambiguity, and is clearly separable from siblings like reschedule_order, rate_order and list_my_orders. 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?

Explicitly bounds usage: allowed only before driver pickup, and after pickup the correct path is a return plus a support call. This names both the precondition and the alternative when the precondition fails, leaving little 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 safety profile (readOnly, idempotent, non-destructive). The description adds value beyond them by disclosing the return contents (availability, market, pickup windows) and the downstream precondition on book_residential_pickup, which is precisely the behavioral context an agent needs before chaining calls.

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 compact sentences, front-loaded with the purpose and followed by the output shape and the sibling dependency. Every sentence earns its place with no redundancy.

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?

There is no output schema, so the description's enumeration of the return values is essential and present. With the input format handled in the schema and the downstream booking constraint stated, an agent has everything needed to call and chain this tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single zipCode parameter is fully documented there, including ZIP+4 handling and extraction behavior. The description adds no parameter-level 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 (check Fold's ZIP coverage) and enumerates the return payload: service availability, market name (LA/SF), and pickup window options. This is clearly distinguishable from siblings like get_service_info or book_residential_pickup.

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?

Establishes a concrete usage relationship: the pickup window options it returns 'can be passed to book_residential_pickup' and that tool 'only accepts ZIPs this tool reports as served', implying this is a pre-flight gate. It does not explicitly exclude or compare against any other sibling, so it falls short of a full when/when-not 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 (destructive/openWorld/non-idempotent) by disclosing that the card is charged immediately, the plan auto-renews, cancellation runs to period end with no refund, and the specific failure mode when no card is on file. This is exactly the behavioral context a billing mutation tool 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-loads purpose then layers prerequisites, pricing, billing/renewal terms, and pre-call instructions. Dense and every sentence is load-bearing, though the three-plan pricing would scan better as a list and the paragraph is long.

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 5-param billing mutation with no output schema and rich annotations, the description covers prerequisites, charge/renewal behavior, cancellation, promo rules, and the error return path. An agent has everything needed to call it correctly and safely.

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, but the description adds meaning the schema lacks: exact per-plan pricing, the annual '1 month free' framing, and promoCode constraints (WELCOME is MONTHLY-only and rejected on ANNUAL). It notably omits that email is optional/conditional in the schema versus its stated identity role.

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: 'Enroll a Fold customer in Fold Club.' It clearly distinguishes itself from sibling enrollment/purchase tools like activate_semester_pass or subscribe_order_updates by naming the Fold Club product and its three plan codes.

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 strong preconditions (recent order code + email identity, saved card required, error path to /app/payment) and an explicit pre-call obligation to confirm charge, auto-renewal, cancellation, and obtain consent. It stops short of naming when-not-to-use or alternative tools beyond the track_order auth-model reference.

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=false, so the safety profile is covered. The description still adds real value by disclosing the conditional no-data behavior for non-business logins, which an agent needs in order to interpret an empty response, though it says nothing about auth/permission failure modes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero preamble, with the eligibility constraint front-loaded before the payload enumeration. The second sentence is a long comma-heavy list but every element is a distinct returned field, so the length is earned.

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 returns and does so field by field, and annotations cover the safety profile. For a zero-parameter read-only summary tool, an agent has everything needed to call it and interpret the result.

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 takes zero parameters, so the baseline is 4. The description correctly implies a fully implicit, account-scoped call with nothing to configure.

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 resource (the connected Fold business account) and enumerates the exact contents it summarizes: deliveries, statement totals, payments, balance, due date, invoice link, scheduled days. It is clear what the tool returns, but it never names the sibling it is distinguished from, so an agent must infer the split against get_my_account.

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 a concrete precondition and eligibility rule: the connected account must belong to a Fold business (B2B) login such as a hotel, office, or property-management company, and data is returned only in that case. It stops short of the explicit alternative ('use get_my_account for personal accounts'), so routing is implied rather than directed.

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

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

Annotations already mark this read-only and idempotent, yet the description still adds real behavior: no hidden fees, the $39.99 minimum billing floor, ~10% accuracy versus the intake weight charge, and that unrecognized garment names are returned in unmatchedItems rather than priced. These are exactly the caveats an agent needs to set expectations when quoting a price.

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 purpose then progressively adds constraints, minimum, accuracy caveat, and the residential/hotel distinction — a logical order with little waste. It runs long for a single paragraph and repeats the residential-pricing point in a way that 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?

With no output schema, the description carries the return shape itself (line items, subtotal, total in cents and USD) and covers the minimum-charge and accuracy edge cases. Nothing material is missing for an agent to call it and interpret the result.

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 earns a step up by framing the two input modes (bags vs. pounds of wash & fold) and by supplying concrete garment phrasing examples like '2-piece suit'. It doesn't restate the 10-bag/200-lb caps or the deprecated tier field, but the schema covers those.

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

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

The description opens with a specific verb and resource — 'Calculate an itemized price estimate' — and immediately scopes it to wash & fold bags/pounds plus plain-word dry-cleaning garments. That framing separates it from get_pricing (rate lookup) and the book_* siblings (scheduling) without any 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?

'Answers how much will it cost before scheduling' states the trigger condition explicitly, and the closing sentence routes hotel guest orders elsewhere ('see get_pricing hotelGuestRates'), so the exclusions and the alternative are both named.

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 establish readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds that this is an informational program overview with pricing-tier structure and onboarding steps, which is useful context beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences: content scope first, then usage triggers. The parenthetical pricing list is slightly dense but every clause earns its place; no padding or repetition of the title.

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 the return content, and it does so (turnover mechanics, pricing by host size, getting started). Nothing needed to call this zero-parameter read 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 tool takes zero parameters and schema coverage is 100%, so the baseline is 4. There is nothing for the description to add on parameter 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 ('Returns') and a specific resource (Fold's linen-turnover program for STR hosts), plus the concrete content scope: same-day turnovers, pricing tiers, onboarding. It clearly sets itself apart from generic siblings like get_pricing or get_service_info by domain, though it does not name an alternative outright.

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 second sentence gives explicit trigger conditions: hosting a short-term rental, managing STR properties, or asking about linen/turnover service between guests. No exclusions or named alternatives are provided, so it stops 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.

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds what annotations cannot: a sign-in requirement and a prereq of a connected Fold account. It also discloses the sensitivity of the payload (gate codes, access notes, card-on-file status, credit balance) and cross-references that book_my_pickup consumes these saved 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?

Three sentences, front-loaded with the gating condition, then the no-auth alternatives, then the return contents. The long enumeration in sentence three is dense but every item is a distinct field an agent may need to reason about, so 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 zero parameters and no output schema, the description carries the full burden of explaining return values and does so explicitly, while also covering auth prerequisites and downstream tool relationships. Nothing an agent needs before invoking it is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes no parameters, so the schema leaves nothing to explain and the baseline of 4 applies. The description correctly spends no words on input syntax and instead describes what comes back.

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 (retrieving the caller's own Fold account) and enumerates exactly what that account record contains — addresses, card on file, credit balance, membership, care preferences, recurring pickups. It also explicitly separates itself from guest/no-auth siblings (get_pricing, check_service_zip, get_estimate, book_residential_pickup), so an agent can route 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?

Leads with an explicit gate — 'Only call this when the customer asks about their own Fold account, saved details or orders' — and names the sibling alternatives for the cases that do NOT require it. This is a complete when-to-use / when-not-to-use / alternative mapping rather than an implied one.

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, and destructiveHint=false, so the safety profile is covered. The description adds useful context (scope is all services, prices are in USD), but says nothing about how current 'current' is, whether rates vary by campus/location, or the shape of the response.

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 clauses, front-loaded with what is returned, then the sibling routing, then the currency detail. No padding and every sentence carries distinct 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 zero-param, zero-annotation-risk read tool with no output schema, the description covers return content and currency unit, which is most of what an agent needs. It leaves minor gaps (granularity of the rate card, whether rates are location-dependent) but is adequate.

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 takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The currency note is a minor extra detail rather than parameter guidance.

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?

Specific verb+resource ('Returns current Fold pricing for all services') with clear scope ('all services'). It also explicitly distinguishes itself from the sibling get_estimate, which is the closest lookalike in the tool list.

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?

Explicitly states the use case ('A quick rate-card overview') and routes the agent elsewhere for the adjacent need ('itemized totals for a specific order come from get_estimate'). This is exactly the when-to-use vs alternative guidance the dimension asks for.

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=false, so the safety profile is covered. The description adds real value beyond them: the pre-intake caveat that items are unknown and the total is estimated, plus the two auth modes (connected account vs. order code + scheduling email).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences with no filler: the first enumerates the receipt contents, the second front-loads the state caveat and auth modes. Every clause carries information an agent needs.

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 compensates by listing returned fields, and it covers both the provisional pre-intake state and the auth paths. Minor gaps remain, such as error behavior for unknown order codes, but nothing critical is missing for a read-only lookup.

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 50% and orderCode has no schema description, but the description explains the relationship between the two parameters: use the connected account alone, or order code plus the email used when scheduling. That resolves the conditional requirement for email better than the schema's terse note.

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

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

The description names a specific resource and enumerates its contents (items, subtotal, fees, discounts, credits, tax, total, payment status), so an agent knows exactly what it returns. It also implicitly differentiates itself from get_estimate by noting the total is only an estimate before intake.

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 line about pre-intake state gives useful context for when the receipt is provisional, and the auth sentence tells the agent how to call it. However, it never explicitly routes the agent away from siblings like get_estimate or list_my_orders, so when-to-use is only implied.

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, and non-destructive, so safety is covered. The description adds genuine value beyond them: it discloses the return payload (code, formatted share link, stats) and the business rule that both sides receive $25 credit after the friend's first pickup.

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-loads the purpose, then usage, then return shape, then the incentive rule. Every sentence carries information, though the final incentive sentence is nice-to-have rather than essential for 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?

For a single-parameter read tool with no output schema, the description supplies everything needed: what it returns, the link format, and the surrounding business rule. Nothing an agent requires 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?

There is a single parameter with 100% schema description coverage, so the schema fully documents 'email'. The description adds no format, casing, or matching guidance beyond the schema, which is the expected baseline for this coverage level.

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 ('Look up a customer's Fold referral code and share link') that an agent can distinguish from every sibling, none of which deal with referrals. The scope is precise and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives two concrete triggering conditions: the customer wants to share Fold with a friend, or wants to check how many people they've referred. It does not name alternatives, but no sibling tool overlaps with referral lookup, so there is little to exclude.

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 safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds genuinely new behavior detail by naming the returned fields (status, campus, term, dorm details if claimed, pickup readiness) and the conditional 'if claimed' caveat — useful given there is no 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?

Two sentences, both earning their place: the first states the operation and its return payload, the second supplies the user-intent triggers. No redundancy or 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 usefully enumerates the returned fields and notes the conditional dorm-details case, which is the main unknown for an agent. Minor gaps remain around error behavior for an invalid or unknown code, but nothing essential to calling it 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?

With one parameter at 100% schema description coverage, the schema already documents the code format and case-insensitivity. The description restates the FSP-XXXXXX pattern but adds no syntax, validation, or edge-case detail beyond it, 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 ('Look up a Fold Semester Pass by code') and enumerates what the response contains. It is clearly a read/lookup operation, though it does not explicitly name the sibling it is distinct from (e.g. activate_semester_pass or buy_semester_pass).

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 concrete triggers in the form of example user questions ('is my pass active yet?', 'what's the status of FSP-XXXXXX?'), which gives clear usage context. It stops short of stating when to prefer this over activate_semester_pass or buy_semester_pass.

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 non-destructive, so the safety profile is covered. The description adds only a list of returned content types, with no behavioral detail such as caching, auth requirements, or freshness of policies.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with the return contents front-loaded and the usage cue second; every clause carries information and nothing is padding.

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

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

With no output schema and no parameters, the description sensibly enumerates what comes back, which is the key missing piece. 'Key policies' is left vague, but the overall picture is sufficient for a simple read 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 takes zero parameters, so there is nothing for the description to clarify beyond what the schema states. Baseline of 4 applies for a parameterless tool.

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

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

States a specific verb ('Returns') and enumerates the resource contents (service area, hours, contact info, policies), which is more than a bare restatement of the title. It does not, however, differentiate itself from overlapping siblings such as check_service_zip or list_campuses.

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 a concrete usage trigger ('when the user asks "where do you serve?" or for a general overview'), which is better than implied usage. It stops short of naming alternatives or when-not conditions, leaving potential overlap with check_service_zip unresolved.

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=false, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value beyond that: the error behavior when the ZIP is already served, and the asynchronous side effect that Fold emails the user if service starts there. It does not describe the response shape, but with no output schema that is a minor gap.

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, no filler, and the core action plus its scoping rule are front-loaded before the error case and consent note. Every sentence carries distinct 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 3-parameter write tool with no output schema, the description covers the action, the guard condition, the error case, the downstream email side effect, and a consent policy. Only the handling of the optional firstName and any pagination/response detail are unspecified, which is acceptable at this complexity.

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 email, zipCode, and firstName are already documented in the schema. The description reinforces the ZIP constraint ('5-digit US ZIP' semantics appear in the schema) and adds a consent requirement for email, but contributes no syntax or format detail the schema lacks. 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 ('Adds an email address to Fold's waitlist') with an explicit scope constraint ('for a ZIP code Fold doesn't serve yet'). That scope constraint is exactly what separates it from the other ZIP/service siblings, so an agent can identify 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 a clear positive condition ('Only for unserved ZIPs') and spells out the failure mode for the wrong condition (served ZIPs return an error). It also adds a consent rule ('Use the person's own email with their permission'). It stops short of naming check_service_zip as the prerequisite lookup, so the alternative is implied rather than named.

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=false, so the safety profile is covered. The description adds real behavioral detail beyond them: a fixed, small result set (four campuses), the exact fields returned (terms, pickup day, weekly/bi-weekly pricing), and that prices are USD. It does not discuss caching or rate limits, but the added context is substantive.

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 purpose, then the concrete return shape, then the downstream dependency and currency note. Every sentence carries information, though the parenthetical marketing aside about 'prepaid weekly laundry pickup for college students' is the one slightly expendable clause.

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 and no parameters, the description carries the full burden and discharges it: it names the cardinality, the fields, the pricing cadences, and the currency. An agent has everything needed to call it and to use its results in buy_semester_pass.

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 takes no parameters, so there is nothing for the description to disambiguate; per the rubric this is the baseline 4. The description correctly does not invent parameter guidance and instead documents the identifiers (campusId, termId) that downstream tools consume.

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 ('List the campuses where Fold offers a Semester Pass') and scopes it with parenthetical context. It is unambiguous and distinguishable from every sibling, since no other tool enumerates campuses.

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?

Explicitly ties itself to buy_semester_pass by noting that tool 'takes a campusId and termId from this list', which tells an agent when this call is a prerequisite. It stops short of stating exclusions or alternatives (e.g. what to do for non-campus laundry), so it falls just below a full when/when-not 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?

Annotations only declare the safe-read profile; the description adds the cap (max 10), the ordering, the privacy rule that order codes are never revealed from an email alone, and the account-connection dependency that changes the result shape. These are real behavioral constraints 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?

Purpose and scope lead, alternatives follow — correct ordering and no filler. The run-on em-dash clauses make it denser and harder to scan than it needs to be for a one-parameter read tool.

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 no output schema, the description sketches both possible return shapes (codes/status/dates/address vs. a bare count), covers the conditional branch, and names the fallback path. Nothing an agent needs 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 coverage is 100% and the email field is already described there, so the baseline is 3; the description adds the privacy rationale for why email yields only a count, which meaningfully explains the parameter's limited effect rather than merely restating it.

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?

Names a specific verb and resource ('List the customer's recent Fold orders'), fixes the scope ('most recent first, max 10'), and explicitly contrasts itself with the track_order sibling. An agent can distinguish it from track_order and get_receipt 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?

Gives explicit routing: use this tool to enumerate recent orders, otherwise use the order code with track_order, or ask the customer to connect Fold. It also states the precondition (connected vs. unconnected account) that changes what the tool is good for.

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: re-rating overwrites the earlier rating, and the response branches — a public review link for high ratings, a pointer to report_issue for low ones. Annotations already cover idempotency and non-destructiveness, and the description corroborates rather than contradicts them; no failure/validation behavior is 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?

Three tight sentences, front-loaded with the action and scale, then auth, then response behavior. Slightly dense in the final sentence but every clause carries information an agent would otherwise have to guess.

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 4-parameter tool with no output schema, the description covers inputs, auth, and the salient conditional response content. Missing only error/validation behavior (e.g., what happens for a non-delivered or unknown order).

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 only 50% schema coverage (orderCode and stars are undescribed), the description compensates by tying orderCode to 'the email used when scheduling' and stating the 1–5 star scale. It doesn't clarify why email is optional in the connected-account case beyond the schema's own note.

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 (records a 1–5 star rating plus optional comment) and scopes it precisely to a 'delivered Fold order'. It also implicitly separates itself from report_issue by casting that sibling as the path for service problems rather than feedback.

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 clear preconditions (order must be delivered) and two authentication paths — connected account, or orderCode + the email used at scheduling. It also routes low-rating cases toward report_issue, though it does not explicitly state when to prefer report_issue over rating (e.g., rating is still recorded alongside a complaint).

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 useful context beyond annotations: a specialist follows up by text or email and re-cleans are free. However, annotations declare destructiveHint=true and idempotentHint=false, and the description does not explain what is destructive, whether case submission can be undone, or what happens after submission. With annotations carrying the safety profile, this is adequate but not rich.

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 purpose is front-loaded, followed by eligibility, follow-up expectations, and input guidance. Every sentence adds actionable information without repetition or waste.

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 support-case creation tool with no output schema, the description covers who can submit, the authentication modes, the issue categories, follow-up behavior, and free re-cleans. The main remaining gap is guidance on preferredResolution and any explicit disclosure of the destructive/non-idempotent behavior already noted in annotations.

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 60%. The description usefully maps the issueType enum to natural-language scenarios and clarifies the email/account access condition. It also adds 'in the customer's words' guidance for the description field, but it never mentions the optional preferredResolution parameter, leaving part of the schema unexplained.

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

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

The description opens with a specific verb and resource: 'Open a support case for an order,' then immediately enumerates the supported problem categories. This makes it clearly distinct from siblings like cancel_order, reschedule_order, and rate_order.

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 clear usage context by listing issue scenarios and explaining the two access modes: a connected Fold account or order code plus scheduling email. It does not explicitly name when to choose this tool over alternatives such as cancel_order or reschedule_order, but the context is strong enough for selection.

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=true and idempotentHint=true, and the description earns credit by disclosing the state-machine gates that determine whether the mutation is even legal — information an agent cannot get from the annotations or schema. It does not mention possible fees, loss of the original slot, or any confirmation/irreversibility detail, which is a meaningful gap for a destructive operation.

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 sentences, front-loaded with the action and followed by the eligibility gates and call requirements in order of decision-making. No filler or restatement of the title.

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 no output schema, the description covers what changes, when it is permitted, and what inputs are mandatory, which is enough to call it correctly. What remains unstated is the outcome surface — fees, whether the old window is released, and what a successful response contains.

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 baseline is 3; the description adds a genuine cross-parameter constraint not encoded in the schema ('Pass at least one leg', since only orderCode is required) and restates the email requirement in conditional form. That extra validation logic is real value beyond the field-level descriptions.

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 ('Move') plus the exact resources affected (pickup date/window, delivery date/window, or both) on an existing order. This cleanly separates it from cancel_order, track_order, and the booking tools that create rather than modify orders.

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 concrete eligibility rules per leg: pickup only in SCHEDULED or PICKUP_ASSIGNED, delivery any time before the driver is en route, plus the identity requirement ('Requires order code + email') and 'Pass at least one leg.' It lacks explicit routing to an alternative when rescheduling is no longer permitted (e.g. cancel_order or report_issue), so it stops just 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.

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

Far exceeds the annotations: it discloses that confirm=false previews every item and flags problems while confirm=true creates real orders charged to the card on file, and notes that returns are evening-only with same-day turnovers depending on a second linen set. Those are exactly the consequences an agent needs before triggering a destructive, open-world write that carries destructiveHint=true and idempotentHint=false.

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 prerequisites and eligibility, then moves through item shape, confirm semantics, and the evening-return caveat in a tight sequence. Some sentences re-encode schema fields, but every sentence carries operational information rather than filler.

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

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

For a destructive, open-world batch write with no output schema, the description covers the prerequisites, the preview-first safety path, the charging consequence, and what the preview response contains (per-item problems flagged). An agent has enough to call this correctly without guessing.

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%, so the schema already documents addressId, checkoutDate, nextCheckInDate default, notes, and confirm. The description restates the same semantics (confirm preview-vs-schedule, nextCheckInDate defaults to the day after checkout) and adds only the "up to 10" cap, which maxItems already encodes. Useful corroboration but little net-new meaning.

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: schedules linen pickups for several guest checkouts at once across the host's saved addresses, capped at 10. It names the sibling whose rules it shares (book_my_pickup) and the sibling that supplies addressId (get_my_account), so an agent can separate it from single-pickup booking tools 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 audience gate ("For short-term-rental hosts") and prerequisite ("Requires the connected Fold account"), plus the routing hint that addressId comes from get_my_account and behavior matches book_my_pickup. It lacks an explicit when-not clause (e.g. use book_my_pickup for a single property), but the multi-checkout framing makes the split reasonably clear.

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, openWorldHint and destructiveHint=false, so safety is covered. The description adds genuinely useful behavior beyond that: a hard result cap of 6, the fields returned (place IDs and addresses), and the geographic coverage boundary. It does not mention auth requirements or what happens with zero matches, 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?

Three short sentences, each load-bearing: purpose+scope, output shape, and the dependency link to the booking tool. The most decision-relevant constraint (service area) 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?

There is no output schema, so the description carries the return-value burden — and it does, specifying count limit and the two fields returned. Combined with 100% parameter coverage and full annotations, an agent has everything needed to call this correctly and use its results.

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 single parameter is fully documented in the schema, including the 2-character minimum and format examples. The description's phrasing 'by name' slightly narrows the schema's stated 'Hotel name or address' input, adding no new syntax or format detail, so baseline 3 applies.

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

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

States a specific verb (Search) and resource (hotel) plus the scoping constraint (within Fold service areas, Los Angeles and San Francisco) and the result cap (up to 6). It also names the downstream consumer of its output (book_hotel_pickup via hotelPlaceIds), so an agent can distinguish it from the booking sibling immediately.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states that book_hotel_pickup requires one of the hotelPlaceIds returned here, which tells the agent when this tool must be called (as a prerequisite step before booking). The geographic limitation is also surfaced as an implicit exclusion — queries outside LA/SF will not yield usable IDs.

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=true and non-idempotent, so the safety profile is covered; the description adds genuinely new behavior: pickups are scheduled a few days ahead, the customer can skip or pause any time, and it produces real recurring orders. What's missing is any statement about billing/recurring charges despite the card requirement, which matters for a destructive recurring commitment.

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 sentences, front-loaded with the prerequisite before the action, with zero redundant restatement of the schema. The closing 'This creates real recurring orders' is slightly redundant with 'standing pickup' but functions as a deliberate warning, so it earns most of 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 3-parameter tool with no output schema and annotations covering the safety profile, the description covers prerequisite, action, scope (default address), lead time, and post-creation control. Gaps remain around what the tool returns and whether setup triggers an immediate charge, but nothing essential for invoking it correctly is absent.

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%, including enum defaults for service and frequency, so the schema carries the parameter burden and a 3 is the baseline. The description adds only 'e.g. every Tuesday', which lightly illustrates daysOfWeek but gives no guidance on combining multiple days with frequency.

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 a standing pickup ... at the customer's default address', with the recurring nature made explicit via 'standing' and 'real recurring orders'. This implicitly separates it from one-off siblings like book_my_pickup and from update_recurring_pickup, but neither sibling is named, so the differentiation is left to inference.

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 a concrete precondition — the connected Fold account must have a saved address and card — which is exactly the kind of gate an agent needs before calling. It also implies the use case ('every Tuesday', standing arrangement) but never explicitly says when to prefer this over book_my_pickup or update_recurring_pickup, so no exclusions are provided.

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?

Far exceeds what annotations provide: it discloses the exact event payload, the Fold-Signature header format with the HMAC construction over "t.body", the fact that a secret is returned, the per-order cap of 3, and both auth modes. Annotations flag this as a non-readOnly, openWorld, destructive, idempotent operation, and the description supplies the operational details an agent needs to call 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 capability and precondition, then structured into labeled Payload and Header segments. Dense but nearly every clause carries information; the trailing auth-and-limit sentence is slightly compressed but not wasteful.

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 compensates by describing both the webhook payload and the fact that a signing secret is returned. Remaining gaps are minor: it does not say how to remove a subscription or what happens when re-registering the same URL.

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?

Adds meaning beyond the 67%-covered schema: email is explained as the address used when scheduling and only needed when there is no connected account, and webhookUrl's https requirement plus the per-order limit of 3 clarify the registration constraints. orderCode is left implicit (it scopes the subscription to one order), but the surrounding text makes that clear.

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 — registers an https URL that Fold POSTs to on every status change of one order — and enumerates the triggering events (picked up, washing, out for delivery, delivered). An agent can immediately tell this is a webhook subscription tool, not a notification-preference or tracking tool.

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 a clear precondition ("For agents that can receive webhooks"), two valid authentication paths (connected account, or order code + scheduling email), and a hard constraint (max 3 per order). It does not, however, distinguish itself from the obvious alternative update_notification_preferences, which an agent could confuse it with for notification setup.

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=true and idempotent=true, so the safety profile is covered. The description goes further and enumerates what comes back (current state, milestone timeline, scheduled dates, itemized items, proof-of-delivery photo URL), which is more than the annotations provide. It does not mention what happens when an order is not found, which keeps it from 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?

Three sentences, front-loaded with the purpose before prerequisites and return contents; nothing is padding. Slightly dense in the middle sentence but still tight.

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 compensates by describing the returned fields, and it covers the optional-parameter edge case. The main missing piece is error behavior when no matching order exists.

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 both properties already document the email-optional-when-connected rule and the FOLD-/FHL- code formats. The description largely restates that, adding the concrete 'FOLD-XXXXXX or FHL-XXXXXX' shape and 'omit it to get their most recent order', but no new semantics beyond the schema. 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 ('Check the status of any Fold order') and immediately scopes it as spanning both hotel-guest and residential pickups, which separates it from the booking and reschedule siblings. An agent can tell what this does 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 clear prerequisites (order code + scheduling email, or neither when the Fold account is connected), which is real usage guidance. However, it never routes the agent away from plausible alternatives such as list_my_orders or subscribe_order_updates, so the when-not-to-use case is only implied.

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: it explains the real-world consequence ('Drivers see these on every pickup and delivery there'), which justifies destructiveHint=true, and clarifies the destructive mechanic (empty string clears a field) and the idempotent overwrite semantics of saving. It also discloses the auth prerequisite (connected account). This is exactly the extra context annotations 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-loads the prerequisite and core action, then packs field meanings, visibility consequence, default behavior, and the clear-field convention into compact clauses with zero filler. Every sentence carries information an agent needs to call the tool correctly.

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 an all-optional mutation tool with no output schema and annotations covering safety, the description supplies the missing pieces: auth requirement, what gets persisted, who consumes it, default-address handling, and how to clear values. Nothing needed for a correct invocation is absent.

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?

Adds meaning the schema lacks: gateCode is a gate/building/lockbox code, howToGetIn covers buzzer/doorman/side entrance, and addressId defaults when omitted. whereToLeaveBag is left to its name and max-length schema entry, and the 40/200/500 char limits remain schema-only, so it falls just short of full coverage of a 75%-documented 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 concrete verb and resource: it saves how a driver gets in at one of the customer's saved addresses, and enumerates the exact fields being written (gateCode, howToGetIn, whereToLeaveBag). No sibling tool covers this resource, so an agent can distinguish it immediately from update_care_preferences or update_recurring_pickup.

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 explicit operational guidance: 'Omit addressId for the default address' and 'Pass an empty string to clear a field', plus the prerequisite that a connected Fold account is required. It stops short of stating when NOT to use it or naming an alternative tool, so it is clear context without explicit 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?

Adds substantial context beyond the annotations: it discloses the account requirement, that preferences apply to all future orders (a persistent side-effect), the partial-update semantics ('only the fields you pass change'), the empty-string clearing behavior, and a max-length constraint. These details are exactly what the annotation set doesn't 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?

Front-loads the account requirement and the core purpose, then details each parameter. Dense but well-organized; slightly long due to inline enum explanations, though these earn their place given the low schema coverage.

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?

Complete for a persistent, partial-update mutation tool: it covers account prerequisites, persistence scope, per-field semantics, clearing behavior, and a length limit. With no output schema and only 33% param coverage, the description fills all the gaps an agent would need.

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 33%, so the description must compensate, and it does: it defines what each enum value means semantically (eco_unscented default, mixed = colors cold/whites warm) and explains the specialInstructions free-text and clearing behavior. This adds meaning well beyond the bare enum lists 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 and resource (saves standing laundry preferences for every future order) with the exact fields it controls. This clearly distinguishes it from the other 'update_' siblings (update_access_info, update_recurring_pickup), which cover different resources.

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 this tool affects every future order (standing preferences vs. one-off), which implicitly frames usage, but does not explicitly say when to use it versus alternatives or state prerequisites beyond 'requires the connected Fold account'.

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 annotations (idempotent, non-destructive write), it discloses an auth precondition, partial-update semantics ('Only the fields passed change'), the side effect that turning texts off routes updates to email, and the return behavior. This is exactly the added context annotations 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?

Dense but every clause earns its place, and the two settings are front-loaded as distinct toggles. The nested parentheticals make it slightly harder to scan than an ideal layout, keeping it from 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?

With no output schema, the description explicitly states 'Returns the resulting settings', and it covers auth, patch semantics, and side effects for a simple two-boolean toggle. Nothing an agent needs to invoke this 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: orderTexts is elaborated with the specific events (picked up, out for delivery, delivered) and the email-fallback consequence. Both boolean flags are given behavioral context beyond the terse schema text.

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 action (turning order-status texts and marketing emails on/off) on a named resource (Fold notification preferences), and enumerates the three order-status events controlled. It distinguishes its two channels from each other, but never differentiates itself from sibling tools like subscribe_order_updates, so it falls 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?

It gives one prerequisite ('Requires the connected Fold account') but offers no explicit when-to-use guidance and never names an alternative such as subscribe_order_updates. Usage is only implied by what the toggles do.

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=false, idempotentHint=true, and destructiveHint=true, so the safety profile is covered. The description adds the connected-account auth requirement and the pauseUntil semantics ('omit to pause until resumed'), which is useful context, but it never spells out what cancel actually destroys or whether it is recoverable — the destructive behavior is left entirely to the hint.

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?

A single compact sentence that front-loads the prerequisite before listing the actions. Every clause earns its place, with no redundancy against the schema or title.

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 three-parameter mutation tool with no output schema, the description covers the actions, the required account context, the ID source, and the pause date semantics. The remaining gap is the consequence of cancel, which the destructiveHint annotation partially covers.

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 33% (recurringId is undocumented), so the description carries real weight: it explains the pauseUntil date format and the 'omit to resume' behavior, and tells the agent that recurringId comes from get_my_account. It adds meaning beyond the bare enum and schema types, though the recurringId format itself remains unstated.

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

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

The description names a specific verb set (pause/resume/cancel) and resource (recurring pickup), matching the title. It is clear what the tool does, though it never explicitly distinguishes itself from the sibling set_recurring_pickup, leaving the agent to infer that this one mutates an existing recurring pickup rather than creating one.

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?

'Requires the connected Fold account' states a prerequisite, and 'recurringId from get_my_account' tells the agent where the ID comes from, which is genuine routing guidance. However, it never says when to choose this tool over set_recurring_pickup, cancel_order, or reschedule_order, so the usage context is only implied.

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