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

With no annotations, the description carries full behavioral burden and excels: it discloses atomicity ('NOTHING is applied'), failure semantics (400 rejection, errors list), optional field handling (omit vs. null), the unpublished-only restriction on resetting price, and side effects like promo price recomputation and background membership refresh.

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

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

The description is a dense, information-rich paragraph with no filler, but it is somewhat long and packs many details. It is well-structured by starting with purpose, then atomicity, then field semantics, each sentence earning its place.

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

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

Given no output schema or annotations, the description covers the main usage, failure modes, parameter semantics, and side effects quite thoroughly. It doesn't describe the full response object or mention rate limits/auth, but these are not critical for a bulk update tool with this level of detail.

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 schema already details omit/null behavior, so baseline is 3. The description adds meaningful nuance such as 'Changing price recomputes the promo price' and 'promo membership is refreshed in the background', which go beyond the schema's field-level descriptions.

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

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

The description clearly identifies the tool as 'Update prices of up to 5000 variants in one synchronous, atomic request', which is a specific verb + resource + scope. It also explicitly contrasts it with 'calling update_variant per item', distinguishing it from a sibling tool.

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

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

It states this is 'the fast path for syncing a whole catalog instead of calling update_variant per item', directly naming an alternative tool and providing a clear usage context. Although it doesn't list explicit exclusions, the alternative and bulk-sync intent are 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses that cancellation is status-dependent, that the optional reason is only kept in the MCP log and not sent to the KIT API, and that no request body is required. These are meaningful behavioral traits beyond a simple 'cancel' statement.

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

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

The description is three sentences long and front-loaded with the core action. Every sentence provides essential context—status dependency, reason handling, and body requirement—with no fluff 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 cancellation tool with only two parameters and no output schema, the description covers the critical aspects: what it does, a key constraint (status), behavior of the optional reason, and request format. It could be more explicit about success/failure responses or which statuses allow cancellation, but that level of detail is not necessary for this tool.

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

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

The input schema already has 100% parameter coverage, with the reason field clearly documented as conversation/tool-log only. The description repeats this same information without adding new parameter-level meaning. It adds the non-parameter note about no request body, but that does not enhance parameter 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 opens with the specific verb+resource phrase 'Cancel an order,' which clearly states the tool's function. It distinguishes itself from sibling tools like confirm_order and complete_order_delivery by naming the exact 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?

The description provides clear context by noting that cancellation depends on the order's current status, setting expectations for when the tool may not work. However, it does not explicitly name alternatives or state when-not-to-use scenarios, so it earns a 4 rather than a 5.

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

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

Since no annotations are provided, the description carries the full transparency burden. It discloses a key behavior: archive is a soft delete (hidden from storefront, restorable). It also reveals the conditional requirement for archive_variants, which is meaningful side-effect information. Missing are details on permissions or return format, but the disclosed behavior is non-trivial and valuable.

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, directly opens with the verb, and contains no filler. It efficiently packs the soft-delete framing, the restorability, and the conditional archive_variants requirement without repetition.

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

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

Given there is no output schema and no annotations, the description covers the core context well: what the tool does, when to use it, and an important side-effect rule. It does not explain return values or broader effects on products, but for a simple toggle action, the context is sufficiently 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?

The input schema already provides 100% coverage with descriptions for all three parameters. The description adds extra meaning beyond the schema by explaining when archive_variants becomes necessary and clarifying the effect of the 'archive' action. This enrichment justifies a score above the baseline of 3.

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

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

The description states a specific verb and resource: 'Archive a category ... or unarchive it.' It also defines the nuance of soft delete and clearly distinguishes from siblings like update_category by naming the two actions. The title and description align, making the purpose unmistakable.

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

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

The description implies when to use the tool: when an archive/unarchive action is needed. It adds a crucial conditional ('If the category is the only one of a product with non-archived variants, archiving requires archive_variants=true'), which guides usage. However, it does not explicitly contrast with alternatives like update_category, though the title and action enum make this 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?

No annotations are provided, so the description carries the full burden. It discloses the primary effect (marks delivery fully completed) and the absence of a request body, but it does not mention permissions, reversibility, or side effects. 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, front-loaded with the core action, followed by usage context and a request note. Every sentence contributes value with no 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 one-parameter tool with no output schema, the description covers the action, when to use, and the request body absence. It lacks return/error details, but given the simplicity, it is nearly complete.

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

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

The input schema covers 100% of the single parameter with 'Order ID (UUID)', so the description adds no extra meaning to the id parameter. The note 'No request body is required' is about request structure, not parameter semantics. 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 action 'Mark the delivery of an order as fully completed' with a clear resource and scope, and it distinguishes itself from sibling order tools like confirm_order and cancel_order by focusing on delivery completion. It also clarifies when this applies (pickup/own delivery with automation off), making the purpose unique.

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

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

Explicitly states intended use: 'Intended for pickup and the store's own delivery when delivery automation is off' and gives an exclusion: 'with automation on, the platform moves the order itself.' This tells the agent when to use the tool and when not, even though no specific alternative tool is named.

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

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

No annotations are provided, so the description carries the full burden. It mentions the status precondition and 'No request body is required,' but it does not disclose the resulting order status changes, potential errors, or idempotency. The 'No request body' statement is ambiguous given the schema requires an id, potentially misleading the agent.

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

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

The description is three sentences long, with the main action in the first sentence and no filler. It is front-loaded and every sentence contributes useful 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?

The tool is simple with one parameter and no output schema, so the description covers the core action. However, the ambiguity between 'No request body is required' and the required 'id' in the schema leaves the agent uncertain about how to pass the parameter, and the description does not clarify the response or side effects of confirming an order.

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 'id' parameter, so the schema already documents its meaning as 'Order ID (UUID).' The description adds no additional semantic value about the parameter, so the baseline 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 starts with 'Confirm an order,' which clearly identifies the verb and resource. It distinguishes from sibling tools like cancel_order and complete_order_delivery by specifying the confirm action and adding the required WAIT_FOR_CONFIRMATION 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 provides an explicit precondition: 'The order must be in the WAIT_FOR_CONFIRMATION status.' This implies when to use the tool. It does not explicitly mention alternatives or when-not to use it, so it stops short of a 5.

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

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

With no annotations, the description must carry the behavioral burden. It explicitly says this operation creates (persists) a new store article, which is the primary, and points to the operation-schema requirement, a useful runtime detail. However, it gives no info about permissions, idempotency, irreversibility, or what is returned, so it is not fully transparent.

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

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

The description is two short sentences: the first names the action and target, the second gives the indispensable operation-schema reference. Every word carries the weight—no fluff, no repeated schema 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?

The description tells the agent how to get the required schema and what the tool does, but it leaves several practical gaps: there is no output schema, no mention of side effects besides creation, and no clue about what to do if the blog already exists (i.e. alternative update_blog). It is a defensible minimal viable definition but not complete for a description with zero annotations.

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 only describes the 'blog' nested object as 'News article matching the CreateBlog request error'. The description enriches this by directly telling the agent to call get_operation_schema("CreateBlog") to obtain the exact shape, which is the critical missing context. It doesn't enumerate all fields, but it points the agent precisely to where they can be resolved.

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 'Create a blog' gives a specific verb, resource, and scope—'store news article'—and naturally distinguishes it from sibling blog tools like get_blog, update_blog, and list_blogs, which have clearly different actions. The title 'Create news article' aligns with the description, so an agent can infer exactly what this tool creates.

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 clearly states the context—'Create a newsletter article'—and adds an effective procedural tip: call get_operation_schema("CreateBlog") before invocation, which is the key usage step. It does not explicitly exclude cases where the blog already exists or mention asking to modify an existing article, so it stops short of a 5.

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

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

With no annotations, the description carries the full burden. It discloses that it creates (mutates) a resource, but doesn't mention permissions, idempotency, side effects, or response format. The reference to get_operation_schema points to request shape, not 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?

Three brief sentences, front-loaded with the purpose, then field requirements. No redundant information.

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

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

The description gives clear field requirements and a pointer to get_operation_schema for the exact shape, but it doesn't describe the return value or any error scenarios. For a create operation with no output schema, this leaves some ambiguity about 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 describes a single 'category' object. The description adds value by enumerating the optional fields (slug, parent_id, display_sequence, etc.) which are not specified in the schema property description beyond a reference to another 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 creates a new product category, using the specific verb 'Create' and resource 'product category', distinguishing it from sibling tools like get_category and update_category. The action and scope are unambiguous.

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

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

