Surfing Dog Inbox

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

Annotations already declare non-destructive and idempotent, so the description focuses on what those hints cannot convey: this is a binding commitment on the person, a stale offer_id returns 409 offer_changed with the current offer, and an unfulfillable change is routed to a human (passed_on) with the agreed terms standing. That is meaningful consequence disclosure beyond the structured fields, though the retry/idempotency nuance is left to the 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?

Front-loaded with the core action and the four accepted offer types before any preconditions, which is the right ordering. The second sentence is heavily nested (consent, terms_sha source, offer_id, stale-offer behavior) and takes real effort to unpack, costing a point, but every clause carries 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?

With no output schema and a binding mutation over 7 parameters, the description covers the outcomes an agent most needs: nothing booked without terms_sha, 409 on a replaced offer, passed_on for unfulfillable changes, and the linked confirmed booking/order result. It does not describe what the returned terms look like or the shape of a successful response, a minor gap.

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

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

Schema coverage is 86%, so the baseline is 3, but the description adds real sequencing semantics the schema does not: terms_sha must come from get_item_status and must only be sent after explicit consent to offer.human, and offer_id ties the answer to a specific offer version. It also names what happens without terms_sha, which is behavior the parameter docs alone do not state.

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 (accept) and enumerates exactly what kind of offer is being accepted: a proposed time, a quote, changes to an order, or a change to a confirmed booking/order. It also flags the special case (offer.kind change) so the agent knows the promise is being moved, not a new promise created. Clearly distinct from decline_offer and make_offer in the sibling 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?

Gives a strong conditional: send terms_sha only after the person said yes to offer.human, and states that sending nothing returns the terms to show them. It also explains the fallback path when a change can no longer be made online (passed_on). It never explicitly names decline_offer or cancel_item as the alternative action, so guidance is clear but not exhaustive.

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 idempotentHint=true and destructiveHint=false, and the description reinforces this with 'Acknowledging twice is harmless.' Beyond that it discloses non-obvious behavior: the instance verifies the counter-signature against the carried key and persists it, and the cryptographic contract (header/payload shape, SHA-256 of the receipt JWS). It does not describe failure modes or what verification rejection looks like.

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 key action and effect are front-loaded in the first clause, followed by the eligible receipt kinds and then the protocol mechanics. It is dense and packed into essentially one long sentence chain, but every clause carries information; little is wasted.

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 crypto-heavy, 7-parameter, no-output-schema tool, the description supplies the signing recipe, the verification/storage behavior, and an idempotency guarantee. Missing only error/failure handling and guidance on which credential parameter to prefer, which is a minor gap given the rich schema descriptions.

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 86%, so the 7 parameters are largely self-documenting, and the description restates the counter_signature contract rather than extending it. It adds minimal semantic detail beyond the schema (no guidance on choosing key vs. pass vs. access_token), 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?

The description opens with a specific verb and resource: 'Counter-sign a receipt this item earned,' and enumerates the four kinds of receipt (promise, amended agreement, ending, refund) so the scope is unambiguous. It is not a tautology of the name/title, though it does not explicitly name a sibling tool it replaces.

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 a clear operational sequence ('Read the item to find its receipts; then send a compact JWS...') plus a prerequisite (the instance verifies it against the key you carry), and reassures that 'Acknowledging twice is harmless.' It stops short of stating when to withhold acknowledgement or naming an alternative tool.

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

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

Annotations declare the destructive/idempotent profile, and the description adds real value beyond them: late cancellations may count against the customer, refusal where the business doesn't record them, refund of 'what is owed back', and a 409-confirm handshake before sending fee_sha. The wording is dense but the substantive behavior is disclosed; no contradiction with destructiveHint=true.

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

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

