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

Annotations already mark this as read-only, open-world, and idempotent, but the description adds important behavior: the directory lists restaurants OPEN for the dining option at `when`, empty results may reflect closure, and there is no paging. These details materially affect how an agent interprets and retries calls.

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

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

The description is front-loaded with the core purpose and then layers return format, prerequisites, caveats, and result limits in a logical order. Despite being dense, every sentence carries operational value and avoids 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 an eight-parameter, no-output-schema tool, the description is complete enough to call correctly: it explains required geocoding, return fields, nearest-first ordering, open-now filtering, empty-result interpretation, and paging behavior. No critical agent-facing behavior is missing.

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

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

Schema coverage is 100%, so parameter descriptions already carry most semantics. The description still adds useful meaning for `when` (default now and its effect on open restaurants), `limit`/`total` (no paging and `total` is every match), and the optional `name` filter, though it does not elaborate on `view`, `radius_miles`, or `dining_option` beyond the schema.

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

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

The description states a specific verb and resource: find restaurants that take orders through Toast near a latitude/longitude point. It also distinguishes the result's GUID as the input needed by toast_get_menu, making the tool's role clear against siblings.

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

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

It explicitly tells the agent to convert an address or city first because the server has no geocoder, and it explains that empty or short late-night results mean restaurants are closed rather than absent, recommending a daytime `when` retry. It also notes the optional `name` filter and the relationship between `total` and `limit` without paging.

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, openWorld, so the safety profile is covered. The description adds a genuinely useful behavioral fact: it requires a toast.app browser sign-in via ContextMint Bridge, which no structured field conveys.

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, front-loaded with the resource and returned fields, then the auth requirement. The field enumeration is slightly long but each element earns its place by telling the agent what to expect.

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

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

For a read-only, single-optional-param tool with no output schema, the description adequately covers both what it returns and the auth prerequisite. Nothing critical to correct invocation is missing.

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

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

Schema coverage is 100% and the single 'view' enum is fully documented in the schema. The description adds nothing about the compact/full axis, so the baseline of 3 is appropriate when the schema does all the 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?

States a specific resource (Toast loyalty programs) and enumerates the returned fields (restaurant, program name, balances, reward progress), so the agent knows exactly what it fetches. It doesn't explicitly contrast with siblings like toast_get_wallet, but the loyalty focus makes it distinguishable.

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

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

The description implies it's the tool for loyalty programs but never states when to use it over toast_get_wallet or other siblings, nor any prerequisites beyond sign-in. No exclusions or alternatives are 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 readOnly/openWorld/idempotent, and the description goes well beyond them: it explains merge semantics for `source=both` (online listing wins, `sources` array), that duplicated items appear under each group so `total_items` counts listings not distinct items, that prices are dollar floats, and that modifier prices are excluded. These are exactly the surprises an agent would otherwise hit at runtime.

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

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

Front-loaded with purpose and return shape, then parameter notes; nearly every clause carries information. The density is high (dollar conversion, dedupe advice, modifier caveat all in one block), but nothing is redundant enough to cut cleanly.

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 six params, the description carries most of the load and does so well, including how to count items correctly. Minor gaps remain: it doesn't say whether `limit` truncates items only or whole groups, and it doesn't state whether truncation is signaled in the response.

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

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

Schema coverage is high (83%) so the baseline is 3, but the description adds real meaning for the two hardest params: `restaurant` accepts a GUID or any link containing one, and `source` semantics are spelled out beyond the bare enum. It also clarifies price units and search scope for `query`. Only `view` and `limit` behavior are left to the schema.

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

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

