APIClaw

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

With no annotations provided, the description carries the full burden and delivers exceptionally: it discloses asynchronous downloading, Processing→Active status transitions, polling endpoint, retry/fail-fast behavior, CONTRACT-tier restriction, and free-of-charge nature. It also includes response examples and error schema, making behavior highly predictable.

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 prose is well-structured and front-loaded with the purpose, followed by lifecycle detail and availability. The response section includes large embedded JSON schemas which add length but are useful given no separate output schema. Overall, the content earns its place, though it is longer than minimal.

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 complexity and the absence of formal output schema and annotations, the description is remarkably complete: it covers use case, lifecycle, polling, error handling, tier access, and includes response examples and validation error schema. Nothing essential seems missing for an agent to invoke this 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?

Input schema coverage is 100% and the schema itself is richly descriptive (URL reachability/auth requirements, name being bookkeeping-only, assetType enum). The description adds no parameter-specific meaning beyond what the schema already states; it mentions the assetId return and usage context rather than param details. 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 opens with 'Register a public URL as a video-generation asset' and repeats a clear, specific action. It explicitly distinguishes this from sibling read/list/generation tools by framing it as the registration step for video generation, and it explains the asset:// reference format that ties it to generation requests.

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 when to use this tool: before submitting a video generation request with an external URL, and how to check readiness via polling. It does not explicitly name sibling alternatives or say when not to use it, but the workflow context is clear and practical.

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 that responses vary by customer tier, includes both legacy and exact credit fields (ADR-0003), and notes the polling uniqueness. It does not mention authentication or rate limits, but as a read operation the risk is low. The description adds substantial behavioral context beyond the tool name.

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 lengthy, including extensive output schema blocks, example JSON, and ADR references with TODO comments. While the lead sentence is concise, the body is dense and could overwhelm an agent. Some details (e.g., TODO timestamps) are not essential for invocation, but the length is partly justified by the lack of a formal output schema.

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

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

The description covers the success and validation responses, tier-specific behaviors, the polling uniqueness for CONTRACT-tier, and the parallel credit fields strategy. It gives example output and details on error structure. For a no-param tool with no separate output schema, this is sufficient for an agent to call it 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?

The tool has zero parameters, so the baseline of 4 applies. The schema is empty and requires no explanation; the description adds no parameter info because none is needed.

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 it 'Get[s] account billing balance' and then explains the tier-specific views (usd vs credits), making the purpose unambiguous. It distinguishes itself from siblings by focusing on billing balance, though it doesn't name alternatives explicitly.

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

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

It provides a concrete 'when to use' scenario: for CONTRACT-tier customers to observe USD balance, noting this endpoint is the only way. It doesn't explicitly mention alternatives or when not to use, but the billing context is clear enough for an agent to decide.

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 transparency burden. It discloses important behaviors: 404 for non-existent or cross-tenant assets to avoid leaking existence, and a CONTRACT-tier restriction. It also includes response schemas and credit field details, adding context beyond the minimal purpose. Slightly less rich because it doesn't describe the 'data' payload structure.

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 opening paragraphs are concise and front-loaded, but the description then includes lengthy response schema blocks (especially the meta section with ADR-0003 migration details and TODOs) that are tangential for tool selection. While structured, it is bloated and not every sentence earns its place.

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

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

For a simple 1-param tool with no annotations and no output schema, the description gives purpose and some error semantics, but it omits the structure of the actual asset data (the 'data' field in the response). The 200 response example only shows meta, not the asset metadata/live status fields the tool is supposed to retrieve, leaving an incomplete picture of what the caller will receive.

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 sole parameter asset_id has no schema description. The description only says 'by id,' which adds virtually no semantic detail beyond the parameter name. It does not specify format, constraints, or examples, failing to compensate for the complete lack of schema-level parameter 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's function: 'Get a video-generation asset by id' and 'Fetch a single asset's metadata and live status.' This is a specific verb+resource combination with a clear scope (by id), and it distinguishes from siblings like create_video_asset, list_video_assets, and poll_video_task.

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 when you have an asset ID and need its metadata/live status, and it adds a clear constraint ('Available to CONTRACT-tier API keys only'). However, it does not explicitly state when to prefer this over list_video_assets or poll_video_task, nor does it provide exclusions or alternatives.

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 and does so thoroughly: it discloses that items omit the `status` field, that listing is served from a local registry without live provider status, and that the tool is restricted to CONTRACT-tier keys. No annotation contradiction exists.

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

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

The opening prose is front-loaded and useful, but the description is bloated by a massive inline response schema, error schema, and examples, including internal TODOs and credit-field details. The first sentence is also redundantly restated in the second sentence.

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 verbosity, the description is highly complete: it covers behavior, ordering, auth requirements, the absence of status fields, how to get live status, and even includes the full response and error schemas. No important aspect of tool selection or 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 input schema already covers 100% of parameters (page, pageSize, assetType) with clear descriptions, so the description adds no parameter-specific meaning. The baseline of 3 applies because the schema does 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 description immediately states 'List your video-generation assets' and clarifies 'List the calling customer's assets, newest first.' It clearly identifies the verb, resource, and scope, distinguishing it from single-asset retrieval tools like get_video_asset.

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 explains when to use this tool for fast/cheap listing and when not to: 'call GET /openapi/v2/model/video/assets/{assetId} when you need the current status of a specific asset.' It also discloses the CONTRACT-tier API key restriction.

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 disclosure burden and does so well: it explains account scoping, omission behavior and the 404 consequence, CONTRACT-tier availability, per-resolution pricing rows, and how task cost is computed.

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 core purpose and operational details are front-loaded and well structured. However, the opening sentence is effectively duplicated by the second sentence, and the description also includes full response/example schema text that is not essential to tool selection.

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 discovery endpoint, the description is complete: it covers what is returned per model, how pricing is represented, how to compute cost, access restrictions, and behavior for unavailable models. Nothing important 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, so there is no parameter semantics for the description to clarify. The baseline for a parameterless tool is 4, and nothing here lowers 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 states a specific verb and resource: listing video generation models available to the account, including contracted prices. It also distinguishes the result from generation/asset tools by explaining that each entry contains the model alias to pass to the video generation endpoint.

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

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

It gives clear usage context: this is how to discover enabled models and aliases before calling the generation endpoint, omitted models return 404, and only CONTRACT-tier keys can use it. It does not explicitly name the sibling tool submit_video_generation as the alternative or state when not to use this tool, so it falls short of a 5.

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

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

Annotations are absent, so the description carries the full burden. It implies read-only behavior via 'Query' and states that no parameters returns all root categories, but it does not explicitly declare read-only status, authentication requirements, rate limits, or side effects. It does disclose mutual exclusivity of parameters and provides response structure, but without annotations, a more explicit behavioral profile would be stronger.

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 prose portion is concise and well-structured: purpose, example, query modes, and related endpoints are clearly organized and front-loaded. However, the description includes a large response schema block (due to no separate output schema) that makes the overall text lengthy, though this is a necessary inclusion rather than redundancy. The core guidance is tight and 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?

