Onhand

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

Annotations already cover read-only, idempotent, non-destructive, closed-world, so the description wisely spends its words on what they cannot express: answers come only from business-approved FAQs (labelled "from the business") and owner-approved website facts with evidence URLs, a false-answer fallback path exists, and answers are never composed or inferred. That grounding guarantee is exactly the behavioral context an agent needs before quoting this tool to a user.

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

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

Four short sentences ordered as purpose, return contents, failure mode, then the non-inference guarantee, so the most important facts are front-loaded. Slightly redundant between "Returns only answers from the business's approved FAQs" and "Answers are never composed or inferred", though each adds a distinct constraint.

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 appropriately spells out the return shape: provenance labels, evidence URLs, and the answered:false case. The one gap is provenance of the `business_id` input, which for a two-required-parameter tool with no schema descriptions would be worth one clause.

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 carry parameter meaning; it partially does by illustrating the style of a valid `question` ("do you take walk-ins?", "is there parking?"), conveying natural-language phrasing without stating the 3-300 character bounds. `business_id` is completely unaddressed, including where an agent obtains one, leaving real ground uncovered at 0% schema coverage.

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 ("Asks a business a specific question") and immediately scopes it with concrete example questions, which separates it from siblings like get_business or search_local_offerings. The first sentence alone is enough to route an agent correctly.

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 example questions and the "approved FAQs / owner-approved website facts" scope clearly convey the kind of factual lookup this tool serves, and the answered:false branch tells the agent the tool will not fabricate. It never names an alternative tool or an explicit "don't use this for X" exclusion, so routing between it and get_business/report_business_facts is left implicit.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavior: availability may be withheld when the shop is listed or when data is stale — a non-obvious conditional outcome an agent could not infer from the schema or 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 short sentences with zero filler, and the decision-relevant constraint (use before committing) is front-loaded ahead of the caveat.

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

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

No output schema exists, so the description owns the return contract, and 'availability is withheld' is left ambiguous — null, empty field, false, or an error is unspecified. For a single-parameter read tool the coverage is close to adequate but leaves the primary result shape undefined.

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

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

There is one required parameter at 0% schema description coverage, so the description carries the full burden — but it says nothing about offering_id (where to obtain it, whether it comes from search_local_offerings, or what an invalid id does). The name is self-explanatory, which keeps this above 1, but no compensating information is supplied.

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

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

States a specific action (re-confirms availability) on a specific resource (one offering) and frames it as a pre-commitment gate, which distinguishes it from the search/prepare/confirm siblings conceptually. It never names an alternative tool, so differentiation requires inference.

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

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

'before committing' implies the call belongs between prepare_booking/search_local_offerings and confirm_booking, but no sibling is named and no explicit when-not condition is given. The second sentence describes response behavior, not invocation 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 the mutation profile (readOnly=false, destructive=true, openWorld=true, non-idempotent), so the description correctly focuses on behavior the annotations can't express: revalidation of the frozen destination or Square catalog, the two possible outcomes (handoff record vs. Square booking creation), and that no payment is taken. It does not say what happens when revalidation fails or how a partial/failed confirm is surfaced.

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

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

Three short sentences, front-loaded with the action and its input source, then side effects, then the payment boundary. No sentence is filler — even the payment note prevents the agent from misrepresenting the flow to a user.

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 for an open-world, destructive, non-idempotent mutation the description covers inputs, side effects, and the payment boundary well. Gaps remain around the result shape (confirmation id? handoff status?) and failure/rollback semantics after revalidation.

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 0% — the schema only says 'string, 1-200 chars'. The description supplies the missing meaning: the value is the intent produced by prepare_booking, i.e. an opaque token with provenance, not free text. It still doesn't say how long an intent stays valid or whether a failed confirm invalidates it.

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

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

States a specific verb and resource ("Confirms one prepared booking") and anchors it to the sibling it depends on: the intent comes from prepare_booking. An agent can immediately tell this apart from prepare_booking, confirm_booking_cancellation, and the handoff-confirm 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?

The prerequisite (intent from prepare_booking) and the 'once' constraint are stated, which implicitly rules out retry loops. What's missing is any explicit exclusion or alternative routing — e.g. when to use check_availability first, or which of the sibling confirm_* tools handle cancellations/handoffs.

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

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

Annotations already declare destructiveHint, idempotentHint and openWorldHint, so the bar is lower, yet the description adds real context: retry safety via intent reuse, reconciliation on ambiguous provider responses, the external Square dependency, and the money boundary (no refunds, no fund movement). What's missing is what a confirmed cancellation actually returns or what failure states look 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?

Three dense sentences, each carrying a distinct load: identity, retry/reconciliation behavior, and financial scope. The core action is front-loaded and 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 destructive, idempotent, one-param mutation tool with full annotation coverage and no output schema, the description covers safety, retry semantics, and side effects on money. The residual gap is the intent parameter's provenance/format, which is the one thing an agent must get right to call it.

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 0% — `intent` is only typed as a 1-200 char string. The description partially compensates by framing intent as a stable handle for a prepared cancellation whose reuse polls status instead of re-sending, which is meaningful semantics. It still never states where the agent obtains the intent value or what form it takes.

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 ("Confirm one prepared Square cancellation") and narrows scope with "one" and "prepared", which implicitly points at the prepare/confirm two-step pattern. It stops short of naming prepare_booking_cancellation explicitly, so the sibling differentiation is inferable rather than stated.

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 operating guidance: an ambiguous provider result means reconcile rather than retry a new cancellation, and repeating the same intent is the way to poll status. It does not explicitly say 'call prepare_booking_cancellation first' or name the alternative tool, but the when-to-call context is clear.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true and idempotentHint=false; the description earns credit for adding what those flags cannot: revalidation of the frozen item, price and destination, the fact that an external artifact (URL handoff, Square payment link, Shopify checkout) is created, and that Onhand never takes payment. It stops short of covering failure/retry behavior or whether a created link can be revoked.

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

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

