Versum

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

Nearly everything the annotations cannot convey is disclosed: possible return statuses (created/confirmed/declined), the `unavailable` error path where nothing is booked, the fact that results are candidates until the user permits, and that this is an outward-facing action. One tension: annotations set idempotentHint=false while the description claims idempotency 'by idempotency_key', which frames retry safety as conditional on the key rather than contradicting the annotation outright, but an agent could read the two signals as inconsistent.

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 safety precondition is front-loaded and the booking mechanics follow in a logical order. It loses a point for repetition ('never on your own judgement' and 'Get the user's explicit yes first' restate the same rule) and for generic catalog boilerplate appended at the end.

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 open-world mutation tool with no output schema, the description covers the essentials an agent needs: gating on user consent, the eligibility condition on the card, the source of the time slot, and the possible outcomes. Only the unspecified response envelope handling and the undocumented note/business_id parameters are left thin.

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 43%, so the description needs to compensate. It does add provenance for start_at ('as check_availability gave it') and explains that idempotency_key governs retry deduplication, but business_id, note and the customer object as a whole carry no added meaning in the description, leaving half the parameter surface documented only by 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 ('Book a slot in the business's own calendar') and spells out the mechanism: take a start_at from check_availability and the platform books it for the named customer. It is clearly separable from place_order (ordering), request_to_owner (requests) and check_availability (reads) named in the 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?

Explicit preconditions are given: only call after the user explicitly agrees to the exact what/where/when/who, and only for a business whose card shows a `book` action with method `connected` and no `book` in `cannot`. It also names the upstream source of start_at (check_availability) and the sibling analogue (place_order), so the when-to-use decision is fully determined.

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 read-only and non-destructive, and the description goes well beyond them: `unknown` is explicitly not «no», an unconnected business returns `not_connected`, slots are returned on the business's own clock with `timezone`/`start_at_utc` correspondence, and the default window is the next 7 days. It also reiterates that nothing is booked, ordered or paid, which is exactly the safety context an agent needs for an open-world lookup.

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 eligibility gate, then product behaviour, then service behaviour, then the safety caveat — a sensible ordering for a branching tool. The closing pointer to server instructions and the listing of separation rules is slightly padded, but every clause carries operational 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 no output schema, the description correctly takes on the return-shape burden, documenting `state`, `slots`, `start_at`, and the `not_connected` case. Minor gaps remain around how many slots come back and what happens when the requested window has no availability.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by explaining that `from`/`to` define the slot window with a 7-day default and that `quantity` is the threshold stock is judged against. It leaves `variant_id` to the schema's own note, so it does not add meaning for every parameter.

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 operation on a specific resource: stock state or booking slots for one business's offering, taken from the business's own connected Shopify/Square. It also distinguishes itself from adjacent siblings by pointing to `book_slot` (which consumes `start_at`) and by scoping itself to cards carrying `live_data`.

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

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

Gives an explicit entry gate (only when the card shows `live_data`) and an explicit exclusion (results are information-only when the card's `cannot` lists `book`), plus a fallback outcome `not_connected`. It does not name a sibling to use instead when the business is not connected or not live, which keeps it just short of a full when/when-not/alternative statement.

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

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

Annotations already cover the read-only, non-destructive, closed-world profile, and the description adds genuinely new behavior: fuzzy matching tolerates typos/word order/punctuation, miss returns `name_not_found` plus lookalikes, and results are 'candidates, not proof'. It also warns that no booking, ordering or payment happens without permission — a safety boundary the annotations do not express.

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 identity and the not-found path, then parameters, then the safety coda — a sensible ordering. Dense but not padded; the density is driven by the tool's fallback semantics rather than by filler.

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

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

With 7 parameters and no output schema, the description carries the right load: matching tolerance, the failure mode, the meaning of the lookalike list, and the per-call card-shaping role of four optional parameters. The only shortfall is that what the returned card actually contains is described by reference to `list_cards` rather than stated.

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

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

Schema coverage is 100%, so every parameter is already documented; the description only adds that `location` orders matches by nearness while `radius_miles` bounds the nearby list, and that `intent`/`query`/`needed_by`/`deliver_to` 'shape the short card the same way as list_cards'. That cross-reference defers the actual semantics to a sibling rather than explaining them, leaving little beyond the schema.

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

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

States a specific verb+resource+scope: 'One business the user NAMED, matched by its name near `location`' — a named-entity lookup rather than discovery. That distinction cleanly separates it from `search_catalog` and `get_business`, so an agent can pick correctly without opening the schema.

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

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

Gives a clear trigger (the user named a business) and the fallback path when the name is absent from the catalogue, including that the up-to-5 nearby matches are 'never presented as the business asked for'. It never explicitly says to use `search_catalog` instead when only a description is known, so the sibling routing is only half spelled out.

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

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

Annotations only declare readOnly/openWorld=false/destructive=false; the description adds materially more: it is free, offerings are paginated 60-per-page cheapest-first with `offerings_page` and a next offset, and `live_data` (platform, synced_at) signals a connected shelf where offerings carry `source: connector`, variants with `inventory` (null = unknown), and `connected`-method actions route through place_order/book_slot. It also warns that nothing is sent, booked, ordered or paid without the user's permission.

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 synonym caveat and the 'Free. One business in full' payload statement are front-loaded, which is the right ordering. The middle block is a dense wall of parenthetical field descriptions that takes effort to parse, and some of it could be itemized, but nearly every clause carries return-shape information justified by the absence of an output 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?

There is no output schema, so the description carries the full burden of explaining the return value — and it does: identity fields, paginated offerings, the six actions with links and `required_fields`, delivery/pickup/on_site/at_customer with area, fee and deadline, freshness, and the connector variant. For a one-parameter read tool this is 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 100% for the single required parameter and the schema already says 'the business id from search_catalog'; the description adds no further meaning about the id's source or format beyond that. With one fully documented parameter, the baseline 3 is correct even though the response-field detail (`offerings_page`, `live_data`) is handled elsewhere in the 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 opens with the specific verb+resource relationship: it is a SYNONYM of get_card, then states it returns 'One business in full, in the same shape for every trade.' An agent immediately knows both what it returns and that a functionally identical sibling exists, so no schema inspection is needed to disambiguate.

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 explicit trigger phrases («can they deliver to me», «are they open now», «what else do they do») and a fallback condition: when search_catalog offered a business with nothing listed and the next step is a telephone call. It also names the sibling alternatives (get_card for the name you know, place_order/book_slot for the connected-method actions) and states the read/quote/order separation rule, so when-not-to-act is covered too.

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

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

Annotations already declare read-only/non-destructive, and the description adds substantial behavior beyond that: offerings are paged 60 at a time cheapest-first with a next_offset, `live_data` appears only when the business runs a connected system, connector-sourced offerings carry variants with `inventory` (null = unknown), and `connected` actions must be taken via place_order/book_slot. Residual gaps are modest (no statement of what an unknown/absent business returns, no rate or size limits beyond the 200 cap already in 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 opening is well front-loaded ('Free. One business in full'), but the body is one dense run-on paragraph built from stacked parentheticals that mix return-shape documentation, pagination rules and connector semantics. Individual clauses earn their place, yet the packaging makes the routing information harder to extract than it needs to be.

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

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

There is no output schema, so the description carries the burden of describing the return value, and it does so thoroughly — record sections, pagination, connector variants, inventory semantics, and the delivery/action vocabulary. The one missing piece an agent would want is how this differs from get_business.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains the paging model (offerings_page reports the total and the next offset) and ties the id back to its source (the business id from search_catalog). It stops short of restating what offerings_limit/offset do numerically, which the schema already handles.

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 makes clear this retrieves a single business in full and enumerates the components of the record (identity, offerings, actions, delivery methods, freshness). However, it never distinguishes itself from the sibling tool get_business, which on its face sounds like the same operation, so an agent cannot tell them apart from the description 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?

It gives concrete triggering questions («can they deliver to me», «are they open now», «what else do they do») and a fallback case after search_catalog returns a business with nothing listed. It also points to server instructions. What it lacks is any when-not guidance or an explicit routing rule against get_business/find_business.

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

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

Goes well past the annotations by disclosing the live-check rate limit (one business per ten minutes regardless of how many offerings you open), the cache indicators from_cache and checked_at, and the degraded ok: false path for non-item catalogues. It also states the side-effect boundary explicitly: nothing is sent, booked, ordered or paid without user permission.

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 cost and scope ('Free. One offering in full…') and each following sentence carries real information about rate limits, caching, failure mode and output handling. Slightly dense, and the pointer to server instructions is boilerplate, 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?

There is no output schema, and the description compensates by naming the key return fields (live_check, from_cache, checked_at, action_url, ok: false with reason) and how to handle action_url. For a single-param read tool with openWorld behaviour, that is sufficient to call and interpret it correctly.

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

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

Only one parameter and schema coverage is 100%, with the schema already saying it is the offering id from search_catalog. The description adds minor framing (an offering belongs to a business and is walked one at a time) but no new syntax or format guidance, so baseline 3 applies.

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

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

States a specific verb and resource — one offering in full, with a single live price/stock request — which is clearly distinct from catalogue listing behaviour. It doesn't name a sibling tool outright (e.g. search_catalog or get_product), but the contrast with walking a whole shop makes the difference inferable.

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

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

Gives an explicit trigger ('Call it before you quote a price to a person') and an exclusion condition (price lists, menus and quote forms have no single-item door and return ok: false). It also separates reading from quoting, requesting and ordering, which tells the agent when not to treat results as final.

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 readOnly/openWorld annotations it discloses a concrete rate limit (one business asked at most once every ten minutes regardless of how many offerings are opened), the live-vs-cached fields (`live_check`, `from_cache`, `checked_at`), the degraded case where the stored reading stands with its date, and an operational rule about passing `action_url` through verbatim with ref=versum. This is exactly the context annotations cannot carry.

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

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

Key information is front-loaded — the synonym relationship first, then behaviour, then the caveats. It runs long and carries some framing overhead ('kept for agents that already know this name', the quotation marks around live_check), but almost every sentence contributes a distinct operational fact.

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

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

There is no output schema, and the description compensates by naming the fields an agent must interpret (`from_cache`, `checked_at`, `ok: false`, `action_url`) and the failure mode for non-item businesses. For a single-parameter lookup tool this covers everything needed to call and interpret it correctly.

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

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

Schema coverage is 100% and the single `id` is already documented as coming from search_catalog, so the schema does the heavy lifting. The description adds only the cross-tool fact that the same id works in both get_product and get_offering, which is a small but genuine semantic addition.

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 first two sentences do the work precisely: it is a synonym of get_offering, it returns one offering in full, and a 'product' is defined as an offering of kind `product` sharing the same id. An agent can immediately tell it apart from search_catalog (many items) and get_offering (identical behaviour, different name).

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 when to call it ('before you quote a price to a person'), why ('a catalogue read yesterday is yesterday's price'), and when it cannot help ('a price list, a menu or a quote form has no single-item door to ask', returning ok:false). It also routes the agent to the server instructions and separates reading/quoting/requesting/ordering.

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?

With readOnlyHint/destructiveHint already covering the safety profile, the description still adds real behavior: the order is fixed and not a ranking, an invalid niche returns variants instead of results, per-card states (open_then/closed_then/unknown, item_price_within_budget) are enumerated, and it warns that results are candidates and nothing is booked without permission. The one flaw is '20 a page' contradicting the schema's 'Default 10' for limit.

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 opening sentences are well front-loaded, but the bulk of the description is a ~140-entry enumeration of trades with counts, which duplicates list_niches — an existing sibling tool — and crowds out the genuinely useful behavioral notes. That list should be a pointer, not inline data.

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 13-parameter, no-output-schema tool, the description covers the card contents (id, name, distance, phone, items, `next`) and the added state fields, effectively substituting for a return schema, and it documents error behavior for bad niches. Gaps are minor: pagination via `page`/`limit` and the `detail` shelf mode are only lightly touched.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: `query` selects which item a card shows rather than filtering, `niche` must be an exact key, and `needed_by` accepts free-text forms like «tomorrow 19:00» or «this week» interpreted identically everywhere. It explains the state vocabulary produced by max_price and deliver_to, though it leaves page, limit, detail, tags and properties 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?

It states a specific verb and resource — every business of ONE trade near a location, in a fixed shelf order — and immediately distinguishes the `query` parameter from filtering, pointing to search_catalog for the latter. An agent can tell it apart from find_business, search_catalog and get_business without opening a schema.

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

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

It gives explicit routing: `niche` must come from list_niches, and finding businesses that carry an item belongs to search_catalog. It also explains the needed_by vocabulary shared across tools. It stops short of stating when to prefer find_business/get_business for a single known business, so it 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 readOnlyHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior: an unrecognized `niche` returns `variants` with a reason and nothing is substituted, so the agent knows to pick a key rather than assume a fuzzy match. It also discloses that coverage is partial and location-scoped, which manages expectations about empty results.

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 first four sentences are well front-loaded and carry all the real information. They are then followed by several hundred words enumerating every trade and its cities, a data dump that no agent can usefully parse and that buries the operating rules. It is far larger than the tool's decision 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?

For a read-only, no-required-parameter listing tool with full schema coverage and no output schema, the description covers modes, location semantics, radius default and the unmatched-key path. Nothing an agent needs to call it correctly is missing; it is over-complete rather than under-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 description coverage is 100%, so all four parameters, the compact/full enum, the location formats and the 15-mile default are already documented structurally. The description largely restates those semantics (variants behavior, detail: full, default radius) rather than adding new meaning. Baseline 3 is the correct ceiling here.

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 sentence gives a specific verb and resource: it lists the trades/niches a catalogue holds near a place, keyed by niche, with business counts inside a radius. An agent can tell this is a browse/enumerate tool rather than a lookup like find_business or get_business. It never names a sibling explicitly, which keeps it short of a 5.

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

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

It does explain the three modes: no `niche` gives compact keys, a `niche` gives that trade in full, and `detail: "full"` lists everything. That is useful invocation guidance, but it is all intra-tool. Nothing says when to call this instead of search_catalog or find_business, which is the real selection question for an agent facing 14 siblings.

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 readOnly/openWorld/non-destructive annotations, it discloses that the call is free, that it re-queries the platform rather than returning a cached snapshot, that only non-final outcomes are worth asking about, and that Shopify-originated carts always answer `unknown`. Return shape is not described, but there is no output schema to lean on.

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 first three sentences are tight and front-loaded with the core semantics and the Shopify caveat. The trailing paragraph quoting the catalog instructions is generic boilerplate and, while safety-relevant, dilutes an otherwise compact definition.

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

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

For a single-parameter read of unknown-vs-final state, the description covers cost, freshness, the Shopify blind spot, and the consent boundary around acting on results. Only the enumeration of possible status values is left unspecified, which is a modest gap with no output schema 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?

Schema description coverage is 0%, so the description carries the burden. It supplies the crucial provenance for order_id — it must come from place_order or book_slot — which the schema's bare uuid format does not convey; the uuid typing itself is left to the schema.

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

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

The description states a specific verb+resource: re-reads the platform for the status of an order_id created by place_order or book_slot, naming both producing tools. It does not explicitly contrast itself with the sibling request_status, so an agent must infer the split between order status and request status.

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 condition for use: call it again when the order is not final (paid? confirmed? declined by the owner?). It also warns that a Shopify cart link will never resolve here. It stops short of naming an explicit alternative for the Shopify case or for final-state polling.

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

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

Goes well beyond the annotations: no customer data is passed for Shopify/Square, nothing exists on the shop until the buyer pays, Versum holds no card, stock is checked live and 'not in stock' is an `unavailable` error with no order created. It also spells out retry semantics via `idempotency_key` (`repeated: true`, same link, never a second order) and enumerates the possible `status` values.

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 consent rule, which is good, but the consent requirement is stated twice (the 🔴 opener and the closing sentence), and the trailing quote of the server instructions adds bulk without new constraints. Dense platform-by-platform prose is efficient enough but not tight.

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

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

No output schema exists, and the description compensates by naming the return fields (`order_id`, `status`, `checkout_url`) and every `status` value. For a multi-platform mutation tool, the risk profile, prerequisites, error case and return shape are all 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 60% schema coverage the description adds real meaning: lines reference offerings by card id and require `variant_id` only when the card lists several variants, `customer` is only needed on WhatsApp, and `note` is dropped on a Shopify cart link. `business_id` semantics (the `connected` + `order` card) are only partly covered.

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 plus the platform-specific mechanics: a Shopify checkout-link cart, a Square order with a payment link, or a WhatsApp message to the owner. It also implicitly separates ordering from adjacent siblings (reading, quoting, requesting, booking) so an agent can tell it apart from book_slot and request_to_owner.

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

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

Gives an explicit precondition ('only after the user has explicitly agreed to this exact action') and a targeting rule ('For a business whose card shows an `order` action with method `connected`'). What's missing is naming the natural predecessor, quote_order, so the agent infers on its own that it should price with quote_order before placing.

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 explains the surprisingly non-read-only annotation (readOnlyHint=false): the tool writes into the shop's own cart and empties it afterwards, so a mutation is expected yet nothing is bought. It further discloses that no personal data is involved, what is deliberately left unknown (tax and fees at checkout, delivery date unless the cart names it), and the degraded path for unsupported platforms. This adds real behavior beyond the annotation block.

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 no-order guarantee and single-cart/single-ZIP scope are front-loaded, and the following sentences cover returns, unsupported platforms, and sequencing without repetition. The prose is dense with em-dashes and parentheticals, which costs some scannability, but no sentence 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 seven-parameter tool with no output schema, the description states what the answer contains (items, delivery options with prices, subtotal) and what is explicitly not returned. Combined with the cart-emptying side effect and the fallback behavior, an agent has everything needed to call it correctly and to interpret the result honestly.

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 every parameter including deliver_to, delivery_date, options and items is already documented in structured form. The description reinforces the delivery_date semantics ('asks for a day') but supplies no syntax, defaults or constraints that the schema does not already carry, so the baseline of 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: 'Prices ONE cart in the shop's own public cart (Shopify or WooCommerce) to ONE ZIP.' It also states the key scope constraint that 'orders nothing' and that the cart is emptied afterwards, which separates it cleanly from place_order and check_availability without the agent needing to open any schema.

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

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

It sets clear conditions: use it to learn what an order would cost before committing, and it warns that other platforms return 'quote not available' with the reason and order link. It also invokes the sequencing rule that reading, quoting, requesting and ordering stay separate. It stops short of explicitly naming a sibling as the alternative when a full order is actually wanted, so it is clear context rather than complete routing.

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

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

Annotations already mark this as a safe, non-destructive, closed-world read, but the description adds behavior those annotations cannot express: waiting is not a promise of an answer, nothing calls back afterwards, hanging up does not cancel the request, and results are candidates rather than proof. It also states that at most 45 of the requested seconds are used, which the schema does not say. That is unusually rich beyond annotation coverage.

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 with the state vocabulary, then the wait semantics, then safety guidance, so the agent meets the most decision-relevant facts first. The backtick-dense enum listing and the quoted server-instruction boilerplate add bulk, but every sentence carries operational meaning; it is dense rather than padded.

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 must explain the returned state values, and it does so exhaustively, including the subtle distinction between `available` (free but NOT booked) and `confirmed` (booked). It also covers waiting, re-polling, and permission gating, leaving nothing an agent needs to call and interpret 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 coverage is only 50%: `request_id` is undocumented in the schema, and `wait_seconds` has a short schema note. The description compensates by explaining that `wait_seconds` defaults to 0 (answer now) and that at most 45 of the allowed 60 seconds are actually used, which is meaningful beyond the schema. `request_id` still gets no explanation of what it identifies or where it comes from, keeping this 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 description states a specific verb and resource: it returns what became of a request to the owner, enumerating both delivery states (`sent`, `link_given`, `expired`, `failed`) and owner outcomes (`declined`, `other_time` + proposal, `available`, `confirmed`). That is far more specific than the title alone. It never names the sibling it differs from, `order_status`, although the phrasing 'request to the owner' does suggest a distinct resource, so a 4 rather than a 5.

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

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

It gives real usage guidance: if the request is still waiting, call `request_status` again later, for example 'when the person asks'. It also clarifies that hanging up does not cancel the request, implying re-polling is normal. However, it never explicitly says when to use this instead of `order_status` or when to prefer a fresh `request_to_owner`, so it falls short of explicit 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?

Annotations cover non-read-only, open-world and idempotent, but the description goes well beyond them: it explains that the same idempotency_key never creates a second request, enumerates the three result states and what each means for what was actually sent, and specifies the post-call obligations (tell the person it is not a booking, where the answer goes, when to schedule request_status). That is exactly the context an agent needs before mutating anything.

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 highest-stakes warning (acts for the user), then scope, then payload, then result states, then follow-up duties. Nearly every sentence carries operational value, though the browser-instruction tail repeats ground already covered by the server instructions and the emoji-flagged opening is a little shouty.

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 nine-parameter mutating tool with a nested customer object and no output schema, the description covers precondition, scope, idempotency, all three return states, the whatsapp_url handoff, and the required follow-up narration. An agent could invoke it correctly and handle every outcome without further information.

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

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

Schema coverage is 67% and the description supplies meaning for the important gaps: it enumerates the payload fields in plain language, explains idempotency_key semantics and the retry contract, and clarifies that next_steps.check_again_after is a pause rather than a promised reply time. It does not add anything about date/time locality or the quantity bounds beyond what the schema already 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?

The description names a specific verb and resource ('Sends what, when, how many, which branch and the person's name and contact') and immediately scopes it to businesses that take requests through Versum via a verified owner. The title and opening line make clear it is a request, not a booking, which separates it from siblings like book_slot and place_order.

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

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

Gives an explicit precondition ('call it only after the user has explicitly agreed to this exact action') and states it is never to be used on the agent's own judgement. It also names the fallback outcomes (link_given, no_channel) that redirect the agent elsewhere, and closes with the separation rule that requesting must stay distinct from reading, quoting and ordering.

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 readOnly/openWorld annotations, the description explains how results should be interpreted: match.fit levels, nothing_fitting, per-business met/violated/unknown conditions, and the fact that no location and no fit yields an empty list rather than unrelated businesses. It also warns that results are candidates and that nothing is sent, booked, ordered, or paid without permission, which is exactly the behavioral context an agent needs.

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

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

The first paragraph is well front-loaded and useful, but it is followed by a massive, typo-ridden coverage list of dozens of trades and cities that dominates the description and consumes far more context than its navigational value justifies. The core semantics are buried under this data dump.

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, but the description explains the key return semantics: best-fitting items first, match.fit interpretation, condition outcomes, and the empty-list case. It defers detailed card structure to the cards themselves, which is reasonable, though the enormous coverage list does not compensate for not describing card fields directly.

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 input schema has 100% description coverage and documents all 11 parameters in detail, so the baseline is 3 even without extra parameter explanation in the description. The description only restates location/default-radius context and condition semantics rather than adding new parameter syntax or format guidance beyond the schema.

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

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

The opening sentence states a specific verb and resource: search for an item, dish, or service by meaning near a location within a default radius, for when the trade is not known. It clearly distinguishes the tool from a known-trade lookup in spirit, but it does not explicitly name a sibling such as find_business as the alternative.

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 'when the trade is not known' gives clear when-to-use guidance, and the no-location behavior is explained. It stops short of explicitly naming when to use find_business or other sibling tools instead, so the guidance is clear but not fully routed.

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