Purpose is front-loaded in the first sentence, but the second sentence is convoluted ('answers first with the fee under its policy and what is owed back') and reads awkwardly, forcing the agent to re-parse. Content earns its place; the phrasing does not.

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 7-param mutation with no output schema, the description covers the important hidden behavior: consequences of late cancellation, refund reporting, and the fee-confirmation handshake. It relies on the schema for credential handling, which is reasonable, so only minor gaps remain.

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 71%, so most parameters self-document. The description usefully explains that fee_sha belongs to the 409 confirm_terms response and should only be sent after the user agrees — context beyond the schema — but it leaves key/pass/access_token/idempotency_key entirely to the schema. Baseline 3 fits.

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 ('Cancel an item you created') and describes the post-cancellation outcomes, so the core operation is clear. It does not explicitly distinguish itself from adjacent siblings such as request_return or decline_offer, and 'item' is never defined (booking/order/stay), leaving some ambiguity.

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 embedded prerequisite 'you created' and the late-vs-refused branch imply when the tool applies, and the confirm flow is described. But there is no explicit when-to-use / when-not guidance and no named alternative for related flows (e.g. returns), so usage must be inferred.

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

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

The description adds behavioral details beyond the readOnlyHint and idempotentHint annotations: it specifies the 14-day maximum window and that times already started or within the business's minimum notice are excluded. This gives useful context about how the tool operates, though it does not describe the return format.

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

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

The description is two sentences, front-loaded with the core purpose and constraints. It contains no redundant information and every sentence earns its place, making it highly concise and well-structured.

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

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

The description lacks details on the output format (e.g., whether it returns a list of timestamps, objects, or an empty result) and does not explain how party_size affects availability. Since there is no output schema, this information is necessary for the agent to interpret the tool's results correctly, leaving a significant gap.

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

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

The description clarifies the meaning of the time range (from/to) as 'between two instants' and the 14-day limit, but it does not explain party_size or service_id. With schema coverage at only 50%, the description does not adequately compensate for the undocumented parameters, leaving their semantics unclear.

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

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

The description clearly states the tool lists free start times for a service within a time window, with specific constraints like the 14-day limit and exclusion of started times. It is specific and understandable, but it does not explicitly differentiate from sibling tools like suggest_time, which also deals with time proposals.

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

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