Three tight sentences, front-loaded with the core action, then the side effects, then the payment-responsibility caveat. No filler or repetition.

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 one parameter and no output schema, the description carries the burden of explaining outcomes, and it names the three possible handoff results plus the payment boundary. It leaves the agent guessing slightly about the return payload and what happens on revalidation failure, but covers the decision-relevant surface.

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 single parameter has 0% schema description coverage, but the description compensates by explaining that 'intent' is the opaque token returned by prepare_checkout and that it encodes frozen item, price and destination. That is real meaning beyond the schema's bare string constraint, though the maxLength/format expectations remain undocumented.

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 ('Confirms a prepared checkout') scoped by 'once using the intent from prepare_checkout', which cleanly separates it from the sibling prepare_checkout. An agent can tell exactly what this tool does without opening the schema.

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

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

The prerequisite is explicit: it consumes the intent produced by prepare_checkout, and 'once' signals it is a single-shot confirmation. It does not state when not to use it or what to do if the confirmation fails, which keeps it 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 declare readOnlyHint=false, idempotentHint=false and destructiveHint=false; the description earns credit by explaining *why* it is not idempotent ('once') and by clarifying the side effect's boundary ('records the handoff but does not submit the request; the shopper provides details on the provider's site'). The only gap is failure behavior for an expired/invalid intent, which 'revalidated' only hints at.

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

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

Two sentences, zero waste: the action and return value come first, and the scope disclaimer follows. Nothing repeats the schema or annotations verbatim.

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 states what comes back (the revalidated provider URL), what the side effect is, and what happens downstream on the provider site. What's missing is only edge-case behavior when the handoff cannot be confirmed or the intent has already been consumed.

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 0% and the single 'intent' parameter is otherwise opaque, but the description supplies its provenance — the value must come from prepare_quote_request rather than be constructed by the agent. That is genuine meaning beyond the schema's type and length constraints, though no format or expiry semantics are given.

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 ('Confirms a prepared quote handoff') and distinguishes itself from the upstream sibling by naming prepare_quote_request as the source of the intent. An agent can tell this is the second half of a two-step quote flow 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 prerequisite is explicit: it consumes the intent produced by prepare_quote_request, so the agent knows this is a terminal confirm step, not a standalone action. It does not, however, differentiate itself from other confirm_* siblings (confirm_checkout_handoff, confirm_booking) or state when not to call it.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, and the description adds substantial context on top: the change is frozen from prepare time, the call is single use, it expires in ten minutes, and it is bound to the sign-in identity that prepared it. That is exactly the operational detail an agent needs before committing a destructive, non-idempotent write.

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

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

Three short sentences, front-loaded with the action and the source of the change, then the non-obvious constraints. No filler and nothing repeated from the title.

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

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

For a one-parameter destructive confirmation tool with a rich annotation set and no output schema, the description covers staging, single-use, expiry and identity binding well. The remaining gap is what 'intent' should contain and what a successful apply returns or fails to do.

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?

'intent' is undocumented in the schema (0% coverage) and the description never defines its format or purpose. It does add one useful clarification, that the real change payload is not passed here, which limits the risk of the agent stuffing change data into this argument, but the semantics of the single required parameter remain 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 names a specific verb ('Apply') and an exact resource ('a listing change staged by update_company_profile'), and it explicitly pairs this tool with the sibling that stages the change, so an agent can distinguish it from prepare-style and other confirm_* 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?

It clearly places this tool after update_company_profile and warns that the arguments supplied here are ignored, which is real usage context. It stops short of naming explicit exclusions or failure conditions beyond the expiry and single-use rules.

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 by disclosing the frozen-payload semantics ('applies the hours that were frozen at prepare time, never hours supplied here'), single-use consumption, a concrete ten-minute expiry, and sign-in binding. These are exactly the behavioral facts the destructive/non-idempotent hints cannot convey.

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

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

Three tight sentences, front-loaded with the action and the source of data, with constraints packed into the final clause. No filler; slightly dense with clauses stacked in one sentence but nothing 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 destructive, non-idempotent one-parameter mutation with no output schema, it covers preconditions, payload provenance, and lifetime. The remaining gaps are the unexplained 'intent' argument and what happens on expiry or partial failure, which slightly under-prepare the agent.

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 sole parameter 'intent' has 0% schema description coverage, and the description never mentions it — no format, no expected content, no relation to the staged change. At 0% coverage the description needed to compensate and does not, leaving the agent to guess what value to supply for the required field.

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 ('Apply opening hours staged by update_hours') and explicitly names the sibling that stages the data, so an agent can distinguish it from update_hours at a glance. The prepare/confirm relationship is stated outright rather than inferred.

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?

Makes clear this is the second step of a two-phase flow, only valid after update_hours has staged changes, and adds eligibility constraints (single use, ten-minute expiry, same sign-in). It lacks an explicit 'if the window expired, call update_hours again' instruction, but the preconditions are unambiguous.

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 establish read-only, idempotent, non-destructive safety; the description layers on genuinely non-obvious behavior: radius widening at 8/16/32/50 km steps, the wider_search envelope with deduplicated results, city-specific statuses (matched/none_in_city/unrecognized), data_coverage and gaps semantics, and the guarantee that suggested actions are never executed by Onhand. Nothing here contradicts the annotations, and no other field carries this information.

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

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

The purpose is front-loaded, but the body is a dense wall of internal jargon (wider_search, matchedOn, data_coverage, gaps, release gates) with several telegraphic fragments such as 'Preserve request_area, public listing-request links and contact next steps.' Most sentences carry real information, but the lack of grouping or formatting makes it harder to parse than its 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 an 8-parameter, nested-object tool with no output schema, the description covers widening behavior, result envelopes, coverage fields, city fallbacks, and non-claims (no stock/price/slot assertions) in substantial depth. The main omission is sibling routing; return-shape explanation is unnecessary since no output schema exists.

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

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