The description covers all 6 optional parameters, explains the behavior for each query mode, includes examples, and details how this tool connects to other endpoints. It also embeds the output schema (since no separate schema exists) and error responses. For a read-only discovery tool with no required parameters, this is comprehensive enough for an agent to select and invoke it correctly without ambiguity.

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 already describes each parameter (100% coverage), but the description adds significant context: it explains the mutual exclusivity of query modes, what each mode does (e.g., 'No parameters: Returns all root categories'), and provides an example. This goes beyond the schema's field descriptions, enhancing the agent's understanding of parameter combinations and intended usage.

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 queries the Amazon category hierarchy by ID, path, parent, or keyword, with a specific verb and resource. It lists distinct query modes and gives an example, and it explicitly distinguishes itself from sibling tools by mentioning related endpoints like /products/search and /markets/search, making the 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?

The description provides explicit usage guidance: 'Use this to discover category structure for filtering in other endpoints' and then describes how this tool relates to /products/search and /markets/search, including the exact parameters those endpoints accept. It also details mutually exclusive query modes and gives a concrete example with categoryKeyword and parentCategoryPath, leaving no ambiguity about when to use it versus alternatives.

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. It discloses that data is based on the latest daily snapshot and that results are paginated (max 100 per page). It also implies a read-only operation via the response schema. These are useful behavioral details, though it doesn't cover authentication, rate limits, or specific side effects (likely none for a search). It adds value 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 core prose is concise and front-loaded with purpose and example. However, the overall description block includes large embedded response schemas (200 and 422) that are redundant given the separate output schema fields. This bloats the definition and reduces conciseness, though the key information is upfront.

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 complex tool with 22 parameters, the description covers the main use case, pagination, and snapshot behavior. It includes an example that clarifies usage. While it doesn't explain every filter in prose, the schema provides those details. The description is sufficient for an agent to select and invoke the tool correctly, though it could mention return value structure more explicitly.

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 already provides descriptions for all 22 parameters (100% coverage). The description only adds an example use of the 'asin' parameter, which is more about usage than parameter semantics. Since the schema fully documents each parameter, the description adds minimal extra meaning, meeting the baseline of 3.

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 function: 'Search competitor products by keyword, brand, ASIN, or category with filters.' It gives a concrete example with an ASIN and differentiates from a sibling tool by noting 'Related: /products/search for broader keyword discovery.' This is specific and distinguishes it from other search 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 explains when to use it: 'Use this to identify competing products around a specific listing or brand.' It also mentions an alternative for broader searches, implying when not to use it. However, it doesn't explicitly state conditions like 'use this instead of products_search when you need competitor context,' so it's clear but not 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 are provided, so the description must carry the transparency burden. It discloses the scoring mechanism, the underlying model, and credit costs, but it also contains a misleading phrase: 'shared list of product documents' while the input schema requires a list of document lists per query. This inconsistency undermines the agent's understanding of actual 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 main human-readable description is concise and front-loaded with a clear one-liner followed by essential details and credit information. However, the inclusion of a large, redundant response schema block (which does not even detail the 'data' payload) makes the overall description longer than necessary without adding much actionable value.

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 is moderately complex with multiple queries and document lists, and no annotations are present. While the input schema is thorough and the response schema is included, the description fails to clarify the exact structure of the 'data' field (the actual reranked results), and the 'shared list' misstatement leaves the usage ambiguous. More examples or a clearer description of the output would be needed for full 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?

Input schema coverage is 100%, so the baseline is 3. The description adds some context (documents can be titles, descriptions, or attributes) and explains credit costs, but it doesn't compensate for the schema's clarity because it introduces the contradictory 'shared list' notion. The schema's own descriptions are more precise.

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+resource ('Rerank documents for ecommerce search queries') and clearly states its purpose: to improve product search result ordering. It distinguishes itself from sibling search tools by focusing on reranking an existing list of product documents, not searching from scratch.

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 says 'Use this to improve product search result ordering,' providing clear context for when to invoke this tool. It also explains how to use it (pass queries and documents), but it does not mention alternative tools or when not to use it, stopping short of a full usage guideline.

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. It discloses the model (fine-tuned SigLIP2), output dimensionality (768), default L2 normalization (and that it can be disabled), accepted input formats (HTTPS/base64/WebP/JPEG/PNG), and credit usage (1 per request). It also includes a detailed response schema with meta and credit fields. It omits rate limits and error handling beyond 422, but for a read-only embedding generator this is substantial transparency.

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 opening description is concise and front-loaded with the essential info. However, the Responses section includes a full JSON schema with internal ADR-0003 discussions, deprecation TODOs, and repeated example/output schema, adding irrelevant bloat that an agent does not need for tool selection or invocation.

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 functionally complete for an agent: it covers what the tool does, how to call it (input constraints, normalization default), what it returns (detailed embedded output schema), and costs (1 credit). The embedded output schema compensates for the missing structured output schema. The internal TODOs degrade readability slightly, preventing a 5.

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

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

Schema description coverage is 100% (both imageUrls and normalizeVectors are fully described). The description restates the input formats and default normalization but adds little beyond the schema. It mentions the vectors align with text embedding space, which is output-oriented, not param-specific. The baseline of 3 applies because the schema already carries the parameter meaning.

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 with specific verbs: 'Generate fashion image embeddings (768-dim vectors for similarity search)' and 'Encode product images into 768-dim vectors aligned with the text embedding space.' It identifies the resource (fashion product images) and output (768-dim vectors), and distinguishes from siblings like openapi_v2_fashion_image_search and openapi_v2_fashion_text_embedding by emphasizing fashion-specific image embeddings aligned with text space.

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 use cases ('visual similarity search, image-to-text matching, duplicate detection, catalog indexing') and clarifies input constraints (HTTPS URLs or base64, max 8 per request, supported formats). It also notes the credit cost. However, it does not explicitly compare with sibling tools or state when not to use this tool, which would make it a 5.

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

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

With no annotations, the description carries the full burden. It includes response schemas for success and validation errors, plus metadata like pagination and credit fields, which offers some insight into behavior. However, it does not disclose explicit side effects, permissions, or rate limits, so transparency is partial.

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 core description is concise, but it starts with two nearly identical sentences ('Search fashion products by image similarity' and 'Search fashion products by visual similarity to a query image'). The lengthy output schema includes internal TODOs and ADR references ('TODO(2026-11, ADR-0003 §8 +6mo)') that are irrelevant for tool selection and add noise.

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 covers the main usage, optional parameters, and error handling, but does not explain the contents of the 'data' payload beyond the schema's generic 'Response data payload.' It also leaves prerequisites like HTTPS requirement to the schema text. Overall, it is adequate but with clear gaps.

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

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

Schema coverage is 100%, so the baseline is 3. The description's mention of 'bounding box to focus' and 'text description for better matching' paraphrases the schema field descriptions without adding new meaning beyond what is already in the input 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 states 'Search fashion products by image similarity' and 'Search fashion products by visual similarity to a query image,' clearly specifying the verb (search), resource (fashion products), and method (image similarity). However, it does not explicitly differentiate this from sibling tools like openapi_v2_fashion_similarity or openapi_v2_fashion_product_search.

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

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

The description provides clear context: 'Upload an image URL to find visually similar fashion products across the catalog. Optionally specify a bounding box... and add a text description for better matching.' This implies when to use the tool, but does not mention alternatives or say when not to use it, so it falls short of a 5.

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

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

