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 real behavioral context beyond that: results are geographically biased toward near_lat/near_long and default to Tehran, which is a ranking quirk an agent must know. It doesn't discuss result count/pagination, but the output schema presumably handles returns.

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

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

Three short sentences, each earning its place: purpose, ordering rule, and geobias caveat. The most decision-relevant instruction ('use first') is front-loaded.

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

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

With an output schema present and rich annotations, the description only needs to add routing and behavior context, which it does fully. An agent knows when to call it, what it returns conceptually, and the bias caveat.

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 baseline is 3, but the description contributes meaning the schema does not: the schema lists near_lat/near_long defaults as null while the description reveals the effective default bias is Tehran. That is genuine added semantics for the geobias parameters.

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

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

States a precise transformation ('place name or address into latitude/longitude') with a clear verb and resource. It is implicitly differentiated from the inverse sibling reverse_geocode and from the food_*/market_* consumers that require its output.

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 when-to-use ('Use first when the user gives an address instead of coordinates') and explains the downstream dependency ('every food_* and market_* tool needs lat/long'). It also instructs to pass a city center for non-Tehran cities, covering the when-not default case.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description adds genuinely new behavioral context by disclosing the conditional 'Gem' hunt discount that may or may not be live, and by clarifying the result granularity is vendor-level.

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, zero filler. The primary purpose is front-loaded and the boundary/alternative note comes after, which is the right ordering.

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 an output schema present the description needn't explain return values, and annotations cover safety. The remaining gap is minor: it does not hint at how many vendors come back or any pagination/limit behavior, but nothing needed to call the tool 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 description coverage is 100% and both lat/long carry inline ranges and Iran-specific bounds, so the schema does the heavy lifting. The description adds no syntax or format detail about the coordinates beyond what is already there, which is the expected 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?

States a specific verb+resource ('List restaurants running a discount now') and adds scope boundaries: vendor-level only, with food_menu named as the place for prices. An agent can distinguish it from food_search, food_restaurants and food_menu 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 an explicit trigger phrase ('which restaurants have offers') and routes a related need to the alternative tool (food_menu for prices). It stops short of stating exclusions or prerequisites, but the alternative routing is clear.

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

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

Annotations already declare this is a read-only, idempotent, non-destructive, open-world read, so safety is covered. The description adds genuine value beyond that: the ranking formula (food after discount + packaging + delivery), the min_order caveat, and the relative slowness 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 the core action and scoping, then usage and the pricing caveat. No filler; minor room to tighten the ranking/caveat sentence but it 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 an output schema present, return-value explanation isn't needed. The description covers purpose, trigger condition, ranking semantics, the min_order pitfall, and sibling routing, which is everything an agent needs to invoke it correctly.

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

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

Schema description coverage is 100%, so lat/long/query/limit/max_restaurants are all documented in the schema. The description adds conceptual context (total price components, min_order) but no parameter-specific syntax or format beyond what the schema already provides, 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 (find the cheapest) and resource (a dish via restaurant menus + FoodParty deals), and explicitly contrasts itself with the sibling food_search. An agent can distinguish it from food_search without opening either schema.

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

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

"Use when the user wants the lowest total price for X" gives clear usage context, and "Slower than food_search" signals the alternative and trade-off. It stops short of an explicit when-not rule, but the cost/speed trade-off effectively routes the agent.

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 genuinely non-structured behavior: the fixed 299k/free-delivery scope, the cheapest-first ordering, and the min_order caveat that a cheap meal may not meet a restaurant's basket minimum.

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

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

Front-loads the scope and constraint, then the trigger phrase, then the caveat – three short units with no filler. The line breaks are slightly awkward formatting but nothing is wasted.

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

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

An output schema exists, so return values need no explanation, and the annotations cover safety. Given the simplicity of a 4-param, non-nested read tool, the description supplies the scope, ordering, and caveat an agent needs; only sibling-relative routing 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 lat/long bounds, limit, and max_price are already fully documented in the input schema. The description's 'at most 299k Toman' is a fixed scope cap rather than an explanation of the max_price parameter, so it adds little parameter meaning beyond the schema 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?

