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

The description richly details behavior beyond the annotations: over-budget rejection before fetching, retries, null incomplete totals, splitBasket savings only when strictly cheaper, groupBy=market spanning branches, and clarification that depot means one physical shop. These are significant behavioral disclosures not covered by readOnlyHint, openWorldHint, idempotentHint, or destructiveHint.

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

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

The description is verbose and covers many edge cases in a single block. It is structured logically (purpose, constraints, output rules) and front-loads the core purpose, but it is longer than necessary and could be more concise. However, the complexity of the tool justifies some 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?

The description is comprehensive for a complex tool with budget limits, retries, grouping rules, and output conditions. It covers missing groups, equal totals, splitBasket conditions, and references market://guide. With an output schema present, it does not need to detail return values, and nothing critical for correct invocation is missing.

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

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

Schema coverage is 67% with descriptions for depots, distance, latitude, longitude, but not for items or groupBy. The description adds meaning for items (exact IDs and pack quantities) and clarifies budget and retry semantics, which are not in the schema. It also explains the depot term. This adds value 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 first sentence clearly states the tool compares exact product IDs and pack quantities via individual lookups, and mentions the budget limits. It is specific about the resource and operation, but it does not explicitly name a sibling tool to distinguish itself from, though it implies alternatives by referencing search offers and switching tools.

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

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

The description provides explicit constraints: never split the list or switch tools to bypass budget, ask the user to narrow, reuse search offers, and follow specific output rules. It gives context on when to use and when not to, though it doesn't name specific alternative tools beyond general references.

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 tool read-only, idempotent, open-world, and non-destructive, so the description supplements rather than repeats them. It adds non-obvious output behavior ('Reports cheapest branches, price spread and promotional fields') and data semantics ('Zero prices are unavailable; percentage is not a discount'). It does not exaggerate behavior or contradict 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?

Four sentences, each serving a clear purpose: what it does, when to use it, what it returns, and key data caveats. The core action is front-loaded, and no sentence is redundant with the schema or annotations.

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

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

For a five-required-parameter tool, the description covers purpose, selection criteria, report contents, and pricing caveats, and an output schema exists so return-value details are not required. The only meaningful gap is that 'identity' is left to inference rather than explicitly described as the product identifier.

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 descriptions already cover latitude, longitude, distance, and depots (80% coverage), so the description does not need to re-explain those. It only implies that 'identity' refers to the single product being fetched and does not explicitly define that parameter, which is the main remaining ambiguity.

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 action and object: 'Fetch one product and compare returned branch prices.' It also distinguishes itself from sibling tools by noting that 'existing search offers can already answer price questions,' so an agent can separate it from market_search_products and market_get_product.

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 a detail lookup or refresh is needed; existing search offers can already answer price questions' explicitly states when to invoke this tool and points to the search alternative for price-only lookup. This gives a direct decision rule for choosing it over the sibling search tool.

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. The description adds that the tool is experimental and that depots are required and never auto-expanded, which provides useful behavioral context beyond annotations. No contradiction.

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

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

The description is brief, two sentences, and front-loads the core purpose and key constraints. Every sentence adds critical information, with 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?

Given the tool has 9 parameters and an output schema, the description covers the unique constraints and usage context. It doesn't explain return values but that's covered by the output schema, and it does mention the experimental nature which is important. Minor gaps remain around pagination that are not fully specified, but the essentials 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 coverage is 67%, and the description explains the relationship between marketName and depot prefixes, and the keyword usage. However, it doesn't explain all parameters (e.g., size, pages) beyond what schema provides, so it adds some value but not complete compensation.

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?

Clearly states the tool finds substitutes at one market chain, and explicitly mentions it is experimental. The verb 'Find' and resource 'substitutes' are specific, and the description differentiates it from similar tools like market_find_similar_products by emphasizing the market chain and depot prefix constraint.

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 key usage guidance: marketName must match depot ID prefix, and keywords should include original id and product title. However, it doesn't explicitly state when not to use this tool or mention alternatives like market_find_similar_products, leaving some ambiguity.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior, so the description doesn't need to repeat those. It adds valuable context beyond annotations: the 'Experimental' flag, the constraint that all three values must come from one source, and the output unit (meters) plus the recommendation to use returned IDs for product queries. This enriches the agent's understanding without contradicting 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?