With no annotations, the description carries the burden. It discloses that the search covers 200M+ fashion products and that results include title, brand, price, image, and retailer link. It does not mention rate limits, auth requirements, pagination behavior, or a read-only guarantee, but the nature of a search tool implies read-only. This is moderate transparency, not comprehensive.

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 first two sentences are concise and front-loaded with the essential purpose. However, the description is flooded with a large 'Responses' section containing example JSON and an output schema, including verbose metadata about credit fields, ADR-0003, and TODOs unrelated to the search functionality. This boilerplate adds significant noise and does not earn its place for an agent selecting the tool.

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 covers the core aspects: what the tool does, scale, filters, and result fields. It omits details like result ordering, no-result behavior, and page-size semantics, though the topK parameter is defined in the schema. The huge response schema provides generic metadata but not a complete data structure for search results, so the description is moderately complete for a search tool with well-documented 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?

The schema descriptions cover 100% of parameters (query, brand, priceMin/Max, sites/excludeSites, topK). The description adds a high-level summary of filtering capabilities ('brand filtering, price range, and retailer domain allowlists/denylists') that maps to the parameters but does not introduce any new meaning beyond the existing schema examples. 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 opens with 'Search fashion products by text query' and elaborates as 'natural-language text query' and 'Searches across 200M+ fashion products from major retailers.' This clearly specifies the verb (search), resource (fashion products), and scope (text-based, 200M+ products). It distinguishes from sibling image/similarity search tools by emphasizing the text-query nature and fashion focus.

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 context: it supports brand filtering, price range, and retailer domain allowlists/denylists, and returns product title, brand, price, image, and retailer link. However, it does not explicitly state when to prefer this tool over alternatives like openapi_v2_products_search or openapi_v2_fashion_image_search, so no exclusion or alternative guidance is given.

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, but the description fully discloses behavior: 768-dim encoding, the output score matrix semantics, higher-is-better interpretation, and per-request credit consumption. It also includes the full response schema and error examples, far exceeding bare functionality statements.

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 core explanation is concise and front-loaded, but the description is then padded with extensive response documentation, including ADR-0003 policy details and TODO comments that are irrelevant for tool selection and invocation. This extra verbosity reduces the overall conciseness.

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 stateless compute tool with two inputs, the description provides complete context: the formula, input constraints via the schema, output format with an example, error responses, and cost. Even though no formal output schema is attached, the description includes the output schema in text, making the context fully self-sufficient.

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?

Both parameters are already well-documented in the input schema with 100% coverage, so the baseline is 3. The description reinforces the text-to-image pairing via the similarityScores[i][j] formula but does not add meaningful new parameter-level details beyond what the schema already states.

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 'Compute text-image similarity scores for fashion products', a specific verb+resource statement. It then details the cosine similarity computation and the score matrix semantics (similarityScores[i][j]), making it clearly distinct from sibling embedding and search 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 states 'Equivalent to text-embedding + image-embedding + dot product in one call', which implicitly tells an agent when to use this combined tool rather than composing separate embedding calls. It also notes the 1-credit cost, but does not explicitly name alternatives or state exclusions, preventing a full 5.

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

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

With no annotations provided, the description carries the behavioral burden. It discloses key traits: output dimensionality (768-dim), default L2 normalization (dot product = cosine similarity), alignment with image embeddings, and a fixed credit cost of 1 per request. It does not describe response data fields in detail, but the core compute behavior is well disclosed.

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 opening prose is concise and front-loaded, but the description becomes bloated by embedding a large OpenAPI response block with generic metadata, credit-field deprecation TODOs, and ADR references that are irrelevant to selecting or invoking this tool. Much of this content does not earn its place and obscures the actual result payload.

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 covers the tool's purpose, parameters, normalization behavior, and credit cost, and the schema covers parameter constraints. However, there is no actual output schema and the response section only shows a generic wrapper with 'data' as an undefined payload, leaving the embedding result structure undocumented. This is a clear gap for an embedding API.

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?

Input schema coverage is 100% with detailed descriptions for both parameters. The description adds extra meaning by explaining that vectors are 768-dim and aligned with the image embedding space, which clarifies why queries are text strings and reinforces the normalizeVectors default. This goes slightly beyond the schema baseline.

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

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

The description opens with a specific verb and resource: 'Generate fashion text embeddings' and 'Encode fashion text into 768-dim vectors', clearly distinguishing it from sibling image-embedding tools (e.g., openapi_v2_fashion_image_embedding). It also names concrete use cases (text-to-image search, semantic product matching, catalog indexing), making the 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?

The description provides clear use cases and context: it is for fashion-specific text aligned with the image embedding space, and mentions 768-dim vectors for similarity search. It does not explicitly name alternative tools or state when not to use it, but the positioning against image embeddings and sibling names is sufficient for most selection decisions.

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 does disclose the credit cost ('Credits: 1 credit per request') and the return structure (bounding boxes, categories, confidence), but it does not mention potential side effects, data retention, or authorization requirements. The embedded output schema adds some transparency but is mostly auto-generated boilerplate.

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 core description is only a few sentences, but it is followed by an extensive inline output schema and response examples that are better placed in a dedicated output schema. This makes the description overly long and violates conciseness. The essential information is front-loaded, but the bulk 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?

Despite the verbosity, the description covers the key aspects: what the tool returns, the input parameter types (via schema), and the response structure including error cases. It even includes credit-related fields. The lack of annotations is partially compensated by the detailed response schema, though alternative tool selection guidance is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description only reiterates the classes parameter ('Use the classes parameter to filter for specific fashion categories') which is already fully explained in the schema. No additional semantic value is added 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 clearly states the tool detects fashion items and returns bounding boxes, category classification, and confidence scores. This specific verb+resource+output distinguishes it from sibling tools like openapi_v2_fashion_image_search or openapi_v2_image_embedding.

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

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

Usage is implied through 'Detect fashion items in an image and return their bounding boxes' and the note to use the classes parameter for filtering. However, there is no explicit comparison or guidance on when to choose this tool over similar fashion-related siblings, nor any 'when not to use' 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?

No annotations are provided, so the description must carry the burden. It discloses that the tool automatically detects fashion items (not requiring pre-defined bounding boxes), mentions credit cost (1 credit per request), and notes optional parameters affecting response content. However, it does not disclose any rate limits, authentication requirements, or what happens when no items are detected. The response schema is provided separately but the description does not summarize return structure beyond the example.

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 moderately sized but front-loaded with a clear purpose sentence. It includes useful information about credits and optional features Human. However, a significant portion is dedicated to a response example and a verbose description of the meta.credits fields (ADR-0003, TODO items) that is unrelated to the tool's core functionality and should be simplified or moved. The structure would benefit from trimming irrelevant 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?

Given the complexity (7 parameters, many optional), the description covers the core functionality but misses some practical details: no mention of image size limits, supported formats, or behavior when no fashion items are detected. With no annotations and no output schema in the structured input (though included in description), the description should more explicitly state common pitfalls (e.g., image URL accessibility) and error scenarios. The credit cost is mentioned but not the exact behavior of partial 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?