States a specific verb (list) and resource (single-person meals) with concrete qualifiers: at most 299k Toman, free delivery, cheapest first. It does not name or differentiate from close siblings like food_find_cheapest or food_menu, so an agent must infer the boundary.

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 triggering intent ('Use for "cheap meal for one"') and adds a real caveat about min_order that affects whether results are usable. It stops short of naming alternative tools or stating when-not to use it, so it is clear context rather than 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 declare readOnly/openWorld/idempotent/non-destructive, so the safety profile is covered. The description adds non-obvious pricing semantics beyond the annotations: final_price = price - discount and packaging applied per item at checkout. It does not mention rate limits or latency, but the added domain context is substantive.

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 compact sentences: the capability statement is front-loaded, followed by the prerequisite, with the pricing formula as a short trailing note. No filler 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?

An output schema exists, so return values need not be described beyond the field summary given. The description supplies the prerequisite chain and pricing interpretation an agent needs to invoke and interpret the call correctly.

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

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

Schema description coverage is 100%, so all five parameters (vendor_code, lat, long, limit, query) are already documented in the schema, including the vendor-code format and the Iran lat/long bounds. The description reinforces the vendor_code provenance but adds no parameter semantics beyond the schema, 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 (Get) and resource (one restaurant's menu) and enumerates the payload fields returned: price, discount, packaging fee and availability. It is clearly distinguishable from siblings like food_search or food_order_costs.

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 positions the tool in a workflow: 'Use after picking a restaurant (vendor code from food_search / food_restaurants).' That is a clear precondition, though it offers no exclusions or contrast against alternatives such as food_find_cheapest or food_party_deals.

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, open-world), so the bar is lower. The description adds real behavioral context about what the operation surfaces: delivery fee and ETA, minimum order, and coupon semantics including the required basket total and first-order-only constraints. It doesn't disclose failure modes (e.g. unsupported coordinates/vendor), but that is a minor gap given annotation coverage.

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

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

Purpose is front-loaded in the first sentence, usage guidance follows, and the closing cross-reference to food_menu prevents double-fetching. Every sentence carries information; no filler.

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

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

With an output schema present, return values need no explanation, and the description still summarizes the key response contents and coupon logic. It supplies usage timing and a sibling cross-reference. Slightly short of 5 only because it omits any note on error/edge conditions for out-of-range coordinates.

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 the schema fully documents vendor_code, lat, and long, including the vendor-code origin. The description adds no syntax or format detail beyond the schema, 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?

Specific verb ('Get') plus precise resource ('the extra costs and conditions of ordering from one restaurant') with clearly enumerated scope: delivery fee, ETA, minimum order, coupons. It also distinguishes itself from the sibling food_menu by noting that per-item packaging fees live there, so an agent can tell the two apart without opening 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?

'Use before recommending a restaurant' gives an explicit trigger condition, which is strong. It also names food_menu as the complementary source for packaging fees. It stops short of stating when NOT to use it or naming a full alternative for the cost-comparison task (e.g. food_find_cheapest), so it falls just short of 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, open-world, non-destructive), so the bar is lower. The description nonetheless adds non-obvious behavior: deals are constrained to a time window and the list is empty outside it, plus limited-stock framing. Return format is not described, but an output schema exists.

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, the resource and scope front-loaded, followed by the usage trigger and the key edge case. No filler or repetition.

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

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

With an output schema present, return values need no explanation, and the description covers what the tool returns and the empty-outside-window edge case. It doesn't note the required lat/long or the Iran-bounded coordinate semantics, but the schema handles those.

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 (lat, long, sort, limit, query) are already documented in the schema. The description adds no syntax, format, or defaulting detail beyond that, 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?

