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

No annotations are provided, so the description carries the full burden. It states it returns keyword suggestions, which is a clear behavioral outcome, but does not disclose potential limitations (e.g., network dependence, rate limits, or what happens if the query is already clean). The behavior is simple and non-destructive, so a 3 is appropriate.

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 concise sentences, front-loaded with the primary purpose, followed by a usage hint and output description. No wasted words; every sentence earns its place.

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

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

The tool has an output schema (not shown), so return values are covered by that. The description covers the purpose, when to use, and what the output is used for. It could mention edge cases or failure modes, but for a simple autosuggest tool, the coverage is adequate.

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 0%, so the description must compensate. It explains the 'query' parameter as the messy shopper wording, adding context beyond the schema's basic type. It also clarifies the purpose of the parameter within the tool's workflow, providing meaningful value.

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 verb ('correct and complete') and resource ('Amazon.in search query'), and mentions it returns keyword suggestions. It implies a role as a preprocessing step, but doesn't explicitly name sibling tools like 'autosuggest' to differentiate them, which would strengthen clarity.

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

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

Explicitly states when to use: 'when the shopper's wording is messy (typos like 'lonovo loq')'. It also indicates the output feeds into amazon_search or compare_marketplaces, but doesn't explicitly state when not to use or list alternatives beyond that implied flow.

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?

With no annotations, the description carries full burden. It discloses the mechanism (Glow address-change call, reloading product HTML) which hints at read behavior, but does not state whether the address-change call has side effects, if authentication is required, or what the exact return format is. Partial transparency, but enough to understand the process.

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 zero redundancy. The purpose is front-loaded, and the second sentence provides method context without fluff. 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?

An output schema exists, so return format is covered elsewhere. However, given the tool's complexity (uses HAR, address-change call), the description does not mention safety, authentication, or potential side effects. It is adequate for basic usage but not fully complete for a tool that performs a multi-step operation with possible mutation.

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 0%, so the description must add meaning. It specifies that pincode must be 6-digit and mentions ASIN, but does not explicitly explain that asin_or_url accepts a URL as well, nor does it clarify the URL format or any validation rules. It adds some value but does not fully compensate for the lack of schema descriptions.

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 (check delivery ETA) and the specific resource (Amazon.in, ASIN, pincode). It is specific and distinct from sibling tools like search_products or get_product, which focus on discovery or product details rather than delivery estimates.

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 (when delivery ETA is needed), but the description does not explicitly contrast with alternatives or provide exclusions. It does not say 'use this instead of X' or mention scenarios where this tool would not be appropriate, 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?

With no annotations, the description carries the full behavioral burden. It discloses that the pincode parameter triggers delivery-location setup via Amazon Glow and refreshes ETA, which is valuable behavioral detail. However, it does not explicitly state whether the operation is read-only, any potential side effects, rate limits, or permission requirements. Since it implies a fetch (read) but doesn't confirm side-effect-free behavior, a score of 3 is appropriate.

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 zero filler. The first sentence front-loads the core purpose and return contents; the second explains the optional parameter and its effect. It is tightly structured and every clause adds value, earning a perfect score.

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 doesn't need to detail return structure, but it already lists the key data (price, specs, delivery, variants, reviews). It also covers the optional pincode behavior. For a fetch tool with a defined output schema, this is complete. It could mention error cases or unsupported inputs, but that is not essential for correct invocation. A score of 4 reflects its adequacy without overreach.

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 explain parameters itself, which it does well. It clarifies asin_or_url (ASIN or /dp/ URL) and pincode (6-digit Indian PIN, sets delivery location, refreshes ETA). It even gives an example ASIN. The only minor gap is that it doesn't specify the exact format of the /dp/ URL or any validation rules, but it's sufficient for an agent to construct valid inputs.

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 clear verb ('Fetch') and a specific resource ('one Amazon.in product'), then enumerates the exact data returned (live price, specs, delivery, variants, reviews). It distinguishes itself from siblings like amazon_search by specifying that it fetches a single product given an ASIN or /dp/ URL, making its purpose 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?