Schema description coverage is 0% across 8 parameters, so the description must carry the load, and it largely does: q is defined as the shopper's want, category as business type, attributes as offering-only narrowing, city as a name/slug/neighborhood that replaces the radius, and research_fact_types as shopper-relevant facts with a capped URL yield. It stops short of stating radius_m's units/default explicitly (only the widening steps are given), leaving one gap.

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?

Opens with a specific verb and dual resource: 'Searches matching offerings and nearby directory businesses together', which implicitly separates it from the offerings-only and businesses-only siblings. However, it never names search_local_offerings or find_nearby_businesses, so the agent must infer the boundary rather than being told it.

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

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

Usage is implied by the combined-search scope and by scattered conditions ('City searches do not widen', 'Never treat directory alternatives as confirmed item or requirement matches'), but there is no explicit when-to-use/when-not statement and no routing against the many sibling search tools. The agent is left to infer selection criteria.

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, idempotent, non-destructive, closed-world, so the description adds real value instead of repeating them: it discloses that rows and the envelope carry `data_coverage` scoped to directory identity only, that unknown evidence dates stay unknown, and that an empty name match does not imply city-wide absence. Those are non-obvious interpretation caveats an agent would otherwise get wrong.

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

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

Four short sentences, front-loaded with the verb and scope before the caveats. Terms like 'envelope' and 'data_coverage' are terse but each sentence carries distinct information, so nothing reads as 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 2-param read-only lookup with no output schema, the description covers the input intent, the return value (ids for get_business), and the coverage/empty-result semantics. The only meaningful omission is how name matching works, which matters for interpreting an empty result.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It does clarify that `near` takes a town or street (the param name alone suggests a coordinate or radius) and that it is optional, but it says nothing about `name` matching behavior (exact vs partial, the 3-char minimum) or the 120-char limits.

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 ('Finds a business by name') plus the optional narrowing dimensions, and indicates the output is ids meant for get_business. It also gestures at the sibling distinction ('a shopper names a shop rather than a place'), though it never names find_nearby_businesses or discover_local 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?

'Useful when a shopper names a shop rather than a place' gives a clear selection condition, and 'Returns ids for get_business' documents the follow-up step in the pipeline. No explicit exclusions or named alternatives, which keeps it 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?

Much of the description is unusually transparent about widening steps, wider_search deduplication, city result statuses, zero-match interpretation, source labeling, and suggestedActions not being automatic. But it also states that 'For a signed-in caller, category-only misses are recorded for those shops,' which describes a persistent side effect contradicting readOnlyHint=true; per the rules, this is an annotation contradiction.

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

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

The description is a dense, run-on paragraph packed with field names and repeated city/radius caveats. It front-loads the purpose, but it is far longer than needed and several sentences are cryptic rather than efficient.

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?

Given 7 parameters, no output schema, and complex widening/city behavior, the description covers return fields, ordering, data_coverage, missing/gaps, city result statuses, and edge cases. An agent has enough information to call it correctly, apart from the readOnly contradiction.

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 has to carry parameter meaning. It explains city versus radius behavior, lat/lng requirements and the ChatGPT exception, q matching, radius widening steps, and the purpose of research_fact_types, though it leaves radius_m units/default and enum semantics mostly 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 opening sentence states a specific verb and resource: 'Searches published businesses' with scope 'nearby, serve the area, or operate online.' It does not name sibling tools such as discover_local or find_business, so differentiation is implicit 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 gives some situational rules, including city versus radius behavior, thin-radius widening, and the ChatGPT location fallback. However, it never explicitly says when to choose this tool over discover_local, find_business, or search_local_offerings, so usage is only implied by parameter combinations.

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 this as read-only, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely useful behavioral context: access is limited to the signed-in shopper, and a 'requested handoff' status must not be conflated with a completed provider booking.

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

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

Two tight sentences with no wasted words. The core operation is front-loaded, and the important status caveat follows immediately.

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

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

This is a simple one-parameter read tool, and annotations cover the safety profile. However, with no output schema, the description does not explain what status values may be returned or how to interpret them beyond the handoff caveat, leaving a meaningful gap for a status-checking tool.

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

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

There is one required parameter, action_id, and schema description coverage is 0%; the schema only supplies UUID type/format/pattern without semantic description. The description refers to 'one booking action' but does not explain where action_id comes from, what it identifies beyond a booking action, or how to obtain it.

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

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

The description states a specific verb and resource: 'Get the status of one booking action,' scoped to 'this signed-in shopper.' It clearly identifies a read/status-check operation, though it does not explicitly differentiate itself from sibling tools such as report_action_outcome or confirm_booking.

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

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

Usage is implied by 'belonging to this signed-in shopper' and the caveat that a requested handoff is not a completed provider booking, which helps an agent interpret what status means. However, it does not state when to use this tool versus alternatives like report_action_outcome or any prerequisites.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds context beyond them: the auth scope needed (billing:write) and a clarification that the returned link does not mint a Stripe portal session. It still doesn't say whether the link expires or is single-use.

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

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

It is short and the exclusion is front-loaded, but the opening sentence is a verbless fragment that reads as a continuation rather than a definition, forcing the agent to reconstruct the purpose from the name.

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

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

