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

Annotations already declare destructiveHint=true, but the description adds value beyond that by stating the deletion is permanent, requires confirm=true, and advises handling active offers. This is useful behavioral context, though it does not mention cascading side effects or post-deletion behavior.

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

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

The description is compact and front-loaded with the DESTRUCTIVE warning, then the action, then the confirm requirement, and finally an actionable tip. No filler or repetition of schema fields beyond what is useful.

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 two-parameter destructive tool with no output schema, the description covers the key safety concerns, the required confirmation, and the important conditional workflow around active offers. Nothing else 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 both sku and confirm are already well documented in the schema. The description restates 'Requires confirm=true,' but adds little new parameter meaning beyond what the schema already says.

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: 'permanently deletes the listing for a SKU.' This clearly distinguishes delete_listing from sibling mutation tools like upsert_listing and set_quantity, and from read-only tools like get_listing.

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

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

The description gives situational guidance: if the listing has an active offer, the agent should set quantity to 0 first and then delete. This points toward a safe sequence involving a related operation, though it does not explicitly name the sibling tool or list 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 burden of behavioral disclosure. It mentions downloading and decompressing, which implies a read-only operation, but does not discuss error handling, permissions, or side effects. It does add the detail that the result is text, which is useful, but lacks deeper behavioral context.

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

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

The description is a single sentence that front-loads the action and includes the key details (download, decompress, ID, return text). There is no filler or redundant information.

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

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

For a simple tool with one parameter and no output schema, the description covers the basic purpose and return type. However, it does not specify the format of the returned text (e.g., CSV, JSON), nor does it mention error conditions or valid ID constraints. These gaps matter for correct invocation but are minor for a straightforward read operation.

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

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

The schema has zero description coverage, so the description must clarify the parameter. It only repeats 'reportDocumentId' without adding meaning about the ID's format, origin, or constraints. This does not compensate for the missing schema documentation.

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

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

The description clearly states the action (download and decompress), the resource (report document), and the identifier (reportDocumentId), plus the return type (text). It distinguishes itself from siblings like request_report and get_report by specifying that it retrieves the actual document content.

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

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

No explicit guidance is given on when to use this tool versus siblings such as get_report or request_report. The description does not mention prerequisites, sequencing, or conditions under which this tool should be preferred, leaving the agent to infer usage from context.

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

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

With no annotations, the description carries full responsibility. It does not disclose whether the operation is read-only, has side effects, or any error/rate-limit behavior. The 'get' prefix implies non-mutating but this is not stated explicitly.

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

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

The description is extremely concise, consisting of two short sentences with no superfluous content. It gets straight to the point without wasting words.

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

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

The tool is simple but lacks essential context: it does not explain how to obtain feedId, what possible statuses exist (beyond DONE), or any error conditions. The mention of resultFeedDocumentId is helpful but incomplete without further details on the response.

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 has one parameter (feedId) with zero description coverage, and the description does not compensate. It does not explain what feedId is, where to obtain it, or its format, leaving the agent with insufficient information to correctly supply 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?

Clearly states it returns a feed's processing status, with a specific verb and resource. However, it does not explicitly differentiate from siblings like get_report, though the feed-specific wording makes the distinction 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?

Provides only a post-processing hint ('When DONE, use resultFeedDocumentId with download_report-style retrieval') but no guidance on when to use this tool versus alternatives. Does not mention conditions like having a feedId from submit_feed or that get_report is for reports, not feeds.

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 does not explicitly state that this is a read-only operation or disclose any side effects, rate limits, or error behavior. The term 'get' implies read-only, but it is not made explicit.

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 free of extraneous words. It conveys the essential purpose and included data sets in a single sentence, making it easy to scan and parse.

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 simple (two parameters, no output schema). The description provides enough context about what is returned and the default includedData value. It omits details like error responses or pagination, but these are not critical for a basic read operation with low complexity.

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% for both parameters (sku and includedData). The description does not add significant meaning beyond the schema, though it does clarify the default for includedData. Since the schema already explains each parameter, a baseline score 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 description clearly states the tool fetches full details for a single SKU, enumerating the specific data sets (summaries, attributes, offers, issues, fulfillment availability). This distinguishes it from list/list operations and provides a precise, actionable purpose.

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

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

