Surfing Dog Inbox

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

Annotations only declare readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds substantial context beyond that: this 'binds your person', omitting terms_sha results in nothing being booked, a stale offer_id yields 409 offer_changed, and unreachable changes are passed to a human. That is exactly the kind of binding/consequence detail 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?

Two very long, run-on sentences pack multiple distinct behaviors (binding requirement, terms_sha sequencing, offer_id staleness, passed_on routing) into dense clauses with awkward phrasing ('Accept another time the business proposed'). Front-loaded with purpose, but low scannability and some redundancy with the schema descriptions.

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 7-parameter mutation with no output schema, the description covers prerequisites, identity binding, error paths, and the outcome ('An accepted quote becomes a confirmed booking or order (linked)'). What is missing is any indication of the success payload shape, though the absence of an output schema lowers that expectation.

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

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

Schema description coverage is 86%, so the schema already documents offer_id, terms_sha, key, and pass in detail. The description mostly restates that (terms_sha must come from get_item_status, offer_id invalidated on replacement), adding only mild sequencing emphasis. Baseline 3 is appropriate.

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

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

States a specific verb (accept) and a precisely enumerated resource scope: an offer for a booking, a quote, an order change, or a change to a confirmed booking/accepted order. The parenthetical on offer.kind ('the promise moves') clarifies what accepting actually does. It is clearly distinguishable from decline_offer, make_offer, and withdraw_from_contract.

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 ('only after they said yes to offer.human') and the sequencing rule for terms_sha, plus a routing rule for offers that can no longer be changed online (passed_on). It does not explicitly name decline_offer as the alternative path, so it stops short of full 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 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 already flag destructive and idempotent behavior; the description adds meaningful nuance about post-window outcomes: late cancellations may count against the customer or be refused depending on business policy. It does not contradict the idempotent or destructive hints. It could still say more about whether the item is deleted versus status-changed, but the added nuance is valuable.

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 with no filler; the core action is front-loaded and the second sentence packs the nuance. The cancellation-window sentence is slightly convoluted but still earns its place.

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

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

For a destructive mutation with no output schema, it would help to say what a successful cancellation looks like and whether the item is removed or just marked cancelled. The description covers policy-dependent outcomes but not the expected result or error surface, so it is adequate but not 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?

Schema coverage is 67%, with key, pass, access_token, and idempotency_key already documented in the schema. The description adds no parameter-level meaning; item_id and reason remain unexplained, though item_id is inferable and reason is optional.

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 clear predicate and object — 'Cancel an item you created' — which is unambiguous against sibling tools like create_booking or get_item_status. It does not explicitly name alternatives, but the action is unique among 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?

It implies the tool is for cancelling a previously created item and includes the 'you created' prerequisite, but it never states when not to use it or what other tool should be used for cancellations by a business or operator. The cancellation-window explanation gives context but not explicit routing guidance.

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

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

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?

Annotations only cover read-only/idempotent/destructive hints, so the description carries the real behavioral load and does: it discloses the two-step priced-booking confirmation flow, that nothing is transmitted without terms_sha, that a differing totalPrice is only noted for the business, and that a no-account caller receives an access_token. These are meaningful traits beyond the structured 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?

Front-loaded with the core action and prerequisite, then pricing, then the confirmation flow, then the return. Every sentence carries distinct information with no filler.

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

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

For a complex, 7-param, nested-object, no-output-schema tool, the description covers purpose, prerequisite, pricing nuance, confirmation gating, and return shape. Minor gaps remain around how a fixed-price vs priced booking is determined and the idempotency_key requirement, but the essentials are present.

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

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

With 57% schema coverage, the schema documents key/pass/terms_sha but the description adds genuine meaning about totalPrice semantics (fixed-price from list_services vs. a noted-only different totalPrice) and reiterates the terms_sha gate. It does not clarify the nested payload fields, though those are largely defined 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 ("Request a service at a time") and immediately differentiates itself from related siblings by pointing to check_availability and list_services. An agent can tell this is the booking-creation tool 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 explicit sequencing ("Check availability first") and a clear when/when-not: a priced booking without terms_sha sends nothing, and the agent must call again with the terms_sha on the customer's clear yes. Both the prerequisite and the confirmation gate are spelled out, 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?

Goes beyond the annotations (readOnlyHint=false, idempotentHint=true) by disclosing the crucial safety behaviour: nothing is sent to the business without terms_sha when a price is present, a sent price differing from the list price is only noted, and a priced order only binds the person after explicit confirmation. This is exactly the write-semantics an agent needs and cannot get from structured fields.

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

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