It states that it accepts an ASIN or a /dp/ URL 'from amazon_search', implying it is meant to be used after searching. This gives context on when to invoke it. However, it does not explicitly mention alternatives like get_product or compare_products, nor when not to use this tool. Still, the reference to amazon_search provides a clear workflow hint, so it earns a 4.

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?

With no annotations provided, the description carries the full burden. It discloses the return format ('Returns rh strings') and notes that facets change by category. It doesn't mention side effects (likely a read operation) or error conditions, but for a simple listing tool, this is adequate. It also implies the output is meant to be passed to amazon_search, which is useful behavioral context.

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

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

The description is extremely concise, with two short paragraphs that front-load the purpose and then immediately explain the output and usage. Every sentence serves a purpose: the first states the action, the second describes the output and how to use it, and the third notes a behavioral trait. 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?

For a tool with one parameter and an output schema, the description covers the essential information: what it does, what it returns (rh strings), and how to consume them (pass as extra_rh on amazon_search). It also notes the category-dependence. It doesn't delve into edge cases or detailed output schema, but the existence of an output schema likely covers that. Overall, it's sufficient for an agent to call it correctly.

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

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

The schema has a single parameter 'query' with no description, and schema description coverage is 0%. The description says 'for a query' which implicitly defines the parameter as the search query, but it adds no additional constraints, format details, or examples. It provides minimal value beyond the schema's name, but it does at least contextualize the parameter.

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's purpose: 'List Amazon.in refinements for a query.' It identifies the specific marketplace (Amazon.in), the action (list refinements), and the input (query). It differentiates from the generic sibling 'list_search_filters' by explicitly mentioning the domain. The examples of rh strings (price, brand, RAM, screen size) further clarify what refinements are.

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 usage guidance: 'Pass those as extra_rh on amazon_search.' This tells the agent exactly how to consume the output. It also notes that facets change by category, implying the output is query-dependent. However, it doesn't explicitly contrast with the sibling 'list_search_filters' or other alternatives, but the domain-specific naming and the 'amazon_search' reference make the intended use 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?

No annotations are provided, so the description carries the full burden. It discloses important behaviors: sponsored cards are dropped unless include_sponsored is true, price filters are encoded as rupees*100, and results are live product cards. However, it omits details like pagination behavior, rate limits, or error handling, which are relevant but less critical for a search tool with an output schema.

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

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

The description is well-structured and front-loaded with the main purpose. It lists output fields and then parameter specifics in a compact, scannable format. Every sentence adds value, and there is no redundancy or fluff. It is concise yet information-dense.

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 existence of an output schema, the description doesn't need to repeat return types, but it still lists the fields. It covers the key parameter quirks and default behavior for sponsored items. Missing are pagination limits and handling of edge cases, but for a search tool with schema support, the description is mostly 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?

Schema description coverage is 0%, so the description must compensate. It explains sort values, min_price/max_price encoding, and extra_rh provenance, which is valuable. It does not mention the 'page' parameter, leaving its semantics unclear beyond the default in the schema. Overall, it covers most parameters well but misses one, so it is above baseline but not perfect.

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

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

States a specific verb-plus-resource: 'Search Amazon.in and return live product cards.' The mention of 'Amazon.in' narrows the scope, and the output fields are listed. However, it does not distinguish itself from sibling tools like search_products or amazon_search, so an agent might struggle to pick this over a similar-sounding sibling without inspecting more.

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 context for parameters (e.g., extra_rh from amazon_list_search_filters) but does not explicitly state when to use this tool versus alternatives. There is no 'when to use' or 'when not to use' guidance relative to sibling search tools, so the agent must infer the appropriate context from the parameter hints.

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?

With no annotations provided, the description carries full responsibility for behavioral disclosure. It states that it returns suggestions, category-scoped searches, and sometimes product matches, which is helpful. However, it does not mention whether the tool is read-only, any side effects, or limitations, so it leaves some behavioral aspects implicit.

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 and front-loaded with the core purpose, followed by usage context and expected results. Every sentence serves a purpose, and there is no redundant information.

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

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

An output schema exists, so return details are covered externally. The description explains what the tool does, when to use it, and what it returns at a high level. It lacks explicit mention of edge cases or query formatting, but for a single-parameter tool with an output schema, it is reasonably 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?