The description implies use for a single SKU via 'one SKU' but does not explicitly contrast with siblings like list_listings or set_quantity. It lacks a clear 'when not to use' or direct alternative guidance, leaving some inference required.

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 of behavioral disclosure. It states the tool returns line items but discloses nothing about error behavior for invalid or nonexistent order IDs, whether the order must exist first, pagination of results, or what the response structure looks like. For a retrieval tool with zero annotation coverage, this is a meaningful 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 a single efficient sentence with no wasted words and the core action front-loaded. It is appropriately sized for a simple one-parameter retrieval tool, though it errs on the side of under-specification rather than richness.

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 there is no output schema, the description should explain what line items are returned, but it doesn't. It also lacks usage context and behavioral details. For a tool with one parameter and no annotations or output schema, the description is the only source of information and it provides only the bare minimum, leaving an agent guessing about return format and error conditions.

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% - the single orderId parameter is already documented as 'The Amazon order ID.' The description adds no semantic detail beyond the schema; it merely implies the order must be specific without elaborating format or provenance. At the baseline 3 for high schema coverage, the description is adequate but adds nothing extra.

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 (Returns) and resource (line items) with clear scope (for a specific order). It distinguishes itself from get_orders by indicating it operates on a single order's contents rather than listing orders. However, it doesn't explicitly name or differentiate from the sibling get_orders, leaving the agent to infer the distinction.

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

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

No guidance is provided on when to use this tool versus alternatives. It doesn't mention that a valid orderId must be obtained from get_orders first, nor does it explain when one would choose get_order_items over get_orders or the listing tools. The prerequisite relationship with get_orders is left entirely implicit.

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 itself must convey behavioral traits. 'Lists orders' implies a read-only operation, and the PII note communicates an important access-control behavior. It does not mention pagination or response shape, but those are partially covered by parameter descriptions.

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. Two sentences convey the core function, default behavior, and a critical caveat without extraneous 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 description is complete enough given the relatively simple parameter set and lack of an output schema. It covers the default behavior and an important access restriction. It does not explicitly explain the return format or how pagination works, but the nextToken parameter description partially covers that.

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 already describes most parameters, and the description adds meaningful context about the default createdAfter value and the PII note. The lastUpdatedAfter parameter is clarified as 'use instead of createdAfter' in the schema. maxResults lacks a direct description, but its type and constraints are clear from 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 lists orders, which is a specific and unambiguous action. It also provides a useful default behavior (last 30 days) and a scope note about PII-restricted data, making the purpose immediately understandable.

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

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

The description gives practical usage guidance by noting the default date range and the PII role requirement. It does not explicitly contrast this with sibling tools like get_order_items or report-based order retrieval, but the provided guidance is sufficient for most callers.

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 full responsibility for disclosing side effects, permissions, or output details. It only mentions fetching metadata and a link to a JSON schema, but does not state whether it is read-only, what happens on invalid input, or any side effects. This leaves significant ambiguity.

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

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

The description is a single, concise sentence that directly states the tool's function without superfluous words. It is well-structured and easy to parse.

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 simple with only two parameters. The description mentions that the output includes a link to the JSON schema, which gives a hint about the return payload. Without an output schema, this is adequate for the low complexity. It does not cover error cases, but that is not critical for this simple metadata fetch.

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

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

The schema provides descriptions for both parameters: locale (with default) and productType (with examples). Since schema coverage is 100%, the baseline is 3. The description adds no extra information beyond the schema, so a score 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 with the verb 'Fetches' and specifies the resource as 'product type definition metadata.' It distinguishes from sibling tools like get_listing or get_orders by focusing on schema/metadata retrieval, making its role obvious.

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

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

The description implies usage for retrieving product type schema definitions but does not explicitly mention when to use this tool over alternatives or provide exclusions. No guidance on scenarios where other tools like get_listing would be more appropriate.

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 burden of behavioral disclosure. It reveals that status can be DONE and that the response includes a reportDocumentId, but it does not enumerate other possible statuses or describe error/failure 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?

Two short sentences with no filler. The primary behavior is front-loaded and the workflow handoff is stated efficiently.

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 status-check flow and the next step, but with no output schema and no annotations it omits important context such as possible status values, whether the call is pollable, and what happens on failure. An agent could call it correctly but may not handle non-DONE outcomes well.

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

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

Schema description coverage is 0%, and the description does not explain how reportId is obtained or what format it should take. The parameter name is somewhat self-explanatory, but the description adds no semantic value beyond the schema.

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

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

The description states a specific verb and resource: 'Returns a report's processing status.' It clearly distinguishes this tool from request_report and download_report, and the DONE handoff to download_report reinforces its role.

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

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