The description states a specific verb and resource ('List today's FoodParty flash deals') and qualifies scope with 'deep discounts, limited stock, time window'. It is clear but does not distinguish itself from close siblings like food_discounted_vendors or market_party_deals, leaving the agent to infer the difference.

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 "what's on a big discount right now"' gives a concrete situational trigger, which is real guidance. However, it names no alternative tool and no when-not condition, so an agent choosing between this and food_discounted_vendors gets no routing help.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so safety and idempotency are covered. The description adds the scoping note that dish prices are absent and that vendor codes come from this call, but gives no auth, rate-limit, or pagination depth beyond what annotations provide.

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 purpose sentence followed by a compact usage block; every sentence earns its place and there is no filler. Slightly longer than strictly necessary but well organized.

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?

An output schema exists, so return-value details are legitimately omitted. For a nine-parameter read-only listing tool the description covers purpose, usage, and the menu-vs-listing boundary, leaving only minor behavioral specifics 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%, so all nine parameters are already documented in the schema. The description only hints at the sort/filter dimensions through prose ('best rated, free delivery, with discount') without adding syntax or format detail beyond the schema, 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') and enriches it with the delivered-to-a-point scope plus rating, delivery fee, ETA and coupon content. It differentiates from food_menu by explicitly excluding dish prices, though it doesn't name the full sibling set.

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 when to use it – browsing or ranking (best rated, free delivery, with discount) or finding a vendor code by name – and names the alternative for a related need ('No dish prices: use food_menu for those'). The condition selecting each path is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds the 'newest first' framing and the shape of a review, but says nothing about refresh cadence, moderation, or vendor-reply availability that would be novel beyond the output 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 tight sentences with the purpose up front and the usage note second. The parenthetical field list ('rating, text, what they ordered, vendor reply') is mildly redundant given a dedicated output schema, but nothing is 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 full schema coverage, complete annotations and an output schema, the description covers what an agent needs: what is fetched and why to fetch it. No gap remains that would cause a mis-call.

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 are fully documented in the schema, including the page size of 10 and the vendor_code format with its source tools. The description adds no parameter-level meaning beyond 'recent', 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 ('Read recent customer reviews of a restaurant') and lists the payload fields. The 'restaurant/vendor' scope implicitly separates it from market_reviews, though it never names that sibling explicitly.

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

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

Gives a concrete decision context: 'Use to judge quality, delays or packaging before recommending a restaurant.' That tells the agent when this tool is worth calling, but offers no exclusions or named alternatives when restaurant data is not what's needed.

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), yet the description still adds real behavior: sort=relevance is a single fast search-index call, while cheapest/biggest_discount drop side items and re-confirm prices against live menus, implying slower/fresher results. It stops short of stating index staleness or coverage trade-offs for relevance sort, or any rate/auth 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?

Three tight sentences, front-loaded with the core action and routing rule, followed by the sort-mode behavior and the alternative tool. No sentence is filler or restates a structured field.

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 an output schema present (no need to describe returns), full annotation coverage, and 100% parameter documentation, the description supplies everything else an agent needs: purpose, invocation triggers, sort trade-offs, and the sibling alternative.

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 the baseline is 3, but the description adds genuine meaning to the sort parameter by explaining what each mode does to results (fast index lookup vs side-item filtering plus live price confirmation), which the schema's bare "Order of the results." does not convey.

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) plus resource (dishes by name), scope (near a delivery point), and returned fields (price, discount, restaurant). It also explicitly differentiates from the sibling food_find_cheapest, so an agent can route without opening either schema.

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

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

Gives concrete trigger phrases ("find X near me", "discounted X") and names the alternative (food_find_cheapest) with the exact condition that selects it (cheapest X across many restaurant menus). The when-to-use / when-to-use-something-else boundary is fully resolved.

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 establish that this is a safe, idempotent read operation, so the description is not burdened with the safety profile. It adds meaningful context by disclosing the return fields (id, names, center coordinates) and a practical caveat about coordinate precision.

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 compact sentences front-load the core purpose and then add one actionable usage note. No filler or redundant restatement.

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

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

Given the low complexity, output schema, and rich annotations, the description is nearly complete. The main remaining gap is that it does not help the agent choose this tool over nearby location siblings such as find_location or reverse_geocode.

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 only parameter (query) is fully documented in the schema with examples. The description adds no additional filtering syntax or behavior beyond what the schema already provides, 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?