Schema description coverage is 100%, so the schema already documents all 7 parameters clearly (text, topK, image, timeout, withTag, boundingBoxes, withEmbedding). The description adds context about the purpose of embeddings and credits, but does not add additional meaning beyond the schema's descriptions. Since the schema is comprehensive, a 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 tool's purpose: generating feature embeddings for fashion items detected in an image. It lists example item types (bags, shoes, clothing, watches) and mentions optional tags and text-image relevance scores. This distinguishes it from siblings like openapi_v2_fashion_image_search (which likely focuses on search) and openapi_v2_image_detection (which likely focuses on detection only).

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 context for computer-vision-based embedding generation and mentions optional parameters (withTag, text for relevance scoring). It does not explicitly state when to prefer this tool over alternatives like openapi_v2_fashion_text_embedding or openapi_v2_image_detection. No exclusion criteria or explicit alternatives are named.

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

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

No annotations are supplied, so the description carries the burden, and it does disclose real behavior: the date is a lookup that resolves to the latest snapshot on or before it, the actual date surfaces as resolvedDate, and single and batch calls both return data.context + data.items[]. It does not mention auth requirements, credit consumption, or failure modes, which keeps it short of a 5.

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

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

The prose is front-loaded and organized into Function and Use cases sections, with no wasted narrative sentences. It loses a point for the clunky numbered headers and for the large embedded response-schema block, which carries ADR/TODO noise that is not agent-relevant.

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 5-parameter read tool with full schema coverage and no annotations, the description covers purpose, response shape, date resolution, and sibling routing well enough to call correctly. It stops short of disclosing cost/credit implications or error behavior, minor gaps given the embedded response schemas.

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 date resolution, keyword/keywords mutual exclusivity and normalization, and the week/US constraints. The prose restates the date and keyword semantics ('one or more keywords', 'latest available week on or before date') without adding syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

The Function section names a specific verb and resource and pins down the payload precisely: a single-week raw snapshot with search demand, competition and advertising metrics, plus the date-resolution semantics (resolvedDate, dataWindow). It explicitly contrasts itself with siblings by stating 'This is snapshot data, not a scored market assessment,' which separates it from market-profile and trend without schema inspection.

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 Use cases section gives an explicit when-to-use ('compare current raw metrics when screening candidate keywords') and names two alternatives with their selecting conditions: market-profile for 'business evidence, levels and interpretations' and trend for 'raw weekly history.' That is a complete routing rule set.

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 disclosure. It states the operation returns data (implies read-only) and includes the full response schema with pagination and credit fields. It does not explicitly mention side effects, auth requirements, or limitations (e.g., only US marketplace, week granularity – though those appear in the input schema). The response schema provides useful transparency, but the description omits deeper behavior like sorting defaults or rate limits. Adequate but not exhaustive.

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 core description is concise and structured with '1. Function' and '2. Use cases', front-loading the purpose. However, the description string includes very long response schemas (200 and 422) that, while informative, bloat the overall description. The prose is efficient, but the inclusion of detailed schemas makes the whole description lengthy. A more balanced approach would move schemas to a separate output schema field, but given the current format, it is acceptable.

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 covers purpose, use cases, and directs to subsequent tools. The input schema documents all parameters and constraints (e.g., only week granularity, US marketplace). The response schema explains the return format, including pagination and credit metadata. It lacks explicit alternatives comparison (e.g., vs. keyword_search_results) but the workflow guidance is clear. For a keyword expansion tool, this is nearly 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?

All 8 parameters have descriptions in the input schema, so the baseline is 3. The description adds no new parameter-level semantics; it mentions 'search volume, rank, and relevance metrics' which map to sortBy enum values, and 'phrase/fuzzy' which is already in queryType. No additional context beyond the schema, so a 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 starts with 'Get keyword expansions' and immediately clarifies the resource: 'Return expanded keywords related to the seed keyword with search volume, rank, and relevance metrics.' It distinguishes from siblings by naming the expansion modes ('phrase' and 'fuzzy') and the use case (building candidate keyword lists), which separates it from detail, trend, and search 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?

Provides an explicit use case: 'Build candidate keyword lists for further research, listing content or advertising evaluation.' It also directs to alternative tools for the next step: 'Use detail or market-profile to assess the returned candidates.' It does not explicitly say when not to use this tool, but the workflow guidance is clear and sufficient.

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 and does well: it discloses per-item credit cost (one credit per marketProfile, zero for identity-only), balance prechecking, meta.creditsConsumedExact, context.resolvedDate semantics, and that zero is a measured value. It omits auth/permission requirements and failure behavior, but the billing and data-semantics disclosure is far beyond a bare description.

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

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

Front-loaded correctly with the action, and the numbered sections aid scanning, but the text is long and repeats itself: keyword-order/identity preservation is stated in both section 1 and section 3, and seasonality is explained twice. This verbosity costs it against a tighter definition.

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 complex keyword-analytics tool with no annotations, the description covers the returned dimensions, identity-only items, peakPeriods edge cases, resolvedDate and billing adequately, even though the output schema's data payload is untyped. Auth and error handling remain unaddressed, keeping it short of a 5.

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

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

Schema coverage is 100%, so the baseline is 3. The description reinforces date semantics ('latest available snapshot on or before date') and keyword-order preservation for data.items[], but these are largely duplicative of what the schema already states; it adds no syntax or format detail the schema lacks.

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

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

The description names a specific verb+resource ('Get keyword market profile') and immediately specifies the returned artifact: six graded market dimensions with raw evidence, ad coverage and annual seasonality at a named path. It also explicitly separates itself from sibling tools (trend-profile, detail, trend), so an agent can distinguish it without opening any 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?

Section 2 lists concrete comparison use cases (demand, concentration, organic entry, supply, brands, product benchmarks) and gives explicit routing rules: use trend-profile with windowPeriods for window-specific volatility, detail for additional snapshot metrics, trend for raw weekly history. It also warns that directions are numeric, not a recommendation to enter or avoid a market.

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 itself carries the behavioral disclosure burden. It says the tool returns factual product data and positions rather than market metrics, that the period is weekly, and that results can be placement-filtered. It also documents success, validation-error, and metadata behavior. Auth or rate-limit details are not covered, but the practical behavior for an agent is adequately 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 well structured and front-loaded with 'Function' and 'Use cases,' which is helpful. However, it is padded with large response schemas, ADR credit-migration notes, and TODO details that an agent needs less for tool selection and invocation. It is readable, but not every sentence earns its place.

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

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

For a 9-parameter read-style query tool, this is largely complete: the description explains what type of data is returned, what is excluded, when to use it versus market-profile, and the response/error envelope. Item-level response fields are not fully expanded, but the sortBy enum implies the product fields, so an agent can safely invoke the tool.

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

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

The input schema already documents all params with 100% description coverage, including formats, defaults, enum meanings, and constraints. The description contributes only high-level context like 'weekly period' and 'optional placement filtering.' Since the schema does the heavy lifting, a 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 opens with a specific verb and resource: 'Return factual product listings and absolute ranking positions for a keyword in the weekly period,' and adds the optional placement-filtering behavior. It also distinguishes itself from sibling endpoints by stating that SERP aggregates and keyword market metrics are intentionally excluded and provided by dedicated metric endpoints.

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 'Use cases' section clearly tells an agent when to use this tool: to inspect which products, brands, and placements appear for a keyword and compare ranking positions. It also points to 'market-profile' for market-level assessments, giving an explicit alternative. It does not enumerate every sibling exclusion, so it stops short of a 5.

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

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