States a specific verb and resource and immediately describes the returned hierarchy (menus → groups → items), so an agent can distinguish it from toast_get_order or toast_find_restaurants without opening the schema. It also names the sibling tool for the one case that could confuse (bare shortUrl → toast_resolve_restaurant).

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 `source` paragraph gives clear conditional guidance (online = what's sold online, pos = full register menu, both = merged), and the `restaurant` note tells the agent when to call toast_resolve_restaurant first. It does not explicitly exclude cases where toast_get_order or toast_find_restaurants would be better, so it stops short of a full when/when-not map.

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

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

Annotations already declare readOnly/idempotent/openWorld, so the safety profile is covered; the description adds the real operational constraint that a toast.app browser sign-in via ContextMint Bridge is required. It also details what comes back (payments, discounts, gift card, delivery) which the annotations 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?

Front-loaded with the return contents, then input provenance, then the auth prerequisite — a sensible order. The field enumeration is long but earns its place since there is no output schema.

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

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

With no output schema, describing the returned receipt fields is necessary and done thoroughly, and the auth prerequisite is stated. The only gap is guidance on choosing the `view` mode, which is a minor omission given the schema documents 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 only 33%, and the description compensates for the two required GUIDs by stating their origin. However, it says nothing about the `view` parameter (compact vs full), leaving the schema's own enum text to carry that meaning alone.

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 ('one of your past Toast orders as a receipt') and enumerates the concrete contents (items, modifiers, tax, tip, payments, delivery address). It is clearly distinguished from the sibling toast_list_orders, which supplies the IDs this tool consumes.

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

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

Explicitly says where the required inputs come from ('Takes the restaurant and order GUIDs from toast_list_orders'), which routes the agent correctly. It does not state any when-not condition, but for a single-record fetch there is little alternative ambiguity.

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/open-world, and the description adds genuinely new context: amounts are denominated in dollars and the call requires a toast.app sign-in in a browser running ContextMint Bridge. It stops short of describing failure behavior when that sign-in is missing or how expiries are ordered.

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?

Content is front-loaded: the payload comes first, then the units note, then the auth prerequisite. Three sentences with no filler, though the list phrasing 'the next expiry, the units that expire, and the units you have received' is slightly repetitive.

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 takes on the return-value burden and does so by naming the four returned data points. The auth prerequisite is the key operational detail an agent needs before calling. Only error/precondition behavior is left unstated.

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

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

Schema description coverage is 100% and the single `view` parameter carries a thorough enum description in the schema, so the baseline applies. The description adds no meaning about `view` beyond what the schema already says about compact vs full.

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 resource (Toast Cash wallet) and enumerates exactly what is returned: available balance including gifted stored value, next expiry, expiring units, and received units. It is clearly distinct from toast_get_loyalty and the order tools, though it never explicitly contrasts itself with them.

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

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

Usage is implied by the domain ('Your Toast Cash' balance) rather than stated: no 'use this when...' clause, no mention of when to prefer it over toast_get_loyalty, and no exclusions. An agent can infer the call site but the description does not route 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 readOnly/idempotent/openWorld, but the description adds real behavior the annotations cannot: enforcement of query-only documents, return of raw data *and* errors, dependency on a signed-in browser session, and the error-recovery contract ('validation errors name the fields the schema lacks'). Missing only volume concerns (rate limits, response size, whether the 8000-char cap applies to variables too).

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

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

Front-loads what it does and where, then scope restriction, then examples, then error-handling advice — a natural call order. Every sentence carries actionable content, with no restatement of the tool name or filler.

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

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

With no output schema, the description steps in to say it returns raw data and errors, and it covers the biggest failure mode (schema validation errors) with a concrete recovery strategy. For an open-ended escape-hatch tool, nothing an agent needs before calling it is absent.

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

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

Schema coverage is 100%, so the schema already defines query/variables/operation_name; the description adds meaning beyond it by naming valid operation shapes (nearbyRestaurants, menusV3 with their input fields) and by framing the query param as accepting fragments only. It adds query-construction guidance the schema cannot express.

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 ('run a read-only GraphQL query against Toast's online-ordering gateway'), names the concrete endpoint, and explicitly positions itself against the sibling set ('for exploring fields the dedicated tools don't cover yet'). An agent can distinguish this from toast_find_restaurants/toast_get_menu without opening any schema.

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

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

Gives an explicit trigger ('exploring fields the dedicated tools don't cover yet') plus an explicit exclusion ('mutations and subscriptions are refused'), which steers agents toward the typed sibling tools for known use cases. Known-good operation names with their input shapes give a concrete starting point rather than open-ended guessing.

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 openWorldHint, but the description goes further by stating 'Read-only, no auth required' and detailing the diagnostic return values. It also explains that the plain-English hint distinguishes bridge-not-up, extension-not-connected, browser capability issues, and server-side problems, which is rich behavioral context an agent needs.

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

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

Despite being detailed, the description is front-loaded with the core action and diagnostic output, followed by a single usage sentence. The URL and enumerated diagnostic fields all earn their place because they define exactly what the tool checks and returns.

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 return values and does so comprehensively: bridge role, port, version, extension link state, elapsed time, and interpretive hints. It also covers auth requirements and the failure-routing use case, leaving no critical gap.

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

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

There are zero parameters, so parameter semantics are not applicable and the baseline is 4. The description correctly does not invent parameter guidance.

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

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

The description states a specific action (round-trips a public GraphQL URL through ContextMint Bridge) and a specific outcome (connection diagnostics covering bridge role, port, version, extension link, round-trip time, and hints). It is clearly a diagnostic tool, distinguishing it from the data-oriented sibling tools like toast_list_orders and toast_get_menu.

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

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

It gives an explicit trigger condition: 'Call this when a real tool fails and you want to know which hop broke.' That directly routes the agent to this tool as a fallback diagnostic after another Toast tool fails, with no ambiguity about the alternative.

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, openWorld, so the description's job is to add operational context — which it does: sort order (newest first), the pagination contract, and the browser-based auth requirement through ContextMint Bridge. It stops short of noting rate limits or behavior when the sign-in is absent/expired.

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 resource and ordering, then the return shape, then the two operational instructions. Every sentence carries information; the field enumeration is dense but justified since no output schema exists.

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 takes on the return-value burden and lists the fields returned plus their formats (ISO-8601 UTC, dollars, Toast-reported status). It also covers auth prerequisite, pagination, and the sibling alternative — nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so both page_size and view are already fully documented, and the description adds only the practical semantics of next_page_token (fetch older orders). That is a small but real gain over the schema, which merely says 'from a previous answer' — leaving the baseline plus a point of value.

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

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

States a specific verb and resource ('Your Toast order history, newest first') and immediately enumerates the returned fields (GUID, restaurant, timestamps, status, items, total). It explicitly contrasts with toast_get_order, so an agent can distinguish sibling scope without opening a schema.

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

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

Names the alternative tool and the condition selecting it: 'Use toast_get_order for a full receipt.' It also states the paging procedure ('Pass next_page_token from the previous answer for older orders') and the prerequisite sign-in. Only true exclusions (e.g., filtering by restaurant or date) are unstated.

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 readOnly/openWorld/idempotent, and the description adds genuinely non-obvious behavior: GUID-bearing links resolve locally with no network call, shortUrl slugs trigger a Toast lookup, and unknown slugs return guid: null plus a next step. The one omission is any hint about lookup latency/failure modes beyond the null case.

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 distinct information: purpose, resolution mechanics, and the failure return. Purpose is front-loaded and there is no redundant restatement of the name or 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?

No output schema exists, and the description compensates by describing both the success return (a GUID for toast_get_menu) and the failure return (guid: null with a next step). Combined with the single-parameter schema, an agent has everything needed to call and interpret 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 100% and the single parameter is already documented, so the baseline is met; the description goes further by decomposing 'reference' into concrete accepted shapes (r-<guid> links, ?guid= params, bare GUIDs, order.toasttab.com shortUrls) and their differing resolution behavior.

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 (resolve) and precise resource (restaurant GUID), enumerates the input forms it accepts, and explicitly names the downstream consumer toast_get_menu. It is trivially distinguishable from every sibling, which are menu/order/loyalty operations.

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?

Clearly frames this as the prerequisite step to toast_get_menu and explains the network vs no-network resolution paths. It does not, however, tell the agent what to do when it has no link/GUID at all (e.g., use toast_find_restaurants), leaving the main alternative unstated.

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