States a specific verb and resource (list cities) and scopes it to cities Snappfood serves, with the returned fields named. It is clear enough to distinguish from food/market tools, but it does not explicitly differentiate from location siblings like find_location or reverse_geocode.

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?

Adds a useful usage tip about treating center coordinates as a rough delivery point when the user only names a city. However, it gives no explicit when-to-use vs alternatives guidance and no exclusions relative to the many sibling tools.

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

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

Annotations already declare the full safety profile (readOnly, idempotent, non-destructive, open-world), so the bar is low. The description still adds real behavioral value by flagging the non-obvious virtual 'kalabarg' entry (id 99999999) that would otherwise look like a normal category, which is a genuine data caveat beyond the structured fields.

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

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

Two short sentences, purpose front-loaded, followed only by the two facts an agent actually needs (id reuse in market_store_products, the special kalabarg entry). No filler or repetition of the schema.

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

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

An output schema exists, so return values need not be explained, and annotations cover the safety profile. The description supplies the one piece of domain knowledge that structured fields cannot (the magic id 99999999), making it complete for a two-parameter read 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% — both lat and long are documented with type and valid ranges — so the schema carries this dimension. The description adds nothing about the parameters themselves; baseline 3 applies per the coverage rule.

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.' It also names the sibling that consumes the output ('The ids work as category_id / subcategory_id in market_store_products'), so an agent can place this tool in the workflow without opening another 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 cross-reference to market_store_products clearly signals the intended use: fetch ids here, then filter products there. That is strong contextual guidance, though it never explicitly says 'use this before market_store_products' or states when not to use it, and no alternative listing tool is named.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, open-world), so the description's added value is the ranking definition ('sorted by final price (price - discount)') and the scan scope (search results of open stores that deliver to the point). The caveat about delivery_fee/min_order hints that those costs sit outside the ranking, which is genuinely useful behavioral context.

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 action, then the trigger, then the ranking and a practical caveat. Every sentence carries information; 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?

An output schema exists, so return-value explanation is not required, and the description still usefully states the sort order. Combined with full schema coverage and annotations, the definition gives the agent what it needs to call the tool correctly; only the sibling boundary 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 the schema fully documents lat/long/limit/pages/query including the Iran bounding boxes. The description only loosely gestures at 'near the point' and adds no syntax or format detail beyond the schema, so the baseline of 3 is appropriate.

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

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

States a specific verb+resource ('find the cheapest in-stock offers for a grocery product near the point') with clear scope. It implies the grocery/market domain but never explicitly contrasts itself with the very similar sibling food_find_cheapest, leaving the agent to infer the boundary from the tool name alone.

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

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

Gives an explicit trigger ('Use when the user wants the lowest price for an item') plus a follow-up rule about checking delivery_fee and min_order before recommending. It stops short of naming alternatives such as market_search or food_find_cheapest, so the when-not condition is absent.

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

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

Annotations already declare read-only, idempotent, open-world, non-destructive behavior. The description adds two useful operational constraints not in the annotations: capacity_per_order limits deal items per order, and segment 'new_user' deals are restricted to new customers. It does not mention return shape or pagination, but an output schema exists. Credit for the extra constraints, no more.

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

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

Three short, front-loaded sentences with no filler. The first sentence carries purpose and ordering; the next two carry usage and constraint. It could be slightly tighter, but 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?

For a read-only list tool with a full schema and output schema, the description covers purpose, ordering, usage cue, and key purchase constraints. It lacks explicit sibling differentiation from food_party_deals, but otherwise contains what an agent needs to call it correctly.

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

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

Schema coverage is 100%, so lat, long, and limit are already documented with ranges and defaults. The description adds no syntax or format detail beyond the schema, 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?