The description provides clear context for use—creating a new category—and lists required vs optional fields. It doesn't explicitly name alternatives, but the verb 'Create' implies its use case vs update/get. No exclusions are given, so it's clear but not fully explicit.

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?

Because no annotations are provided, the description carries the full behavioral burden. It states the primary side effect (creating something), but it does not disclose permission requirements, idempotency, duplicate handling, or what happens to related data. It also does not describe the response behavior.

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

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

The description is two compact sentences. The purpose is front-loaded, and the follow-up instruction about retrieving the exact request schema is both relevant and necessary.

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

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

The description is reasonably complete for a simple create operation because it tells the agent where to get the precise request shape. However, with no annotations and no output schema, it still leaves important context unspecified, such as error behavior, authorization needs, and what the response contains.

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 only presents an opaque nested object, so the description adds meaningful value by instructing the agent to call get_operation_schema("CreateCharacteristic") for the exact request shape. This compensates for the otherwise unhelpful parameter definition.

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 says exactly what the tool does: "Create a product characteristic." The verb and noun are specific, and the resource clearly distinguishes it from list/update characteristic tools and from characteristic-group tools elsewhere 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?

The action "Create a product characteristic" makes the basic usage obvious, but the description does not mention preconditions, when not to use this tool, or alternatives such as update_characteristic. The guidance is implied rather than stated.

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?

There are no annotations, and the description does not disclose side effects, idempotency, authorization needs, validation behavior, or what a successful create returns. The pointer to get_operation_schema only covers request shape, not runtime 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 clean sentences: the action is front-loaded, and the second sentence provides an immediately useful pointer to the exact request shape. Every word contributes.

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 pointer to get_operation_schema addresses the core request-shape problem created by the nested 'group' parameter. However, with no annotations, no output schema, and no behavioral notes, the description still leaves effects, return values, and operation nuances unexplained.

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 single group parameter has 100% schema description coverage: 'Group matching the CreateCharacteristicGroup request schema.' The description adds nothing meaningful beyond that, so the baseline 3 applies.

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

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

States a specific action and resource: 'Create a product characteristic group.' It is clear, though it mostly restates the tool name and does not explicitly distinguish the create operation from the sibling list/get/update characteristic-group operations.

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 instruction to call get_operation_schema('CreateCharacteristicGroup') gives the agent a concrete preparation step for building the request. It does not, however, state when to choose this tool over competing group-related tools or describe exclusions.

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

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

No annotations are provided, so the description carries the full burden. It mentions required fields and dynamic_filter, but it does not disclose authentication needs, side effects, idempotency, or response format. For a mutating create operation, this is minimal transparency.

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

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

The description is three short sentences, front-loaded with essential information and a useful pointer to get_operation_schema. There is no redundancy or filler; every sentence earns its place.

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

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

Given the nested request shape, lack of annotations/output schema, and single parameter, the description is largely complete: it names all required fields, specifies allowed values, and directs the caller to get_operation_schema for the exact request shape. It omits outcome/error/response details, but the schema pointer mitigates the 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?

The schema only provides a generic nested 'collection' object with a pointer to CreateCollectionRequest, but the description adds meaning by spelling out required fields and enum values (ACTIVE|INACTIVE, STATIC|DYNAMIC) and noting when dynamic_filter applies. This exceeds the schema's bare description.

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

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

The description clearly states the action ('Create a new collection') with the specific resource and lists required fields and types. It distinguishes itself from sibling collection tools (update_collection, delete_collection) by explicitly indicating creation.

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 prerequisites (required fields) and a pointer to get_operation_schema, but it does not explicitly state when to use this tool versus alternatives like update_collection. The usage is implied by the name and context, not explicitly stated.

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

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

No annotations are provided, so the description must disclose behaviors. It mentions required fields and points to get_operation_schema, but does not explain side effects, permissions, return value, or irreversibility. For a mutation tool, this is a notable 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 two efficient sentences, front-loaded with the purpose and required fields, and ends with a helpful pointer to get_operation_schema. No wasted words.

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

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

For a create operation with no annotations or output schema, the description provides the essential input requirements and points to get_operation_schema for exact shape. However, it lacks information about the response, error cases, or behavioral implications, leaving some gaps for the agent.

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 is minimal, only naming the required fields. The tool description adds meaning by detailing the structure of discount_value, discount_dates, status, and binding_mode with their allowed values, which the schema does not provide. This goes beyond the schema description.

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

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

The description states 'Create a new discount' with a specific verb and resource, clearly distinguishing it from update_discount and other discount-related siblings.

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 tool's purpose implies when to use it (creating versus updating), but there is no explicit guidance on when not to use or alternative tools. Listing required fields gives context, but no exclusions.

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

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

No annotations are provided, so the description carries the full burden. It only states the action and a parameter requirement; it does not disclose side effects, authentication needs, idempotency, error behavior, or the return value. For a mutation tool, this is a notable 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 two sentences long, front-loaded with the primary purpose, and includes only essential information (requirement and schema reference). No filler or redundancy.

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

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

For a complex tool with a nested product object and no output schema, the description effectively directs to get_operation_schema for the full request shape, which is a practical pattern. However, it omits details about the response or failure modes, so it is not fully complete but sufficient for invocation.

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

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

Schema coverage is 100%, providing a baseline of 3. The description adds value by specifying that category_ids is an array of category UUIDs and requires at least one, which is not fully detailed in the schema. It also points to get_operation_schema for complete request shape, enhancing parameter understanding.

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 'Create a new product' with a specific verb and resource, clearly distinguishing it from siblings like list_products, get_product, and update_product. It is not a tautology and directly conveys the tool's function.

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

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

The description explicitly requires category_ids with the constraint 'at least one', and instructs the agent to call get_operation_schema("CreateProduct") for the exact request shape. This gives clear usage context, though it does not explicitly mention when not to use the tool or alternatives.

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

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

With no annotations, the description carries full responsibility for behavioral disclosure. It reveals a critical non-obvious behavior: 'The live API rejects codes containing lowercase letters even though the spec documents no format constraint'. This goes beyond basic expectations and is genuinely useful for avoiding API errors.

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

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

The description is four sentences, each earning its place: purpose, required/optional fields, the lowercase warning, and the schema pointer. It is front-loaded with the verb and resource, and contains no redundant information.

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

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

Given the complexity of a nested promocode object and the absence of an output schema, the description covers required and optional fields, enum types, a gotcha, and a pointer to the exact request schema. It does not describe return values or error behavior, but for a create tool with an external schema reference, it is reasonably complete.

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

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

The schema only describes the single parameter as matching a schema and points to get_operation_schema. The description adds essential semantics by enumerating required fields (code, title, discount_value, promocode_dates, type) and their sub-structure (e.g., discount_value with type PERCENT|VALUE), plus optional fields. This enriches the sparse schema description.

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

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

The description opens with 'Create a new promocode', clearly stating the verb and resource. It distinguishes itself from siblings like update_promocode and create_discount by explicitly naming the entity type and listing its specific fields.

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

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

The description provides clear context for when to use this tool (creating a new promocode) and includes a practical tip ('Call get_operation_schema("CreatePromocode") for the exact request shape'). It does not explicitly exclude alternatives, but the sibling naming makes the intended use obvious.

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 behavior-transparency burden. It goes beyond the obvious by disclosing the media rule: at most one video, a video requires an image in the same list, and the video_id must be READY after an upload/polling workflow. It does not disclose potential failure modes, permissions, or the response shape, but the validation detail is substantial.

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 dense sentences with no filler. The purpose is up front, required fields immediately follow, and the media edge case is given practical, actionable detail. The final pointer to get_operation_schema avoids bulk while preserving completeness.

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 create operation with a nested request object and no output schema, the description covers the main legal hazards and gives an explicit pointer to the authoritative schema. However, it leaves some context implicit, such as what the response contains and whether the operation can fail due to product state, relying instead on get_operation_schema discovery.

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?

Even though schema coverage for the single variant parameter is 100%, the description adds crucial semantic depth beyond the schema's generic 'matching the CreateVariantRequest' text. It names required fields and explains non-obvious media/video constraints, significantly helping an agent construct a valid parameter object.

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 precise action ('Create a new variant') and the resource ('under an existing product'), tying it directly to create_variant while differentiating it from create_product and update_variant. The added phrase '(sellable item)' clarifies the domain without ambiguity.

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

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

The description gives clear usage context: the variant belongs under an existing product, and the required name and product_id are stated. It also explains the prerequisite for media/videos and directs to get_operation_schema for exact shape. It does not explicitly name alternatives or state when not to use the tool, so it misses a 5.

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

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