The description is three concise sentences, front-loaded with the core purpose. It avoids redundancy, includes the experimental caveat, and packs the output unit and downstream usage into the last sentence. Each sentence earns its place, and the structure is very efficient.

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

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

Given the tool's moderate complexity and the existence of an output schema (not shown), the description covers the critical aspects: source requirement, experimental status, output units, and how to use results. It lacks details on error conditions or configuration of env location, but those are peripheral for an agent selecting and invoking the tool. Overall, it is sufficiently complete.

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

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

The input schema describes each parameter with clear definitions, covering 100% of the parameters. The description adds a note about source of values (call vs env) but does not materially extend the meaning of latitude, longitude, or distance beyond what the schema already states. Since schema coverage is full, baseline of 3 is appropriate; the description gives minor extra context about the source requirement.

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 ('Find') and resource ('nearby physical branches'), which immediately clarifies the tool's function. It also adds distinguishing detail by mentioning coordinate/radius or env location as inputs, and hints at downstream usage (choose depot IDs for product queries). No sibling tool appears to target depots specifically, so it is clearly differentiated.

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

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

The description implies usage: it tells the agent that a location source is required and that the returned depot IDs are for product queries. However, it does not explicitly state when to use this tool over alternatives, nor does it mention exclusions or prerequisites. The guidance is inferred rather than direct, so it is adequate but not strong.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable behavioral context beyond those hints: results may be merely similar rather than equivalent, and the user must verify title and package size. This is a meaningful caveat not captured by the schema or annotations.

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

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

Two sentences with no filler. The core mechanism is stated first, and the important caution about similarity is placed immediately after. Every word 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 rich output schema, detailed parameter descriptions for most fields, and strong annotations, the description covers the essential operational nuance. It lacks explicit sibling differentiation and does not explain why location and depot parameters are required, but those are largely documented in the schema. Overall adequate 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 75%, and the id and keywords parameters lack their own schema descriptions. The description clarifies their joint role—id is the exact product id and keywords should be its title—which adds meaning beyond the raw schema and helps an agent construct valid 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 specific action ('Find related products') with the exact input mechanism ('using exact product id and its title as keywords'). It clearly identifies the resource domain, though it does not explicitly distinguish itself from the sibling market_find_alternatives beyond the word 'similar'.

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 useful context by warning that similarity is not equivalence and telling the user to inspect title and package size. However, it gives no explicit guidance on when to choose this tool over siblings like market_find_alternatives or market_search_products, nor any when-not-to-use conditions.

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 the operation as read-only, open-world, and idempotent. The description adds meaningful behavioral context by flagging the API as experimental and by revealing that latitude/longitude are parsed from API tuple positions rather than provided as first-class 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?

Three short sentences, each carrying distinct information: purpose, experimental status, and return behavior. There is no redundant or filler content, and the most important detail 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?

For a one-parameter tool with an output schema, rich annotations, and a straightforward purpose, the description is largely sufficient. It could be more complete by noting a typical use case or explicitly contrasting with reverse geocoding, but nothing critical is missing for 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?

The schema has 100% description coverage for the single parameter, and the description does not need to add much. It reinforces that the input is free-form address/place text, but it does not provide additional semantic details 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 uses a specific verb-plus-resource construction ('Find address suggestions') and identifies the tool as an experimental map API. It clearly conveys forward geocoding, though it does not explicitly name market_reverse_geocode as the opposite sibling to sharpen differentiation.

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 explicit guidance about when to use this tool compared with siblings like market_reverse_geocode. The phrase 'address suggestions' implies a forward-geocoding/autocomplete use case, but the description leaves the selection logic to inference.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral context by noting that query, parentId, and flat are local filters and that returned names are Turkish, but it does not disclose pagination, ordering, or hierarchy traversal 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?