The description provides no guidance on when to use this tool versus alternatives such as suggest_time or create_booking. It implies usage for checking availability but does not offer exclusions or routing advice, leaving the agent to infer the appropriate context.

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 (writable, non-destructive, idempotent), the description discloses the pricing rule (a fixed-price service costs the business's listed price and any differing totalPrice is merely noted), the gating behavior that a priced request sends nothing to the business without terms_sha, and that an access_token is returned for account-less callers. These are the non-obvious behaviors an agent cannot infer from schema or hints.

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?

Five tight sentences, roughly ordered from action to the pre-call check to the confirmation loop to the return value, with no filler. The telegraphic, clause-chained style ('a different totalPrice you send is only noted for the business') costs some readability but nothing is wasted.

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 9-parameter tool with nested policy/deposit/attachment objects and no output schema, the description covers the decisive parts: availability pre-check, terms_sha confirmation gate, price semantics, and the item/access_token return. It does not mention idempotency_key behavior or the visit_for linkage, both of which are left entirely to the 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?

At 67% schema coverage the description adds genuine meaning to the highest-stakes fields: endTime and reservationFor.name may be omitted because they derive from the service's durationMin and name, and totalPrice is informational rather than binding for fixed-price services. It leaves key/pass/attachments to their already-detailed schema descriptions, which is reasonable but leaves partial reliance on the schema.

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

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

The opening names a concrete action and resource ('Request a service at a time'), and the closing states what comes back ('the item' and an access_token), so an agent knows this creates a booking record rather than a read. It does not explicitly contrast itself with nearby siblings like create_order, request_quote or suggest_time, so differentiation is only implied via 'Check availability first'.

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 real sequencing guidance ('Check availability first') and spells out the two-phase flow: without terms_sha nothing is sent, you receive confirm.summary/confirm.terms_sha to show the person, then call again on their clear yes. It stops short of naming when to prefer create_order, request_quote or suggest_time instead, so no full alternative map.

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, the description discloses that product lines use the business’s list price, unpriced lines wait for business pricing, and a priced order is not sent or bound without terms_sha. It also explains the confirmation summary returned for the user, which is meaningful behavioral context for a write tool.

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

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

The description is compact and front-loads purpose and pricing rules, with no obvious filler. The pricing sentence is dense but earns its place given the complexity of the order-pricing and confirmation semantics.

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

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

For a complex write tool with no output schema, the description explains the confirmation summary but not the successful order response or broader return shape. Other nested parameters rely on the schema, leaving a clear output-side gap even though the critical confirmation flow is covered.

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

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

The description adds significant meaning beyond the schema for orderedItem: productId/sku pricing, total-price derivation, and the effect of sending a different price. It also explains the terms_sha confirmation gate, while the schema already documents key, pass, attachments, and idempotency_key.

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?

“Order products” names a specific action and resource, and the pricing explanation distinguishes the tool from list_products by making list_products the price source rather than the order path. An agent can identify this as the product-ordering write operation.

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

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

The two-step confirmation flow is explicit: call without terms_sha to get confirm.summary and confirm.terms_sha, then call again only after a clear yes. It does not explicitly route against sibling alternatives such as request_quote or make_offer, so it is clear context without full when/when-not guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description adds semantic consequences: the booking request or order is closed, an agreed change is kept, or a requested change is taken back. It does not elaborate on irreversibility or auth flows, but the schema covers identity and idempotency.

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

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

The description is front-loaded with the core action and stays relatively compact. The middle sentence is dense and awkwardly phrased ('To a change it asks for...'), but it carries important semantic distinctions rather than 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 an 8-parameter mutation tool with rich schema coverage and annotations, the description covers the key business scenarios and the optional reason fields. Auth, idempotency, and parameter details are handled by the schema, so no major gap remains.

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 88%, so the schema already explains most parameters in detail. The description only calls out reason and reason_code, adding little beyond the schema's own documentation, so baseline 3 is appropriate.

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

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

The description uses a clear verb phrase ('Say no to...') and names the resources involved: proposed times, proposed changes, quotes, and requested changes. It is understandable and distinct from accept_offer, though it could more directly label the operation as declining an offer.

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 concrete usage contexts: declining another time, business-proposed changes, quotes, or taking back a requested_change. It does not explicitly name alternatives such as accept_offer or withdraw_from_contract, so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds value by naming the fields and explaining that doors_elsewhere entries carry a URL and optional platform. However, with no output schema, it does not fully describe the return structure or whether fields can be absent.

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?

It is a single dense sentence with no filler, but the phrase 'where it takes any other kind instead' is grammatically awkward and forces the reader to reparse it. The field list is front-loaded, but the doors_elsewhere clause could be clearer.

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-parameter read with no output schema, the description does list the main return categories and partly explains doors_elsewhere. It still leaves the response shape and the meaning of 'other kind' ambiguous, and gives no usage context. It is minimum viable rather than complete.

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 about inputs. The baseline for a no-parameter tool is 4.

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 enumerates the profile fields returned (name, time zone, currency, languages, accepted item types, doors_elsewhere), which makes the resource clear. It never uses an explicit verb like 'returns' or 'retrieves', but the field list leaves little doubt it is a business-profile read. It is distinguishable from all transactional siblings.

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?

There is no statement of when to use this tool versus siblings, and no prerequisites or exclusions. The only implied usage is that an agent needs business configuration, which is left entirely to inference.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description usefully adds what the returned status contains: proposed terms, who is waited on, possible next actions, and thread contents. It does not cover error behavior or freshness, but it adds meaningful behavioral 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?

The description is a single dense sentence that front-loads the core purpose and then elaborates on returned content. It is information-rich and mostly earns its length, though the nested parentheticals make it slightly harder to scan.

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 needs to explain return content, and it does so by naming the offer terms, waiting party, next actions, and thread. Authentication and item identity details are handled by the schema, so the remaining description is largely complete for this read-only status tool.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema. The description adds no additional parameter meaning, making the baseline score of 3 appropriate.

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

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

The description clearly identifies the resource as an item's current state and specifies the kind of information returned: offer terms, waiting party, next actions, and thread. It does not explicitly name sibling alternatives, so it is clear but lacks direct differentiation.

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?

Usage is implied by 'an item you created' and the status-oriented description, but there is no explicit when-to-use guidance or comparison to action-oriented siblings like accept_offer or decline_offer. The agent must infer that this is the read-only status-checking option.

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 and idempotent, so the description adds genuinely useful context: prices are in minor units, the gtin is 14 digits where present, stock status is included, and 'the price here is the one that counts' establishes this as the authoritative price. It says nothing about pagination behavior despite a cursor parameter.

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 dense sentences with the returned content front-loaded and the filter semantics following. The telegraphic 'ids: ...; gtin: ...' style is efficient, though it sacrifices a little readability.

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

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

With no output schema, the description does well to describe the returned product shape and price units. However, for a 5-parameter, 40%-coverage list tool it leaves q, limit, and cursor unexplained and gives no pagination guidance, which an agent needs to call it correctly at scale.

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

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

Schema coverage is only 40%: q, limit, and cursor have no schema descriptions, and the description does not compensate for any of them. It adds some meaning to gtin (accepts any length, 14-digit canonical form) and ids (live price for previously-seen products), but those are the two parameters that already had 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?

The description states the resource and its content precisely: orderable products with prices in minor units, barcode, and stock status. It never states the verb 'list' or the filtering/pagination nature of the operation, and it does not distinguish itself from the sibling list_services.

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 ids and gtin clauses give workflow context ('read the live price of products a network showed you, before your person agrees') and differentiate the two filters. But there is no guidance on when to use this tool versus check_availability or get_item_status, and the q parameter's purpose is left entirely implicit.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, lowering the burden on the description. The description adds useful pricing semantics (price.per=person and total = price times partySize), which is context beyond annotations. However, it does not clarify pagination behavior or that the response is a list with a cursor, and the 'send partySize' wording could be mistaken as a parameter of this endpoint.

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

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

The description is short and front-loads the core meaning: bookable services with duration and price. The second sentence adds a specific pricing nuance, which is useful but not essential for invoking a list endpoint, so it slightly distracts. Overall, there is 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?

Without an output schema, the description partially explains the returned data (duration, price) and price semantics, but it does not describe the pagination shape or how cursor works. For a simple read-only list endpoint, this is adequate but has clear gaps.

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

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

Schema description coverage is 0%, so the description must compensate for the undocumented parameters. It does not explain limit or cursor at all, and the only parameter-like detail mentioned, partySize, is not part of this tool's input schema. Thus the description adds no useful meaning for the actual parameters an agent must use.

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 identifies the resource as 'bookable services' and notes their key attributes (duration, price), so an agent can infer this is a service catalog listing. It does not explicitly state the 'list' action, but the tool name and title make that reasonably clear. It does not differentiate from siblings like list_products or check_availability.

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?

There is no guidance about when to use this tool instead of alternatives such as check_availability or list_products. The price-per-person note hints at downstream booking behavior but provides no exclusion criteria or context for selecting this endpoint.

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 (readOnly=false, idempotent=true, destructive=false), the description discloses substantial behavior: changes go back to the business as their request, price negotiation only applies where get_business_profile says price_negotiable, otherwise the input routes as a person's message, is never refused, passed_on after a few rounds, and what was proposed or agreed still stands.

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

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

The description is a single dense paragraph with em dashes and nested conditionals that is difficult to parse. Most clauses carry relevant information, but the structure is not cleanly front-loaded and could be tightened substantially.

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

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

For a complex 9-parameter negotiation tool with no output schema, the description covers negotiation paths, fallback-to-message behavior, and outcome persistence ('what the business proposed, or what was agreed, still stands'). The schema handles identity, pass, and idempotency details; exact response and error shapes are not described but are less critical here.

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 89% schema description coverage, the baseline is 3, but the description adds scenario-specific meaning: start_time is a free check_availability slot for bookings versus the requested time for quotes; lines index into offer.terms.lines for order-change offers but the order's orderedItem on confirmed/accepted items; total_price and unit_price apply only where the business profile says price_negotiable.

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 opening phrase 'Answer what the business proposed with only what your person would change' names a counter-offer action, and subsequent clauses enumerate start_time, lines, delivery_when, quantity, and price changes. It distinguishes offer responses from changes on confirmed bookings or accepted orders, though the run-on phrasing prevents a crisp verb+resource statement.

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 establishes the context of responding to a business proposal with changes and details what conditions route a price into negotiation versus a message. However, it never explicitly contrasts make_offer with accept_offer or decline_offer, nor states when not to use this tool.

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, the description discloses that the item moves on and that details on other items are kept as a message for the business. These are meaningful behavioral side effects, though 'the item moves on' remains vague about the resulting state.

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

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

The description is short and front-loads the main purpose and trigger. The second sentence is somewhat ambiguous but still compact and relevant.

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?

It explains the triggering situation and main side effect, and annotations cover idempotency and safety. However, with no output schema, the description does not explain what the caller gets back or what 'the item moves on' means for subsequent calls.

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 high at 83%, so the schema already explains most parameters, including key, pass, access_token, and idempotency_key. The description only implicitly reinforces the 'details' parameter as the answer to the business question and adds no further 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?

The description states a specific action: answering what the business asked about an item, and explicitly ties the trigger to get_item_status needing a detail. It does not clearly differentiate from the sibling send_message, especially since it says details on other items are kept as a message.

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 a clear trigger: use when get_item_status says a detail is needed. It also describes what happens if invoked on any other item, though it does not explicitly name send_message as the alternative for generic messaging.

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. The description adds only 'Creates a quote_request item', which is nearly tautological and provides no extra behavioral context (e.g., side effects, notifications).

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 no wasted words and the key action front-loaded. However, it is arguably under-specified for a tool with seven parameters and nested structures.

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

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

For a complex mutation tool with nested objects and no output schema, the description is far too sparse. It omits essential context such as the payload structure, budget vs. budgetMax, urgency, and attachment handling.

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 57%, so the description carries some burden. It mentions no parameters, leaving the agent to rely entirely on the schema for semantics—especially for the complex nested 'payload' object.

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

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

The description states a specific verb ('Ask for a price') and resource ('something custom'), and clarifies that it creates a 'quote_request item'. It does not explicitly differentiate from siblings like make_offer or create_order, but the action is 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?

No guidance on when to use this tool versus alternatives such as make_offer or create_order. The implied usage ('for something custom') is vague and lacks explicit context or 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?

Beyond the annotations (which already say idempotent, non-destructive, mutating), the description explains the consequence of each reason: faulty/not_as_described/wrong_item fall under a legal guarantee at no cost to the customer, while changed_mind is a withdrawal within the period or a business-policy return after it. It also states the return is created as a linked object visible under refunds in get_item_status, filling in for the missing 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?

Front-loads the precondition, then reason semantics, then lines, then outcome; each clause carries information and there is no redundancy. The telegraphic style is dense but readable.

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 9-parameter mutation with no output schema, the description covers trigger, reason consequences, line selection, and the observable result (a linked return listed under refunds). It omits what happens next in the lifecycle (approval, who accepts) but is sufficient to invoke 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 78% and already documents key, pass, idempotency_key, and lines. The description adds real meaning for reason by explaining the legal and cost implications of each enum value, and clarifies lines semantics (indices into orderedItem, omitted means all), which is more than a restatement.

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 (ask to send goods back) and resource (goods from an order), with a clear precondition: it applies once the goods reached the person. An agent can distinguish it from cancel_item or withdraw_from_contract by that precondition alone.

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 activation condition ('once an order's goods reached your person') and explains which reason values are available and their legal consequences, which guides selection. It does not explicitly exclude or name alternatives for cases like unshipped orders, leaving a small gap.

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

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

Annotations already declare non-read-only, idempotent, non-destructive; the description adds only the ownership constraint "an item you own." It is silent on the fact that messages are dispatched to an external issuing network via passes, on the required idempotency key for agents, and on whether the send is reversible or delivered asynchronously.

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 nine-word sentence with no filler, but the brevity crosses into under-specification rather than efficiency. The new-vs-reply distinction is at least 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?

This is a 9-parameter mutation tool with a nested contact object and no output schema, so the description carries a lot of explanatory burden. Key questions an agent needs answered — how the recipient is identified, what the access_token grants, what a successful send returns — are left entirely to the 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 56% and the description contributes nothing to close that gap. The rich schema notes on key, pass, item_id, access_token and idempotency_key do the work, while undocumented parameters like body, subject, message_id and the nested contact object get no help from the 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?

"Start a conversation, or reply on an item you own" conveys two modes of a send operation, but never states plainly that it sends a message, to whom, or over what channel. No sibling tool overlaps in function, so differentiation is not an issue, but the purpose remains only loosely specified.

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 new-vs-reply branching is implied (start a conversation vs reply on an item), which is usable guidance. However there are no prerequisites, no mention of when a pass/key/contact is required versus an access_token, and no exclusions or alternatives.

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

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

Beyond the annotations, the description discloses the full interaction contract: the business confirms or counter-proposes, a confirmed booking stays as agreed until the business accepts the move, and repeated rounds or exceeded change limits hand the request to a human, returned as passed_on. That is exactly the kind of outcome and escalation context an agent cannot get from readOnlyHint/idempotentHint alone.

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 tight sentences with the counter-proposal condition front-loaded and no filler. The middle sentence is dense but every clause carries behavioral information (confirmation loop, move semantics, escalation), so nothing could be cut without losing meaning.

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 7 parameters, no output schema, and a mutation-style flow, the description covers the outcome states and even names the passed_on escalation field. What it leaves implicit is the identity/credential parameters (key/pass/access_token) and idempotency expectations, though the schema does document those.

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

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

Schema coverage is 71%, and the description adds real meaning for the critical parameter: start_time must come from check_availability output and the end time is derived from service length, not supplied. It also explains that on a confirmed booking the end keeps the existing booking's length. item_id and note carry no added explanation, which keeps it below a 5.

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 opening clause gives a specific verb and object: propose a different time than the one the business proposed, with start_time constrained to slots returned by check_availability. That distinguishes it from check_availability itself, but the relationship to the sibling make_offer (also a proposal-style tool) is never clarified, leaving one plausible source of confusion unresolved.

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

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

It states a concrete precondition for use — start_time must be one of the free times check_availability lists — which effectively routes the agent through that sibling first. It also separates the two operating modes (pending proposal vs. already-confirmed booking) and notes escalation after several rounds. It stops short of any explicit 'do not use this when…' exclusion.

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 discloses the key side effect of the first call (emailing six digits) and the second-call verification behavior, going beyond the annotations' simple readOnly/idempotent/destructive flags. It does not cover code expiry or failure modes, but the important behavioral traits are present.

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

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

The description is compact and front-loaded with the trigger condition, then walks through the two-step flow without wasted words. It could be slightly cleaner, but every sentence contributes to correct usage.

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

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

The description covers the essential two-phase flow and parameter roles, but there is ambiguity around access_token: the description implies it is needed for the first call while the schema marks only item_id as required. It also omits return behavior and error handling, which matters for a multi-step verification tool with no output schema.

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

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

The description maps item_id to the target item, access_token to the first call that sends the code, and code to the second verification call. This adds meaning to item_id, which lacks a schema description, and clarifies how the code and access_token relate to the workflow.

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

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

The description clearly states the tool's purpose: verify a known customer by emailing a six-digit code and then confirming the code. It gives a specific trigger ('identity.recognised is weak') and explains the two-phase flow, which distinguishes it from siblings like acknowledge_receipt or send_message.

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 an explicit when-to-use condition: when identity.recognised is weak and the person supplied an email of a known customer. It also spells out the exact call sequence, including the code round-trip, but it does not mention alternatives or exclusions.

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

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

The description adds substantial behavior beyond the annotations: no request is sent without confirm_withdrawal, the first call returns a statement to show the person, refunds happen before shipment, goods must come back after receipt, and partial lines are supported. This matches the destructive and idempotent hints without contradicting them.

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

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

The description is front-loaded with the core action and two-step flow, and every sentence carries operational meaning. It is somewhat dense and can be hard to parse in one pass, but it is appropriately sized for a destructive multi-step workflow.

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

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

For a complex destructive tool with no output schema, it covers the critical flow, confirmation requirement, refund behavior, partial-line handling, and fallback outcomes. It does not fully document the response shape, but it gives enough context for an agent to call the tool correctly.

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

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

Schema description coverage is high at 88%, so most parameter meaning is already documented. The description still adds useful semantics for confirm_withdrawal and lines, explaining the confirmation gate and that line quantities apply only after goods reached the person.

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

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

The description states a specific action and resource: a person withdraws from a paid booking or order. It distinguishes the process from a business-policy return by mentioning that some cases become a return or are passed on, though it does not name sibling tools like request_return explicitly.

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 clearly explains when to use the tool: within the business-stated withdrawal period, after checking get_item_status, and with a two-step confirmation flow. It also states when-not cases past the period or non-returnable items and describes the alternative outcomes passed_on or business-policy return.

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