With no annotations available, the description carries the burden of disclosure. It adds a key behavioral trait: the URL slug is auto-generated from the title and immutable. It also points to the operation schema for shape, but doesn't disclose return values or permission requirements, preventing a 5.

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

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

The description is two sentences, front-loaded with the core action, and every sentence adds critical information: the action, the required field, the immutable slug behavior, and a pointer to the operation schema. No redundant words.

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

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

Given the tool has a nested object parameter, no output schema, and no annotations, the description covers the essential requirements and provides a critical behavioral warning. It also directs to get_operation_schema for exact shape, which compensates for the vague input schema. It could mention the return value, but the essential context is present.

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

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

Although the schema already describes the warehouse parameter and the required title, the description adds the crucial detail that the slug is generated from the title and cannot be changed later. This goes beyond the schema and enriches the meaning of the title parameter, justifying a 4 over the baseline 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 it creates a new warehouse, with a specific verb and resource. This distinguishes it from sibling tools like update_warehouse, get_warehouse, and list_warehouses.

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 clear context for when to use (creating a warehouse), states the required title, and directs users to get_operation_schema for exact request shape. However, it does not explicitly mention alternatives or when not to use it, so it lacks the strict 'when-not' guidance for a 5.

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

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

No annotations are provided, so the description carries the full burden, and it is exceptionally transparent. It discloses HTTPS enforcement, allowed events, the endpoint's behavior change for ORDER_STATUS_CHANGED, and the security critical fact that the signing secret is shown only once.

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

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

The description is front-loaded with the core purpose and immediately covers constraints. It is longer than minimal, but every section conveys a distinct behavioral requirement, and the use of NOTE and IMPORTANT highlights critical caveats in a scannable way.

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

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

Despite having no output schema, the description covers the essential context: request validation, event choices, event behavior caveats, and one-time secret handling. It could more explicitly describe the returned webhook resource, but the pointer to get_operation_schema fills most 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?

The single webhook parameter is documented at 100% coverage in the schema, but the description adds meaningful detail: the HTTPS requirement, allowed events, the events to prioritize, and a pointer to get_operation_schema for the exact request shape. This goes beyond the schema's generic reference to CreateWebhookRequest.

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

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

Opens with 'Create a new webhook', which clearly names both the action and the resource. It distinguishes itself from sibling tools such as get_webhook, update_webhook, delete_webhook, and validate_webhook, so an agent can immediately tell this is the creation 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?

The description gives a clear context for usage: creating a webhook, requiring HTTPS, and restricting to specific events. It does not explicitly contrast with alternatives like update_webhook, but the 'new' in the first sentence makes the intended operation 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?

The description adds 'Permanently' and 'This cannot be undone,' which goes beyond the destructiveHint annotation by emphasizing irreversibility. It does not contradict the annotation and provides useful behavioral context about the operation's consequences. However, it could mention other side effects (e.g., impact on associated objects), but for a simple deletion, this is adequate.

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 short sentences, front-loaded with the action and resource. Every word contributes to understanding the tool's purpose and irreversibility. There is no redundant information.

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

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

For a tool with one parameter, no output schema, and a destructive operation, the description is reasonably complete: it states what, how (by ID), and the irreversible nature. It does not explain post-deletion effects or error conditions, but these are not essential for basic use. It is slightly below a perfect score because it omits any mention of what happens to associated data (e.g., collection cards).

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

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

The input schema already documents the 'id' parameter as 'Collection ID (UUID).' The description only repeats this with 'by its ID,' adding no new meaning beyond the schema. Since schema coverage is 100%, a baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Permanently delete a collection by its ID.' The verb 'delete' and resource 'collection' are specific, and the permanence caveat adds clarity. It is easily distinguished from sibling tools like update_collection or get_collection.

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

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

The description implies when to use the tool (when you want to delete a collection) but does not explicitly state alternatives or exclusions. It does not mention, for example, that this should be used instead of update_collection when permanent removal is intended. Usage guidance is implied by the tool name and description, but not directly stated.

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

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

The description adds behavioral context beyond the destructiveHint annotation by stating 'This cannot be undone,' emphasizing irreversibility. This is useful for an agent deciding whether to invoke the tool, though the annotation already indicates destructive potential.

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 with no filler. The key information (delete operation, permanence, target by ID) is front-loaded.

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

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

For a simple deletion tool with one documented parameter and a destructiveHint annotation, the description provides sufficient context. The irreversibility warning and ID requirement cover the essential operational details, though no output schema exists to clarify return values.

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

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

The input schema fully documents the single 'id' parameter as a webhook ID (UUID). The description's reference to 'by its ID' aligns with the schema but does not add additional semantic detail beyond what the schema already 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?

The description clearly states the tool's function: 'Permanently delete a webhook by its ID.' The verb 'delete' and resource 'webhook' are specific, and the description distinguishes it from sibling webhook operations (get, create, update, validate, list).

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

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

The description implies the tool is for removing webhooks, but it does not explicitly state when to use it versus alternatives like update_webhook or other means of disabling. No exclusions or alternative references are provided, so usage guidance 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?

With no annotations, the description carries the full burden and does well by explaining the soft delete nature, status change to ARCHIVED, and that the discount stops applying but remains restorable. This is important behavioral context beyond just the action.

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 packs essential information: the action, the soft delete semantics, and the restorability. Every clause earns its place with no 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 two-parameter tool with no output schema, the description adequately explains both action outcomes. It does not cover error scenarios or prerequisites, but the core functionality is sufficiently described.

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 documents both parameters with 100% coverage. The description adds context about the meaning of archive/unarchive actions but does not significantly extend parameter semantics beyond the schema.

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

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

The description clearly states the tool's function: archiving or unarchiving a discount, with specific effects. It distinguishes itself from sibling tools like update_discount or manage_discount_objects by focusing on the archive/unarchive 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 description provides clear context for when to use this tool (to archive or unarchive a discount) and implies it over other tools, but does not explicitly mention alternatives 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It does this admirably: fresh documents are always requested, nothing is cached, PDF links are signed and expire at expires_at, links should not be stored, and skipped chunks come back with a reason. This is critical operational context that would otherwise be invisible to the agent.

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

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

The description is dense but every sentence earns its place: purpose and grouping, behavior around caching/expiry, skip conditions, and the source of chunk IDs. It is front-loaded with the primary action and contains no filler or redundant restatement of 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?

For a tool with one fully documented parameter and no output schema, this description is complete. It explains what the tool returns (PDF links and skipped items), the grouping semantics, the expiration behavior, and the conditions under which chunks cannot be processed. An agent has enough context to invoke it correctly and interpret the result.

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

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

The input schema already provides 100% coverage of the single parameter, including required fields, types, array bounds, and the non-repetition rule. The description usefully reinforces that delivery_chunk_id comes from get_order delivery_chunks[].id, but it doesn't need to add more detail; the baseline of 3 applies because the schema does the heavy lifting.

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

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

The description states a specific verb ('Generate waybills') with a clear resource ('order delivery chunks') and outcome ('return links to PDF documents'). It goes beyond the tool name by explaining grouping by warehouse + delivery service, which distinguishes it from delivery-related siblings like complete_order_delivery or get_order.

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 clearly implies when to use the tool: for delivery chunks that need waybills, and explicitly notes when chunks will be skipped (self-pickup, delivery not created, no warehouse, unsupported service). It also points to get_order as the source of chunk IDs, which guides the agent to a prerequisite call, though it doesn't name alternative tools explicitly.

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 readOnlyHint annotation covers the safe-read trait, and the description merely repeats 'get.' It adds no behavioral detail beyond the annotation, such as what happens when no article is found, whether a partial read is returned, or how the article content is represented. No contradiction, but also no added transparency.

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

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

The description is a single short sentence with no filler, the main action and object are front-loaded, and every word earns its place. For a simple single-parameter getter, this is appropriately 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?

For a tool this simple, the description is mostly complete: it states the get action, the resource, and the filter by ID, with strong schema coverage and a readOnly annotation. However, there is no output schema, so the description could have noted whether the return is null/missing on not-found or how the article body is a returned.

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 fully documents the required 'id' parameter as a 'News article ID (UUID)', giving 100% schema_description_coverage. The description's 'by ID' reinforces the parameter but does not add session relativity beyond the schema, so it lands at 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?

The description states a clear verb and resource: 'Get one store news article by ID.' It maps well to the tool's get-by-ID nature and implies a single-resource retrieval, distinguishing it from list_blogs and mutation tools like create_blog/update_blog. The slight name/title mismatch ('blog' vs 'news article') keeps it from 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?

