ForthClear Liquidation Marketplace

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

Beyond the readOnly/title annotations, the description discloses two important behaviors: orders not owned by the caller are silently skipped, and the return value is the CSV body plus a suggested filename. This tells the agent exactly what to expect despite the lack of an output schema.

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

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

Two sentences carry all essential information: output format, column list, endpoint nature, scoping behavior, and return shape. There is no redundancy or filler.

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

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

Given a single parameter, full schema coverage, and read-only annotations, the description provides everything needed to invoke the tool correctly. The explicit return format compensates for the missing 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 description coverage is 100%, including ownership and max 200 per request, so the schema already documents the only parameter. The description repeats the ownership constraint but adds no new parameter-level detail; 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: 'Export the calling seller's orders as CSV', and clarifies the exact columns. This distinguishes it from sibling tools, none of which perform bulk order export.

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 clear context: it is for exporting order data as CSV and is scoped to the seller's own orders. It does not explicitly name alternatives or exclusion conditions, but the sibling list contains no comparable export tool, so the intended use is evident.

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?

Goes well beyond the annotations (destructive/openWorld): it discloses that tracking overwrites any existing tracking, that each updated order triggers a buyer shipment message, that non-owned orders are skipped, and that the result is bucketed per-order success/failure. This is exactly the side-effect detail an agent needs for a destructive write.

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 with the core action and cap, then behavioral caveats, then return shape. Three dense sentences with little waste, though the 200 limit is repeated from the schema and the endpoint path is somewhat incidental.

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

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