With no output schema and no parameters, the description carries the full burden of explaining the return value, yet it never says what a 'billing link' is (URL string? object with expiry? one-time?). The auth and exclusion notes are helpful but the result shape is left unspecified.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The auth-scope note is the only input-adjacent detail and it is present.

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 describes the destination ('where the merchant manages their subscription') but never states the actual action, that the tool returns a billing link/URL. The name and title carry most of the meaning; the text distinguishes it from get_connection_link and get_subscription only implicitly by topic.

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 a useful negative constraint ('It does NOT open Stripe's portal: that session is minted on the API') and a prerequisite ('Requires billing:write'), but no positive statement of when to call this versus get_subscription or get_connection_link.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description still adds substantial context: confirmed vs unconfirmed facts, evidence URLs and source dates, coverage classes, and the guarantee that suggestedActions are never executed. It stops short of stating not-found behavior or whether hours carry a timezone.

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 return summary, which is good, but the body is a dense unbroken run of caveats. The open-now point is made three times ('Operating status does not establish open-now hours', 'Posted hours are not open-now', 'These facts carry no availability claim'), which is redundant.

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

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

With no output schema, the description carries the full burden of explaining the payload, and it does so thoroughly field-by-field (evidence, conflicts, capabilities, coverage, hosted/hostedBy). Gaps are minor: id provenance and error/empty-result behavior.

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 single id parameter carries no documented meaning beyond a UUID pattern. The only hint is the passing mention that hosted/hostedBy entries 'have their own id for get_business'; the description never says the id comes from find_business/discover_local results or what happens with an unknown id.

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

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

States a concrete verb and resource plus scope: 'Returns a published business profile, hours, area, and rating.' That clearly distinguishes it from write siblings and from the search siblings (find_business, find_nearby_businesses), though it never names them explicitly as the retrieval path that produces the id.

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

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

Usage is only implied: the required id plus 'each has its own id for get_business' suggests a detail-fetch after a search or after finding a hosted/hostedBy reference. There is no explicit when-to-use/when-not or pointer to find_business/find_nearby_businesses as the way to obtain an id.

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, idempotent, closed-world and non-destructive semantics, so the bar is lower. The description adds real value beyond them by naming the required scope (company:read) and clarifying that the caller cannot target another entity.

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

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

Two sentences, zero filler, with the core behavior front-loaded before the auth and scoping caveats.

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, yet it only says 'the company' without indicating the fields or shape returned. Adequate to call it, incomplete for interpreting the result.

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

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

Zero-parameter tool, so the baseline is 4. The sentence 'takes no company identifier from the caller' usefully explains why the schema is empty rather than leaving the agent to wonder if a parameter was omitted.

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 ('Return the authenticated merchant's own company') and scopes it to the caller's own entity rather than an arbitrary one. This implicitly separates it from get_business, but no sibling is named, so an agent must infer that distinction.

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 prerequisite 'Requires company:read' is stated and the phrase 'takes no company identifier from the caller' hints at the contrast with an identifier-based sibling, but there is no explicit when-to-use vs get_business guidance or exclusion.

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

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

Annotations already cover the read-only, idempotent, non-destructive, non-open-world profile, and the description adds real value beyond them: it discloses that the caller needs connections:write, that this service lacks the credentials to complete consent/confirmation/revocation, and that the response carries an explanatory sentence. The apparent tension between readOnlyHint=true and a write scope is disclosed rather than contradicted, which is exactly the 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 length is reasonable and there is little filler, but the opening is a relative clause ('Where the merchant connects...') instead of the front-loaded statement an agent needs — 'Returns a dashboard link for...'. The key fact, that this returns a link rather than performing anything, arrives late and only implicitly.

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 two-parameter, read-only tool with no output schema, the description covers the security scope, the hard capability limit (no credentials for consent/revocation), and hints at the return payload ('plus a sentence saying what happens there'). What is missing is a concrete statement of the returned link's form and per-action expectations, but the critical call-safety facts 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?

Schema description coverage is 0%, so the description must carry parameter meaning, and it only partly does. It enumerates the action values in prose (connect, reconnect, map_locations, disconnect) and implies that consent/location confirmation/revocation map to specific action branches, but the provider parameter and the returned-link semantics for each action are never explained; the enums do much of the remaining work.

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 domain (connecting/reconnecting/mapping/disconnecting a POS or catalog source) and explicitly states it does not perform the action, but it never plainly says it returns a link/URL to a dashboard page. An agent must infer the return from the tool name and the oblique phrase 'Where the merchant connects...' rather than from a stated verb+resource.

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

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

It clearly carves out what the tool is not for — consent, location confirmation and revocation happen in the dashboard, not through this service — which tells the agent when not to expect completion. However, it gives no explicit routing versus siblings such as list_connections or get_billing_link, so the choice among related tools is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral context beyond that: slots are offers rather than holds, no payment is taken, and stale-sync or already-started slots are omitted rather than guessed — which tells the agent how to interpret gaps in results. It stops short of describing limit/pagination behavior.

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

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

Three short sentences with no filler; the core scope and ordering are front-loaded, and the caveats about staleness and non-reservation follow in service of that. Nothing repeats the name or the annotations.

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

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

With no output schema, the description does well to explain what a returned slot means (an offer, not a hold) and why some slots are absent. However, for a read tool with a 3-parameter schema, leaving limit and offering_id semantics entirely undocumented leaves a real gap 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 0%, so the description must carry parameter meaning, but it only covers business_id implicitly ('at one business'). The limit parameter (default 10, max 20) and the offering_id filter are never explained — an agent cannot tell that offering_id narrows slots to a single offering type.

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

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

States a specific resource and scope: open appointment windows at exactly one business, returned soonest first. The scope and ordering make it distinguishable from broad search tools, but it never mentions the closely related sibling check_availability, so the boundary with that tool is left to inference.

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

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

Usage is only implied: an agent can infer this is the read step that precedes prepare_booking/confirm_booking. There is no explicit statement of when to use this versus check_availability, search_local_offerings, or find_nearby_businesses, and no preconditions are given.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds two pieces of real value beyond that: the required auth scope (billing:read) and a data-boundary guarantee ('Never returns Stripe identifiers'), which tells an agent what it will not get back.

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

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

Three short sentences, front-loaded with what the tool returns, followed by the auth requirement and the exclusion. No filler, no restatement of the title.

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

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

There is no output schema, so the description carries the burden of describing the return shape, and 'what the organization is paying for' is vague about whether that means plan name, seats, price, billing status, or renewal date. The auth and exclusion notes help, but an agent still cannot predict the response structure.

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?

Zero parameters, so there is nothing for the description to disambiguate — baseline 4 applies. Implicitly scoped to 'the merchant's organization' rather than an arbitrary ID, which is consistent with the empty 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 names the resource precisely — the merchant organization's paid subscription — which is distinct from siblings like get_billing_link or get_company. It reads as a noun phrase rather than an explicit verb+resource, but the intent (fetch current subscription/plan info) is unambiguous.

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

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

No guidance on when to call this versus get_billing_link, get_company, or get_action_status, all of which appear in the sibling list and could plausibly be confused with billing/account queries. The caller must infer the trigger condition entirely.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the bar is lower, yet the description still adds two pieces of context: the required auth scope and a negative disclosure that provider identifiers, cursors and error text are never returned. That last point is genuinely useful because it tells an agent this result cannot be used to diagnose sync failures.

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, no filler. The subject of the response is front-loaded, followed by the permission requirement and the exclusion note in descending order of importance.

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

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

With no output schema and no parameters, the description carries the return-shape burden and does so adequately by naming the entities and the sync-status field plus what is omitted. Minor gap: it does not hint at whether an empty connection list is a normal state or what the sync-status values can be.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The description correctly stays silent on inputs rather than inventing filtering options.

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 the specific resource (connected point-of-sale and catalog sources) and the key derived attribute (whether each is syncing), scoped to the merchant. It does not explicitly differentiate itself from related siblings such as get_connection_link, but the resource is unmistakable.

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

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

'Requires connections:read' gives a prerequisite, which implies this is the read path for inspecting connection state. However, there is no explicit statement of when to use this versus get_connection_link or get_action_status, and no exclusions are offered.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered; the description adds value by disclosing the required auth scope ('company:read') and that no caller-supplied identifier is accepted. It does not, however, say what happens if the merchant has no locations or whether the result set is paginated.

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 auth precondition is stated up front. The opening sentence is a fragment that describes the returned resource rather than the action, which slightly hurts front-loading.

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 no-parameter, read-only list under strong annotations, the essentials are present: merchant scoping, auth scope, and absence of inputs. What a location record contains and whether results are paged are unknowns, but they are minor for this complexity level.

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

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

The tool takes zero parameters, so the schema carries all burden and the baseline is 4. The description correctly reinforces that no identifier or filter is accepted, avoiding a false expectation of arguments.

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 the merchant's trading locations and scopes it to the authenticated merchant, but it is a noun-phrase fragment with no verb, so it never explicitly states that it lists/returns them. An agent must lean on the title 'List my locations' to recover the action. It does implicitly differentiate from get_business/find_business (plural, self-scoped, no identifiers).

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 versus siblings such as get_business, list_connections, or list_subjects. The phrase 'takes no identifier from the caller' hints that this is an unfiltered self-scoped listing, but no explicit condition or alternative is named.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds real behavioral context beyond them: an empty collection is the expected result when no membership exists, meaning the agent should not treat an empty list as an error.

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, both load-bearing: the first states scope, the second states the empty-result behavior and the recovery path. No preamble or restatement of the title.

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

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

With no output schema, the description carries the burden of explaining the return, and it does so at least for the empty case. It never says what a populated result contains (identifier, name, role), so the agent knows when it is empty but not what it can extract when non-empty.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; the empty-schema situation is handled correctly.

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

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

The description gives a specific verb and resource ("List the organizations this sign-in belongs to") and scopes it to the caller's own memberships, which distinguishes it from business-search siblings like find_business. It does not, however, reconcile the name (list_subjects) with the term "organizations," nor distinguish it from select_subject, so an agent must infer that a subject is an organization.

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 supplies a clear calling context (fetch the memberships tied to the current sign-in) and an explicit follow-up branch: when the result is empty, call setup_account before claiming a business. It stops short of naming select_subject as the downstream consumer of these results, so the routing between the two is left implicit.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description still adds real value: a hard cap of twenty results, an explicit prompt-injection warning that review text is untrusted data, and a disclosure of what is deliberately omitted (shopper identity, booking identifier, provider reference). The one gap is that the 'up to twenty' cap implies no pagination without saying so or how to get more.

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

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

Three tight sentences, each doing distinct work: scope first, safety warning second, return-surface limits third. Nothing repeats the schema or the annotations.

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 steps in to characterize the return set (count ceiling, excluded identifiers), which is exactly what an agent needs. It stops short of describing ordering, pagination/continuation behavior, or the review fields (rating, date) that likely come back.

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% and the single parameter business_id is never named in the description, so the agent must map 'a published business' to it themselves. That phrase does carry meaning — the business must be published/listed, not merely known — which partially compensates for the missing parameter documentation.

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

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

Specific verb ('Reads') plus a precisely scoped resource ('up to twenty receipt-backed reviews of a published business'), which is far more informative than the title alone. The read-only framing implicitly separates it from the write sibling submit_verified_review, but that sibling is never named.

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

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

Usage is only implied: the agent can infer this is the retrieval path for a business's reviews, but there is no statement of when to call it versus submit_verified_review or ask_business, and no prerequisites (e.g. must the caller own or have claimed the 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?

It adds genuinely useful behavior (Square vs. URL handoff, no payment taken, exact return payload), but 'Changes nothing' directly conflicts with annotations declaring readOnlyHint=false, and the tool requires an idempotency_key while declaring idempotentHint=false — an unexplained tension an agent could act on incorrectly. The safety profile presented in prose does not match 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?

Three tight sentences: purpose first, then the branching behavior, then the guarantees and return shape. No filler, and the most decision-relevant fact (what happens on confirm) is front-loaded.

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

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

With no output schema, the description usefully enumerates what comes back (provider, destination, price when applicable, consequence to approve), which is exactly the compensating detail needed. The remaining gap is parameter meaning and failure/prerequisite conditions for a 5-param mutation-adjacent tool.

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

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

Schema description coverage is 0% across 5 parameters and the description explains none of them: the role of business_id vs. offering_id vs. slot_id, when each is optional, or what handoff_kind actually selects is left entirely to the enum. The required idempotency_key — the single field whose semantics most need explanation given the conflict with idempotentHint — is unaddressed.

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

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

Specific verb (prepare) plus resource (reservation/appointment), and it crisply explains the two outcomes: a live Square Appointments connection books on confirm, everything else becomes a provider-hosted URL handoff. That contrast implicitly separates it from confirm_booking and from the other prepare_* siblings without the agent needing to open 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?

The 'on confirm' phrasing plus 'returns ... for the shopper to approve' makes clear this is the pre-commit, information-gathering step that precedes a confirming call. It stops short of naming confirm_booking explicitly or stating exclusions (e.g., when slots are unavailable, use get_open_slots/check_availability first).

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

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

Adds real context beyond the annotations: 'Changes nothing upstream' and 'Onhand does not refund or move money' clarify the non-destructive nature despite readOnlyHint=false, and the ten-minute intent expiry is a useful behavioral trait. It does not explain what happens if the intent expires or whether repeated calls with the same idempotency_key are deduplicated, despite idempotentHint=false.

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

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

Three short sentences, each carrying distinct information: eligibility scope, return behavior, and side-effect boundary. Front-loaded with the constraint and 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?

With no output schema, the description correctly explains the return value (a ten-minute intent with the exact consequence) and the no-upstream-change guarantee. The remaining gap is the undocumented parameters, which is the only thing an agent still needs.

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% and the description never mentions booking_id or idempotency_key. With two required parameters entirely undocumented in both schema and description, the agent gets no guidance on format, source of the booking_id, or idempotency semantics.

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

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

States a specific verb (prepare) and resource (booking cancellation) plus a scope constraint: only Square appointments created for this shopper. It implies the two-step flow via 'returns a ten-minute intent' but never names the sibling confirm_booking_cancellation, so differentiation is inferential 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?

The 'only for a Square appointment Onhand created for this shopper' clause gives a clear eligibility condition, and 'returns a ten-minute intent' signals this is the first of a two-step prepare/confirm flow. It stops short of explicitly saying when to skip this and call confirm_booking_cancellation directly.

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 say readOnlyHint=false, destructiveHint=false, so the key added value is 'Onhand takes no payment' plus the approval-before-confirm pattern and the fact that non-Square/Shopify shops hand off a provider-hosted URL. Useful context beyond the hints, though it never addresses the required idempotency_key or what happens on retry given idempotentHint=false.

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

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

Three short sentences, no filler: scope first, provider-variant behavior second, return value and payment posture last. Every sentence adds information an agent needs.

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

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

With no output schema, the description still says it returns listed price and destination for approval, and it clarifies the two funnel paths and that no payment occurs. What's missing is error/failure behavior and the meaning of the idempotency key, but the core decision path 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 description coverage is 0%, so the description must carry the params, and it explains only offering_id indirectly ('one currently available item'). business_id and especially idempotency_key (which is required while the annotation says idempotentHint=false) are never explained, leaving a real gap.

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 ('Prepare checkout') and constrains scope to 'one currently available item', which separates it from the confirm_* siblings. It stops short of naming an alternative tool, so it is clear but not fully differentiated.

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 mention that eligible Square/Shopify connections 'create hosted checkouts on confirm' implies this is the pre-step to confirm_checkout_handoff, but the link is never stated explicitly and no when-not-to-use guidance is given (e.g., what to do if the item is no longer available).

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-destructive, closed-world, non-read-only behavior. The description adds useful scope context by stating that no contact details or project description are accepted or sent, but it does not explain what the prepare step actually creates, how long the handoff remains valid, or why an idempotency key is required despite idempotentHint=false.

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

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

Two short sentences with no filler. The core action is front-loaded, and the second sentence adds a meaningful constraint rather than restating the title.

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

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

There is no output schema, and the description only briefly gestures at the return value ('show exactly where the shopper will continue'). With two required parameters at 0% schema coverage and no explanation of idempotency behavior, the definition is not complete enough for an agent to call it confidently.

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% for both parameters. The description only vaguely implies that business_id identifies the 'verified quote destination' and says nothing about idempotency_key, so it does not compensate for the undocumented 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 and resource: prepare a handoff to a verified quote destination. It is clear what the tool does, but it does not explicitly distinguish itself from the sibling confirm_quote_handoff, leaving the prepare-vs-confirm boundary to inference.

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

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

The phrase 'currently verified quote destination' implies a precondition, but the description never states when to use this tool versus confirm_quote_handoff or what to do if no verified destination exists. Usage is implied rather than guided.

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

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

Beyond the annotations it discloses the side effect ("a failure queues a re-check of the link"), the write-once constraint, the 72-hour window, and the authorization scope (signed-in shopper only). That is exactly the context the destructiveHint/idempotentHint flags cannot convey on their own.

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

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

Three tight sentences, front-loaded with what is reported, then constraints, then the semantic boundary. Every clause carries distinct information; nothing is repeated from the schema or annotations.

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 2-parameter write with no output schema, the description covers purpose, scope, timing, and the failure side effect. It stops short of saying what the call returns or what error surfaces on a duplicate report or a call after 72 hours.

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 carry the load. It enriches the outcome values ("failed (dead link or broken form)") and the once-per-action framing explains action_id's role, but it never says where action_id comes from or what shape it takes beyond the schema's uuid pattern.

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

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

Specific verb plus resource: reports whether a confirmed booking, order, or quote handoff completed, failed, or was abandoned. The enumerated outcome vocabulary lets an agent distinguish it from confirm_*_handoff siblings and from get_action_status 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?

"Once per action, within 72 hours, for this signed-in shopper only" gives concrete preconditions for calling it. The closing sentence routes the agent away from misuse ("not a receipt: it never completes a booking or backs a review"), implicitly pointing at confirm_booking and submit_verified_review, though no sibling is named explicitly.

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 write/non-destructive/non-idempotent; the description adds substantial context beyond them: evidence 'enters quarantine for verification', the receipt 'grants no publication authority', and collection is gated. These are the genuinely useful facts an agent needs before writing. It stops short of describing what a successful call returns or whether resubmission duplicates data — consistent with idempotentHint=false but never stated.

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 action and its bounds are front-loaded in the first sentence, and the remaining sentences are short and each carries a distinct constraint (consent, exclusions, quarantine, gating). A few phrases are compressed to the point of jargon ('release gates', 'signed research receipt'), but nothing is redundant.

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

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

For a tool with a deeply nested schema, no output schema and no field documentation, the description leaves an agent unable to construct a valid payload: fact_type variants, source_url/observed_at requirements, and business_id vs. location_id are all unaddressed. The governance context is thorough, but the operational context needed to actually call it is missing.

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

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

Schema description coverage is 0% and the schema's eight fact_type variants (hours, menu_item, service, capability, price_band, phone, website, permanent_closure) along with required source_url and observed_at are explained nowhere. The description does hint at the receipt and the five-finding cap, but it never mentions business_id or location_id, and its ban on 'availability' and 'item prices' sits awkwardly against the permitted capability.available and price_band variants.

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 ('Submit ... public business facts') plus a quantity bound ('up to five') and the receipt requirement, so an agent knows exactly what action this performs. It never names the neighboring write tools (submit_verified_review, report_action_outcome, update_hours), so differentiation from siblings is left to inference.

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

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

'Ask the shopper before calling' is an explicit precondition and the content exclusions ('No personal information, availability, item prices, HTML or instructions') bound what may be submitted. However, there is no guidance on when to prefer this over sibling submission tools, and 'Collection is off until release gates are satisfied' suggests the tool may be unavailable without saying how the agent should detect or react to that state.

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

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

Goes well beyond the annotations: discloses the privacy treatment of coordinates (kept only as a coarse area, never stored exactly), that no email is collected and there is no follow-up, and a per-caller-per-day rate limit. It also explains what the returned status values mean and that neither promises coverage, and constrains how the agent may relay `message`. Nothing here contradicts the write-oriented annotations (readOnlyHint=false).

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

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

Purpose and privacy posture are front-loaded, and every clause carries information (privacy, consent, rate limit, status meaning, message handling). It is dense with semicolon-chained clauses, which costs some scannability, 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?

With no output schema and three undocumented parameters, the description still covers what the agent needs: when to call, what to send, what comes back (accepted/queued plus message semantics), privacy implications, and the rate limit. Nothing material to a correct invocation or correct shopper-facing response is missing.

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

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

Schema description coverage is 0%, so the description must carry the load, and it does: lat/lng are explicitly optional ('if known') and are described as reduced to a coarse area, and category is named as the primary payload. It adds no format or granularity guidance for category beyond the schema's maxLength, so it stops short of full coverage.

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

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

States a specific verb and resource ('Records that a shopper wants a shop category near a place') plus the intent ('so Onhand can see where to add listings'), which cleanly separates it from the search/discovery siblings like find_business and discover_local. An agent can tell this is a demand-capture write, not a lookup, 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 operating condition ('Ask the shopper before calling') and frames the situation in which it applies (a shopper wants a category near a place). It does not explicitly name a fallback such as discover_local when the category already exists, so routing versus alternatives is left partly to inference.

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

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

Annotations already say readOnly/idempotent/non-destructive, and the description adds substantial behavior on top: at most one widening step at 8/16/32/50 km, deduplicated and separately labeled wider results in neutral order, owner-approved offerings ordered first, unconfirmed public website results carrying no price or availability, and the version 1 envelope shape. It also warns that empty results describe only this query and never city-wide coverage, which prevents a serious misinterpretation.

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?

Nearly every sentence carries real operational information, but they are delivered as one undifferentiated block where widening rules, output envelope, ordering, citation policy and parameter notes are interleaved. Front-loading is weak: the crucial city-parameter semantics arrive at the very end. Structured bullets would have preserved the content with far less parsing cost.

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 documenting the envelope fields, data_coverage, reach values and the null-distance virtual case. A complex read tool with a nested parameter is mostly covered, but the unexplained `attributes` object and the absence of any radius_m definition leave a gap an agent would notice when filling the schema.

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

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

Schema description coverage is 0%, so the description must carry all parameter meaning. It explains `city` well (name, slug or neighborhood, with examples, plus the matched/none_in_city/unrecognized outcomes) and implies the radius step behavior, but never defines `radius_m` units, default or cap, and never mentions `q` or the nested `attributes` object at all. With 6 parameters and a nested object, this compensates for only about half.

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?

Opens with a specific verb and resource: 'Searches items and services near a point.' The scope (radius around a point, optional city narrowing) and the differentiation from directory-oriented siblings (discover_local includes directory businesses; find_nearby_businesses searches when nothing matches) let an agent place this tool precisely.

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 concrete routing rules: use find_nearby_businesses when nothing matches, discover_local when directory businesses are wanted, and that city searches do not widen. It also warns never to treat directory alternatives as confirmed matches. It lacks an explicit 'when not to use this at all' statement, and the guidance is scattered rather than organized as a decision list.

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 (idempotent, non-destructive, non-read-only) by disclosing server-side authorization: an organization the person does not belong to is refused, and the choice is re-validated on every subsequent call. That persistent-session and validation behavior is exactly the kind of context annotations cannot 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?

Two sentences, both load-bearing, with the effect (what later tools act for) front-loaded and the failure mode second. No filler or restatement of the title.

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

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

With no output schema and one undocumented parameter, the description should say what a successful selection returns and how long it persists (per-session vs. per-conversation). It covers the authorization rule but leaves those operational details missing.

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

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

Schema coverage is 0% — organization_id has no description, only a uuid format and pattern. The description partially compensates by implying the ID must be an organization the person belongs to, but it does not say where to source a valid ID or whether an alternative like the zero-UUID sentinel is meaningful.

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 (choose) and resource (organization) plus its downstream effect: it sets the subject that later merchant tools act for. That distinguishes it from list_subjects (discovery) well enough to route correctly, though it never names that sibling explicitly.

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

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

"later merchant tools act for" implies this is a prerequisite step before merchant calls, but the timing is left to inference. There is no explicit instruction on how or when to obtain a valid organization_id (e.g. via list_subjects) and no stated when-not case.

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 this is a non-destructive, idempotent, closed-world write. The description adds useful behavior—claim records intent and does not grant membership—but does not explain what account is returned, auth requirements, or idempotent semantics.

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

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

Three short sentences, with the core action and scope front-loaded. Every sentence adds distinct information about the kind values.

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 simple two-parameter setup tool with rich safety annotations, the description covers invocation sufficiently. Minor gaps remain around return values and explicit disambiguation from start_business_claim.

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 0% schema description coverage, the description carries the parameter burden and does well: it explains the kind enum and ties display_name to kind=shopper. It leaves minor gaps, such as whether display_name is ignored for claim and the 80-character limit.

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 ('Create') and resource ('this sign-in's account') and states the scope 'before any business exists.' It also distinguishes the two account kinds, though it does not explicitly name the start_business_claim sibling.

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

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

Establishes clear context for when to call: before any business exists. The kind-specific sentences guide the shopper/claim choice, but no explicit when-not or alternative tool is named.

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

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

Annotations already declare non-read-only, non-destructive, idempotent, closed-world, so the safety bar is lower. The description adds genuinely new context: the call is a handoff that returns a verification page, and it explicitly disclaims granting ownership or creating a membership — the two side effects an agent would most plausibly assume. It omits caller auth requirements and what happens if the business is already claimed.

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

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

Two sentences, zero filler. The prerequisite and the action come first; the negative scope statement follows as a compact boundary. Nothing is repeated from the title.

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

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

For a single-parameter tool with annotations and no output schema, the description covers the prerequisite, the effect, the return value shape (a page), and the negative side effects. The remaining gap is failure behavior — already-claimed businesses, permission errors — which an agent would have to discover at runtime.

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 description coverage is 0%, so the description must compensate. 'Point at a live business' does imply business_id selects an existing, active business (the 'live' qualifier is real added meaning), but it never states the UUID format or what counts as 'live'. Adequate, not thorough.

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

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

States a specific action ('point at a live business'), names the resource, and describes the concrete outcome ('return the page where the person proves control'). It also explicitly bounds the effect ('Does not grant ownership or create a membership'), which separates it from a membership-granting sibling an agent might otherwise confuse it with.

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 sequencing precondition — use this after setup_account with kind claim — which is exactly the context an agent needs to order its calls. It stops short of naming when NOT to use it (e.g., business already claimed, or an alternative claim-completion tool), so it earns 4 rather than 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=true, openWorldHint=true), the description adds that the content is publicly visible to all shoppers, that only the original shopper may call it, and that repeated calls return the original review without modification. This gives valuable behavioral context, though it doesn't elaborate on the destructive nature of publishing public content.

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 four tight sentences, front-loaded with the core action and followed by the most important prerequisites. Every sentence adds useful information without repetition.

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

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

For a mutation tool with no output schema and existing annotations, the description covers authentication scope, caller identity, idempotency, and public visibility. The main gap is that parameter semantics are not explained, but the schema still provides types and constraints.

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 schema description coverage at 0%, the description needs to compensate but largely does not. It mentions 'rating and review' and links booking_id to 'one review per booking', but it provides no detail on parameter formats, constraints (e.g., rating 1-5, body max 500 characters), or what each parameter expects.

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 ('Publishes') and resource ('rating and review'), and states the key precondition ('after a provider-verified completed Square checkout'). This clearly distinguishes it from the read-only sibling list_verified_reviews.

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 clear prerequisites: a completed Square checkout, reviews:write scope, and the original booking shopper. It also implies when not to use it (one review per booking; repeated calls are no-ops). It doesn't explicitly name alternatives, but the only sibling for reviews is list_verified_reviews, which is obviously for reading rather than publishing.

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 by disclosing that no state is mutated, that the return value is a one-time intent plus a human-readable confirmation sentence, that company:write is required, and that the company is inferred from the caller rather than passed in. These are exactly the auth and side-effect details annotations cannot 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?

Three tight sentences with the core purpose first, the no-side-effect constraint second, and the auth/identifier note last. No filler or restatement of the title.

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

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

Explains the return payload in lieu of an output schema and covers auth and scoping, so an agent knows what to expect. The remaining gap is the required idempotency_key's role, which is neither in the schema nor the description.

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 0% schema description coverage, the description must carry parameter meaning, and it names four of the five fields (display_name, website, phone, categories). It does not explain the required idempotency_key or any format/length constraints, leaving a meaningful gap.

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 ('Stage a change to the merchant's own listing') and enumerates the affected fields (name, website, phone, categories), so an agent can tell it apart from the confirm_* sibling without opening either 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?

'Changes nothing on its own: returns a one-time intent and a sentence describing exactly what confirming it would do' clearly establishes this as the first half of a two-step flow, implying the confirm sibling is the follow-up. It stops short of naming confirm_update_company_profile explicitly or stating 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?

Goes well beyond the annotations: it discloses that the call is non-mutating despite readOnlyHint=false, that it returns a one-time intent plus the projected full week, that days becoming closed are included, and that company:write scope is required. These are exactly the behavioral facts an agent needs before wiring it into a two-step flow.

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

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

Three short sentences, front-loaded with the action, then the non-mutation guarantee, then the permission requirement. No filler and nothing repeated from the 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?

Covers the essentials for a 3-required-parameter mutation with no output schema: what is staged, that nothing changes yet, what comes back, and the auth scope. Remaining gaps are the lifetime/expiry of the one-time intent and the day-of-week encoding, which an agent would have to guess.

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 0% schema description coverage the description must carry the load, and it partially does: location_id is constrained to the merchant's own locations, and "the full week as it would read" implies hours is a full replacement rather than a patch. However, idempotency_key is never mentioned and the dow/open/close encoding (which integer day-of-week convention, time format) is left entirely undocumented.

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 ("Stage new opening hours") plus a scope restriction ("for one of the merchant's own locations"). The phrase "Changes nothing on its own" immediately separates it from the sibling confirm_update_hours, so an agent can tell the two apart without opening either 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 clear context for when to call it: this is the staging step, it produces a one-time intent, and it requires company:write. It never names confirm_update_hours as the follow-up call, so the agent must infer the next step from the sibling list rather than from the description.

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