With no annotations provided, the description must carry the burden of behavior disclosure. It does mention the data return format (data.context + data.items[].series[]), the 93-day range limit, and that batch and single requests return the same structure. However, it does not explicitly state whether the operation is read-only (destructive hint absent), authentication requirements, or any rate limits. Given the tool is likely a read operation, some behavioral context is missing but the description is not misleading.

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 with numbered sections ('1. Function', '2. Use cases') that front-load the core purpose and key constraint. It is concise, with no redundant filler, and the sibling comparison is included in the use cases. The inclusion of full response schemas in the description is necessary for completeness but is external to the description text itself. Minor redundancy exists with the schema (e.g., 93-day limit repeated), but overall it is 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 input schema is detailed and complete (100% coverage, clear constraints), and the output schema is provided in the description, the description covers what the tool does, when to use it, the data shape, and the key limitation (93-day range). It lacks explicit mention of pagination (though output schema includes page/pageSize), but this is covered by the output schema. The description is complete enough for an agent to call the tool correctly without additional 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 100%, so the schema thoroughly documents each parameter: dateFrom/dateTo formats and constraints, keyword vs keywords mutual exclusivity, max items, case sensitivity, and granularity/marketplace consts. The description adds minimal value beyond mentioning the 93-day limit (already in schema) and the data return shape. Baseline 3 is appropriate because the schema is doing 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 description clearly states the tool returns raw weekly time-series data for keywords over a date range, with 'not precomputed trend conclusions' explicitly distinguishing it from trend-profile. It explicitly names the sibling tool trend-profile for precomputed conclusions, making it easy for an agent to choose the correct tool.

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

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

The description explains when to use this tool (plotting weekly search demand/ranking history, inspecting changes) and when to use trend-profile instead (precomputed direction/volatility over fixed windows). It does not explicitly mention exclusions for other siblings like keyword_detail or keyword_search_results, but the use-case guidance is clear and actionable for the most relevant alternatives.

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 and delivers substantial behavioral disclosure: the data is precomputed (not live), output preserves keyword/window order, billing occurs once per keyword with at least one window profile, and results are observed conclusions, not forecasts or causal explanations. These traits go well beyond anything the schema states.

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 prose is tight and front-loaded: Function, then Use cases, with the loaded facts (precomputed, window sizes, order preservation, billing, non-forecast) in the first short paragraph. Minor redundancy — the heading repeats the phrase 'Get keyword trend profile' — but no filler or irrelevant 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?

The tool is moderately complex (6 params, a oneOf keyword/keywords gate, no output schema, no annotations), and the description compensates well by teaching how to read the response ('Read trend for search-demand and ABA-rank direction, and trendEvidence for supporting metrics'). It could have given a data-shape example, but the field-level guidance covers the essential interpretation need.

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

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

Schema coverage is 100%, so the baseline is 3, and the schema documents each parameter thoroughly (date lookback, mutual exclusivity, LOWER(TRIM(value)) constraints, window enums). The description adds meaning beyond the schema: ordering of results preserves keyword/requested-window order, and the billing-per-keyword semantic tying windows to a single charge, which are not visible in the input 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?

States a specific verb and resource: 'Return precomputed trend profiles for one or more keywords over fixed 4, 8, 12, or 26-period windows.' The 'precomputed profile' framing differentiates it from the raw sibling openapi_v2_keyword_trend, and the 'observed conclusions, not forecasts' clause scopes its semantics. An agent can tell this from sibling trend tools without opening either schema.

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

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

Gives explicit use-case context: 'Summarize observed search-demand and ABA-rank direction over a supported window.' It names the alternative directly — 'Use trend to inspect the weekly data behind a conclusion' — routing the agent to the sibling raw-trend tool when detail is needed. This is explicit when-to-use and when-to-prefer-alternative 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?

With no annotations, the description carries the full burden and does well: it discloses billing (balance must cover distinct requested markets, check does not deduct credits, empty data costs zero), null-denominator rules for price/rating means, and snapshot/date resolution behavior. It does not cover auth or rate limits, leaving a small gap.

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 long but front-loaded with a labeled Function / Use cases / Example / Data range structure, so the agent can skip sections. Some content (date snapshot rules, null metric handling) duplicates the schema descriptions, which is mild waste.

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 complex aggregation tool it covers sample definition, US-only scope, category independence, null handling, and billing. An output schema exists so return values needn't be spelled out, yet the description restates them at length. Nothing critical an agent needs is missing.

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

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

Schema description coverage is 100%, so the schema already documents date, sampleType, categoryIds, marketplace and includeDescendantCategoryProducts. The description reinforces the sample-selection metric and the example request but adds no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

The description gives a precise verb and resource: it selects up to 100 listings by unit sales or revenue, aggregates and ranks by brand, and returns top-N brand concentration shares. An agent can tell this is a brand-level concentration tool. It never explicitly names the sibling alternatives (seller_concentrations, top_product_concentrations), 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 'Use cases' section states clear conditions: assess brand dominance, compare Top 3/5/10/20 concentration and new-product composition, study brand competition via listing counts and example products. It gives no when-not to use or named alternative, so it is clear context without 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?

With no annotations, the description carries the full burden and discharges it well: it discloses the up-to-100 sampled nature, that missing metrics stay null, that an unpublished explicit date returns no data, the resolvedDate reuse rule, a pre-query balance requirement, and that billing counts distinct returned markets while empty data is free. It also explains that means exclude null-metric listings and may have different denominators. Only the return shape and pagination semantics are left unaddressed, which the output schema covers.

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?

Numbered sections (Function, Use cases, Example, Data range) front-load the core behavior, and the example concretizes invocation. Section 4 is dense, packing sample, date, billing and null-handling details into one block, but each sentence carries operational value for this complex tool.

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

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

An output schema exists, so return values need no explanation, and the description covers the non-obvious traits an agent needs: sampling, null policy, date/resolvedDate behavior, and billing. The main gap is that it never routes the agent among the many sibling markets_*_distributions tools, which matters given how similar their names are.

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 each parameter thoroughly, setting the baseline at 3. The description adds marginal value: the example shows categoryIds/sampleType pairing, and 'Data range' clarifies the US-only marketplace and descendant inclusion. Nothing about parameter syntax or formats is added 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 'Function' section states a specific verb and resource: select up to 100 Listings by monthly unit sales or revenue, then group by A+/video configuration and return an A+ aggregate. This distinguishes it from sibling distribution tools (price, rating, seller, listing-age) by its content-configuration focus. The output composition (counts, shares, per-listing means) is named explicitly.

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

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

A dedicated 'Use cases' section says to use it to assess A+ and video adoption and compare sales/revenue across content groups for PDP planning. That gives clear context for selection but does not name alternatives (e.g., the other markets_*_distributions tools) or state when-not to use it, so it stops short of a full routing rule.

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 and does so thoroughly: US-only scope, sample-of-100 methodology, null handling for missing metrics and means, distinct-denominator caveats, snapshot/date resolution rules, and a billing model (balance check does not deduct credits, empty data costs zero, billing per distinct returned market).

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 numbered sections (Function, Use cases, Example, Data range) front-load the purpose and the example JSON is immediately usable. The 'Data range' paragraph is a dense run-on mixing scope, nulls, billing and denominators, which slightly hurts scanability.

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

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