The description is two sentences with no filler. The core purpose is front-loaded, and the additional sentence about local filters and Turkish names earns its place by conveying practical usage details.

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?

Annotations and the presence of an output schema reduce the burden on the description. However, with zero parameter documentation in the schema, the description leaves significant gaps about how to use query, parentId, and flat effectively. It is adequate but not fully complete for a tool with three optional parameters.

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 for the lack of parameter documentation. It only states that query, parentId, and flat are local filters, without explaining what each parameter does, how they interact, or what values are expected. This is insufficient for an agent to use the parameters confidently.

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 clearly states the tool retrieves hierarchical categories, which is a specific verb and resource. It also hints at its role in category searches via Turkish names, helping distinguish it from search_by_category, though it does not explicitly name the sibling.

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

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

The description implies the tool is used to obtain category names for subsequent category searches, but it does not explicitly state when to prefer this over alternatives like market_search_by_category or market_search_products. There is no when-not guidance or mention of prerequisites.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds that the filter is applied 'locally' and that the output is a 'chronological series with change statistics,' which is useful context beyond the schema. However, it does not detail any edge cases or limitations beyond that.

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

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

The description is a single, front-loaded sentence that efficiently states the action, scope, optional filter, and expected return. It avoids redundant wording and is appropriately sized for the tool's complexity.

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 presence of an output schema, the description does not need to elaborate on return structure. It covers the core inputs, the optional filter, and the nature of the output (chronological series with change statistics), which is sufficient for an agent to understand the tool's purpose and primary call parameters. It does not mention any rate limits or dependencies, but those are minor given the read-only, idempotent nature.

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 57%, with descriptions for depots, distance, latitude, and longitude. The description mentions uniqueId and depots explicitly and clarifies from/to as optional date filters applied locally, adding value for those parameters. However, it does not fully compensate for the missing schema descriptions of uniqueId, from, and to, leaving some interpretation to the agent.

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 clearly states the verb ('Get') and resource ('market price series') along with key inputs (uniqueId and depot IDs). It is distinct from siblings like market_get_product or market_compare_basket by focusing on price history, though it does not explicitly name an alternative to disambiguate further.

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 gives no explicit guidance on when to use this tool versus the many market siblings. It only implies usage through the name and mentions the optional local filter, but there is no statement of prerequisites, exclusions, or alternative tool selection criteria.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety and side effects. The description adds valuable behavioral context: returns location-specific data, includes promotional fields and indexTime, and warns that barcode wire type is unverified. This extra caveat is useful disclosure beyond the structured 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?

The description is two sentences: the first states the core purpose and output, the second adds a caveat. It is front-loaded with the main action and avoids unnecessary details. Every word earns its place, with 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?

Given the tool has an output schema, the description does not need to explain return structure. It covers the essential purpose, the identity parameter semantics, and the notable barcode caveat. It does not explain how to obtain the required 'depots' parameter (e.g., via market_find_nearby_depots), but the schema description for depots partially covers that. Overall, it is sufficiently complete for an agent to invoke correctly when it has an identity and location context.

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 50% for the 4 meaningful parameters (latitude, longitude, distance, depots) since size, pages, and identityType are constrained constants and effectively non-variable. The description clarifies that identity is an opaque string, adding meaning beyond the raw schema pattern. It does not redundantly restate schema descriptions for the other parameters, which 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?

Description clearly states the action ('Get product'), the target resource ('product'), and the method of identification ('opaque string identity with identityType=id'). It also previews the key output fields (location-specific branch offers, promotional fields, indexTime), distinguishing it from sibling search tools like market_search_products. The caveat about barcode wire type adds specificity.

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

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