Front-loaded with the core action and the pricing rule in the first two short sentences. Later sentences get dense and slightly convoluted, but every clause carries real semantic content about the confirm flow, so there is little 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 7-parameter nested write tool with no output schema, the description covers pricing, line types, and the two-phase confirmation, and even names the returned confirm.summary/confirm.terms_sha. Authentication via key vs pass is left to the schema, which documents it well, so coverage is nearly 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?

Schema coverage is only 57%, and the description compensates by clarifying that prices are in minor units and by explaining how orderedItem lines relate to productId/sku and to the total, none of which the schema documents. It stops short of covering the remaining opaque fields deliberately (contact, delivery, paymentMethod).

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 ("Order products") and delineates scope via pricing behaviour, which separates it from quote/offer siblings like request_quote and make_offer. It is clear what the tool does, though the two-phase confirm behaviour makes it slightly less crisp than a single-purpose definition.

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 context: name a product to take the business's list price, omit one to leave it for the business to price, and call again with terms_sha on a clear yes. It implies when to send a price vs wait, but never names an alternative sibling (e.g. request_quote) or states an explicit when-not condition.

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

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

Goes beyond the annotations by spelling out the consequence in each branch: declining a business-proposed change closes the booking request/order, declining a change to a confirmed booking/order keeps what was agreed, and declining on a requested_change retracts it. That is meaningful state-consequence disclosure. It does not cover auth or error behavior, which the schema partially carries.

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, which is good, but the sentences are dense strings of parenthetical clauses ('no keeps what was agreed', 'on a change your person asked for (requested_change), it takes that back') that are hard to parse on first read. No sentence is wasted, but the phrasing is not clean.

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, multi-state mutation with no output schema, the description covers the branching outcomes well and the annotations declare the safety profile. It is slightly short on what a successful call returns or how the closed/retracted states surface to the caller, but otherwise complete enough 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 88%, so the schema already documents item_id, offer_id, key, pass, access_token, idempotency_key, reason and reason_code. The description only adds a light steer on reason/reason_code ('for anything your person wants to know') and says nothing about item_id vs offer_id selection. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb ('decline'/'say no') and enumerates the resources it applies to: a proposed time, business-proposed changes, and a quote. It is clearly the negative counterpart to accept_offer, though it never names that sibling explicitly, so an agent infers the pairing rather than being told.

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 situations in which to decline (another time, business-proposed change, quote, taking back a person-requested change), which is solid usage context. It stops short of explicit exclusions or naming accept_offer as the alternative path, so it is clear-but-not-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 readOnlyHint and idempotentHint; the description adds valuable behavioral context by explaining the response perspective ('in the business's words') and its components: proposal, terms_sha, who is waiting, available next actions, and conversation thread. This goes beyond the annotations 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 key action and resource are front-loaded, and every clause adds substantive detail. It is one long sentence with a heavy colon-separated list, which is efficient but slightly dense; a little more structural separation would improve 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?

There is no output schema, so the description rightly carries the burden of explaining what the response contains, and it does so well. It omits edge cases like missing or nonexistent items and exact error behavior, but the read-only annotations plus rich return description make the tool usable for correct invocation.

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

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

Schema description coverage is 75% and the schema already explains key, pass, and access_token in detail. The tool description itself adds no parameter-specific guidance, and item_id has no schema description, but its meaning is self-evident. A 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 specific verb and resource: 'get' the 'current state of an item'. It enumerates what the status contains (offer with terms_sha, who it waits on, next actions, thread), which clearly separates it from the mutation and creation siblings like create_order, accept_offer, and 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?

It anchors usage to 'an item you created' and to the waiting state ('waits for your person to answer'), so an agent can infer this is the read-status/polling tool after creation or an offer. It does not explicitly name when-not-to-use or alternatives, 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 readOnlyHint and idempotentHint, so the safety profile is covered. The description adds useful domain context—products are orderable and prices use minor units—but it does not disclose pagination, filtering, or any other runtime behavior beyond what the annotations already imply.

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 extremely short, free of filler, and front-loads the most decision-relevant trait (orderability). It earns its place, though the brevity leaves out useful invocation details that could have been added without bloating the text.

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 zero parameter descriptions, this sparse definition is not complete enough for confident invocation. It gives no explanation of what the returned product objects include beyond prices, no parameter semantics, and no pagination behavior. The name and annotations carry the operation and safety profile, leaving too much implicit.

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 natural-language description carries the burden of explaining parameters. It completely fails to mention q, limit, or cursor or how they affect the call. The phrase about minor units helps interpret response values, not input parameters.

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 is a noun phrase describing the resource ('Orderable products with prices in minor units') rather than an explicit action, leaving the verb to the tool name. It does distinguish products from the sibling list_services by noting they are orderable and priced, but it does not clearly state that this tool lists or retrieves them.

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

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

There is no guidance on when to use this tool versus alternatives. It never mentions siblings such as list_services, check_availability, or create_order, and it does not state when this tool should or should not be chosen. 'Orderable products' only weakly implies use for product browsing.

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?

Annotations cover the write/idempotent/safe profile, but the description adds substantive behavior: the proposal is not binding and stands until the business says yes, non-negotiable pricing is forwarded as a message rather than refused, and frequent or post-round suggestions are passed_on. It stops short of describing the response envelope, but for a no-output-schema negotiation tool the behavioral disclosure is unusually deep.

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 content is front-loaded, but it is delivered as one enormous multi-clause sentence riddled with em-dashes and conditionals, making it hard to scan. Branching logic this complex should be broken into list items rather than a single dense paragraph.

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 9 parameters, nested objects, and no output schema, the description does the heavy lifting by explaining the two negotiation regimes and the fallback path. It omits any description of the success response payload and only hints at the 409 offer_changed case (which the schema documents), but the core decision logic is covered.

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

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

Schema coverage is 89% so the baseline is 3, but the description adds real meaning: index 0 drops a line, start_time means a free slot for a booking versus a target time for a quote, quantity is quote-specific, and total_price/unit_price are gated on price_negotiable. These are semantic distinctions beyond the raw field names.

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: answer the business's offer with counter-terms (start_time, quantities, delivery_when, quantity, or a price), and frames it as a request that goes back to the business. This is enough to distinguish it from accept_offer/decline_offer, though it never names those siblings, so the differentiation is inferred rather than explicit.

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 lays out explicit branches: free times come from check_availability, a quote time is the time it is for, order changes are indexed in offer.terms.lines, confirmed bookings/accepted orders change orderedItem, and pricing is only an answer where get_business_profile says price_negotiable. It names the sibling tools and the conditions selecting each path, plus the fallback (goes to a person as a message) and never-refused behavior.

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 idempotency and non-read-only behavior. The description adds meaningful context beyond that: on the target item the workflow moves on, while on other items the details are kept as a message for the business. This helps the agent anticipate side effects without contradicting 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 with no filler. The first sentence front-loads the action and trigger; the second concisely states the side-effect distinction. Every clause earns its place.

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

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

The description covers what the tool does, when to use it, and the behavioral outcome, which is sufficient for a 6-parameter tool. The required item_id has no description in either the schema or the tool description, and there is no output schema, leaving minor gaps, but overall the context is strong.

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 (83%), with detailed descriptions for pass, key, details, access_token, and idempotency_key. The tool description itself adds no parameter-specific meaning beyond restating the purpose of 'details', so the baseline of 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 specific verb ('Answer') and a clear resource ('what the business asked about an item'), and it explicitly ties the trigger to the sibling get_item_status. This distinguishes it from send_message or request_quote, making the purpose 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?

The description gives a clear context for use: call it when get_item_status indicates a detail is needed. It also explains the behavioral difference on the target item versus other items, but it does not explicitly name alternatives or state when not to use it, so it stops short of full 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 cover read-only and destructive hints, and the description adds a concrete side effect: it 'creates a quote_request item'. However, it does not explain whether the request is binding, what happens after creation, or how the idempotency guarantee works.

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 filler, and the core action is front-loaded. It is efficient, though arguably under-specified for the complexity of the input schema.

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

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

For a mutating tool with a six-parameter nested schema and no output schema, this description is too thin. It omits when to call it, how identity and idempotency fit in, and what response to expect; the helpful parameter descriptions inside the schema only partially compensate.

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

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

Schema description coverage is only 50%, and the description adds no parameter-level meaning. The payload, contact, and message parameters have no documentation in either the schema or the description, so an agent must infer semantics from nested field names.

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

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

The description clearly states the action ('ask for a price') and the resource ('something custom', creating a 'quote_request item'), so an agent can distinguish it from create_order or create_booking. It stops short of naming those siblings explicitly, but the core purpose 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?

There is no guidance on when to use this tool versus create_order, check_availability, or list_products/services. The phrase 'something custom' implies a scope, but no prerequisites, exclusions, or alternative routing 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?

Annotations already declare idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: who bears the cost per reason (legal guarantee vs. own policy), that changed_mind is time-boxed to a withdrawal period, and that the return surfaces as linked and appears under refunds in get_item_status. It does not contradict 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?

Compact and front-loaded: the precondition and action come first, then reason semantics, then line selection, then the return's downstream linkage. Some sentences are heavily compressed and read as run-ons, but 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?

For a 9-parameter mutation with no output schema, the description covers the action, reason economics, line selection, and result linkage reasonably well. It still leaves `wants` (refund/exchange/credit) and the `other` reason unexplained, and gives only 'comes back as linked' about the response.

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%, so the schema mostly carries parameter meaning and a 3 is the baseline. The reason semantics (faulty/not_as_described/wrong_item as the legal guarantee vs. changed_mind as a withdrawal) add value, but the lines sentence merely repeats the schema description verbatim and the description omits `wants`, `note`, and the `other` enum value.

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 (send goods back / request a return) with a clear scope gate: goods must already have reached the person. That implicitly separates it from pre-delivery siblings like cancel_item, though it never names them. 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?

The opening clause gives the triggering condition ('Once an order's goods reached your person'), which is genuine when-to-use guidance and implies when-not (before delivery). It does not explicitly route to alternatives such as cancel_item or withdraw_from_contract, 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 readOnlyHint=false, idempotentHint=true, and destructiveHint=false, covering the basic side-effect profile. The description adds the ownership constraint and the start-vs-reply distinction, but does not disclose authentication needs, delivery behavior, or rate limits; acceptable given annotations, but not enriching.

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 ten-word sentence with no filler; both clauses are informative and front-loaded. It is very easy to parse and every word earns its place, though brevity contributes to gaps in other dimensions.

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 9 parameters, a nested contact object, sensitive identity fields, and no output schema, one sentence is not enough to make the tool callable correctly without opening the schema. The description omits response/error behavior, agent idempotency requirements, and identity-handling guidance, so it is incomplete for its 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 56%, and the description adds no parameter-level meaning beyond restating the item_id behavior already present in the schema. The required body, recipient identity (key/pass/contact), message_id, access_token, and idempotency_key semantics are left entirely 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?

Description uses specific verbs 'start' and 'reply' with resources 'conversation' and 'item you own', clearly indicating a messaging tool. It does not explicitly name sibling alternatives, but the two-mode framing is unambiguous enough to distinguish it from booking/order/status tools.

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

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

The phrase 'Start a conversation, or reply on an item you own' gives two clear call scenarios and an ownership constraint. It does not state when to prefer siblings like acknowledge_receipt or request_quote, nor any when-not conditions, so usage guidance is implied rather than explicit.

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 and non-destructive, but the description adds real behavioral context: the counter-proposal loop, that a confirmed booking stays as agreed until the business agrees, that the end time preserves the booking's length, and that the request escalates to a human (passed_on) after a few rounds. Auth requirements for key/pass are 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?

The key constraint is front-loaded in the first clause, and every sentence carries behavioral information. The prose is dense and clause-heavy ('After a few rounds, or past the changes a booking may have...'), which lowers readability, but 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?

For a 7-parameter negotiation tool with no output schema, the description covers the negotiation lifecycle, the escalation path and the response expectations well enough to call it correctly. Only the credential mechanics (pass/key exchange) are left entirely to the schema, which is acceptable.

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 reinforces the most consequential parameter, start_time, by tying it to check_availability and stating the end follows the service length. It adds nothing for note, key, pass, access_token or idempotency_key, which the schema mostly documents, so this is baseline-plus rather than compensating for gaps.

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+resource — asking the business for a different time than the one proposed — and immediately names the sibling check_availability as the source of valid start times. It is clearly distinguishable from accept_offer/make_offer, though it never explicitly contrasts itself with those 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?

It gives an explicit prerequisite ('start_time must be one of the free times check_availability lists') and describes the two resulting contexts: a pending proposal versus a confirmed booking. It does not say when to prefer this over make_offer or accept_offer, 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?

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?

Annotations declare destructiveHint=true and idempotentHint=true, and the description adds substantial context beyond them: nothing is transmitted until confirm_withdrawal is sent, the first call returns a statement (confirm.statement), refunds differ depending on whether goods shipped, only specified lines come back, and the business emails a copy. It also discloses the non-returnable / passed_on escalation path, which no structured field covers.

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?

Every sentence carries real information and the purpose is front-loaded, but the prose is a dense run-on with awkward phrasing ('withdrawal on get_item_status', 'passed_on') that makes it harder to parse than the content warrants.

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 still conveys the two-step protocol, the statement response, and the refund/return outcomes, and the schema documents the eight parameters well. It stops short of describing the shape of the returned statement or the exact fields sent to the business, which an agent executing the flow would want.

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 already 88%, so the schema carries most parameter meaning. The description does add a conditional rule for 'lines' (only used once goods reached the person) and links confirm_withdrawal to the person's confirmation, but adds little about item_id, pass, key, or idempotency_key beyond what the schema states.

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 — a person withdrawing from a paid booking or order within the business's stated withdrawal period — and contrasts it with a return handled under the business's own policy. It is clearly distinguishable from a generic cancellation, though it never names the sibling cancel_item or request_return tools directly.

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 scope conditions: use only within the period the business states, obtained via get_item_status, and never for expired, non-returnable, or passed_on cases. The two-step confirm flow and the refund/return branches are spelled out, but the alternatives for the excluded cases are described as concepts rather than by tool name (e.g. request_return).

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