Shopfront Chennai Local Commerce

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds real behavioral content beyond that: a mandatory prerequisite (must obtain a locality from the customer rather than calling speculatively) and the guarantee that 'results already satisfy distance, budget, and open-now constraints,' which tells the agent not to post-filter. Return shape and limits are not described, so not 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?

Four short sentences with no filler. The purpose is front-loaded, the operational prerequisite follows immediately, and the closing sentence preempts redundant client-side filtering. Every sentence changes agent behavior.

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

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

There is no output schema and only a readOnlyHint annotation, so the description has to do more than one short constraint sentence for a 9-parameter tool. It resolves the biggest ambiguity (locality is required in spirit even though the schema marks nothing required) but leaves the return shape, result count behavior, and most parameter roles unexplained.

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

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

Schema description coverage is 0%, so the description carries the full burden for 9 parameters. It meaningfully covers only locality (a 'Chennai area') and category ('when it is clear'), and only implicitly gestures at radius_km, max_price_inr, and open_now through the constraint sentence. lat, lng, limit, and query are never explained, leaving more than half the surface undocumented.

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

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

The description states a specific verb and resource with scope: 'Find and rank local shops in Chennai for a customer request.' That is far more concrete than a generic search, and the Chennai framing separates it from catalog siblings like get_catalog and search_catalog. It stops short of naming an explicit sibling it is distinct from, so it lands at 4 rather than 5.

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

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

It gives genuine when-to-use direction: always supply locality when the customer states their location, and ask for a Chennai area before calling if they haven't. It also says to use category 'when it is clear.' No alternative tools are named and no exclusion conditions are given, so it is clear context without the explicit routing that a 5 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?

readOnlyHint=true already tells the agent this is a safe, non-mutating call. The description adds genuinely new context: the link pre-populates a standard enquiry message and varies by channel. It says nothing about the returned link's structure, whether the message is customizable, or that nothing is persisted.

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?

A single front-loaded sentence with the verb first and no filler; every clause (three link types, standard message, shop + optional item) carries information. Slightly run-on but appropriately sized.

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, no enums, and 0% schema coverage on 4 parameters, the description should explain the missing parameters and roughly what the returned link looks like. It omits two parameters entirely and says nothing about the return value, leaving real gaps 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 0% across 4 parameters, so the description must carry the semantic load. It maps shop_slug and item_id ('for a shop and optional item') but leaves customer_note and preferred_time entirely unexplained, and adds no format or constraint detail for the two it does mention.

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

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

States a concrete verb (Generate) plus the outputs it produces (WhatsApp deep link, booking URL, phone dial link) scoped to a shop and optional item. That is unambiguous and unlike the sibling tools (find_shops, get_catalog, search_catalog), though it never explicitly contrasts itself with them.

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

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

Usage is only implied: it is clear this is for producing a contact/enquiry link for a shop, and it notes a 'standard customer enquiry message' is attached. There is no statement of when to prefer this over siblings or any precondition (e.g., shop must exist, link is shareable vs clickable).

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 readOnlyHint annotation already establishes this is a safe read, so the bar is lower. The description usefully adds that results are grouped by category and include price and duration, plus that pagination is cursor-based — return-shape context the annotations do not provide. It stops short of stating default behavior for the optional kind parameter or how the cursor is obtained.

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?

A single dense sentence with the core purpose front-loaded and no filler. It is slightly overloaded, stacking output shape and pagination into one clause, but every element 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?

For a simple read-only list tool with no output schema, the description covers the return grouping, the key fields, and pagination — enough to call it. It omits the kind default, cursor acquisition, and any routing versus search_catalog, which are the remaining gaps.

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

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

Schema description coverage is 0%, so the description must compensate. It implies shop_slug ('for a shop'), cursor ('cursor-based pagination'), and kind ('menu or service' maps to the product/service enum), giving partial semantic grounding. However it never names the enum values or states what happens when kind is omitted, leaving real ambiguity for a 3-parameter tool.

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 ('Retrieve available menu or service catalog items for a shop') and adds meaningful scope detail: grouping by category, price/duration fields, and cursor pagination. It does not, however, distinguish itself from the sibling search_catalog, so an agent cannot tell from the description alone which of the two to pick.

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

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

There is no when-to-use guidance and no mention of the obvious alternative, search_catalog, which appears in the sibling list. The phrase 'available ... items' hints at a browse/listing context but no condition or exclusion is stated.

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?

readOnlyHint=true already tells the agent this is a safe read. The description adds useful scope context by characterizing the profile as 'public' and listing exactly which fields are returned, but it says nothing about error behavior for an unknown slug, rate limits, or whether closures/hours are timezone-qualified.

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?

A single dense sentence that front-loads the verb and resource, then lists outputs. The field enumeration is long but each item is informative rather than filler, so it earns its length despite reading as a run-on list.

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

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

With no output schema, the description correctly carries the burden of describing return values and does so well. However, it is silent on the sole input parameter and on failure modes, leaving real gaps for an agent that must decide when to call this versus find_shops.

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

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

There is one required parameter and schema description coverage is 0%, so the description is the only place semantics could be supplied — and it never mentions shop_slug, its format, or where the value comes from. The name is self-explanatory, but the description does not compensate for the coverage gap.

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

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

States a specific verb (Retrieve) and resource (public shop profile) and enumerates the returned fields, so the agent knows exactly what it gets back. It does not, however, differentiate itself from the sibling find_shops or explain that this is the by-slug lookup path.

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

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

No when-to-use guidance, no prerequisites, and no mention of the sibling alternatives (find_shops for discovery, get_catalog/search_catalog for menu data). The only hint at usage is the required slug parameter, which the description never discusses.

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, so the safety profile is covered. The description usefully adds that matching uses text similarity plus full-text search, but says nothing about ranking, default limit, pagination, or result caps (limit max 20), which an agent would want before 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?

A single front-loaded sentence with no filler; the core action and scope come first, filters second. Slightly dense but 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 five parameters, 0% schema coverage, and no output schema, the description should explain the search contract — default/max result count, ordering or relevance behavior, and slug format. None of that is present, leaving real gaps for correct invocation.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains max_price_inr ('price ceiling') and kind ('item kind filtering') but leaves query semantics, shop_slug format, and the limit parameter (bounds/default) entirely undocumented.

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

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

States a specific verb and resource ('Search items within a specific shop catalog') plus the mechanism (text similarity and full-text search) and filterable facets. It is clearly distinguishable from get_catalog or get_shop_info by implication, but it never names a sibling or draws the contrast 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?

There is no when-to-use / when-not-to-use guidance and no mention of the sibling tools (find_shops, get_catalog, get_shop_info). The only implicit cue is that a text query is required, which the schema already enforces.

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