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

Annotations already declare readOnlyHint and idempotentHint, but the description adds crucial behavior beyond that: retries are included, over-budget calls are rejected before fetching, incomplete totals are null, and no automatic substitutions or purchases occur. It also clarifies subtle semantics like 'depot means one physical shop' and when splitBasket may be presented as a saving. These are exactly the behavioral details an agent needs beyond the annotation flags.

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 dense paragraph of ~150 words, but every sentence carries operational weight (budget, grouping, splitBasket rules, depot definition). It is front-loaded with the core purpose, then constraints, then edge-case handling. While longer than the typical high-quality one-liner, the tool complexity justifies the length and there is no fluff 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?

The tool has an output schema, so return structure does not need to be described. The description covers budget limits, retries, incomplete totals, splitBasket presentation rules, depot semantics, groupBy branch behavior, and explicitly states no substitutions. It even references an external guide (market://guide) for missing groups and equal totals, leaving very few gaps for an agent to call and interpret results 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 67% (4 of 6 params have descriptions). The description compensates with meaningful context: it ties items to 'exact product IDs and pack quantities', explains the impact of groupBy=market possibly spanning branches, and clarifies that depots are required and never auto-expanded. It does not systematically explain each parameter, but it adds enough to make parameter intent clear 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 opens with 'Compare exact product IDs and pack quantities via individual product lookups', which clearly states the verb, resource, and scope. It distinguishes this from siblings by referencing basket-level constraints (basketItems, basketRequestBudget) and later conditions on presenting splitBasket, which is unique to basket comparison. An agent can tell it apart from single-offer tools like market_compare_product_offers.

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 explicit when-not guidance: 'Never split the list or switch tools to bypass the budget; ask the user to narrow the comparison.' It also sets expectations for result handling ('Present complete groups first...') and fallback rules ('follow market://guide for missing groups'). It does not name an alternative tool explicitly, but the sibling list and the 'switch tools' prohibition make the boundary clear enough.

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 carry the safety profile (readOnly, openWorld, idempotent, non-destructive), lowering the bar. The description goes beyond them with non-obvious interpretation semantics: 'Zero prices are unavailable; percentage is not a discount' prevents agents from misreporting free items or discount percentages, and it summarizes returned content (cheapest branches, price spread, promotional fields). These are exactly the behavioral details that prevent invocation errors.

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 with a distinct job: purpose, usage guidance, return-value summary, and data interpretation caveat. The core action is front-loaded and every sentence earns its place with zero 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 a rich output schema and complete annotations, the description covers purpose, usage, return values, and pitfalls — enough for an agent to invoke correctly. The remaining gaps are the undocumented 'identity' parameter and indirect sibling differentiation, which are minor against the schema's coverage.

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 80%, so the schema already documents latitude, longitude, depots, and distance with useful constraints. The description adds no per-parameter meaning and leaves the undocumented 'identity' parameter unexplained. Baseline 3 is appropriate since the schema carries the heavy lifting.

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

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

The opening sentence 'Fetch one product and compare returned branch prices' states a specific verb, resource, and scope in one line. This clearly distinguishes it from market_get_product (single fetch without comparison) and market_search_products (search without branch-price comparison).

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' gives explicit invocation context, and 'existing search offers can already answer price questions' provides a concrete when-not condition that routes agents toward search siblings. It stops short of naming market_search_products or market_compare_basket explicitly, so the routing is clear but not fully exhaustive.

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 disclose read-only, idempotent, and non-destructive behavior, lowering the bar. The description adds value beyond annotations with the 'Experimental' flag and the strict marketName-prefix matching requirement. It does not detail failure behavior when the prefix mismatches or any reliability caveats implied by 'Experimental.'

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 with the purpose front-loaded in the first. The 'Experimental' fragment is terse but earned, and the final sentence packs critical usage constraints. Nothing is redundant, though 'Experimental' could arguably carry a bit more context.

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

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

For a 9-parameter tool with six required fields and an output schema, the description covers the non-obvious id/keywords semantics and the scope constraint. Missing: what happens on marketName/depot prefix mismatch, and no guidance on pagination controls or the reliability implications of 'Experimental.' Moderate complexity meets moderate completeness.

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%, leaving id, keywords, and marketName undocumented in the schema. The description directly compensates by mapping id to 'original id', keywords to 'product title', and tying marketName semantically to the depot ID prefix. This is real added meaning for exactly the parameters that most need it.

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 action and resource: 'Find substitutes at one market chain.' The 'at one market chain' scope is a genuine constraint that helps an agent understand the tool's domain. However, it never names the closest sibling (market_find_similar_products) or explains how substitutes differ from similar products, so differentiation is implied rather than explicit.

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

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

The description provides invocation constraints—'marketName must match each supplied depot ID prefix; provide original id and product title as keywords'—which help construct a valid call. But it gives no when-to-use guidance, no exclusions, and names no alternatives from the 14 sibling tools, so an agent cannot decide when to choose this over market_find_similar_products or market_search_products.

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 non-destructive behavior. The description adds useful context beyond those: it flags the tool as 'Experimental' and clarifies that response distances are in meters, which is not obvious from the input schema. No contradiction with 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?

Three short sentences, each earning its place: the core purpose, the experimental warning, and the critical output-unit/usage note. The main action is front-loaded and there is 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?

For a simple read-only lookup with a rich output schema and strong annotations, the description is complete. It adds the non-obvious response unit (meters) and downstream usage guidance (choose returned depot IDs for product queries), while the schema and annotations cover safety and 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 100%, so the schema already documents latitude, longitude, and distance. The description reinforces that distance is a radius in km and calls coordinates 'explicit', but it does not add substantial new parameter meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description states a specific action ('Find nearby physical branches'), a specific method ('explicit coordinates and radius in km'), and the resource type. 'Explicit coordinates' also distinguishes this from geocoding/reverse-geocoding siblings, so an agent can tell it apart 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 gives clear context: use this when you have explicit coordinates and a radius, and then use the returned depot IDs for product queries. It does not explicitly name alternatives or exclusions, but the 'explicit coordinates' phrasing implies the boundary against geocoding 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?

The description adds behavioral context beyond the readOnly/idempotent annotations: 'exact product id' stresses matching precision, and 'Similarity is not equivalence: inspect title and package size' warns that returned matches require manual verification. This does not contradict any annotation.

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 no filler. The core instruction is front-loaded, and the second sentence adds an essential caveat rather than redundant detail.

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 schema descriptions for latitude, longitude, depots, distance, and pagination, plus the existence of an output schema, the description covers the key missing semantics: how to set keywords and how to interpret 'similar' matches. It lacks explicit sibling routing, but that gap is a usage-guidance issue more than a completeness failure.

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 75%, leaving id and keywords without semantic descriptions. The description fills this gap by stating that id must be exact and that keywords should be the product's title. It does not spell out how to format or truncate the title, so it is helpful but not exhaustive.

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 action and resource ('Find related products') and specifies the method ('using exact product id and its title as keywords'), which distinguishes it from free-text search tools. It does not explicitly differentiate it from the sibling market_find_alternatives, so it stops short of a 5.

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

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

The phrase 'using exact product id and its title as keywords' implies a use case and input prerequisite, which is more than no guidance. However, there is no explicit when-to-use versus siblings like market_find_alternatives or market_search_products, nor any when-not-to-use or exclusions.

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

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

Annotations already 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 and idempotentHint, so the safety profile is covered. The description adds useful behavior beyond those annotations: the from/to filter is applied 'locally' and the result is a chronological series with change statistics. This clarifies output shape and filtering semantics 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 entire description is one compact sentence that front-loads the core action and then adds the key qualifiers: optional filter behavior and returned outputs. Every clause earns its place; there is no redundant 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?

The output schema covers return values, so the description need not restate them. Still, the description leaves a meaningful gap: 'uniqueId' is not semantically clarified, and the relationship between required latitude/longitude and the depot list is not explained. The schema partially fills this via depots' description, but the description alone would not let an agent confidently construct a correct 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 coverage is only 57%, so the description must compensate. It adds meaning for depots ('selected product depot IDs') and from/to (date format, local filtering), but 'uniqueId' remains undefined and ambiguous—the agent cannot tell from the description what entity it refers to. Latitude, longitude, and distance are already described in the schema, so those are adequately covered.

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 and resource: 'Get market price series' for a unique ID and selected depot IDs. It also states the date filter and the returned outputs (chronological series, change statistics), which clearly distinguishes it from siblings like market_get_product or market_compare_product_offers.

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 enough context to infer the intended use: retrieving historical price series with optional date filtering. However, it does not explicitly state when to prefer this over alternatives, nor does it mention exclusions or conditions such as when compare/offer tools should be used instead.

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, and destructiveHint=false. The description adds useful behavioral context beyond that: it returns location-specific branch offers, promotional fields, and indexTime, and it explicitly warns that 'Barcode wire type is unverified.' No contradiction with 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?

Three short sentences, no filler. The core lookup mechanism is front-loaded, followed by return-value highlights and a caveat. 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 an output schema present, the description does not need to enumerate return fields exhaustively. It covers the essential lookup mode, location-specific behavior, and a data-quality caveat. It could be more complete by naming sibling tools for routing, but it is sufficient for a read-only, idempotent lookup.

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%, with depots, distance, latitude, and longitude already described. The description adds meaning for identity ('opaque string identity') and reinforces identityType=id, but it does not clarify size or pages. Those are constrained to constants, so the gap is minor, but the description only partially compensates for the schema's missing 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 states a specific verb ('Get'), a resource ('product'), and a precise lookup mode ('opaque string identity with identityType=id'). It clearly distinguishes this from broader search tools like market_search_products, though it does not explicitly name sibling alternatives.

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 should be used when you have an opaque string identity and identityType=id, and it notes location-specific output. However, it gives no explicit guidance on when to choose this over market_search_products, market_find_similar_products, or market_compare_product_offers, nor does it state exclusions.

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

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

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 carry readOnly/idempotent/non-destructive safety. The description adds only a validation constraint (nonempty category filter, explicit location/depots) and no additional runtime behavior such as default scope, empty-result handling, or matching semantics. It does not 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?

One tight, front-loaded sentence with no filler. Every clause carries useful information: search type, accepted category levels, language, and hard prerequisites.

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?

Despite an output schema and safe annotations, this is a 16-parameter search endpoint with nested objects; a 22-word description is under-specified. It omits what entity is returned, how valid category names are obtained, and how this relates to market_search_products or market_get_categories.

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 44%, and the description adds meaning for the category parameters (Turkish names from the category tree) and emphasizes location/depots. However, many remaining optional parameters (brand, market_names, offer_price, refined_*) have no schema or description coverage, so the text only partially compensates for the 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 names a specific action ('Search') and the distinguishing input ('menu_category, main_category or sub_category Turkish names from the category tree'), and the 'at least one nonempty category filter' constraint separates it from a general product search. It does not explicitly state the returned resource (products vs offers), so it does not fully earn a 5.

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

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

It clearly states the core prerequisites: at least one nonempty category filter and explicit location/depots. This prevents invalid calls, but it does not name sibling tools such as market_search_products or market_get_categories or give when-not-to-use guidance.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the description only needs to add value beyond those. It adds useful behavioral nuance: fuzzy search still needs result validation, explicit depots are required, only one zero-based page is returned, and the market://guide preserves alternatives and exact requirements. No contradiction with 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 concise at three sentences and front-loads the action with 'Search products and facets.' Each sentence contributes a distinct fact, though the 'market://guide' reference is cryptic and unexplained.

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 17 parameters, 4 required fields, nested objects, and only 41% schema coverage, this description is too thin to fully specify the calling contract. It relies heavily on an external market://guide and does not clarify array filter semantics or the relation between product search and facets. The output schema covers return values, but the input behavior remains under-specified.

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 41%, and many filter arrays such as brand, main_category, sub_category, and refined_quantity_unit have no descriptions. The description names only refined_volume_weight and order as examples and refers to 'known API filters', which is a pointer rather than an explanation. It adds meaning for keywords ('fuzzy search') and prerequisites, but does not compensate for the large undocumented parameter space.

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

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

The description opens with a specific verb and resource: 'Search products and facets, one zero-based page,' which immediately conveys what the tool does and its pagination scope. It does not explicitly differentiate itself from sibling tools like market_search_by_category or market_get_product, but the constraints and filter examples make its role reasonably 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 invocation context: combine keywords with known filters, require explicit location and nonempty depots, and follow market://guide for exact requirements and alternatives. It does not name alternative tools or provide when-not-to-use conditions, but it communicates prerequisites and validation cautions effectively.

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, and non-destructive behavior. The description adds valuable context beyond annotations by explicitly stating 'No network access' and enumerating what the status report covers, which helps set expectations for an agent.

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 sentence with no filler. Every phrase adds meaning: what is reported and the key behavioral constraint. It is front-loaded and immediately understandable.

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 zero-parameter status tool with a rich output schema and comprehensive annotations, the description is complete. It explains the tool's scope and network behavior, leaving no critical gap for an agent 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?

The tool has zero parameters, so the schema fully covers parameter semantics. The baseline for a zero-parameter tool is 4, and the description correctly adds no unnecessary 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 uses a specific verb ('Report') with a clear resource: mode, network lock, supported endpoints, and local limits. This distinguishes it from all sibling tools, which perform searches, geocoding, or product lookups rather than reporting status.

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 clear usage: call this tool to obtain environment/status information. It does not name alternatives, but no sibling tool serves the same purpose, so the context is clear and no exclusions are 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 declare readOnly/idempotent/non-destructive, and the description adds valuable behavioral detail: it is experimental, returns at most 100 items, emits specific fields (identityType=id, pages=0, size=identities.length), and states there is no purchase or persistent basket mutation. This goes beyond the annotations without contradicting them.

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-loaded: purpose first, then the experimental caveat, then the advisory warning, then behavior. Each sentence adds necessary information; only the technical emission detail feels slightly dense, but nothing is redundant.

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 sync tool with an output schema and rich annotations, this description covers the critical context: purpose, cardinality, experimental status, misuse warning, and no side effects. It does not explain how to initiate a refresh or what 'explicitly requested' means in practice, but an agent can safely invoke it with the provided information.

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%, so the parameters are mostly self-documenting. The description adds a little semantic value by linking identities.length to the response size and enforcing the 100-item cap, but it does not explain the other parameters beyond what the schema already provides, 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?

The description clearly states the verb and resource: 'Fetch up to 100 product identities in one call for an explicitly requested refresh.' This distinguishes it from search or detail tools, though it never names a specific sibling tool to differentiate against.

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

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

It explicitly says when to use ('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 the alternative tools to use instead, which keeps it from a 5.

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