An output schema exists, so return values need not be described, and the description still covers the remaining agent-facing gaps: scope, sample construction, date/snapshot behavior, and credit/billing implications. Nothing material 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 description coverage is 100%, so all five parameters are already documented in the schema, including date, sampleType, categoryIds and includeDescendantCategoryProducts semantics. The description largely restates these (date omission, sampleType ranking) rather than adding syntax the schema lacks, 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 'Function' section states a precise verb and resource: select up to 100 Amazon Listings by monthly unit sales or revenue and group them by fulfillment type, then list the exact output metrics. This distinguishes it clearly from the many sibling distribution tools (price, rating, content, listing-age) which group by a different dimension.

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 'Use cases' section gives clear context: profile supply by fulfillment type and compare counts, sales, revenue, prices and ratings to inform fulfillment choices. However, it never states when NOT to use this tool nor names an alternative among the numerous sibling *_distributions tools, so the agent must infer the routing itself.

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 load and does so richly: balance must cover distinct requested market count before querying (a non-deducting check), billing counts distinct returned markets, empty data costs zero, missing metrics return null, missing dates are not filled, results are chronological, US-only, and the leading sample is reselected each month-end so membership changes are not a fixed cohort. It even warns that means use different denominators and that zero values participate.

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?

Content is front-loaded with Function and Use cases, then example and constraints, which is good structure and nearly every sentence adds operational value. The long 'Migration from the previous history response' table, however, is mostly reader-migration guidance that is tangential to selecting and calling the tool in a fresh session, adding bulk that a new agent does not need.

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 multi-param, billed, time-series analytics tool, the description covers the key behaviors an agent needs: marketplace scope, date semantics, sample selection logic, null handling, empty-response shape (data=[]), billing precheck, and return ordering. Because an output schema exists, it does not need to restate return values, and the extra response-shape notes are bonus rather than gaps.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a runnable example and, importantly, documents legacy argument names (categoryId/startDate/endDate/byRevenue100) that are normalized to the canonical categoryIds/dateFrom/dateTo/revenueTop100. It also clarifies 'each category is analyzed independently; product coverage can include or exclude descendants,' reinforcing the includeDescendantCategoryProducts semantics 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 Function section states a specific verb and resource: 'Return monthly historical profiles of category markets' and enumerates the metrics (Listing counts, sales totals, sample means for price, rating, ratings count, unit sales, revenue). This clearly distinguishes it from snapshot siblings like openapi_v2_markets_profile and from openapi_v2_products_history, which operates on products not categories.

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 Use cases section gives concrete contexts (tracking counts/sales/revenue across snapshots, comparing market size across months for seasonality/trend research) and the Data range section excludes new-product and distribution history. It stops short of explicitly naming an alternative sibling (e.g., 'use markets_profile for the current snapshot') or stating hard when-not-to-use conditions beyond those 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?

With no annotations, the description carries the full burden and does so well: US-only scope, sample basis of up to 100 listings, null handling for missing metrics, snapshot/date behavior including resolvedDate, and billing semantics (prepaid balance check, per distinct market billing, zero cost for empty data). Mean denominator rules for null metrics are also disclosed.

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?

Numbered sections (Function, Use cases, Example, Data range) front-load the purpose and keep the long content navigable. Some date/snapshot guidance is repeated between section 4 and the schema, and the billing paragraph is dense, but length is largely justified for a multi-metric analytical endpoint.

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 5-parameter analytical tool with an output schema and no annotations, the description covers everything an agent needs: what the sample is, marketplace restriction, category independence and descendant behavior, date/snapshot rules, and cost implications. Return-value details are correctly left to the output schema.

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

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

Schema coverage is 100%, so a baseline of 3 applies; the description adds value with a worked example payload, the snapshot/date semantics ('omit date for latest', explicit date requires a published snapshot), and the null-denominator behavior of the returned means. It doesn't add much on sampleType beyond the enum's own description.

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

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

States a precise verb and resource: select up to 100 Amazon Listings by monthly unit sales or revenue, then group by listing-age range, returning count/share/sales/revenue and per-Listing means. The 'listing-age range' grouping dimension distinguishes it from the many sibling distribution tools (price, rating, content, fulfillment) without needing to name them.

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

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

The 'Use cases' section gives a concrete scenario: profile the mix of newer vs established Listings and assess dependence on established products. That tells the agent when this tool is appropriate, but it names no alternatives or exclusions (e.g. vs listing_launch_trend or other markets_* distributions).

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 and delivers: US-only, capped sample of up to 100 listings, latest snapshot only, missing metrics null and missing periods unfilled, and explicit billing/precondition rules ('balance must cover the distinct requested market count... this check does not deduct credits; empty data costs zero'). This is rich 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?

Front-loaded and sectioned (Function/Use cases/Example/Data range), which aids scanning, but it is long and repeats itself verbatim — 'Profile the launch-date composition of the current leading sample by first-launch month or year' appears in both section 1 and section 2, with other redundant phrasing throughout.

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 an output schema exists, return format need not be described, and the definition still covers sample selection, date-range semantics, null/period-filling behavior, marketplace restriction, and credit/billing preconditions across all 7 parameters. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents every parameter including dateFrom/dateTo semantics, sampleType, and granularity. The description's example and data-range prose reinforce concepts but add little parameter meaning beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource: 'Show the distribution of current leading Listings by first-launch month or year.' It also clarifies the scope ('describe the sample' rather than all listings launched), which implicitly separates it from siblings like listing_age_distributions, but no sibling is named explicitly.

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

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

The 'Use cases' section gives clear context: profile launch-date composition and compare cohorts to understand newer vs established product mix. However, it never states when NOT to use it nor points to any alternative tool (e.g. listing_age_distributions vs this launch-date view).

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 and does so extensively: US-only scope, independent category analysis, descendant inclusion behavior, null handling, snapshot/date semantics, billing unit price and empty-data cost, and denominator caveats for means. This is rich operational 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 long but organized into numbered sections with the core function front-loaded. Most sentences carry useful operational detail, though the length is on the higher side for a single tool.

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 complex tool with five parameters, no annotations, and an output schema, the description is complete enough. It covers sample definition, date behavior, marketplace restriction, descendant handling, billing, and missing-data semantics without needing to explain return values.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces sample selection and date behavior, but most parameter-level meaning is already supplied by the schema, so it does not substantially exceed the structured 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 states a specific verb and resource: select up to 100 Amazon Listings by monthly unit sales or revenue and group them into price bands. It clearly distinguishes this tool from sibling distribution tools by focusing on price bands and the returned price/rating/sales metrics.

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 a use case: profiling the market by price band for pricing and price-band positioning. It does not explicitly name alternative sibling tools or state when not to use this tool, but the context is clear enough for an agent to know when it 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?

With no annotations, the description carries the full burden and largely delivers: US-only scope, null semantics for missing metrics, full-market vs up-to-100-Listing leading sample, the explicit-date-must-be-published rule with a no-data failure mode, and detailed billing behavior (pre-query balance check at unit price, billing by distinct returned market, empty data costs zero). Auth requirements and any rate limits are the notable omissions.

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 numbered sections and the worked JSON example are genuinely helpful and the purpose is front-loaded. But the description is long and repeats the full-market vs leading-sample distinction in two places ('full-market Listing counts... plus leading-sample per-Listing means' and again in Data range), so several sentences do not earn their 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 values need not be explained, and the description covers the remaining operational questions an agent needs: date resolution, marketplace constraint, sample selection, null handling, and billing. For a read-only multi-parameter data query this is close to complete, with only auth/permission prerequisites and pagination unaddressed.

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

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

