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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: results are geographically biased toward near_lat/near_long and default to Tehran, which materially affects output.

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 lines, purpose front-loaded, followed by usage and the bias caveat. No filler sentences and every clause carries actionable information.

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

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

With annotations and full schema coverage in place, the description covers purpose, workflow position, and the bias quirk. It does not describe the shape of the returned list (multiple place results given the 'limit' param) and no output schema exists to compensate, leaving a minor gap.

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

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

Schema description coverage is 100%, so baseline is 3. The description earns an extra point by explaining the intent of near_lat/near_long ('Biased toward... pass a city center for other cities'), clarifying a parameter whose schema text alone is terse.

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 transformation: 'Turn a place name or address into latitude/longitude.' This clearly distinguishes it from the sibling reverse_geocode, which does the opposite direction. An agent can select it without ambiguity.

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

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

Gives explicit sequencing ('Use first when the user gives an address') and names the downstream consumers ('food_* and market_* tools need lat/long'). It also documents the default bias location and how to override it for other cities, which is the key routing decision an agent must make.

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 the safety profile is covered. The description adds one genuine behavioral detail beyond that: results conditionally include the short 'Gem' hunt discount when live, and the result set is vendor-level only. That is useful but thin, and no pagination or result-size behavior is described.

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, zero filler, and the primary purpose plus the sibling-differentiation constraint are front-loaded. The trigger phrase follows immediately after.

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 signals what comes back (vendor-level discount list, optionally including the Gem hunt offer) and the annotations cover safety. It is nearly complete; only result size/ordering behavior is unaddressed for a geo-scoped listing tool.

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

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

Schema description coverage is 100% and both parameters (lat, long) carry bounds and meaning in the schema. The description adds nothing about the coordinate parameters, so the baseline 3 applies.

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

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

States a specific verb and resource ('List restaurants running a discount now') and explicitly delineates its granularity against the sibling food_menu ('Vendor-level only: food_menu has prices'). An agent can distinguish it from food_menu, food_party_deals and food_find_cheapest 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?

Provides an explicit trigger phrase ('Use for "which restaurants have offers"') and names an alternative for a closely-related need (food_menu for prices). It lacks any when-not-to-use guidance against the other food_* deal tools, so it is clear context without exclusions.

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

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

Annotations already declare readOnly, idempotent, open-world, non-destructive, so the safety bar is low. The description adds real behavioral value beyond that: the ranking formula (food price after discount + packaging + delivery fee), the min_order caveat, and the latency trade-off versus food_search.

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 the tool does, followed by usage, then the caveat and trade-off. Nothing is padding.

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

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

There is no output schema, but the description tells the agent what it effectively returns (dishes ranked by total landed price) and warns about the min_order edge case. It is complete enough to call correctly, though the shape of results and result count behavior are only implied.

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

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

Schema description coverage is 100%, so lat, long, query, limit, and max_restaurants are already documented with meaning, defaults, and bounds. The description explains the cost model that drives ranking but adds no parameter-specific syntax or format beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource (find the cheapest way to get a dish) plus the exact mechanism (scans nearby open restaurant menus and FoodParty deals). An agent can distinguish this from food_search and food_party_deals 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?

Explicitly says when to use it ("Use for the lowest total price of X") and routes the agent away from the sibling by contrast ("Slower than food_search"). It also gives a concrete precondition to check: min_order, since a cheap dish may not reach the basket minimum.

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, and non-destructive, so safety is covered structurally. The description adds real behavioral context beyond that: result ordering (cheapest first), a hard price ceiling, free-delivery requirement, and the warning that a cheap meal may fail the minimum basket — a genuinely useful operational caveat. Return format/pagination is not described, keeping it below 5.

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 tool's scope and constraints front-loaded and the caveat placed last as an actionable warning. Every clause carries information an agent can act on.

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 is responsible for signaling the shape of results; it does so via 'cheapest first' and the price/delivery constraints. Four parameters are fully covered by the schema, and the min_order caveat closes the main operational gap, though the absence of any note on result limits or empty results is a minor shortfall.

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%, with lat/long bounds, limit default, and max_price all documented in-schema, so the baseline is 3. The description's 299k price ceiling and cheapest-first ordering give indirect meaning to max_price and the result ordering but add no syntax or format detail beyond what the schema already carries.

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 precise verb+resource ('List single-person meals') with concrete constraints: price ceiling of 299k Toman, free delivery, and cheapest-first ordering. It distinguishes itself from generic siblings like food_search by the single-person/cheap scope, though it never names the closest alternative (e.g. food_find_cheapest) so the 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?