No usage guidance is provided. The description does not state when to prefer this tool over alternatives, e.g. 'use list_blogs to find articles without an ID' or 'use list_blogs to browse.' An agent must infer the usage solely from the ID parameter.

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 aligns with the readOnlyHint annotation (a read operation). It does not add extra behavioral context such as error handling or response format, but for a simple getter, the annotation already covers the key safety trait. No contradiction, but no additional disclosure beyond the annotation.

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

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

The description is a single, concise sentence that is front-loaded with the verb and resource. It conveys all necessary purpose without extra words.

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

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

For a simple read-only getter with one parameter and no output schema, the description is adequately complete. It implicitly indicates the return is the category object. It could mention not-found behavior, but this is a minor gap given the tool's simplicity and annotations.

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 the only parameter 'id' with a description ('Category ID (UUID)') at 100% coverage. The description's 'by its ID' adds no new semantics. Baseline 3 is appropriate since the schema fully handles parameter meaning.

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

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

The description 'Get a single product category by its ID' uses a specific verb and resource, clearly distinguishing it from list_categories (which retrieves multiple) and create/update actions. It precisely states what the tool does.

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

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

The usage is implied: retrieve a category when you have its ID. However, there is no explicit mention of when to use this over list_categories or any alternative. The context is clear but not explicitly differentiated from siblings.

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 correctly indicates a read operation and the readOnlyHint annotation confirms it, so there is no contradiction. However, it adds no extra behavioral context such as response shape, errors, or auth expectations. This is acceptable for a simple getter with strong 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 one short sentence with no filler. It front-loads the intent and contains all necessary concept-level information for this tool.

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

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

For a single-parameter getter with full schema coverage and no output schema, the description is completely adequate. An agent can correctly invoke the tool knowing it should pass one characteristic ID.

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 documents the only parameter as a Characteristic ID (UUID) with 100% coverage. The description's 'by ID' only restates the schema, adding no new meaning.

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

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

The description clearly states the verb (Get), the resource (one product characteristic), and the access pattern (by ID). This distinguishes it from list_characteristics and get_characteristic_group without requiring the agent to open the schema.

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

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

'By ID' makes it clear the tool is the single-record lookup for a characteristic when a specific characteristic UUID is already known. It does not explicitly name alternatives, but the query context is unambiguous enough.

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

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

The readOnlyHint annotation already establishes that this is a safe read operation. The description adds minimal behavioral context beyond confirming single-resource retrieval, but provides no information about not-found behavior, authentication, or return shape.

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 redundant words. It includes the verb, resource, cardinality, and lookup method in a clear, front-loaded structure.

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 single-parameter read operation, the description is sufficiently complete: the agent knows what to request, what to pass, and that one entity will be returned. It does not describe the response shape, but the absence of an output schema makes that less critical here.

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 covers the only parameter fully: id is required, is a string, and is described as a UUID. The description only restates 'by ID', adding no meaningful information beyond the schema, so the high-coverage baseline of 3 applies.

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

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

The description states both the action ('Get') and the resource ('product characteristic group'), plus the cardinality ('one') and lookup mechanism ('by ID'). This clearly distinguishes it from sibling tools like list_characteristic_groups and get_characteristic.

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 'by ID' implies use when a known characteristic group ID is available, but there is no explicit guidance about when not to use it or that list_characteristic_groups should be used for fetching all groups. Usage is only implied, not explicitly routed.

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 readOnlyHint annotation already indicates a safe read operation. The description adds value by specifying the exact fields returned (title, slug, status, type, SEO fields), giving the agent insight into the output without needing a separate schema. It does not cover error cases or authentication, but for a simple read-only get, this is sufficient.

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, focused sentence that front-loads the core action and resource. It includes relevant field information without any filler or repetition, making it concise and easily parseable.

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

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

For a simple 1-parameter read-only tool with a clear schema and a readOnlyHint, the description provides all necessary context: what it does and what it returns. No output schema is needed because the description already enumerates the returned fields, and no additional prerequisites or side effects are relevant.

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 documents the single 'id' parameter with a description ('Collection ID (UUID)'), achieving 100% coverage. The description adds no further parameter syntax or format details, only restating that the tool gets by ID, which matches the baseline 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 the action ('Get') and the resource ('a single collection by its ID'), making it unambiguous. It also lists the fields returned (title, slug, status, type, SEO fields), which distinguishes it from sibling tools like list_collections or create_collection.

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: use this when you need a specific collection by ID. However, it does not explicitly mention when to use an alternative like list_collections for multiple collections or get_category for categories, leaving the guidance 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?

The annotation readOnlyHint=true already indicates a safe read operation. The description adds context by specifying that the user is the one who owns the API token, clarifying the relationship between the token and the returned user. No contradiction with annotations.

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

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

The first sentence is concise and informative. The second sentence, 'Operation: GetCurrentUser,' is redundant since it repeats the tool name/operation. While not harmful, it adds little value. Overall the description is short 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 zero-parameter read-only tool with no output schema, the description sufficiently covers the tool's function. It could mention the fields returned, but for a simple user object this is often implied. The description is adequate given the tool's simplicity.

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

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

The tool has zero parameters, and the schema is empty with 100% coverage. There is nothing for the description to explain about parameters. The baseline of 4 for 0 params applies, and the description appropriately says nothing.

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: 'Get the user that owns the API token.' This is a specific verb (get) and resource (user determined by token ownership), which distinguishes it from other get_* tools like get_customer or get_product. The tool's name and title reinforce its meaning.

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

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

The description implies usage context: use this tool to retrieve the authenticated user's information. It does not explicitly mention alternatives or situations to avoid, but because it targets the current user only, there is little ambiguity. The unique scope makes it clear that this is the tool for the current user.

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 readOnlyHint annotation already signals a safe read operation, and the description adds only the 'single' and 'by ID' scoping. It does not disclose not-found behavior, response shape, or redaction effects beyond what the parameter schema already says. No contradiction with annotations.

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

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

The description is a single, front-loaded sentence with zero filler. It conveys the essential purpose immediately and wastes no 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 schema fully documents parameters and the readOnlyHint covers safety, but there is no output schema and the description does not describe return fields or error behavior. It also does not point to sibling tools for related lookups. Adequate for a simple getter, but with noticeable gaps.

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

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

Schema coverage is 100%, and both parameters have clear descriptions in the schema, especially the redact parameter. The tool description itself adds no parameter-level meaning, so the baseline 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 states a specific verb ('Get'), a clear resource ('customer'), and the qualifier 'single customer by their ID', which distinguishes it from list_customers (plural) and get_current_user (current user). This is unambiguous and easy for an agent to act on.

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

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

The description implies the tool should be used when a single customer's ID is known, but it does not explicitly name alternatives such as list_customers or get_current_user, nor does it state when not to use this tool. Usage is inferable rather than explicitly guided.

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

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

Beyond the readOnlyHint annotation, it discloses pagination behavior and the critical coverage-envelope semantics, explicitly forbidding the agent to claim completeness when coverage is partial. This is exactly the kind of non-obvious behavior an agent needs.

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 dense, well-structured sentence with the main action first and the critical coverage caveat second. No filler or repetition of schema fields.

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 no output schema, the description names the return envelope fields and gives the behavioral rule for partial coverage. For a read-only paginated listing with fully documented parameters, nothing essential to calling or interpreting the result 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 the schema already documents id, page, and per_page fully. The description adds only the generic 'paginated' context, which meets but does not exceed the baseline for fully documented parameters.

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

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

States a specific action (list) and resource (order IDs for a customer by customer ID), with pagination noted. This clearly separates it from siblings such as get_order (one order) and list_orders (all orders).

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?

Clear intended context: retrieve a customer's order IDs, paginated. It does not explicitly name alternatives or say when not to use it, so it misses the top bar for explicit routing, but the 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?

The readOnlyHint annotation already indicates a safe read operation. The description adds useful context about the returned fields (title, value, dates, status, binding mode), going beyond the annotation without contradicting it.

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

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

The description is a single, front-loaded sentence that conveys the tool's purpose and scope without any filler. Every word earns its place.

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

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

For a simple get-by-ID tool with one required parameter, read-only annotation, and no output schema, the description is complete. It states what the tool retrieves and what fields are returned, which is sufficient.

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

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

The schema provides 100% coverage for the single parameter 'id' with a clear description (Discount ID UUID). The tool description adds no additional semantic meaning, so the baseline of 3 is appropriate.

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

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

The description clearly states a specific verb and resource: 'Get a single discount by its ID.' It also lists the returned fields (title, value, dates, status, binding mode), distinguishing it from list_discounts which retrieves multiple discounts.

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

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