The description implies use when you have an opaque identity and need a specific product with location context, but it does not explicitly contrast with alternatives such as market_search_products or market_compare_product_offers. There is no 'when not to use' guidance or mention of prerequisites like needing to first call market_find_nearby_depots to get depots. The context is clear but not fully explicit about selection criteria.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses experimental status, potential HTTP 500 failures, and instructs not to retry. It also adds the clarification that this is not the product category tree, providing further scope. This significantly enriches behavioral context without contradicting any 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?

The description is three sentences long, front-loaded with the primary action, and each sentence provides necessary information: purpose, experimental caution, and clarification. There is no redundant or filler content; every phrase 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 (zero parameters, explicit output schema), the description covers all needed aspects: what it does, when to use it, how to handle errors, and what it is not. The output schema handles return values, so the description does not need to repeat that. The context is fully complete for an agent to decide when to invoke it and how to interpret results.

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

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

The tool has zero parameters, and the schema confirms this (coverage 100% trivially). Per the rubric, a baseline of 4 is appropriate when no parameters exist. The description does not need to explain parameters, and it correctly omits any parameter details.

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 explicitly states the verb and resource: 'List market chains via /api/v1/categories.' It further disambiguates from siblings by stating 'Not the product category tree,' which clearly distinguishes it from market_get_categories. The purpose is specific and unambiguous.

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

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

The description provides clear usage guidance: 'Optional, never a prerequisite for search or comparison.' It also specifies error-handling behavior ('On 500 report unknown chain active status and do not retry'), which tells the agent exactly what to do in a failure case. This is explicit and actionable.

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, so the safety profile is covered. The description adds meaningful extra context: 'Experimental map API' warns about stability, and the note about capitalized Lat/Lon query parameters reveals a behavioral detail about the underlying API beyond 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?

The description is three short sentences with the core purpose front-loaded. The additional notes about experimental status and parameter capitalization are each informative and non-redundant. No wasted words.

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 a simple read-only tool with two fully documented parameters, a rich annotation set, and an output schema, the description covers the essential context. The only slight gap is that the 'capitalized Lat/Lon' note is not reconciled with the lowercase latitude/longitude schema, which could momentarily confuse an agent, but this does not prevent 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 100%, and the schema already provides clear descriptions for both latitude and longitude. The description adds little beyond labeling them as coordinates, so it does not exceed the baseline required when the schema handles the semantic load.

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: 'Resolve coordinates into address fields and display_name.' This clearly conveys reverse geocoding. It does not explicitly name the sibling `market_geocode_address` or contrast with it, so it stops short of full sibling differentiation despite the tool name making the distinction obvious.

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 purpose implies when to use the tool: when you have coordinates and need address fields. However, it provides no explicit when-not-to-use guidance, no mention of alternatives, and no prerequisites or context about preferring another tool. The usage is only implied.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful constraint context (category filter required, depots must be explicit), but does not disclose behavior such as error handling, pagination, or how category names are resolved.

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

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

The description is short and front-loads the search action and category scope. The phrase 'call or configured location' is awkward and slightly unclear, but overall the text is efficient and does not waste words.

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

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

This is a complex tool with 16 parameters, nested objects, and an output schema. The description only covers the category filter and required location/depots. It does not mention how to obtain category names (e.g., via market_get_categories), explain optional filters, or clarify the ambiguous 'call or configured location' phrase. The output schema reduces the need to describe return values, but the input-side context is still incomplete.

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 only 44%, so the description must compensate for many undocumented parameters. It explains the category filter requirement and mentions depots/location, but it does not clarify brand, order, offer_price, market_names, refined_quantity_unit, refined_volume_weight, or other optional filters. This leaves a significant semantic 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?

The description states a specific verb ('Search') and a clear resource: products filtered by menu_category, main_category, or sub_category Turkish names from the category tree. It does not explicitly say 'products', but the category-based scope and the sibling tool market_search_products make the intent clear.

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 gives clear required conditions: at least one nonempty category filter, a location, and explicit depots. It does not name alternatives or state when not to use this tool, but the prerequisites are explicit enough for an agent to decide whether this tool applies.

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). The description adds useful behavioral details: it is a single-page search, requires nonempty depots, and warns that fuzzy search needs result validation. It also mentions following a guide for preserving alternatives. These go beyond annotations and provide practical constraints.

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

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