Gives a direct trigger phrase ('Use for "cheap meal for one"') and adds a practical prerequisite caveat about checking min_order before committing. It does not state when NOT to use it or name sibling alternatives, so it stops short of the top tier.

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, open-world and non-destructive, so the bar is low; the description adds real domain behavior by stating final_price = price - discount and that packaging is charged per item at checkout. That is value beyond the structured fields, though auth/pagination/rate-limit context is absent.

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

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

Two sentences, no filler; the core purpose is front-loaded and the pricing rule follows as supporting detail. Every clause earns its place.

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

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

For a read-only menu lookup with no output schema, the description covers what is returned, when to call it, and how prices resolve. Combined with 100% schema coverage and a full safety annotation set, nothing essential 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 100%, so all five parameters (vendor_code, lat, long, limit, query) are already documented in the schema. The description's price/discount/packaging language describes outputs rather than adding parameter meaning, so baseline 3 applies.

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

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

States a specific verb (get) and resource (one restaurant's menu) and enumerates the returned fields (price, discount, packaging fee, availability). It clearly differs from restaurant-listing siblings, though it never names an alternative 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?

'Use after picking a restaurant' gives a clear sequencing cue that places it downstream of food_search / food_restaurants, and the schema notes vendor_code comes from those tools. No explicit when-not-to-use guidance is offered, keeping 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 already cover the safety profile (readOnly, idempotent, non-destructive), so the description earns credit for disclosing the payload shape: delivery fee, ETA, minimum order, coupon conditions with required basket total, first-order-only flag. It does not mention that results are location-dependent beyond the implied lat/long inputs, nor any rate/caching 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?

Two tight sentences: the action first, then the usage trigger, then the enumerated return fields. The trailing pointer to food_menu for packaging is dense with routing value and costs nothing in length.

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 compensates by enumerating the meaningful return fields (fees, ETA, minimum, coupon conditions, basket thresholds). Combined with the read-only annotations and fully documented inputs, 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 description coverage is 100%, including where vendor_code comes from, so the schema already carries the parameter burden. The description adds only that lat/long select the restaurant's delivery point, which is a marginal over-specification of the obvious.

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 + resource: 'Get the extra costs and conditions of ordering from one restaurant', with the scope (one vendor, per delivery point) made explicit. It also carves out a boundary against food_menu by stating packaging costs live there instead.

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?

'Use before recommending a restaurant' gives a concrete decision point in the agent's workflow, which is unusually actionable. It does not state any exclusion or negative case (e.g. what to use when no coordinates are known), so it stops short of full when/when-not guidance.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld). The description adds genuinely new behavioral context beyond them: results are scoped to the current deal window, are stock-limited, and return empty outside the window. It does not mention rate limits, pagination, or auth needs, but for a read-only list tool this is solid disclosure.

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, front-loaded with the verb and resource, with the scoping caveat immediately after. No filler, no restatement of the title, and the quote-style usage hint is the only stylistic decoration.

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 indicating what comes back, and it does so at a conceptual level (deals with discount depth, stock status, and time window). Geographic/temporal scope and the empty-window edge case are covered; exact return shape, freshness of 'today', and result ordering are left unstated but are minor for a read-only listing.

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 lat/long, sort, limit and query are all documented structurally, which sets the baseline at 3. The description adds only implicit semantics ('still in stock' explains the implicit availability filter) and says nothing about sort ordering, limit behavior, or title-substring matching that would supplement 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 opens with a specific verb and resource ('List today's FoodParty flash deals') and enriches it with the defining attributes: deep discounts, limited stock, time window, still in stock. That is enough to distinguish it from a generic search, but it never names or contrasts with nearby siblings like food_discounted_vendors or market_party_deals, which an agent may reasonably 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?

It gives a clear usage trigger ('Use for "what's on a big discount right now"') and a hard operating condition: deals only exist inside starts/ends, and the list is empty outside that window. It stops short of telling the agent when NOT to use it or which sibling to prefer for adjacent needs (e.g. cheapest meal vs. flash deal).

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 non-destructive, so safety is covered. The description adds real value beyond that by disclosing what comes back (rating, fee, ETA, coupon) and, importantly, what does not (no dish prices), which prevents a wrong call.

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 zero waste: the capability and its returned fields come first, then the usage note and the alternative. Nothing is padded or restated.

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

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

For a 9-parameter listing tool with no output schema, the description covers purpose, key returned fields, and the main boundary against a sibling. Pagination and sort semantics live in the schema, but the absence of any note on result volume or paging behavior is a minor gap.

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

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

Schema description coverage is 100% and every one of the 9 parameters is documented in-schema, including the sort enum and the price-class caveat, so the description need not repeat them. The description adds no syntax or constraint detail beyond the schema, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('List restaurants') plus the scope ('delivering to a point') and the payload it returns (rating, delivery fee, ETA, coupon). It also explicitly distinguishes itself from the dish-price sibling by naming food_menu, so an agent can route 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?

Gives clear usage context ('browse or rank restaurants or find a vendor code by name') and one explicit exclusion pointing at food_menu for dish prices. It stops short of naming other close siblings like food_find_cheapest or food_discounted_vendors, which an agent might also want signposted.

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, so the safety profile is covered. The description adds the review content shape, which is useful, but says nothing about pagination limits, rate limits, or whether reviews can be absent for a vendor.

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 first states the operation and the returned fields, the second states the decision context. Information is front-loaded and every clause earns its place.

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

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

With no output schema, the description usefully summarizes the return contents (rating, text, order items, vendor reply) and the schema covers paging and truncation. Missing only edge-case behavior such as empty review sets or maximum page depth.

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%, with page, full_text and vendor_code all documented including the 400-char default and the source of the vendor code. The description adds no parameter-level detail beyond what the schema already supplies, so baseline 3 applies.

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

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

States a specific verb and resource ('Read recent customer reviews of a restaurant') and enumerates what the reviews contain (rating, text, ordered items, vendor reply). It does not explicitly contrast with the parallel market_reviews sibling, but the 'restaurant' qualifier implicitly scopes it, so an agent can distinguish them by resource type.

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 second sentence gives clear situational guidance: use it to judge quality, delays or packaging before recommending. It does not name alternatives or state when not to use it (e.g. market_reviews for non-food stores), which keeps it just short of a 5.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld). The description adds genuine behavioral context beyond that: 'relevance is one fast index call' discloses relative latency, and cheapest/biggest_discount are flagged as dropping side items and confirming prices on live menus, which warns about result-quality tradeoffs. It stops short of describing result shape or pagination.

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 usage triggers, then per-sort behavior and the sibling handoff. No filler or restated field names.

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 tells the agent what a result contains (price, discount, restaurant) and how sorting changes result composition. Minor gaps remain around result volume/pagination and the hidden protein-store behavior, but nothing essential to a correct call 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 the baseline is 3, but the description earns extra by explaining what the sort enum values actually do to results rather than restating them. It does not, however, touch limit, discounted_only or include_protein beyond what the schema already says.

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 ('Search dishes by name') plus the scoping constraint ('near a delivery point, with price, discount and restaurant'). It also explicitly names the sibling it is not (food_find_cheapest), so an agent can separate it from the other food_* tools 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?

Gives concrete trigger phrasings ('find X near me', 'discounted X') and an explicit exclusion rule: use food_find_cheapest for the cheapest X across many menus. It also explains which sort mode suits which intent, which is real when-to-use guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered elsewhere. The description adds useful context by disclosing the returned fields and the approximate nature of center coordinates, but says nothing about pagination, filtering behavior, or result size.

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, front-loading the resource and scope before the practical tip. Nothing is wasted.

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

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

With no output schema, the description helpfully enumerates the returned fields and explains the coordinate semantics. Combined with annotations that cover the safety profile, this is nearly complete; only filtering/pagination behavior 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 description coverage is 100% and there is only one optional parameter, so the schema fully documents the query filter (Persian title or English code). The description adds no parameter detail, which is acceptable at this coverage level but earns only the baseline.

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 cities Snappfood serves') and names the returned fields (id, names, center coordinates), which cleanly separates it from reverse_geocode/find_location siblings. It stops short of explicitly naming an alternative tool, so it is clear but not maximally 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?

It provides one usage condition ('Use the center as a rough delivery point when the user only names a city'), which implies when the tool is useful, but it never states when to prefer a sibling like reverse_geocode or find_location. Guidance is present but partial.

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, openWorldHint and destructiveHint=false, so safety is covered. The description adds genuine extra context the annotations cannot: the special virtual kalabarg category id 99999999 and the downstream role of the returned ids. It says nothing about return shape or hierarchy, but with annotations carrying the behavioral profile that is a minor gap.

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 first, then the integration detail and the one exceptional id. Nothing is repeated from the schema or annotations, and every sentence earns its place.

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

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

With no output schema, the description usefully summarizes the return value (categories and sub-categories plus ids) and flags the one special id, which is the kind of thing an agent would otherwise get wrong. It stops short of clarifying whether sub-categories are nested or returned as a flat list, but it is sufficient for a two-parameter, read-only reference tool.

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

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

Schema description coverage is 100%, so lat/long are already documented as the delivery point and the schema documents the numeric bounds. The description adds no parameter-level detail and does not explain why a location is required to list categories. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource ('List SnappMarket product categories and sub-categories with their ids') and names the sibling that consumes the output, market_store_products. An agent can distinguish this reference-data lookup from the search/cheapest/store tools in the market_* family 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?

The description explains what to do with the output ('The ids work as category_id / subcategory_id in market_store_products'), which implies the intended workflow, but it never states when to call this tool versus alternatives such as market_search or market_stores. Usage is implied rather than explicit, and no prerequisites or exclusions 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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description usefully adds behavioral detail beyond them: it scans only open stores that deliver to the point, returns a single flat list sorted by final price, and flags delivery_fee/min_order as requester-side checks. With no output schema, this return-shape disclosure carries real value.

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 core purpose and free of filler. Minor slack in 'near the point' phrasing, but nothing that wastes the agent's attention.

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 5 parameters, the description fills the most important gap by describing the return (a flat list sorted by final price) and the post-call checks. It does not explain what limit/pages trade off against latency, but the schema bounds make that largely inferable.

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

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

Schema description coverage is 100%, so lat/long/query/limit/pages are already documented in the schema itself. The description gestures at 'near the point' and 'grocery product' but adds no format, unit, or constraint detail beyond what the schema states; baseline 3 applies.

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

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

States a specific verb and resource ('Find the cheapest in-stock offers for a grocery product') plus the geographic scope ('near the point'). It distinguishes itself implicitly from the near-identical sibling food_find_cheapest via the 'grocery' framing, but never names that sibling, so the differentiation 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?

'Use for the lowest price of an item' states the intended context, and the closing note on checking delivery_fee/min_order is a useful invocation guideline. However, with food_find_cheapest sitting in the sibling list, the absence of any explicit when-not-to-use or alternative-tool routing is a real gap.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, openWorld). Description adds valuable beyond-annotation context: sorting is by biggest discount, and critically the business rules about capacity_per_order limit and 'new_user' segment restrictions. Does not describe pagination or return format, but annotations lower the bar.

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 sentences, front-loaded with the primary purpose. No wasted words, though the last sentence packs two separate business rules (capacity_per_order and new_user segment) which could be split for clarity.

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?

Complete for a read-only list tool: purpose, scope, sorting, and key business constraints are present. An agent knows what it gets and the ordering. Missing only pagination details or a sample return structure, which is acceptable given no output schema.

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

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

Schema description coverage is 100%, so lat/long/limit are fully documented in the schema including ranges. The description adds no new parameter syntax or format detail beyond referencing 'the point' for location. Baseline 3 applies when schema does the heavy lifting.

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

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

States a specific verb (List) and resource (SnappMarket market party flash deals), plus scope (near the point) and ordering (biggest discount first). Distinguishes itself from siblings like market_search and market_find_cheapest which lack the deal semantics.

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 'Use for the best grocery discounts right now' which gives clear context. However it doesn't name alternative tools like food_party_deals or market_find_cheapest as alternatives, nor when-not to use 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 readOnlyHint, idempotentHint, non-destructive and openWorld, so the safety profile is covered. The description adds only the per-store scoping nuance ('in one store'), and says nothing about rate limits, auth, or what the truncated default response looks like.

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

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

Two short sentences, zero waste, with the core action front-loaded before the usage hint. Nothing redundant or padded.

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

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

For a simple read-only lookup with fully documented parameters and no output schema, 'details and price' adequately signals the return content. A brief note on what 'details' includes (or the 400-char truncation default) would make it complete, but the essentials for correct invocation 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 100%, so product_id, vendor_code and full_text are fully documented in the schema. The description's 'one product's details and price in one store' loosely reinforces the two required identifiers but adds no format or constraint detail beyond the schema. Baseline 3.

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 and resource: 'Get one product's details and price in one store.' This clearly separates it from list-style siblings like market_store_products or market_search by scoping to a single product. It stops short of naming a sibling explicitly, so it doesn't reach a 5.

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

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

'Use to confirm the current price of an item the user picked' gives a concrete usage context, which is better than nothing. However it offers no when-not guidance or routing to alternatives such as market_find_cheapest or market_search when the product id is unknown.

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 a safe, idempotent read. The description adds genuinely new behavioral facts: the result set is capped at 30 comments, there is no paging, and repeated calls return the same set — all useful for deciding whether the tool is worth calling.

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 the core operation front-loaded ahead of the usage hint. The trailing 'rating 0-5' phrase is slightly ambiguous (rating field range vs. overall score) but costs little.

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 responsibly describes the return shape (30 comments with ratings) and the fixed result-set behavior. An agent has enough to call it and interpret results, though the rating-range phrasing could be clearer.

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

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

Schema description coverage is 100%, so both parameters are fully documented in the schema. The description adds only the rating scale (0-5) and the 30-comment cap, which does not materially extend what the schema already conveys.

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 ('Read a store's 30 most relevant customer comments'), which is far more precise than the title alone. It implicitly separates itself from food_reviews by scoping to stores, but never names that sibling to make the distinction 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?

'Use as a quality check before recommending a store' gives a concrete decision context for invoking the tool. It offers no exclusions or comparison against the restaurant-review sibling, so it falls short of full when/when-not guidance.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuine result-shape context: the response is grouped by store, includes closed stores, and caps at roughly 5 matching products per store. It does not discuss pagination limits, but that is largely in the schema.

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

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

Two sentences, no filler. The core behavior is front-loaded and the alternative-tool routing is compressed into a single trailing clause.

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 return-value burden and does describe the store-grouped structure and per-store product cap. It stops short of describing pagination semantics or an empty-result case, which are the remaining unknowns for an 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?

Schema description coverage is 100%, so lat/long/query/page/limit are all documented in the schema itself. The description only implies the geographic filter ('delivering to the point') and adds no format or constraint detail beyond that, so the baseline 3 applies.

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

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

States a specific verb (Search) and resource (grocery product) plus the scope that defines it: across all SnappMarket stores delivering to the given point. The scope clause alone differentiates it from nearby siblings like market_stores and market_store_products.

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 states the use case ('see which stores carry an item and at what price') and names the alternative for the contrasting need ('For one flat cheapest-first list use market_find_cheapest'). This is exactly the when-to-use / when-to-use-something-else guidance that routing requires.

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 and non-destructive, so safety is covered; the description still adds real behavioral context beyond them. Specifically it warns that coupons carry conditions and that is_applicable returns false when logged out, plus that results are point-dependent. That is meaningful disclosure on top of the annotations.

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

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

Front-loaded with the payload enumeration, then usage, then caveats — a sensible ordering with no filler. The basket-cost formula sentence is useful for interpreting delivery_fee and min_order, though it is slightly tangential since this tool does not compute baskets itself.

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 burden of describing returns and does so by naming the key fields. Read-only/idempotent semantics are covered by annotations, and the logged-out coupon caveat closes the main behavioral gap. Only minor omissions remain (no mention of failure behavior for an invalid vendor_code).

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%, including the vendor_code pattern and its sourcing from market_search / market_stores, so the schema carries the parameter burden. The description only hints at the geo scope via 'for the point' and adds no format or sourcing detail beyond what is already documented. Baseline 3 is appropriate.

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

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

States a specific verb and resource (get one store) and enumerates exactly what is returned: delivery fee, minimum order, opening hours, rating and coupons. The scope qualifier 'for the point' plus 'one store's' cleanly separates it from list-oriented siblings like market_stores and market_search. An agent can tell what this tool yields 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?

'Use before recommending a store' gives a concrete when-to-use context, which is more than most siblings offer. It does not name an alternative or a when-not condition (e.g., vs. market_store_products or market_reviews), so it stops short of full routing guidance.

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

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

Annotations already cover readOnly/idempotent/non-destructive/open-world, so the description only needs to add mode semantics — and it does, disclosing the surprising no-argument behavior (returns the store's categories and sub-categories) and the query-vs-category precedence rule. Pagination and result shape remain undisclosed.

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?

One lead sentence plus three short bullets, front-loaded with the tool's identity and then the argument branches. No filler, no repetition of schema text.

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

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

For a 7-parameter read tool with no output schema and full annotation coverage, the mode behavior and precedence rules are the critical missing pieces and they are present. The absence of any hint about result shape or page semantics leaves a small 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?

With 100% schema description coverage, the schema already documents each parameter, so 3 is the baseline. The description earns an increment by documenting cross-parameter relationships the schema cannot express: query overriding category_id and subcategory_id requiring category_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 specific verb and resource with explicit scope ('Browse or search the products of one store'), and the three bullets clarify the distinct output modes. It does not, however, address overlap with siblings like market_categories or market_stores, which the no-argument mode partially duplicates.

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 bullets give concrete conditions per argument combination and even resolve precedence ('query ... wins over category ids'), so an agent knows how to choose. There is no explicit when-not or naming of alternative tools (e.g. market_categories for category listing), which keeps it below a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds that results are geo-scoped to a delivery point and discloses the surfaced fields, which is useful, but it says nothing about pagination behavior, result caps, or what happens when no store delivers to a point.

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 capability statement comes first and the routing guidance second, so the agent gets the essential information 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?

No output schema exists, and the description compensates by naming the key returned fields (delivery fee, minimum order, rating). Combined with the fully documented input schema, an agent has enough to call it correctly; only edge-case and pagination behavior is unaddressed.

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

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

Schema description coverage is 100%, so lat, long, page and sort are already documented with ranges and enum values. The description only hints at the geo requirement ('delivering to the point') and the rating/fee fields that sort operates on, adding little beyond the schema. Baseline 3 applies.

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

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

States a specific verb (List) and resource (SnappMarket stores) plus the scope qualifier (delivering to the point) and names what it returns (delivery fee, minimum order, rating). It also names the sibling market_store_products, so an agent can distinguish it without inspecting schemas.

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 gives the use case: 'Use to pick a store before browsing it with market_store_products,' which establishes a clear ordering relative to that sibling. It stops short of excluding the other plausible alternatives (market_search, market_find_cheapest, market_store_info), so 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?

The annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds output examples and a workflow context, but it does not add deeper behavioral details such as precision, coordinate system, error handling, or rate limits.

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 are front-loaded with the core action and immediately followed by the intended workflow. There is 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?

For a simple two-parameter read-only tool with rich schema coverage and safety annotations, the description is nearly sufficient. It gives output examples and a use case, though it does not explain what happens when coordinates fall outside a serviceable area.

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

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

Schema description coverage is 100%, so both lat and long are already documented as delivery point coordinates with bounds. The description does not add syntax, format, or precision details beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific verb and resource: 'Describe coordinates in words', with examples of the kind of textual output produced. It is clear what the tool does, but it does not explicitly distinguish itself from siblings such as find_location or list_cities.

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 second sentence gives a clear intended use case: 'confirm a delivery point with the user before searching.' It lacks explicit when-not-to-use guidance or named alternatives, so it falls 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.