The description implies the use case: when you need a single discount by ID, not a list. It does not explicitly name alternatives or exclusions, but the context is sufficiently clear given the sibling tools.

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

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

Annotations declare readOnlyHint=true, and the description's 'Get metadata' is consistent with a read operation. The description adds value by specifying the return fields (name, size, URL), which is useful since there is no output schema. No extra behavioral details like auth or errors are disclosed, but the read-only nature is already covered.

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 immediately states the action, target, and output. It is front-loaded, contains no redundant wording, and every word contributes meaning.

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

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

For a simple single-parameter read operation with annotations covering safety, the description is complete. It states the input (ID), the target (previously uploaded file), and the output fields (name, size, URL). No output schema exists, but the description provides the necessary return information. Complexities like error handling are not essential for this simple tool.

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

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

The input schema already provides full coverage for the single parameter 'id' with description 'File ID (UUID)'. The description adds only the context that the file was 'previously uploaded', which is mildly helpful but not essential. Baseline 3 applies because schema does the heavy lifting.

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

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

The description uses the specific verb 'Get' with the resource 'file' and clearly states the output is metadata (name, size, URL) identified by ID. This is distinct from sibling tools like get_video or get_order, so there is no ambiguity about its 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 clearly states it is for 'previously uploaded file', implying use after upload_file. It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to select this tool when needing file metadata.

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 the description aligns with a safe read operation. It adds useful context about the response contents (status, balance, purchase info) but does not disclose potential error behavior or note that redact only affects the response—though the latter is documented in the schema.

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

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

A single, front-loaded sentence states the action, target, and key response fields with zero wasted words. It is immediately scannable and efficient.

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

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

For a simple read-only single-resource retrieval tool with fully documented parameters and a readOnlyHint annotation, the description covers the essential behavior. It communicates the return payload shape well enough; only explicit guidance about when to prefer list_gift_cards is missing, which is a minor 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 coverage is 100%, so both parameters are already well documented. The description adds no extra meaning beyond restating that the card is fetched 'by its ID' and mentioning redaction indirectly via personal data, so it does not elevate 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?

The description uses a specific verb ('Get') and resource ('a single gift card by its ID'), and enumerates what is returned (status, balance, purchase info). This clearly differentiates it from sibling list_gift_cards and other get_* tools without requiring schema inspection.

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

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

The description implies usage: call this when you have a gift card ID and need one specific card's details, versus listing all gift cards. However, it does not explicitly mention list_gift_cards or state when not to use this tool, leaving the comparison 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?

Despite the readOnlyHint annotation already indicating a safe read, the description goes further by detailing the complete return payload: HTTP method, path, parameters, content type, pagination info, and dereferenced schemas. It also clarifies the operational purpose ('to learn the exact body shape'), which adds value beyond the annotation.

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

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

Two sentences, no redundancy. The first sentence enumerates the return contents, the second gives usage instruction. Every word earns its place.

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

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

For a single-parameter tool with no output schema, the description is fully self-sufficient: it explains what the tool returns and when to call it. The absence of an output schema is compensated by explicitly listing the metadata components returned.

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 the single parameter operation_id is thorough, including format (PascalCase), an example, and a pointer to search_operations. The description itself does not add parameter-specific detail beyond this; it only contextualizes the parameter's use. Since schema coverage is 100%, a baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Get full metadata for one KIT API operation by operationId.' It lists exactly what is returned (HTTP method, path, parameters, schemas) and explicitly distinguishes itself from siblings by instructing to call it before kit_request or create/update tools.

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

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

The second sentence provides explicit usage guidance: 'Call this before kit_request or any create/update tool to learn the exact body shape.' This names the exact context and tools it pairs with, making it clear when to use this tool instead of guessing.

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 readOnlyHint annotation already covers the read-only nature. The description adds useful context about what the response contains (line items, delivery chunks, payment, status), but it does not describe error behavior, redaction effects, or other response details. This matches the baseline for a description that adds some value beyond annotations but leaves behavioral 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?

One focused sentence that leads with the action and resource, then lists the key response contents. Every part is informative and there is no filler or redundancy.

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

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

For a simple read-only get-by-ID tool with two well-documented parameters and no output schema, the description adequately covers what the agent needs: what it retrieves and what the response includes. The parameter schema covers the redaction option, and annotations cover safety. Nothing critical 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%, and the schema already provides detailed descriptions for both parameters, including the redact behavior. The description merely reinforces 'by its ID' without adding new parameter-level meaning, so the baseline of 3 applies.

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

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

The description states a specific verb ('Get'), a single resource ('a single order'), and the identifier needed ('by its ID'). It distinguishes itself from plural list tools like list_orders and from related order tools like get_order_payment_link or get_order_addons.

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 makes the usage context clear: use this when you need one specific order by ID. It does not explicitly name alternatives or exclusion criteria, but the singular framing and the resource scope are enough for an agent to infer when this tool 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?

The readOnlyHint annotation already declares the operation is read-only; the description adds the scoping detail of filtering by order ID, but does not describe return format, error behavior, or any side effects. Consistent with annotations, but not adding extensive 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?

A single, front-loaded sentence that conveys the tool's purpose without extra words. Every element is necessary.

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

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

For a simple read-only list tool with one parameter, the description covers the input and the general output (addons). However, it lacks detail on the shape of the returned addons or edge cases like missing orders, but given the tool's simplicity, it is mostly complete.

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

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

The input schema provides 100% coverage for the single 'id' parameter with a clear description. The description's mention of 'by the order ID' reinforces but does not add new semantics beyond the schema.

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

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

The description uses the specific verb 'List' and clearly identifies the resource as additional services (addons) attached to an order, scoped by order ID. This distinguishes it from sibling tools like get_order and list_orders.

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

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

The description implies the use case (retrieve addons for a specific order) but does not explicitly mention alternatives or exclusions. However, the context is clear enough to infer when 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?

Adds substantial behavioral detail beyond the readOnlyHint annotation: the link is permanent, identical across calls, valid in any order status, never expires, and cannot be revoked even if the API token is revoked. This is exactly the kind of non-obvious behavior an agent needs 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?

Front-loaded with the primary purpose and includes high-value warnings about permanence and non-revocability. The trailing 'Operation: GetOrderPaymentLink.' line is redundant with the tool name, preventing a perfect score.

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

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

The tool is simple, has only two parameters, and the description provides enough context to invoke it correctly. Since there is no output schema, the description makes clear the result is a signed payment link, though it does not spell out the exact response shape.

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 fully documents both id and source parameters. The description itself adds little parameter-level meaning beyond identifying the order context, matching the baseline 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?

States a specific verb and resource: 'Get the signed payment-page link for an order'. It clearly conveys what the tool does and distinguishes it from sibling tools like get_order because it returns a buyer-facing payment link, not order data.

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

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

The description explains the intended use case: 'to be sent to the buyer — they can pay without logging in'. It gives clear contextual guidance even though it does not explicitly name alternative tools or when-not-to-use 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, so the read-only nature is covered. The description adds the useful detail about category bindings but does not disclose other behavioral aspects such as not-found handling or the exact response structure.

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

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

The description is a single, concise sentence that front-loads the primary purpose and includes one meaningful extra detail. No wasted 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 single-get tool with one required parameter, a readOnlyHint annotation, and no output schema, the description is largely sufficient. It conveys the core action and a key return enrichment, though it could mention error behavior or return format for full completeness.

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

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

The input schema fully documents the single 'id' parameter as a Product ID (UUID), leaving no ambiguity. The description adds no additional parameter context, so the baseline of 3 applies.

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

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

The description clearly specifies the verb 'Get' with a specific resource ('a single product by its ID') and adds a distinguishing detail ('including its category bindings') that sets it apart from sibling tools like list_products or get_variant.

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 fetching one product by ID. It does not explicitly mention when to use an alternative (e.g., list_products for multiple products), but the 'single product by ID' phrasing provides sufficient situational clarity.

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 readOnlyHint annotation already signals a safe read operation. The description adds value by listing the fields included in the response, but it does not disclose other behavioral aspects such as error handling or pagination. Since the annotation covers the safety profile, a score of 3 is appropriate.

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

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

The description is a single, front-loaded sentence with no superfluous content. Every word contributes to conveying the tool's action, scope, and included data.

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 single-item fetch tool with one well-documented parameter and a read-only annotation, the description is complete. It lists the returned fields, compensating for the absence of an output schema, and no additional context is needed.

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 fully documents the single 'id' parameter (UUID) with 100% coverage. The description does not add additional parameter-specific details, so it meets the baseline for schema-covered parameters without enhancing them further.

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 ('Get') and resource ('single promocode') with a clear scope ('by its ID'), which distinguishes it from list-oriented sibling tools like list_promocodes. It also enumerates the fields returned, providing exact 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 clearly indicates this tool fetches one promocode by ID, which is the appropriate use case when a specific promocode is needed. It does not explicitly mention alternatives (e.g., list_promocodes for all promocodes), so it lacks explicit exclusionary guidance.

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

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