Schema description coverage is 100%, so the schema already documents date, sampleType, categoryIds, marketplace and includeDescendantCategoryProducts, and it even explains the concentration-ranking behavior of sampleType. The description adds only marginal framing ('each category is analyzed independently; product coverage can include or exclude descendants'), which is close to what the schema fields already state, so the 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 verb and resource — 'Get a comprehensive category market profile' — and enumerates exactly what the profile contains (market size, leading-sample means, concentration summaries). It is clearly distinguishable from a generic getter, but it never names or contrasts the many sibling endpoints (brand_concentrations, seller_concentrations, distributions, history) that return overlapping sub-metrics, so an agent must infer the boundary itself.

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 'Use cases' section gives context ('build a category market profile... compare demand scale and competitive characteristics'), and the data-range section usefully points at market search's resolvedDate for snapshot consistency. However there is no explicit when-to-use-this-vs-alternatives guidance against the distribution/concentration siblings, and no statement of when this tool is the wrong choice.

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 and does so well: it discloses the sampling basis (leading top-100 sample, results describe the sample), US-only scope, null handling for missing metrics, mean-denominator rules, and detailed billing behavior (balance must cover distinct requested market count; the check does not deduct credits; billing counts distinct returned markets; empty data costs zero). This is unusually rich disclosure beyond what any annotation would provide.

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

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

The numbered sections (Function, Use cases, Example, Data range) front-load the purpose and the example is compact and useful. It is dense and somewhat over-long, and the date/snapshot sentence duplicates the date parameter description almost verbatim, which is wasted space.

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 complex, unannotated analytics tool this covers the essentials: scope, sampling, snapshot/date semantics, null and denominator handling, and billing. An output schema exists so return fields need not be re-explained (though they are), and the only real omission is guidance on obtaining valid category IDs and how this tool relates to its many distribution siblings.

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 every parameter (date, sampleType, categoryIds, marketplace, includeDescendantCategoryProducts) is already documented in the schema. The description reinforces sample semantics and the date/snapshot rule, but adds no syntax or meaning the schema lacks, so the baseline of 3 applies.

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

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

The 'Function' section states a specific verb and resource: select up to 100 Amazon Listings by monthly unit sales or revenue, then group them by rating-count range, and it enumerates the returned measures. This is far more precise than a generic 'distributions' tool. It never names the obvious sibling openapi_v2_markets_rating_distributions (star-rating buckets) or price/listing-age distributions, so differentiation is left implicit.

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 'Use cases' section gives a clear analytical context: compare sales/revenue for Listings with few versus many ratings to assess accumulated rating volume. That is genuine usage guidance, but there are no exclusions or explicit alternatives (e.g., when to prefer rating_distributions over rating_count_distributions), so it stops short of a 5.

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

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

With no annotations, the description carries the full burden and does so thoroughly: US-only scope, per-category independence, null handling, snapshot-date rules (unpublished date returns no data), a pre-query balance check that does not deduct credits, billing by distinct returned markets with empty data costing zero, and per-mean denominator caveats. These are exactly the behavioral traits an agent could not infer otherwise.

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?

Well organized into Function / Use cases / Example / Data range with the purpose front-loaded, and the example is compact. It costs some points for repetition, notably the date/snapshot rule which duplicates the schema, and a dense billing sentence that could be tightened.

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 5-parameter, output-schema-backed analytics tool, the description covers everything an agent needs: scope, snapshot semantics, cost/billing behavior, and metric-specific caveats like excluding null-metric listings while counting zeros. An output schema exists, so the absence of return-format detail is not a gap.

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

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

Schema description coverage is 100%, so the schema already documents every parameter; baseline is 3. The description's example JSON and date guidance largely restate the schema descriptions (the date rule is repeated almost verbatim), adding little beyond what the structured fields already provide.

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 'Function' section states a specific verb and resource: select up to 100 Amazon Listings by monthly unit sales or revenue, then group by star-rating range. The grouping dimension (star rating) clearly differentiates it from the sibling openapi_v2_markets_rating_count_distributions, and it also enumerates the exact returned metrics.

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 'Use cases' section gives clear context (profiling customer-rating patterns, assessing demand distribution in the leading sample), and the data-range text routes the caller to the resolvedDate from market search. It does not, however, state when NOT to use this tool or name a sibling to use instead when the question is about rating counts rather than star-rating bands.

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 and does reasonably well: US-only scope, per-category independence, descendant inclusion behavior, nulls for missing metrics, a trailing-30-day view plus month-end snapshots beginning 2026-02, cutoff resolution semantics, and explicit "charged per call, including empty results" cost disclosure. It omits pagination limits/interaction with large result sets, but the core behavioral facts are present.

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?

Numbered sections (Function, Use cases, Example, Data range) front-load purpose before detail, and the JSON example compactly conveys the request shape. Given a 14-parameter tool, the length is proportionate with little padding.

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

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

An output schema exists, so return-value documentation is not required. The description supplies the data range, snapshot semantics, cost model, and filtering/sorting/pagination scope an agent needs to call this correctly. The only soft spot is the lack of explicit routing against near-neighbor market endpoints.

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 explains every parameter in detail (including nuanced ones like includeDescendantCategoryProducts and the date cutoff). The description adds the worked example and restates the descendant-coverage behavior, but contributes little semantic meaning beyond the structured fields. 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?

Opens with a specific verb+resource ("Find category markets") and enumerates the metric families it searches over (market size, supply, prices, sales, new-product activity, competition), plus filtering/sorting/pagination. This is clearly a bulk category-market search, distinct in kind from single-row siblings like openapi_v2_markets_profile. It never names a sibling, so an agent must infer the boundary from scope alone.

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

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

The "Use cases" section gives a real context ("Screen categories... to narrow product research and compare candidate markets"), which is more than implied usage. However, it names no alternatives and no exclusions, so it does not tell the agent when to prefer this over openapi_v2_markets_profile, openapi_v2_markets_history, or the many distribution endpoints.

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 and does so extensively: US-only coverage, sample-based results, missing metrics remaining null, date-snapshot requirements, balance checks, billing rules, and the fact that empty data costs zero. These details are important for correct invocation and cost expectations.

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 front-loaded with the function and organized into numbered sections, making it easy to scan despite its length. It is verbose for a tool definition, but most details serve the complexity of the endpoint.

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 complex market-analysis tool with five parameters and an output schema, the description covers sample construction, date behavior, billing, null handling, and scope limitations. Nothing material appears missing 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?

Schema description coverage is 100%, so the schema already documents the five parameters thoroughly. The description reinforces sample and date semantics, but adds little parameter meaning beyond what the schema provides, making 3 the appropriate baseline.

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

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

The description gives a specific verb and resource: it selects up to 100 Amazon Listings, aggregates and ranks them by seller, and reports Top 3/5/10/20 seller concentration. This clearly distinguishes the seller-concentration analysis from sibling tools such as brand and product concentration tools, even without naming them.

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

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