The description is a compact paragraph, not overly long, and front-loads the core purpose. It packs multiple pieces of guidance without redundancy, though it could be structured more clearly with bullet points for the distinct constraints.

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

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

For a tool with 17 parameters, nested objects, and many siblings, the description feels incomplete. It points to an external guide for exact requirements, which shifts burden. It doesn't explain facets, alternative handling, or how to combine filters beyond examples. The output schema helps, but given complexity, more context is needed.

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

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

Schema coverage is only 41%, and the description only highlights two filters (refined_volume_weight, order) and location/depot requirements. Many parameters (brand, categories, offer_price, etc.) have no description in either schema or the tool description, leaving a significant gap. The description does not compensate for the low 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?

The description states a clear action: 'Search products and facets' and specifies 'one zero-based page', which distinguishes it from paginated search variants. However, it doesn't explicitly differentiate from sibling tools like market_search_by_category or market_find_similar_products, so it's clear but not fully unique.

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 some usage context: location/radius can come from env, depots are required, and it points to a guide for exact requirements. But it doesn't explicitly say when to use this tool over alternatives or when not to use it. The reference to 'market://guide' implies more info but doesn't give concrete alternative selection criteria.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds the important behavioral trait 'No network access,' which is not expressed in the annotations and meaningfully shapes expectations for a local-only status report.

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 content of the report is front-loaded and the key limitation, 'No network access,' is stated immediately afterward.

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 parameterless status tool with an output schema and comprehensive annotations, the description is complete: it names exactly what is reported and explicitly declares the network behavior. Nothing needed for correct invocation is missing.

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

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

The tool has zero parameters and an empty schema, so the baseline is 4; there are no parameter semantics for the description to clarify. The description focuses entirely on what is reported, which is appropriate for a parameterless 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?

The description states a specific action ('Report') and a concrete resource: mode, network lock, supported endpoints, and local limits. It clearly distinguishes this status tool from the data-retrieval siblings by noting it has 'No network access'.

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 context is implied rather than explicit: it is a local status/health check, and the absence of network access contrasts with sibling tools that query market data. However, it never says 'use this when you need X' or names alternatives, leaving some inference to 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 provide readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable context beyond annotations: it notes the tool is 'Experimental', states it emits identityType=id, pages=0, size=identities.length, and confirms 'No purchase or persistent basket mutation'. These details clarify output behavior and operational constraints not captured in 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?

The description is three sentences with no fluff. The main purpose is front-loaded, followed by a critical warning, then output specifics. Every sentence earns its place, and it is appropriately sized for the tool's complexity.

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 that an output schema exists, the description need not explain return values in detail. It covers purpose, exclusions, and output behavior. It is complete for a read-only, idempotent tool. A minor gap is not explicitly naming sibling alternatives, but the warning about basket budgets and live tests covers the main misuse scenario.

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 80% (4 of 5 parameters have descriptions). The description adds minimal extra meaning about parameters; it mentions 'up to 100 product identities' which aligns with the identities array but doesn't elaborate on latitude, longitude, distance, or depots beyond what the schema already states. With high schema coverage, the baseline is 3, and the description does not significantly exceed that.

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

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

The description states a specific action (Fetch up to 100 product identities) with a clear resource and context ('for an explicitly requested refresh'). It distinguishes from siblings by warning against using it to bypass basket budgets or run large live tests, which differentiates it from search and compare tools. This is a precise, non-tautological purpose.

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 explicitly specifies when to use the tool ('explicitly requested refresh') and when not to ('Never switch to this tool to bypass a basket budget or run large live tests'). It does not name specific sibling tools, but the exclusions provide clear usage boundaries. This is strong guidance, though naming alternatives would have made it a 5.

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