The readOnlyHint annotation already indicates a safe read operation. The description adds meaningful context beyond that by explaining the hierarchy (id, name, parent region id), which helps the agent understand the data structure. It does not contradict the annotation.

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

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

The description is concise and front-loaded, with the primary purpose stated in the first sentence. The hierarchy details are useful. The trailing 'Operation: GetRegions' is redundant and adds little value, slightly detracting from conciseness.

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

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

With no output schema, the description partially explains the return shape (hierarchical regions with id, name, parent id). It could be more explicit about whether the list includes all levels or how parent relationships are represented, but for a simple read-only list tool it provides 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 tool has zero parameters, so the baseline of 4 applies. The description does not need to explain parameter semantics, and the schema fully covers the empty parameter list. No additional parameter information is required.

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 a list of geographic regions, specifying the resource type (countries, regions, cities) and the hierarchical structure. This is a specific verb+resource definition that distinguishes it from other get/list tools like get_product or list_categories.

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

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

No explicit when-to-use or alternatives are mentioned, but the name and description imply it is the tool for fetching geographic regions. There is no competing regions tool among siblings, so the intended usage is easily inferred, but explicit guidance is absent.

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 readOnlyHint annotation already indicates this is a safe read operation. The description adds the specific data returned (id, slug, b2c_url) and an internal operation name 'GetStore', but does not disclose additional behavioral traits such as authentication requirements, potential errors, or data freshness. The added information is modest and not a contradiction.

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 at two short sentences. The first sentence conveys the purpose and scope, while the second provides a useful API operation identifier. There is no redundant or filler content, making it an efficient and well-structured description.

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

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

For a tool with no parameters and no output schema, the description is complete. It clearly states what information is returned and the scope ('current store'). The sibling context shows this is the only store-related tool, so there is no ambiguity or need for additional caveats. All necessary context is present.

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

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

The tool has zero parameters, and the rubric establishes a baseline of 4 for such cases. The description does not need to explain parameters, and it does not attempt to add irrelevant parameter info. The mention of return fields helps somewhat, though it is not parameter-related.

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

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

The description clearly states the tool's function: 'Get information about the current store (id, slug, b2c_url).' The verb 'Get' plus the resource 'store' and the specific fields returned make the purpose unambiguous. Although there are no directly competing store tools in the sibling list, it effectively distinguishes itself from other getters by its scope.

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 by stating 'current store', which is clear context for when to call it. There are no alternative store-related tools in the sibling list, so no explicit exclusions are needed. It does not explicitly say 'use this when you need store identity', but the context is sufficiently 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?

Beyond the readOnlyHint annotation, the description discloses a non-obvious behavioral property: feed URLs remain stable across content updates, enabling one-time fetching and scheduled downloads. It does not describe the exact response structure, but for a read-only zero-parameter tool this is a minor 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 compact and front-loaded, with the core purpose in the first sentence and the useful stability behavior in the second. The trailing 'Operation: GetStoreFeeds' line is mildly redundant with the tool name, but it does not detract much.

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

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

For a zero-parameter, read-only tool, the description is complete: it names the resource, lists the feed formats, and explains the key behavior an agent needs to schedule downloads. No output schema exists, but the return value is sufficiently implied by 'permanent links'.

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

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

The tool has zero parameters, so the baseline of 4 applies. There is no parameter ambiguity and the description correctly focuses on the output rather than inputs.

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

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