The description states a specific verb (list) and resource (SnappMarket 'market party' flash deals), and notes the sort order (biggest discount first). It does not explicitly differentiate itself from the closest sibling food_party_deals, but the 'grocery' / 'SnappMarket' framing and 'market party' label give enough specificity that an agent can identify the correct vertical.

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 when-to-use cue ('when the user wants the best grocery discounts right now') but no when-not-to-use and no named alternative. With food_party_deals present as a direct sibling, an agent would benefit from knowing which vertical to pick, and that routing is left implicit.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds only the purpose and a use case, without extra behavioral context like rate limits, auth needs, or response characteristics.

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 core action and followed by a usage note. No wasted words; 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?

Given the tool's simplicity, 100% schema coverage, rich annotations, and an existing output schema, the description covers the essential purpose and usage. It could be slightly more complete by mentioning sibling alternatives for routing, but nothing critical 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 the schema fully documents both parameters (product_id and vendor_code). The description adds no additional semantic detail beyond what the schema provides, which is the baseline for high coverage.

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

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

States a specific verb and resource: 'Get one product's details and price in one store.' This clearly distinguishes it from list-oriented siblings like market_store_products, but does not explicitly name any alternative tool.

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 a clear use case: 'Use to confirm the current price/discount of an item the user picked.' It does not mention when not to use it or suggest alternatives such as market_search or market_find_cheapest.

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 establish readOnly, idempotent, and non-destructive behavior, so the description only needs to add what structured fields cannot. It does that well by disclosing the fixed 30-comment result set and explicitly stating there is no paging, which prevents wasted paging calls. It does not mention ordering/recency semantics of 'most relevant' or failure behavior for an unknown code.

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

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

Two short sentences, both earning their place: the first defines the payload, the second gives the usage trigger, and the no-paging note closes the loop. Nothing redundant with the name or title.

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

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

With an output schema present, return-shape details are rightly omitted, and the description covers the calling caveats an agent actually needs: the fixed 30-item payload and the absence of paging. Complete for a single-parameter read 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 coverage is 100% – vendor_code has a pattern, an example, and a pointer to market_search / market_stores as its source. The description adds no parameter guidance, so the baseline 3 applies; the schema is doing all the work here.

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

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

States a specific verb and resource ('Read a store's 30 most relevant customer comments') and even scopes it with a count and rating scale. It implicitly distinguishes itself from food_reviews by targeting stores rather than restaurants, but it does not name a sibling outright.

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 clear condition for reaching for this tool over store metadata tools. It stops short of naming alternatives (e.g. market_store_info for factual attributes vs reviews for sentiment) or stating 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 readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description adds real behavioral value that annotations cannot: results include closed stores and cap at ~5 matching products per store, which shapes how the agent should interpret and present 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?

Four short sentences, front-loaded with the core action and scope, then result shape, then the routing alternative. No filler or repetition of the title.

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

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

For a read-only search with an output schema and 100% schema coverage, the description covers scope, result shape and sibling routing adequately. Pagination behavior across page/limit is left entirely to the schema, which is acceptable given the output schema exists.

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

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

Schema description coverage is 100%, with lat/long ranges, Persian query guidance and page/limit constraints all documented in the schema. The description adds no parameter detail beyond what the schema already provides, 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 with scope: search a grocery product across ALL SnappMarket stores delivering to a given point. It explicitly separates itself from the sibling market_find_cheapest, so an agent can route without opening either schema.

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

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

Gives a positive use case ('see which stores carry an item and at what price') and names the alternative tool with the condition that selects it ('for a single flat cheapest-first list use market_find_cheapest instead'). Explicit when-to-use and when-to-use-something-else.

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, openWorld, non-destructive), so the bar is lower, yet the description adds real behavioral context: the true-cost formula, the min_order requirement, and the logged-out caveat that 'isApplicable is false for logged-out users.' That logged-out behavior is a genuinely useful disclosure not present in the structured fields.

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

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

The purpose is front-loaded in the first sentence, followed by the practical cost formula and a caveat. It is compact and every line earns its place, though the multi-line formula fragment is slightly less tidy than a single clean paragraph.

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

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

An output schema exists, so return values need not be explained; the description covers purpose, when to use, the cost calculation, and a key behavioral caveat. Complete for an agent to call it correctly, with only minor room for naming alternatives.

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, and vendor_code are already fully documented in the schema, including ranges and the vendor_code pattern. The description adds no parameter-level syntax or format detail 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?