The description gives explicit conditional guidance: when the status is DONE, use download_report with the reportDocumentId. This tells an agent when this tool is the right choice and what to do next, though it does not mention polling cadence or when not to use it.

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 word 'Returns' suggests a read-only operation and no side effects, but the description does not explicitly state that it does not modify data or mention potential errors, permissions, or data freshness. With no annotations to supplement this, transparency is only moderate.

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

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

The description is a single concise sentence that directly states the function and the returned fields. There is no unnecessary wording or redundant information.

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

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

For a no-parameter tool without an output schema, the description provides sufficient context by naming the resource ('seller's marketplace participations') and listing the included fields. It is complete enough for an agent to know what to expect.

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 no parameters, so there are no parameter details to explain. The description accurately reflects the zero-input nature and focuses on the output, avoiding any ambiguity.

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

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

The description clearly states the tool returns the seller's marketplace participations and enumerates the specific fields included. This verb-resource combination is distinct from all sibling tools, which focus on listings, orders, and reports.

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 seller profile or marketplace participation data is needed, but it does not explicitly compare with sibling tools or state when to prefer this over alternatives. No sibling tool serves the same purpose, so the lack of explicit differentiation is less critical, but guidance is still minimal.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It adds useful context by stating the list is 'real-time' and that it 'paginates through all pages', which implies it handles fetching the entire dataset. However, it does not explicitly confirm the operation is read-only (though obvious), nor does it mention any potential response size, rate limits, or whether it returns full listing objects or just SKU identifiers. The provided info is above minimal but still has gaps.

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

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

The description is a single efficient sentence plus a parenthetical, with no wasted words. The primary purpose ('list all listings') is front-loaded, and the pagination detail adds valuable information without redundancy. It is both concise and well-structured.

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

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

Given the tool has no parameters and no output schema, the description is reasonably complete. It clarifies the scope (all SKUs for the seller) and the pagination behavior, which are the key operational aspects. However, it leaves ambiguous whether the returned data is just SKU identifiers or full listing details, and it does not mention any filtering or sorting options (though none are implied). For a simple list-all tool, this is adequate but not exhaustive.

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

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

There are zero parameters, so the schema coverage is trivially 100%. The baseline for a 0-parameter tool is 4, and the description does not need to add parameter-specific meaning. It correctly omits any parameter details since none exist.

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

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

The description clearly states the tool lists all catalogued SKUs for the seller, naming the underlying method (searchListingsItems) and explicitly mentioning pagination through all pages. It distinguishes itself from sibling tools like get_listing (single item) and upsert_listing (create/update) by focusing on the bulk listing action.

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 context is clear: this tool is for retrieving all listings, as opposed to get_listing for a single listing. While it doesn't explicitly state 'use this when you need all listings' or exclude alternatives, the purpose is so direct that an agent would infer the appropriate usage. No exclusions are mentioned, but the listing nature is unambiguous.

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

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

No annotations are provided, so the description carries the full burden. It transparently states that the operation creates a request and returns a reportId, implying a write operation. However, it does not disclose that report generation is asynchronous or that the report will not be immediately available, which is a behavioral detail an agent might need to know.

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 states the action, the return value, and provides useful examples in just two sentences. No unnecessary words or redundancy.

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

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

For a simple creation tool with one parameter, the description provides enough context to understand its role in the overall report workflow (create, then get, then download). The sibling tool names reinforce this. It lacks an explicit mention of the report lifecycle, but that is not essential for calling 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?

The schema description for reportType is minimal: 'SP-API report type.' The tool description provides example values, which helps, but the schema itself lacks detail about the expected format or available valid values. The description does not fully clarify what constitutes a valid reportType beyond the examples given.

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: 'Creates a report request and returns a reportId.' It also provides specific example report types, which makes the purpose concrete and distinguishable from sibling tools like get_report (retrieves a report) or download_report (downloads report content).

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 the verb 'Creates' and the context of sibling tools, but the description does not explicitly differentiate when to use this tool versus get_report or download_report. It lacks explicit guidance such as 'Use this to initiate a report; use get_report to check status or download_report to retrieve data.'

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 of behavioral disclosure. It only states the action ('Sets the fulfillment quantity') but does not mention side effects, such as whether this triggers a feed submission, whether it is reversible, or what the response looks like. It also does not explain the significance of the 'DEFAULT channel' beyond a qualifier. This is insufficient for a mutation tool with zero annotation coverage.

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

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

The description is a single, tight sentence that states the action and a key scoping qualifier. There is no fluff or repetition. It is optimally concise and front-loaded.

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

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

For a mutation tool with three required parameters and no output schema or annotations, the description is under-specified. It omits any mention of return values, error conditions, prerequisites (e.g., product type must be valid), or the operational impact (e.g., feed submission). An agent would need to infer too much about the tool's behavior.

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 three parameters (sku, quantity, productType) including the meaning of quantity (0 to remove the buyable offer). The description adds only the channel context, not parameter-specific meaning, so it does not go beyond 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 clearly states the verb 'Sets' and the resource 'fulfillment quantity for a SKU', with an explicit channel qualifier '(merchant-fulfilled / DEFAULT channel)'. It is specific and unambiguous, but it does not reference any sibling tool to differentiate, so it does not fully earn a 5.

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

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

The channel qualifier implies that this tool is for merchant-fulfilled listings only, which provides some usage context. However, it does not explicitly state when to use this tool versus alternatives (e.g., for FBA or other channels), nor does it mention any prerequisites or exclusions.

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

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

The description explicitly says 'WRITES to your account' and mentions creating/uploading, aligning with the destructiveHint annotation. It does not detail side effects, but the annotation already covers destructiveness, so the bar is met.

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

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

The description is two sentences, direct, and free of unnecessary detail. Every clause adds information about purpose or workflow.

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?

It covers what the tool does, the intended bulk use case, and the return value (feedId for polling). Without an output schema, this is sufficient 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?

The schema fully describes all three parameters (content, feedType, contentType), so the description adds little beyond the schema. It implies content is the body but does not add meaningful constraints or format details.

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

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

The description clearly states the action (submit a feed) and the resource (feed) with a specific verb. It also mentions 'in one call' and 'bulk operations' to distinguish from per-item tools like upsert_listing, though it does not explicitly name alternatives.

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

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

It provides context on when to use this tool ('Common for flat-file / JSON_LISTINGS_FEED bulk operations') and instructs to poll with get_feed using the returned feedId, effectively guiding the asynchronous workflow.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the PATCH mechanism but does not disclose side effects, error conditions, required permissions, reversibility, or what happens if the SKU doesn't exist. For a mutation tool, this is insufficient.

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

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

A single, front-loaded sentence that efficiently conveys the core action and its convenience aspect. No wasted words, though the term 'purchasable_offer' may be jargon but is still precise.

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

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

This is a mutation tool with no annotations and no output schema. The description does not cover success/failure outcomes, prerequisites, or error handling, leaving an agent without critical information needed to invoke it correctly and interpret results.

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

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

Schema coverage is 100% and the description adds little beyond what the schema already states (selling price, optional MRP). It does not provide additional context on units, validation rules, or interaction between price and mrp, so it meets the baseline without enriching semantics.

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 sets the selling price (and optional MRP) for a SKU via a purchasable_offer PATCH, and distinguishes it from a full upsert. This is specific and immediately differentiates it from upsert_listing, 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 phrase 'without a full upsert' implies this is the tool to use when only updating price, contrasting with upsert_listing. However, it does not explicitly mention alternatives like set_quantity or state when not to use it, though the context is reasonably clear.

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 HTTP method (PUT) and the need for complete attributes, but does not explicitly state that the operation will overwrite existing listing data or mention side effects like validation failures or state changes beyond what is implied by 'upsert.'

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

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

The description is two sentences, highly concise, and well-structured. It front-loads the action and follows with parameter priorities and requirement options, avoiding any unnecessary filler.

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

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

Given the moderate complexity (four parameters including a nested attributes object) and no output schema, the description lacks information about the expected response format, potential errors, or the fact that the operation is a full replacement. It does cover the core usage but misses some contextual details that would help an agent handle the operation safely.

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

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

Schema coverage is 75% (3 of 4 params have descriptions). The description adds value by clarifying 'full attributes object' and explaining that requirements can be LISTING or LISTING_PRODUCT_ONLY, which complements the enum definition and gives semantic meaning 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 states a specific verb and resource: 'Creates or updates a listing via PUT.' It clearly differentiates from siblings like get_listing, delete_listing, update_price, and set_quantity by focusing on the full listing upsert operation.

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 explicit parameter guidance (productType, sku, full attributes) and explains the requirements enum values (LISTING vs LISTING_PRODUCT_ONLY). However, it does not explicitly contrast with alternatives like update_price or set_quantity, which could clarify when to use this tool over those.

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