Schema description coverage is 0%, so the description must compensate. It only implies the query is the shopper's raw input by saying 'wording is messy', but it does not elaborate on format, length, or any constraints. The description adds minimal meaning beyond the parameter name 'query'.

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 a specific verb ('Correct and complete') and resource ('Flipkart search query'), and distinguishes the tool's purpose from siblings like search_products and amazon_autosuggest by emphasizing it's for messy queries. The mention of 'first' also implies a distinct role in the search flow.

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 'Use this first when the shopper's wording is messy (typos, missing brand/model)', which gives clear when-to-use guidance. However, it does not explicitly list when not to use it (e.g., when the query is already clean, use search_products directly), so it's strong 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?

No annotations exist, so description carries full burden. It discloses parallel search, returns organic cards with live selling_price, and suggests follow-up actions. This provides a reasonable behavioral picture for a search tool, even though it omits pagination or error handling. Adds value by clarifying the real-time price aspect.

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 adding value: purpose, when to use, what it returns, follow-up guidance. Front-loaded with the core action, no fluff, well-structured.

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?

Covers main use case and follow-up, but omits explanation of parameters and any details about output format beyond 'top organic cards'. The presence of an output schema helps, but its content is unknown. For a tool with multiple parameters and zero schema descriptions, more completeness would be expected.

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% and the description does not explain any parameters except implicitly query via 'same query'. It does not mention limit, max_price, or min_price, though their names are somewhat self-explanatory. With zero schema coverage, the description should compensate, but it does not.

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

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

States a specific verb (Search) and resource (Flipkart and Amazon.in in parallel). Clearly differentiates from siblings which are single-marketplace searches by mentioning 'across stores'. Also specifies it returns top organic cards with live prices.

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

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

Explicitly says 'Use this when the shopper wants the cheaper/better listing across stores.' This gives clear context. It also suggests follow-up calls to get_product and amazon_get_product, implying this is a preliminary step. Does not explicitly name alternatives but implies single-store searches are not this tool's purpose.

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?

With no annotations, the description must carry the behavioral burden. It discloses that calls run in parallel, that the tool accepts 2–5 items, and that results are live fields identical to get_product. It does not cover error handling or invalid inputs, but the core behavior is transparent enough for a fetching/comparison tool.

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, front-loaded with the core action and outcome. Every sentence adds value: input source, return shape, and when to prefer this tool. No filler or redundancy.

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, the description is nearly complete: it defines the operation, input source, count limit, and return shape. It could additionally state what happens when fewer than 2 or more than 5 items are provided, but that is a minor gap and 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?

The schema provides no description for pid_or_urls, so the description compensates by explaining it accepts pids or URLs sourced from search_products and expects 2–5 items. It does not specify URL formats or behavior for invalid entries, but this is solid semantic guidance for the single parameter.

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 ('Fetch 2–5 Flipkart products in parallel') with a clear outcome: side-by-side comparison. It distinguishes itself from get_product by emphasizing parallel fetching and comparison, and from search_products by being a comparison tool. The purpose is immediately 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?

Explicitly tells the agent where inputs should come from ('Pass pids or product URLs from search_products') and gives a clear use case: use this instead of mixing remembered prices with a new search. It does not explicitly say 'use get_product when you need a single product,' but that exclusion is strongly 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?

With no annotations, the description carries the burden, and it does well: it discloses what is and is not captured ('Review bodies and pincode-accurate delivery ETAs are not in this capture'), warns to 'Quote the numeric selling_price from this payload,' and indicates liveness. This is meaningful behavioral context, though it doesn't mention failure modes or rate limits.

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

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

Three tight, front-loaded sections: what it does, accepted arguments, and exact return content with exclusions. Every sentence adds value and the structure makes it skimmable for an agent.

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 2-parameter complexity and the presence of an output schema, the description is more than complete: it goes beyond the schema to list exact return fields, call out exclusions, and provide a quoting instruction. Nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 0%, so the description is the only source of parameter meaning. It fully explains both parameters: pid_or_url accepts a product URL or pid with an example, and listing_id is optional and selects a specific seller listing (LST...). This compensates completely for the bare schema.

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

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