With no output schema, the description supplies the return shape (per-order success/failure buckets) plus ownership filtering, overwrite behavior, and side effects. 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 coverage is 100%, so baseline is 3, but the description adds real meaning: the tracking fields are applied identically to every listed order, and carrier_name is auto-detected when only a tracking number is supplied. That clarifies the all-orders-or-nothing semantics the schema alone doesn't convey.

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+resource (mark orders as shipped), the scope (up to 200 of the calling seller's own orders), and the optional tracking write. No sibling overlaps this operation, so it is unambiguously distinguishable from bulk_export_orders or get_order_status.

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

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

The description establishes clear context: it operates on the calling seller's orders only, in bulk, with an optional tracking payload. It doesn't explicitly name a when-not case or an alternative tool, but no sibling covers single-order shipping, so the omission is minor.

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?

Adds real context beyond annotations: the 200-item cap, seller-ownership filtering, per-product validation, and the underlying endpoint mapping. Annotations already flag destructiveHint=true and idempotentHint=false; the description does not restate that, but also does not explain what happens to a partial batch when some products fail validation.

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

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

Three sentences, zero padding, with the ownership and volume constraint front-loaded before the mode enumeration. The final mode sentence overlaps with the schema enum descriptions but remains useful for scanning.

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 destructive bulk mutation with no output schema and no annotation coverage of return semantics, the definition never states what the response looks like or how partial failures are reported. Annotations cover the safety profile, but the result behavior is left entirely implicit.

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 schema already documents all three parameters including enums and ranges. The description's mode/value mapping largely repeats the schema's own descriptions, adding little beyond the 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?

States a specific verb (bulk update), resource (prices or MOQ), and scope (up to 200 of the calling seller's own listings). This clearly separates it from create_listing and search_inventory in the sibling set.

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?

Explains that it is a thin adapter over two specific backend endpoints and gives explicit guidance on which mode to choose for which value type. It lacks any when-not-to-use guidance (e.g., single-listing edits vs. bulk, or how to handle failures).

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, openWorldHint=true, and destructiveHint=false, so the safety profile is covered structurally. The description adds nothing behavioral beyond that: it does not say whether the listing publishes immediately, requires moderation, or is reversible. With the annotation bar in place, this near-zero added context warrants a 2.

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 with zero filler, so nothing is wasted. The size is arguably too lean for an 8-parameter creation tool, but as a conciseness measure it is tight and well-formed.

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

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

The tool has 8 parameters, 5 required, and mutating side effects in an open-world marketplace, yet the description omits what happens on success (e.g., listing visibility, review flow). The output schema covers return values and the schema covers inputs, but the operational context an agent needs before invoking a non-idempotent create is absent.

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%, including enum documentation for category and condition and unit notes for prices in cents, so the schema carries the full burden. The description mentions no parameters at all, 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 description states a specific verb and resource ("Create a new product listing") and adds audience scope with "(seller tool)". It is clear what the tool does, though it never distinguishes itself from peers like bulk_update_listings or search_inventory beyond the seller-facing framing.

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

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

There is no when-to-use guidance, no prerequisites, and no naming of alternatives (e.g., bulk_update_listings for edits). The parenthetical audience hint implies a seller context but leaves the agent to infer when creation is 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful non-annotation context: access is scoped to the authenticated buyer via X-MCP-API-Key or a buyer X-Agent-Token, implying authorization/ownership checks that an agent must satisfy.

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

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

One sentence, front-loaded with the resource and the returned fields, with the auth caveat in a trailing parenthetical. It is efficient, though the dense credential phrasing slightly taxes readability.

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

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

For a read-only, single-parameter tool with no output schema, the definition covers purpose, returned fields, and the authorization model. It does not describe error cases (e.g., order not owned by the caller), which would be the only meaningful remaining 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% for the single order_id parameter, so the schema already carries the parameter documentation. The description only implies that order_id must belong to the authenticated buyer; it adds no format, range, or lookup detail, which matches the baseline 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 gives a specific verb+resource (get order status) and even enumerates the returned facets (status, tracking, inspection deadline), which clarifies scope beyond the bare title. It does not explicitly differentiate from the nearest sibling get_quote_status, so it falls 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?

There is no guidance on when to use this tool versus alternatives such as get_quote_status or the bulk order tools. The only conditional content is about authentication, not about choosing this tool.

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

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

Annotations already mark the operation as read-only and non-destructive, so the description does not need to repeat that. It adds that the output is an AI-powered recommendation rather than a guaranteed market price, but it does not discuss response behavior, edge cases, or any additional requirements.

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

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

One sentence with no filler; the core action and domain are front-loaded. Every phrase ('AI-powered,' 'pricing recommendation,' 'inventory,' 'seller tool') adds useful targeting 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, read-only recommendation tool with full parameter documentation and an output schema, the description is largely sufficient. The only meaningful gap is the absence of explicit usage conditions, but an agent can still identify the tool and invoke it correctly from the structured fields.

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 parameters are already well documented. The description adds no extra meaning about category, condition, quantity, or original_retail beyond that 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 pairs a specific verb 'Get' with the resource 'pricing recommendation,' scoped to inventory and seller use. This clearly distinguishes the tool from siblings such as search_inventory or get_product_details, which cover different operations and resources.

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 context ('for inventory' and 'seller tool') but no explicit when-to-use or when-not-to-use guidance, and it names no alternative tools. The appropriate usage is implied rather than stated: call this when a seller needs an AI-powered pricing recommendation for inventory.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds no behavioral context such as required permissions, rate limits, or the nature of the returned details. It does not contradict the annotations, but it provides no additional transparency beyond what structured fields already convey.

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, direct sentence with zero filler. It front-loads the action and resource, making it immediately clear what the tool does. There is no unnecessary elaboration.

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

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

For a simple read-only tool with one well-documented parameter and an existing output schema, the description is adequate. It states the purpose clearly, the parameter is fully defined in the schema, and return values are presumably covered by the output schema. However, it could be slightly more explicit about the scope of 'detailed information' (e.g., which fields are included), though that is likely captured in 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?

The input schema has 100% description coverage because product_id is described as 'Product ID (format: product_123)'. The tool description does not add any extra meaning or context about the parameter, so it remains at the baseline of 3 for high schema coverage.

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

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

The description clearly states a specific verb (Get) and resource (product details), and narrows scope to 'a specific product' which implies retrieval by ID. This distinguishes it from sibling tools like search_inventory (which lists products) or get_pricing_recommendation (focused on pricing). However, it does not explicitly name alternatives, so it falls short of a perfect 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 description provides no guidance on when to use this tool versus its siblings. It does not mention search_inventory for finding products or get_pricing_recommendation for pricing, nor does it state any exclusions or conditions. An agent is left to infer usage purely from the name and description, which is 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations by clarifying that results are scoped to the calling seller's products and that the default view is pending requests.

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

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

The description is a single, front-loaded sentence with no filler. The key scoping information ('seller's products', 'seller tool') is included without repeating the schema's parameter 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?

For a one-parameter read-only tool with an output schema and annotations covering safety, the description is nearly complete. It falls slightly short of 5 because it does not acknowledge the responded/all statuses or clarify the relationship to the closely related quote-request tools.

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 status parameter has a clear description, enum values, and a default. The description adds no parameter-level meaning beyond what the schema already provides, so 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 identifies a specific verb and resource ('Get ... quote requests') and narrows scope to the seller's own products, which separates it from request_quote and respond_to_quote. It is slightly less than 5 because it says 'pending' as if that were the entire purpose, while the schema shows status can return responded or all 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 gives context by marking this as a seller tool for incoming requests, so an agent can infer it is for viewing rather than creating or replying. However, it never explicitly states when to prefer this over respond_to_quote, request_quote, or seller_inbox_summarise, nor does it name those alternatives or exclusion conditions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely useful behavior context: the field-level content of the response (status enum, price, shipping after seller reply) and the two authentication paths.

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 dense, front-loaded sentences with no filler; the read purpose and payload lead. 'And what to do next' is slightly vague but does not waste much 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?

There is no output schema, so the description carries the return-value burden and does so by listing status values and reply fields. Auth requirements are also covered, leaving little an agent needs to call 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?

Schema coverage is 100% so the schema already documents both params. The description still adds meaning by noting status_token originates from request_quote's response and that it can be omitted when using a buyer token — explaining when the optional param is actually 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?

States a specific verb and resource ('Read back a quote you filed') and enumerates exactly what comes back: status values, seller price/shipping, next steps. It is clearly distinguishable from siblings like request_quote, respond_to_quote, and get_quote_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?

Gives concrete auth guidance: pass the status_token returned by request_quote, or use a buyer X-Agent-Token/account key to read your own quotes without one. It does not explicitly contrast with sibling tools, but the retrieval context 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?

Goes well beyond the annotations by disclosing the state transition to 'issue_reported', that the issue is recorded, that admins are notified, and the exact auth requirement (X-MCP-API-Key or buyer X-Agent-Token). It does not say whether a second dispute can be opened on the same order, which is the only real gap, and nothing here contradicts destructiveHint=false or openWorldHint=true.

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 dense sentences with zero filler, front-loading the action and precondition before the side effects and auth note.

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?

No output schema exists, yet the description covers the trigger condition, resulting state, side effects and authorization, which is enough to invoke correctly. The return value of the call is left unspecified, but that is minor for this action.

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

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

Schema description coverage is 100% and both enums are documented, so the schema already carries parameter meaning. The description only hints at 'records the issue' without clarifying reason vs. description vs. requested_action, 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 (open) plus resource (dispute) and adds the scope condition ('on a delivered order awaiting the buyer's confirmation'). No sibling tool handles disputes, so this is unambiguous within the toolset.

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 a clear precondition for use (delivered order awaiting buyer confirmation) and the required actor (the order's buyer). It stops short of naming alternatives or a when-not-to-use case, e.g. contacting the seller first.

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 provide readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true, covering double-charge risk and safety profile. The description adds useful context about the seller opt-in prerequisite and order-size threshold, but doesn't mention what happens on failure (e.g., payment handling, order creation side effects). With annotations carrying the primary behavioral burden, this is adequate but not rich.

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

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

Two sentences, zero waste. The primary use case is front-loaded, and the alternative is presented immediately after.

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 no output schema, the description covers the critical eligibility conditions and the fallback path. It omits return behavior (order confirmation details) and error modes, but given the annotations already signal non-idempotency and open-world reach, it is close to complete for correct invocation.

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

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

Schema coverage is 100% with clear descriptions for all five parameters, so the schema does the heavy lifting. The description adds no parameter-level detail (e.g., units semantics, format constraints) beyond what the schema already declares. 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?

States a specific verb and resource ('one-step purchase for products') with immediate scope qualifiers ('instant checkout enabled', 'orders under bulk threshold'). Clearly distinguishes itself from the named sibling request_quote.

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

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

Explicitly defines when to use this tool (products with seller opt-in and small orders) and names the alternative (request_quote) for the disallowed conditions. Nothing is left to inference for an agent deciding between the two.

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

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

Annotations already declare non-read-only, open-world and non-idempotent behavior. The description adds genuinely new operational context beyond that: the 5-per-hour-per-IP anonymous rate limit, the credential-free path, and where the seller's reply is delivered.

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

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

Two tight sentences with no filler; the core action and the keyword-level usage constraints are front-loaded in the first clause, and nothing repeats the 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?

With annotations covering the safety profile and an output schema covering return values, the description supplies the missing pieces an agent needs (auth paths and rate limit). Minor gap: no guidance on failure behavior when the anonymous quota is exhausted.

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 seven parameters and their formats. The description adds only that buyer_email is required and serves as the reply address, which is useful but marginal against a fully documented 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+resource ('Request a bulk quote for a product') and tags itself as a buyer-side tool, which distinguishes it from seller-side siblings like respond_to_quote and get_quote_requests. It does not name an alternative explicitly, so it falls 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?

Explains the credential model clearly: works without credentials, buyer_email is required as the reply destination, and a buyer X-Agent-Token binds the quote to an account. It gives conditions for use but never says when to prefer this over siblings such as get_quote_status or respond_to_quote.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so safety basics are covered. However, the description adds no behavioral context of its own — it never says that accept/counter are binding commitments to the buyer, whether a decision can be changed, or what happens on repeated calls despite the non-idempotent flag.

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 a single front-loaded clause with no waste, but it is so terse that it borders on under-specification; the parenthetical qualifier is the only extra information offered.

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 state-changing seller action with no output schema, the description omits the outcome of each decision (e.g. that accepting creates an order or locks in terms) and any error or precondition context. Annotations cover only the generic safety profile, leaving the workflow gaps 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%, including the action enum and the counter_price dependency, so the schema carries the parameter burden. The description adds no parameter detail, making the baseline 3 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 names a specific verb+resource ("Respond to a buyer's quote request") and the "(seller tool)" qualifier separates it from buyer-side siblings like request_quote and get_quote_requests. It is clear what the tool acts on, though it doesn't explicitly name which sibling to prefer.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as get_quote_status or get_quote_requests. The agent must infer the workflow entirely from the name.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds the notion of 'available' inventory but doesn't disclose return behavior, sorting, or that all parameters are optional filters. With annotation coverage, this is adequate but not rich.

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 one sentence, front-loaded with the core action, and contains no filler. 'with filters' is slightly generic but doesn't waste words; it could have been more informative without becoming verbose.

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

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

The tool has a fully described schema and an output schema, and annotations cover safety, so the gaps are mostly around usage guidance and sibling differentiation. An agent can reasonably infer how to call it, but not when to prefer it over related read tools.

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%; each parameter already has a description including default/max for limit and the enum for condition. The description's generic 'with filters' adds no parameter-specific meaning 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 description states a specific verb ('Search') and resource ('available liquidation inventory'), and mentions filters. It doesn't explicitly differentiate from sibling read tools like get_product_details, but the verb 'search' implies a list/scoped query rather than a single-item lookup.

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 given on when to use this tool vs alternatives, or when to use a sibling like get_product_details for individual item lookups. The description is a bare directive with no exclusions or 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false. The description adds real context beyond them: the return shape ('search_inventory product shape plus a similarity score in [0, 1]') and an auth note ('No credentials needed'). It does not cover ranking order or pagination behavior, but the added return/auth detail clears the lowered bar.

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

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

Three tight sentences: purpose first, return shape second, auth third. The example query earns its place by illustrating the natural-language input. No filler.

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

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

With no output schema, the description compensates by naming the return shape and similarity score, and it flags the auth requirement. What remains thin is the relationship to the sibling search_inventory and ranking/pagination behavior, but for a read-only search tool this is close to complete.

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

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

Schema description coverage is 100%, so all five parameters including the enum-constrained condition are documented in the schema itself. The description only illustrates the query parameter through an example and adds no syntax, filtering, or limit semantics beyond what the schema provides.

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+resource ('Semantic catalog search') and the ranking mechanism ('ranks listings by similarity to a natural-language description'), with a concrete example query. It implies but never names its obvious sibling search_inventory, so the agent must infer the split between semantic and keyword 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 phrase 'natural-language description' and the example 'something like AirPods but cheaper' implicitly signal when semantic search is preferred over exact-match search, but there is no explicit when-to-use/when-not or named alternative among the many siblings (search_inventory in particular). Usage is left to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only nature is covered. The description adds behavioral context by specifying the three buckets of information and reaffirms 'Read-only digest', which is consistent. It doesn't introduce new security or mutation concerns, and the added detail about content goes beyond the annotations.

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

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

The description is two sentences, front-loaded with the digest contents and followed by a concrete use case. Every word earns its place—no redundancy, filler, or restating of the title. It is highly compact and informative.

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

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

For a read-only tool with no output schema, the description adequately explains what the digest includes and when to use it. It does not detail the output format (e.g., counts vs. items), but given the tool's summarize nature and the presence of sibling tools for granular details, this is acceptable. The safety profile is covered by annotations, so the description is complete enough for selection and invocation.

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

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

The input schema covers 100% of the two parameters (limit and window_hours) with descriptions, including defaults and bounds. The tool description does not add extra parameter semantics beyond restating the input's purpose. Since schema coverage is high, the baseline of 3 applies; no additional value is provided.

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 ('summarise') and resource ('seller's inbox') and enumerates concrete content categories: pending quote requests, at-risk orders, and reported issues. This clearly distinguishes it from sibling tools like get_quote_requests or bulk_mark_shipped, which focus on single actions or data types.

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

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

It states the intended context: 'Useful for a daily standup or cron-driven agent that decides which bulk action to run next.' This clarifies when to use it, aligning with the decision-making workflow. It does not explicitly mention when not to use it or name alternatives, but the use case is clear and enough for an agent to select it appropriately.

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 declare readOnlyHint=false, idempotentHint=false, openWorldHint=true, destructiveHint=false. The description goes beyond them by disclosing the webhook delivery is an HMAC-signed POST, that polling is available via a concrete resource path, and that credentials are required. It omits quota/duplicate-subscription behavior, which a mutating, non-idempotent tool would benefit from.

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

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

Two tight sentences; the core action is front-loaded and the delivery mechanics follow. The trailing 'Requires credentials.' is short and earns its place as an operational caveat, though the sentence structure could be marginally tighter.

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

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

With no output schema, nested query/channels objects, and a non-idempotent mutating operation, the description covers what is needed to call it correctly: what gets saved, where matches go, and that auth is needed. Missing details on duplicate-subscription handling and limits are minor 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 description coverage is 100%, so both the query filter object and the channels array are already well documented in the schema, including the 1-5 constraint and channel types. The description restates the channel options and adds no format or syntax detail beyond the schema, so 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+resource ('Save a search') scoped to the calling agent principal, and clarifies that new matches are pushed to channels. It does not explicitly name a sibling like search_inventory to distinguish persistence from one-shot search, 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?

Use is implied: this is the tool for persisting a search and receiving ongoing notifications. However, there is no explicit when-to-use vs when-not guidance (e.g., use search_inventory for immediate results instead of subscribing) and no prerequisites beyond 'requires credentials'.

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