A dedicated 'Use cases' section states when the tool is useful: assessing seller concentration, comparing Top 3/5/10/20 seller concentration, and examining leading sellers. It does not explicitly name alternatives like brand_concentrations or top_product_concentrations, so the agent must infer the boundary from the tool names.

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 and delivers: US-only scope, the 100-Listing sampled (not population) nature of results, null handling for missing metrics and per-metric denominators, snapshot/date semantics, and explicit billing rules (distinct returned markets, empty data costs zero, balance pre-check). This is unusually rich behavioral disclosure.

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?

Numbered sections (Function, Use cases, Example, Data range) front-load the purpose effectively, and the example is compact. The 'Data range' block is dense and repeats some date rules already in the schema, slightly hurting conciseness but the depth is defensible for an annotation-free tool.

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 complex, US-only, sampled distribution tool, the description covers scope, sampling limitations, cost, and empty-result behavior, while the output schema handles return structure. An agent has everything needed to decide and invoke correctly.

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

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

Schema description coverage is 100%, so parameters are already documented, and the description's example ({categoryIds, sampleType}) adds little semantic detail beyond the schema. It reinforces date/sample meaning but does not introduce formats or constraints the schema lacks, so the baseline 3 applies.

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

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

States a precise verb and resource: select up to 100 Listings by monthly unit sales or revenue and group them by seller country, returning count/share/sales/revenue metrics. The grouping key (seller country) distinguishes it from sibling distribution tools such as price, rating, fulfillment, content, and listing-age distributions without needing to open 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 'Use cases' section gives clear context — profile supply origins by seller country and compare counts/sales/revenue for geographic competition — which tells an agent when this tool is relevant. It does not, however, name exclusions or which sibling to prefer when a different distribution dimension is wanted.

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 and does so unusually well: it discloses US-only scope, snapshot semantics (omit date = latest; explicit unpublished date returns nothing; use resolvedDate), null handling, and billing behavior (balance must cover distinct requested markets; empty data costs zero; no credits deducted by the check). It even explains denominator behavior for the means.

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?

It is long, but cleanly sectioned into Function / Use cases / Example / Data range with the core purpose front-loaded and a concrete example request included. Most sentences carry distinct information, though the return-value enumeration is partly redundant given the output schema.

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

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

Given an output schema exists, the description need not explain returns, yet it supplies scope, snapshot/date rules, billing, and null semantics — everything an agent needs to call this read-only concentration endpoint correctly. Nothing material is missing.

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

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

Schema description coverage is 100%, so the schema already documents date, sampleType, categoryIds, marketplace, and includeDescendantCategoryProducts. The description mostly restates these (snapshot date rules, ranking metric, independent markets) rather than adding syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

The 'Function' section states a concrete verb+resource+scope: select up to 100 Amazon Listings by monthly unit sales/revenue, rank them, and compute Top 3/5/10/20 product-group concentration shares. This is specific and distinguishes the 'product group' focus from the brand/seller concentration siblings, though it never names those alternatives outright.

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

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

The 'Use cases' section gives clear when-to-use context (assess concentration, compare Top-N, examine leading products for competitor research). It does not, however, state when-not to use it or explicitly route the agent to brand_concentrations/seller_concentrations, so there are no 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?

No annotations are provided, so the description carries the full burden. It discloses key behaviors: missing ASINs return status=empty rather than being dropped, ordering for parentAsin mode, snapshot selection via dateRange, resolvedDate behavior, validation failure reason codes, and billing credit rules. It doesn't detail pagination mechanics or the full Product model, but the disclosed behaviors are substantial and specific.

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 with clear sections (Function, Use cases) and front-loads the core purpose. It is dense but every sentence adds value, covering modes, edge cases, validation, billing, and alternatives. Slightly long but justified by 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?

For a read tool with no annotations and no output schema, the description covers the essential operational context: modes, limits, error behavior, billing, and snapshot selection. It doesn't describe the Product model fields, but the output schema is absent and the description names the shared model, which is acceptable for a detail-read endpoint.

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 all six parameters thoroughly. The description adds context about mutual exclusivity, request ordering, and snapshot semantics, but most parameter meaning is already in the schema. 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 opens with a specific verb and resource ('Read products by ASIN or parent') and immediately distinguishes the two mutually exclusive modes. It clearly differentiates from siblings like openapi_v2_products_search, openapi_v2_products_history, and openapi_v3_realtime_product by naming them and their 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 'Use cases' section explicitly states when to use this tool (known ASIN list, watchlist, enumerating parent variants) and when to use alternatives (/products/search for discovery, /openapi/v3/realtime/product for live data, /products/history or /products/sales-trend for changes over time). This is explicit routing guidance.

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

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

With no annotations provided, the description carries the full burden and does so impressively. It discloses per-point vs. change series semantics, non-continuous timestamps, the distinction between page-text monthlySalesFloor and catalog-snapshot values, ASIN normalization rules and the 422 error, null data when no observation exists, and credit billing. This goes far beyond a simple 'get history' statement.

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 long but deliberately structured into '1. Function' and '2. Use cases', with the core purpose front-loaded. Every sentence earns its place by clarifying behavior, constraints, or alternatives. The organization makes the length appropriate for the endpoint'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?

Despite the lack of a full output schema for the data payload, the description explains the response structure (per-point series, change series, latest, context) well enough. It covers input validation, edge cases (no observation, invalid aspects), billing, and usage context. An agent has everything needed to invoke this 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?

Although schema coverage is 100% and the baseline is 3, the description adds substantial meaning beyond the schema. It explains that aspects trims the response to the listed series, that asin must be canonical with the exact regex pattern, that the date range can be up to 730 days, and that marketplace is constrained to US. These details help the agent construct valid calls and interpret errors.

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?

Opens with a specific verb+resource: 'Get a product's day-by-day page history'. The description then precisely scopes it to one ASIN over a date range, and explicitly distinguishes it from sibling tools like /products/sales-trend and /products/detail. There is no ambiguity about what this endpoint does.

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?

Section 2 explicitly states when to use this tool ('see how a listing changed day by day') and when to use alternatives ('Use /products/sales-trend for monthly sales... Use /products/detail for current facts'). This is exactly the kind of when/when-not guidance that helps an agent choose correctly.

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 is transparent about the operation being a read-only query (no side effects mentioned). It does not hide any potential costs or limitations beyond what is inherent in the request. Since no annotations are provided, the description carries the burden, and it does not mislead.

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 well-structured: it starts with the core purpose, then details the rank types in a bullet-like style, and ends with a related tool reference. No redundant or vague phrasing.

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 covers the essential context: what the tool does, how rank types differ, and a pointer to an alternative. It does not explicitly mention pagination or the output structure, but the input schema already includes pageSize and the output schema is provided in the response section. This is sufficient for a simple read endpoint.

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?

All parameters have descriptions in the schema, and the tool description adds extra clarity, especially for the rankType parameter by explaining what each enum value means in business terms. This goes beyond the schema's basic description, providing full semantic 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 clearly states the tool's function: 'Return a product-level Top-N leaderboard for a category.' It also specifies the different rank types (sales, surging, newRelease) with their meanings, distinguishing it from other product-related tools like search.

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

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

The description provides guidance on when to use this tool versus alternatives by mentioning 'Related: /products/search for custom filters and sorting.' This implies that the leaderboard is for predefined ranking types, while search is for custom queries. However, it doesn't explicitly state conditions for choosing one over the other, so a small deduction.

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