The description opens with a specific verb and resource: 'Fetch one Flipkart product with live price, specs, offers, and reviews.' It clearly differentiates from siblings like search_products (one product vs. search results) and amazon_get_product (Flipkart vs. Amazon). The outcome is unmistakable.

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

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

The description implies when to use the tool: when you need one product's details, accepting a URL from search results or a pid. However, it never explicitly names alternatives or states when not to use it, such as 'use search_products to find products' or 'use amazon_get_product for Amazon products.' Usage guidance is present but 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says 'Return' without explicitly stating that this is a read-only operation, nor does it mention authentication, pagination, error behavior, or side-effect safety. The read-only nature is implied but not made transparent.

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 states the operation, resource, and input with no filler. Every word contributes to the meaning.

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 read-only tool with an output schema, the core calling scenario is covered: given a pid or url, return similar products. The main gap is the lack of behavioral details (e.g., auth or side effects), but the low complexity and output schema mitigate the incompleteness.

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 sole parameter is pid_or_url, and the description says 'pid or url', which adds minimal context by indicating the parameter identifies the product whose similar items are returned. However, this largely mirrors the schema title and provides no additional format, validation, or disambiguation details, so it only partially compensates for the 0% schema description 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 uses a specific verb ('Return'), names the exact resource ('Flipkart's similar / you-may-also-like products'), and specifies the input ('a pid or url'). This clearly differentiates it from siblings like get_product or search_products, which serve different purposes.

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 for when to use the tool: when similar or you-may-also-like products are needed for a Flipkart product ID or URL. It does not explicitly name alternative tools or exclusion conditions, so it stops short of a 5, but the intended use is unambiguous.

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?

No annotations are provided, so the description carries the behavioral disclosure burden. It explains the dynamic nature of facets by category, states that filter ids and params strings are returned, and gives the important caution that facet names should not be guessed. This is meaningful behavioral context 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 sentences, front-loads the core purpose, and adds practical usage details without waste. Every sentence contributes valuable information.

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

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

For a single-parameter tool with an output schema, this description is complete. It explains what is returned, how to use the returned values, and warns about category-dependent facet changes, giving an agent everything needed to call and apply the tool 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 0%, so the description needs to compensate. It references 'a query' and 'current query', making it clear that the query parameter is the search term to fetch facets for, but it doesn't provide examples, constraints, or formatting details. The single parameter is simple, but the description only partially compensates for the missing schema documentation.

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 lists Flipkart facets for a query to refine search_products, including specific facet examples and the purpose of returning filter ids and params. It also distinguishes itself by naming Flipkart, separating it from the Amazon sibling 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 gives explicit context: call this tool to get facets for a given query and pass the returned params to search_products. It also advises always calling for the current query instead of guessing facet names, which is strong usage guidance, though it doesn't explicitly contrast with the Amazon marketplace variants.

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?

With no annotations, the description carries the full burden of behavioral disclosure. It explains the tool's output structure (product cards with pricing, rating, badges, etc.) and the behavior of key parameters, such as sort ordering and min_rating semantics. It does not cover rate limits, error handling, or side effects, but those are less critical for a search operation.

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 organized into a purpose sentence, an output-shape sentence, and parameter semantics with examples. It front-loads the most important information and each sentence earns its place, though it is a little longer than strictly necessary.

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

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

An output schema is present, and the description still goes beyond it by explaining card fields and parameter behavior. It covers the ambiguous parameters and connects to list_search_filters. Missing pieces like pagination semantics and no-result behavior are minor and do not block correct invocation.

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

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

Schema description coverage is 0%, so the description must add parameter meaning. It does so for the non-obvious parameters: sort lists all allowed values, min_rating is defined as '4★ & above', brands is exemplified as a JSON array, and extra_facets gets concrete raw-parameter examples. Self-evident parameters like max_price and page are left to 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 'Search Flipkart and return live product cards' – a specific verb, target marketplace, and output type. This clearly distinguishes it from direct alternatives like amazon_search and from single-product/compare tools like get_product and compare_products. The enumeration of card fields further removes ambiguity.

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

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

The description establishes the core use case (searching Flipkart products) and refers to list_search_filters as a source of raw facets, which is a hint at a related workflow. However, it never explicitly states when to prefer this tool over siblings such as get_product, compare_products, or amazon_search, leaving routing to inference.

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