The description uses a specific verb ('Get') and a precise resource ('permanent links to the store's catalog feeds'), and enumerates the three feed types (ICML, YML, YML_GOODS). This clearly differentiates it from other get_* sibling tools such as get_store or get_warehouse.

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

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

The description provides clear usage context: fetch the feed URL once and reuse it on a schedule because the URL never changes. It does not explicitly name alternatives or exclusions, but no sibling feed tool exists, so this is sufficient.

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

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

The readOnlyHint annotation already indicates a safe read operation. The description adds value by specifying the exact data returned (name, SKU, pricing, stocks, media, status), giving the agent a concrete expectation of the response content.

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

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

The description is a single, front-loaded sentence that conveys the action, target, and scope without extraneous words. Every element earns its place.

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

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

For a simple single-entity read tool with one fully described parameter and a readOnlyHint, the description is complete. It states exactly what is fetched and includes the key data fields, making it sufficient 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?

The schema fully documents the id parameter as 'Variant ID (UUID)' with 100% coverage. The description only restates 'by its ID' without adding new semantic detail, so it meets the baseline but does not elevate it.

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

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

The description clearly states the tool gets a single variant by ID, listing the included fields (name, SKU, pricing, stocks, media, status). This distinguishes it from list_variants (list) and create_variant/update_variant (mutations).

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 fetching one specific variant when its ID is known. It provides clear context but does not explicitly name alternatives or exclusions, such as 'use list_variants to search without an ID.'

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

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

Beyond the readOnlyHint annotation, the description reveals the status lifecycle (UPLOADED -> PROCESSING -> READY/ERROR), explains when the content field is populated, mentions error details, and notes that processing time scales with video length. This is rich behavioral context that helps set expectations.

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

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

The description is three sentences, with the primary purpose front-loaded. Each sentence adds distinct value: the core action, the polling use case, and a rate-limit warning. No redundant or filler content.

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

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

Despite having no output schema, the description covers the essential response behavior: status transitions, the content field condition, error details, and polling cadence. For a simple get-by-id tool with one parameter and rich annotations, this is complete and self-sufficient.

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

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

The input schema already documents video_id thoroughly, including its source and opaque nature, with 100% parameter coverage. The description text adds no additional parameter-specific meaning, so the 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 a single video by ID and reports its current processing status. It distinguishes itself from list_videos by focusing on a single resource and explicitly links to upload_video for polling, making the purpose specific and unambiguous.

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

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

It explicitly says to use this tool after upload_video to poll, describes the status flow, and provides a concrete polling constraint ('at most once every 5 seconds'). This gives clear when-to-use guidance and implies when not to use it (for listing multiple videos, covered by list_videos).

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 readOnlyHint annotation already indicates this is a safe read operation. The description adds the return fields (title, slug, status), which is useful context. It does not disclose error behaviors (e.g., 404 if not found) or any filters, but the annotation lowers the bar; this meets the minimum viable level.

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 with front-loaded verb and resource. It includes essential context (return fields) without any waste.

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

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

For a simple single-parameter read operation with a readOnly annotation and no output schema, the description is sufficient. It mentions the return fields, which is enough for typical use. It doesn't explain error handling, but that's not critical for a basic getter.

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

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

The input schema already provides complete coverage of the only parameter ('Warehouse ID (UUID)'), so the description adds no extra semantic value. Baseline of 3 is appropriate because the schema does the heavy lifting.

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

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

The description clearly states the tool's function: 'Get a single warehouse by its ID' and lists the specific fields returned (title, slug, status). This distinguishes it from sibling tools like list_warehouses (which retrieves all warehouses) and update_warehouse/create_warehouse (which mutate).

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

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

The description implies the use case: when you have a warehouse ID and need a single warehouse's details. It contrasts with list_warehouses by specifying 'a single warehouse'. However, it does not explicitly mention alternatives or when not to use this tool, so it falls short of full explicit guidance.

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

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

The annotations already mark readOnlyHint=true, and the description adds the specific returned fields (URL, subscribed events, status), which helps the agent understand the response. No contradictory information is present.

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

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

One compact sentence, front-loaded with the verb and object, no filler. Every word earns its place.

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

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

For a simple get-by-ID operation with one parameter and a read-only annotation, the description sufficiently covers purpose, input, and the key output fields. Since there is no output schema, mentioning the return fields is especially valuable.

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 documents the single 'id' parameter as a UUID string, and the description only repeats 'by its ID' without adding format or usage details beyond the schema. Baseline 3 is appropriate given 100% 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 the action ('Get'), the resource ('a single webhook'), and the identifying parameter ('by its ID'). It also distinguishes itself from sibling tools like list_webhooks or create_webhook by specifying a single webhook 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?

The description implies usage: when you have a webhook ID and need its details. However, it does not explicitly mention alternatives like list_webhooks for multiple webhooks or validate/update/delete for other operations, so guidance is only implicit, not explicit.

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

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

With no annotations provided, the description carries the full burden and does substantial work: it warns that calls are 'REAL calls against the live store,' that write operations 'take effect immediately,' and that 'there is no sandbox.' It also discloses the validation behavior and the ability to skip it with validate=false, which is important risk-relevant 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 compact and front-loaded: purpose first, then the critical warning, then the workflow, then validation details. Every sentence adds essential information without 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?

For a generic escape-hatch tool with no output schema and no annotations, the description covers the essential ground: what it does, how to use it safely, how to discover operation details, and how validation works. It could briefly mention that the response shape varies by operation and is documented via get_operation_schema, but the existing guidance is already strong for a tool of this 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?

The input schema already covers 100% of the parameters with descriptions, so the baseline is 3. The description adds some workflow context, telling the agent to get body shape from get_operation_schema and that validation can be disabled, but it mostly reinforces rather than extends the schema's parameter documentation.

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

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

The description states a specific verb ('executes') and a clear resource ('ANY of the 166 Yandex KIT API operations by operationId'), immediately positioning it as a generic escape hatch. It also distinguishes itself from the many dedicated sibling tools by noting it covers 'operations without a dedicated tool.'

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

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

It gives an explicit workflow ('search_operations -> get_operation_schema -> kit_request'), which tells the agent how to discover and construct a call. It identifies when this tool is the right choice ('including operations without a dedicated tool'), though it does not explicitly say to prefer dedicated sibling tools when one exists.

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 readOnlyHint annotation already signals safety, and the description adds substantial behavioral context beyond it: CRITICAL-first ordering, newest-first within severity, pagination semantics, and the machine-readable coverage envelope. The explicit instruction that partial coverage must be reflected in the user-facing answer is especially valuable.

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 dense sentences, each adding necessary information: listing behavior and ordering, API filter default, and response coverage semantics. There is no filler, and the most identifying information is front-loaded.

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

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

For a read-only list operation with no output schema, the description covers the essential invocation and interpretation details: pagination, ordering, default filtering, and the coverage envelope with a normative rule for partial results. The parameter schema fills in the remaining input details, so no critical information is missing.

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

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

Schema description coverage is 100%, so the parameters themselves are already fully documented. The description mostly restates or reinforces what the schema already says, such as the ACTIVE default, without adding new parameter-level 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 opens with a specific verb and resource — "List system alerts of the store" — and adds precise behavioral detail: pagination, severity ordering, and newest-first ordering within severity. This makes the tool clearly distinguishable from mutation siblings like resolve_alert and from other list_* tools.

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

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

The description gives clear context on how the listing behaves: it is paginated, sorted, defaults its status filter to ACTIVE, and can return partial coverage. It does not explicitly name an alternative for changing or resolving alerts, so the guidance is clear but not exhaustive.

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

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

Beyond the readOnlyHint annotation, the description discloses two important behaviors: results are paginated, and the response includes a machine-readable coverage envelope with specific fields. It also imposes a clear output obligation when coverage is 'partial', which is high-value context an agent needs to avoid misleading users.

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: a one-sentence purpose statement followed by one sentence on the critical coverage contract. No filler or repetition of schema 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?

With no output schema, the description compensates by specifying the coverage envelope fields and the required handling of partial coverage. It stops short of describing the item shape or defaults like JSON output, but those are either schema-covered or not required to invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema fully documents all five optional parameters. The description adds the pagination context but no extra parameter-level details, which aligns with the baseline of 3.

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

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

The description opens with a specific verb and resource: 'List store news articles,' clarifying that the tool enumerates blog/news items rather than acting on a single one. This separates it from siblings like get_blog, create_blog, and update_blog, even without naming them.

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

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

The description implies the tool should be used whenever store news articles need to be listed, but it does not explicitly state when to prefer it over alternatives or mention any exclusions. There is no explicit guidance such as 'for a single article, use get_blog', so usage context is implied rather than stated.

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

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

Beyond the readOnlyHint annotation, the description discloses a critical behavioral trait: the coverage envelope and the mandatory rule that partial coverage must be reflected in user-facing answers. This is exactly the kind of non-obvious behavior an agent needs to avoid misleading users.

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 with no filler: purpose is front-loaded, then the status requirement, then the critical coverage caveat. Every sentence adds distinct value and the most important warning is placed at the end where it can be emphasized.

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 list operation with 100% schema coverage and a readOnly annotation, the description is nearly complete: it covers pagination, status default, and the partial-coverage rule. It does not describe the category item fields in the response, but that is not necessary for a simple listing operation and no output schema is expected.

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

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

The input schema already covers all 6 parameters, so the description does not need to re-explain them. It does add the status-filter requirement and the coverage envelope context, but these are more response/usage details than parameter semantics. The schema carries the parameter burden, 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 clearly identifies the operation as listing product categories, with pagination explicitly stated. This distinguishes it from sibling tools like get_category (single category) and category_action (mutation), even without naming them.

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

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

The description gives clear context: it lists categories, is paginated, and requires a status filter with a sensible default. It does not explicitly state when to use this tool over get_category or category_action, but the listing vs singular/mutation distinction is strongly implied by the wording.

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 tool readOnlyHint=true, and the description adds valuable behavioral detail beyond that: pagination, keying by characteristic value rather than ID, the coverage envelope fields, and a mandatory user-facing handling rule for partial coverage. This is strong, non-obvious behavioral disclosure.

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

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

Three dense sentences with no filler. The core purpose is front-loaded, followed by keying semantics and the critical coverage-handling rule. Every sentence contributes essential operational context.

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

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

For a read-only paginated listing tool with no output schema, the description covers the important response semantics: item identity, color values, hex codes, pagination, and the coverage envelope. Combined with the fully documented input schema, an agent has enough to call the tool and interpret results correctly.

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

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

Schema description coverage is 100%, so the input schema fully documents all six parameters. The description adds context about pagination and the coverage envelope but does not need to restate parameter semantics; the baseline of 3 applies.

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

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

The description clearly states the verb ('List'), the resource ('color values of the store's characteristics'), and key output detail ('hex codes'). It does not explicitly differentiate from the sibling list_characteristics, though the color-specific focus and keying note make the scope reasonably clear.

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

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

No guidance is given on when to use this tool instead of alternatives such as list_characteristics. The usage context is implied by the tool's name and resource, but there are no explicit conditions, exclusions, or alternative routing.

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

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

Beyond the readOnlyHint annotation, the description discloses a critical non-obvious behavior: the response's coverage envelope can be 'partial', and the agent MUST reflect this in user-facing answers and cannot claim the listing is complete. This is valuable transparency that prevents a misleading response.

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, purpose first, then the critical coverage caveat. Every sentence earns its place, and the most important operational constraint is stated explicitly without fluff.

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 paginated list tool with no output schema and readOnlyHint annotation, the description covers the only non-obvious contract an agent must honor: handling partial coverage. Parameter details are fully in the schema, and sibling differentiation is clear enough from the resource name. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema fully documents all parameters. The description adds high-level pagination context but does not explain individual parameters like all, page, per_page, fields, or format. Baseline 3 is appropriate since the schema carries the parameter semantics burden.

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 ('List') and resource ('product characteristic groups'), and adds the key scope qualifier 'paginated'. This clearly differentiates it from sibling tools like list_characteristics (different resource) and get_characteristic_group (single item).

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 this is the tool for retrieving a paginated list of characteristic groups, but it never explicitly names alternatives or states when not to use it. There are no exclusions or prerequisites, only implied usage 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?

Beyond readOnlyHint, it discloses pagination, the machine-readable coverage envelope fields, and the mandatory user-facing handling of partial coverage; this is non-obvious behavior an agent would otherwise miss.

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 first names the operation, the second gives the most important response constraint; every word earns its place.

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

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

With no output schema, the prose covers the coverage envelope well, but it never names the field that actually holds the characteristic items, leaving response extraction slightly under-specified.

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

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

The input schema already documents all five parameters at 100% coverage; the prose adds no parameter-level semantics, 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?

States a specific action and resource ('List product characteristics') and immediately flags pagination; it is clearly distinct from get_characteristic and the characteristic group/color listers.

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 list-vs-get naming and 'paginated' qualifier imply bulk listing, but the prose does not explicitly direct the agent away from get_characteristic or state when the list variant is preferred.

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

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

Beyond the readOnlyHint annotation, the description discloses important behavior: the response includes a coverage envelope, and coverage:"partial" MUST be reflected in user-facing answers, forbidding claims of completeness. This is a critical behavioral constraint an agent would not know from annotations or schema alone.

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

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

The description is three sentences with no filler. It front-loads the core purpose, adds a concise definition of collections, and ends with an essential operational warning about partial coverage. Every sentence earns its place.

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

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

With no output schema, the description helpfully explains the coverage envelope and the partial-coverage rule. It could go slightly further by indicating what fields collection items contain or explicitly directing to get_collection for a single collection, but the current level is sufficient for a filtered-list tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-level meaning beyond the schema, though it does set the general pagination context that relates to page, per_page, and all.

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

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

The description uses a specific verb and resource: 'List collections of the store (paginated).' It goes beyond the name by explaining what a collection is and distinguishing STATIC vs DYNAMIC collections, making it clearly distinct from sibling tools like get_collection, create_collection, and manage_collection_cards.

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 makes the listing scope clear and provides context about pagination and coverage, but it does not explicitly name alternatives such as get_collection for retrieving a single collection. The usage is implied rather than explicitly contrasted with sibling tools.

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

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

Beyond the readOnlyHint annotation, the description discloses important response behavior: the coverage envelope fields and the strict requirement that coverage:'partial' must be reflected in user-facing answers and forbids claiming completeness. This is exactly the kind of non-obvious behavioral context an agent needs.

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 with no filler. The core function is stated first, then the critical coverage semantic is front-loaded. Every word earns its place.

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

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

For a read-only list operation with fully documented parameters and a readOnlyHint annotation, the description covers the essential behavioral contract. The coverage envelope warning is the key missing piece from schema/annotations and it is included. No output schema exists, but the description provides enough return-shape context to guide correct use.

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%, with each parameter already well documented in the schema. The tool description adds no new parameter-level meaning, so the baseline 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?

Description uses a specific verb and resource ('List customers of the store') and adds the pagination qualifier, clearly distinguishing this from single-customer tools like get_customer and from other list_* siblings. It directly states what the tool does without ambiguity.

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

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

The description makes it clear this is a paginated listing operation and the coverage-envelope note tells the agent how to handle partial results. It does not explicitly name alternatives or exclusion conditions, but the context is clear enough for selecting this tool over get_customer or other list_* siblings.

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 readOnlyHint=true already declaring the safety profile, the description adds a meaningful non-obvious behavior: the response includes a machine-readable coverage envelope, and coverage:'partial' must be reflected in the user-facing answer and forbids claiming completeness. This is valuable caveat-based transparency beyond the annotation and 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?

Three short sentences with no filler: first sentence states purpose, second states the critical requirement, third explains the coverage caveat. The most decision-relevant information is front-loaded.

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

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

There is no output schema, so the description compensates by documenting the key return-value nuance: the coverage envelope and the obligation to expose partial coverage. Parameter semantics are fully covered by the schema. A minor gap is that no item-level return shape is described, but the coverage behavior is the more important missing piece and is handled 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 100%, so all six parameters already carry definitions. The description only reinforces that status is required without adding syntax, defaults, or enum semantics beyond what the schema provides, so the baseline 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 states a specific verb ('List'), resource ('discounts'), and scope ('of the store'), with two key modifiers: filtered by status and paginated. This clearly marks it as the plural listing endpoint and distinguishes it from get_discount, create_discount, and other discount actions without ambiguity.

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

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

The description gives useful invocation context: it is a status-filtered listing, the status parameter is required, and pagination is available. However, it does not explicitly name alternatives such as get_discount for retrieving a single discount, nor does it state when this tool should not be used in favor of a sibling.

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

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

The description adds meaningful behavioral context beyond the readOnlyHint annotation, especially the coverage envelope semantics and the mandatory requirement to reflect coverage:'partial' in user-facing answers. It also warns against claiming a complete listing when coverage is partial. This is valuable operational guidance that annotations do not provide.

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

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

The description is compact and well-structured. The first sentence establishes core purpose, the second defines scope and alternative tools, and the third conveys critical response semantics. Every sentence earns its place with no redundant filler.

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

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

Given there is no output schema, the description compensates by explaining the coverage envelope and URL output. It clearly handles scope exclusions and pagination context. Minor gaps remain, such as default sorting or exact response item fields, but the essential operational details are covered.

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 input schema already fully documents all parameters. The description adds context about pagination and the coverage envelope but does not describe individual parameter semantics beyond what the schema provides. Baseline 3 is appropriate.

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

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

States a specific verb ('List'), a clear resource ('the store's uploaded files'), and an explicit output aspect ('with their URLs'). It differentiates itself from video-related tools by naming get_video/list_videos as the alternative, making the tool's scope immediately distinguishable.

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

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

Explicitly states the tool covers only IMAGE and OTHER files and that videos live in a separate scenario, directing the agent to use get_video/list_videos instead. The pagination options are also clarified by mentioning pagination and auto-pagination context, leaving little ambiguity about when to use 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?

Beyond the readOnlyHint annotation, the description discloses a critical operational behavior: the response carries a coverage envelope and 'coverage:"partial"' MUST be reflected in the user-facing answer, forbidding claims of completeness. This is substantive behavioral context not available from 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?

Two tight sentences: the first front-loads the core purpose, the second adds the essential coverage-envelope caveat. No filler or redundancy.

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

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

With 0 required parameters, full schema coverage, and a readOnlyHint annotation, the description covers the tool's distinctive behavior (coverage envelope) and core usage. The lack of an output schema is partially mitigated by describing the envelope, though item-level fields are left to the fields parameter/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%, so every parameter (all, page, per_page, status, dates, format, redact, fields) is already documented in the input schema. The description only summarizes pagination and filters without adding parameter-level 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 action ('List'), a specific resource ('gift cards of the store'), and key scoping details ('paginated', optional status and purchase-date filters). This clearly distinguishes it from singular tools like get_gift_card and from other list_* tools.

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

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

The description provides clear context for when to use this tool: listing gift cards with pagination and optional filters. It does not explicitly name alternatives or state when not to use it, but the purpose is specific enough to guide selection among the siblings.

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 tool as read-only, and the description adds valuable behavioral context: the coverage envelope (coverage, received, total_count, pages_read) and the mandatory rule that partial coverage must be reflected in user-facing answers. It also discloses the newest-first ordering.

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 dense sentence with no filler. It front-loads the core purpose and then adds the critical partial-coverage constraint, which is exactly the behavioral detail an agent must not miss.

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?

Since there is no output schema, the description appropriately explains the response coverage envelope and warns about partial results. Combined with the detailed parameter schema, the agent has enough information to call the tool correctly; only minor details like default pagination size are left to the 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%, and each parameter already has a detailed description in the schema. The tool description does not add extra parameter-level meaning, but it does not need to because the schema is thorough.

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?

Description uses a specific verb and resource: 'List orders of the store' with clear scope ('of the store'), plus ordering ('newest first') and pagination. This distinguishes it from single-order tools like get_order and customer-scoped tools like get_customer_orders.

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 clearly implies this is the paginated listing endpoint for store orders, but it does not explicitly state when to prefer it over alternatives such as get_order or get_customer_orders. No exclusions or alternative routing are given.

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

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

Goes well beyond the readOnlyHint annotation by disclosing the coverage envelope (coverage, received, total_count, pages_read), the mandatory rule that coverage:'partial' must be reflected in the user-facing answer and forbids claiming completeness, and the CSV behavior of defaulting to top-level scalar fields only (id and group_id) without flattening variant data. These are non-obvious behavioral constraints that materially affect agent output.

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

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

Four sentences with zero filler; the core purpose and routing guidance are front-loaded in the first two sentences, and the remaining two add only high-value behavioral details. Each sentence earns its place and the key disambiguation from list_variants is placed early.

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 present, the description compensates by documenting the response envelope fields and the partial-coverage contract, and it names the concrete CSV default fields (id and group_id). It stops short of fully describing the JSON item shape or pagination semantics, but for a straightforward list tool whose parameters are fully documented in the schema, the coverage is strong.

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

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

Schema description coverage is 100%, so the baseline is 3; the description adds genuine value on top by specifying that format:'csv' defaults to id and group_id specifically, does not flatten variant data, and by tying the coverage envelope to pagination behavior. The schema already covers the mechanics of each parameter, so the description's contribution is additive but modest.

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

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

Opens with a specific verb plus resource ('List product records (paginated)') and then differentiates from the sibling list_variants by articulating the data-model difference: a product carries grouping and category data, not a sellable name, SKU, price or stock. This makes the tool's scope unambiguous and separates it from its closest sibling.

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

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

Explicitly states when to use it ('explicit raw product-group or catalog-structure dumps') and names the alternative for the other case ('Ordinary catalog exports use list_variants'). No inference is required — the selection condition and the rejected alternative are both spelled out.

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