States a specific verb ('Get') and resource ('one store's delivery fee, minimum order, opening hours, rating and coupons'), and the enumerations make the returned scope concrete. The 'one store's' framing distinguishes it from list-oriented siblings like market_stores and market_search without needing to name 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?

'Use before recommending a store to know the true cost of a basket' gives an explicit usage context, reinforced by the cost formula and the min_order constraint. It stops short of naming alternative tools or stating when-not to use it, so it is clear context without 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 declare readOnlyHint/idempotentHint/non-destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the no-argument fallback returns categories and sub-categories with their ids, and query overrides category filters. It does not discuss pagination beyond the schema's page param, which keeps it from a 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?

Three tight bullets, front-loaded with the core purpose, then the branching logic in the order an agent would evaluate it. 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 7 parameters fully documented in the schema and an output schema present, the description only needs to explain the invocation modes, which it does completely. 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 the baseline is 3, but the description contributes a semantic the schema does not encode: the precedence of query over category_id and the coupling of subcategory_id to its parent category_id. That is real added meaning beyond the field-level docs.

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

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

The first sentence gives a specific verb pair (browse/search) and a precise resource (products of one store), which cleanly separates it from siblings like market_product (single product), market_categories, and market_stores (store discovery). An agent can identify the tool's role without opening the schema.

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

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

The description enumerates three mutually exclusive modes — query, category_id (+subcategory_id), or neither — and states precedence explicitly ('takes precedence over category ids'). This is exactly the when-to-use guidance an agent needs, with no inference required.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so safety and mutability are covered. The description adds useful result-content context (fee, minimum order, rating) but says nothing about pagination behaviour despite a page parameter, leaving the behavioural picture only partially filled in beyond the structured fields.

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

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

Two short sentences, with the core action and scope front-loaded and the workflow guidance second. Nothing is redundant with the title or annotations, and every clause carries 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 an output schema present, return-value details need not be restated, and annotations cover the safety profile, so the description only needs to establish purpose, usage, and sequencing — which it does. The one omission is pagination behaviour for the page parameter, a minor gap for a 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 all four parameters carry descriptions with ranges and defaults, so the schema does the heavy lifting and the baseline of 3 applies. The phrase 'cheapest delivery or best rated' indirectly mirrors two of the three sort enum values, but the description never names the sort or page parameters or adds format/syntax detail 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 names a specific verb and resource ('List SnappMarket stores delivering to the point') and even enumerates the returned attributes (delivery fee, minimum order, rating), so the agent knows exactly what this tool produces. Sibling differentiation is partial: it names the follow-on tool market_store_products but does not distinguish itself from look-alikes such as market_store_info, market_find_cheapest, or market_search.

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 pick a store (cheapest delivery or best rated) before browsing it with market_store_products' gives a clear use context and the logical next step in the workflow. It does not state when NOT to use it or how it differs from the other market_* discovery tools, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds that the result is a human-readable place description and frames the confirm-before-search workflow, but says nothing extra about latency, accuracy, or failure behavior beyond what annotations and the output schema provide.

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, output semantics first and usage second, with zero filler. 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?

An output schema exists, so return structure need not be explained, and annotations carry the safety profile. The description covers what the tool does and when to call it; only explicit routing against find_location is missing, which 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 coverage is 100% and both parameters carry range and Iran-specific context, so the schema does the heavy lifting. The description adds no coordinate-format or precision detail beyond the schema, 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?

The description states a specific verb+resource (describe coordinates in words) and enumerates the kind of output (point of interest, street, neighbourhood), so an agent can tell it apart from search-oriented siblings. It does not explicitly name its natural counterpart find_location, but the reverse-geocoding intent is unmistakable.

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

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

It gives a clear condition for use: 'Use to confirm a delivery point with the user before searching.' That is actionable timing guidance. It stops short of naming the alternative tool (find_location) or when not to use it, which would be needed for a 5.

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