A1 Yandex KIT MCP
Server Quality Checklist
Latest release: v1.5.0
- Disambiguation4/5
Tool purposes are overwhelmingly distinct: each entity has clear list/get/create/update/archive/action wrappers, and the resource name disambiguates most tools. The main ambiguity is that `kit_request` is a generic escape hatch overlapping with every dedicated tool, and a few pairs like `bulk_update_prices` vs `update_variant` require careful reading; the detailed descriptions usually resolve this.
Naming Consistency4/5The set mostly follows a predictable `verb_noun` pattern: list_products, get_product, create_category, update_discount, delete_webhook. Minor deviations like the generic `kit_request` and the `*_action` archive/unarchive naming keep it from being perfectly consistent, but it is still highly readable and predictable.
Tool Count1/584 tools is far beyond the 25+ threshold and lands in the extreme over-many range. A huge part of the surface duplicates what search_operations, get_operation_schema, and kit_request already provide, making the toolset unnecessarily hard to scan and navigate.
Completeness5/5Coverage is effectively complete for the store-management domain: products, variants, categories, orders, customers, discounts, promocodes, warehouses, collections, webhooks, characteristics, videos, files, blogs, and alerts all have lifecycle tools. Any remaining API operation can still be reached through search_operations -> get_operation_schema -> kit_request, so there is no dead end.
Average 4.1/5 across 84 of 84 tools scored. Lowest: 3.1/5.
See the Tool Scores section below for per-tool breakdowns.
- 1 of 1 community issues answered or closed in the last 6 months
- 212 commits in the last 12 weeks
- Last stable release on
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
This repository includes a glama.json configuration file.
This server has been verified by its author.
Add related servers to improve discoverability.
How to sync the server with GitHub?
Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.
To manually sync the server, click the "Sync Server" button in the MCP server admin interface.
How is the quality score calculated?
The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).
Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.
Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).
Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.
Tool Scores
- Behavior2/5
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.
Conciseness5/5Is 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.
Completeness3/5Given 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.
Parameters3/5Does 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.
Purpose4/5Does 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.
Usage Guidelines2/5Does 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.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of disclosing behavior. It only says 'Update,' which implies mutation, but does not state whether this is a partial update or full replacement, whether it requires special permissions, what side effects occur, or what the response looks like.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact: one sentence states the operation and one sentence provides the critical next step for constructing the operation. There is no filler, repetition of schema content, or unnecessary context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides just enough for an agent to begin: it identifies the candidate tool and tells it where to find the exact request shape. However, there are no annotations, no output schema, no return-value semantics, and no behavioral caveats, so several aspects of a correct call are left undisclosed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents id and blog, and the blog object is deliberately opaque. The description meaningfully adds that the agent must call get_operation_schema("UpdateBlog") to resolve the exact request shape; this is an actionable pointer not present in the input schema itself.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a clear verb+resource pattern: 'Update a store news article.' This clearly marks it as the mutation counterpart to get_blog and create_blog, though it does not add any scope details beyond what the title already suggests.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no when-to-use guidance or comparisons to siblings such as create_blog or get_blog. The directive to 'Call get_operation_schema("UpdateBlog")' is useful for obtaining the request shape but does not explain when this tool should be chosen over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full responsibility for behavioral disclosure. It states that the tool updates a group, but it does not mention mutation effects, partial vs. full updates, permission requirements, idempotency, or what the response will contain.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: it states the operation in the first sentence and directs the agent to the authoritative request shape in the second. There is no filler or repeated schema information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for starting invocation because it names the operation and defers to get_operation_schema for exact request shape. However, it omits broader context: when to use this instead of other group operations, what happens after an update, and any behavioral caveats. It is a workable but not fully complete description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers both parameters with descriptions. The description adds meaningful guidance by telling the agent to call get_operation_schema('UpdateCharacteristicGroup') for the exact request shape, which is essential for the loosely specified 'group' object. It stops short of fully defining the nested fields itself.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Update a product characteristic group.' The qualifier 'product' helps distinguish it from the similarly named update_characteristic and create_characteristic_group siblings. It does not explicitly name sibling alternatives, but the operation is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus creating, retrieving, or listing characteristic groups. The only guidance is to call get_operation_schema for the exact request shape, which helps with request construction but not with tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
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.
Conciseness5/5Is 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.
Completeness3/5Given 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.
Parameters3/5Does 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.
Purpose4/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says 'Update' and defers to get_operation_schema; it does not disclose permissions, side effects, idempotency, partial-update behavior, or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler: the operation is stated first, and the schema-fetching advice is placed second. Every sentence earns its place, and the pointer to an external operation schema keeps the description compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter update tool with an opaque nested object, the description supplies the core purpose and a precise path to the exact request shape. Still, it omits when to choose this tool over related characteristic tools, expected output, and any behavioral or permission context, making it minimally viable but not richly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents id and characteristic with 100% coverage, so the baseline is 3. The description adds value by directing the agent to get_operation_schema('UpdateCharacteristic') for the exact nested characteristic shape, which is useful because the characteristic object uses additionalProperties: {} and lacks concrete property definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action and resource: 'Update a product characteristic.' This is specific enough to distinguish it from characteristic-group and characteristic-color tools, though it does not explicitly name alternatives. Overall the purpose is clear and not tautological.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an explicit directive: 'Call get_operation_schema("UpdateCharacteristic") for the exact request shape,' which guides the agent on a necessary step before invocation. However, it does not explain when to use this tool versus create_characteristic, list_characteristics, or other update variants, so usage context is mostly implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation already declares readOnlyHint=true, so the read-only nature is covered outside the description. The description adds 'paginated,' indicating that the returned data may span pages, which is a small behavioral insight. It does not explain clamping, auto-pagination limits, or response shape, but these are already represented 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence: 'List product characteristics (paginated).' It front-loads the main verb and resource and adds only the important qualifier 'paginated' in parentheses. There is no filler content, and the structure stays optimally scannable for an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has low complexity, a read-only annotation, and fully documented optional parameters, so the description does not need to explain mechanics in depth. It does not have an output schema and the description does not mention the return format or any ordering/sorting behavior. The tool is also vaguely comparable to similar sibling list tools, so a slightly richer contextual note would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and each parameter has a meaningful description including defaults, ranges, and behavior of 'all'. The main description does not need to repeat parameter details because the schema carries that burden. For a fully self-documenting schema, the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description names the specific action 'List' and the specific resource 'product characteristics,' so the main function of the tool is clear. The parenthetical '(paginated)' adds a useful qualifier about list behavior. It does not explicitly call out differences from sibling list tools such as list_characteristic_groups or list_characteristic_colors, which prevents a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'List product characteristics' implies a common use case: obtaining a paginated list of characteristic records. However, the description does not explicitly say when to use this tool instead of get_characteristic, list_characteristic_groups, or list_characteristic_colors. Sibling names provide context, but the description offers no direct 'when to use' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already communicates that this is a safe read operation, and the description adds the paginated behavior. This is consistent and adds some behavioral context, but the description does not disclose much beyond the annotation and input schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single well-formed sentence with no wasted words. It front-loads the operation, resource, and key pagination behavior, making it appropriately concise for a simple list endpoint.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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 a fully documented input schema, the description is largely complete. It does not describe the return format, but no output schema exists and no mandatory fields are required, so an agent has enough information to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents all three parameters with clear descriptions, so the description does not need to repeat parameter semantics. The 'paginated' note provides some complementary context, but no additional meaning is added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the operation as a list action targeting product characteristic groups and explicitly notes pagination. It is clear even though it does not explicitly differentiate itself from sibling tools like get_characteristic_group or list_characteristics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The semantic meaning of 'List product characteristic groups' implies when it should be used, and the pagination note adds context about paged collection retrieval. However, the description does not explicitly state when to prefer this tool over alternatives or mention any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
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.
Conciseness5/5Is 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.
Completeness3/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior2/5
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.
Conciseness5/5Is 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.
Completeness3/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior2/5
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.
Conciseness5/5Is 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.
Completeness3/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description adds minimal behavioral context beyond 'paginated'. Pagination behavior is also documented in the schema parameters, so the description does not significantly disclose additional traits like default limits, auto-pagination semantics, or response envelope structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. 'List customers of the store (paginated)' is concise and every word adds value: verb, resource, scope, and behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the schema and annotations cover safety and pagination parameters, the description does not clarify the response structure (e.g., whether it returns a raw array or a paginated wrapper object). With no output schema, this is a gap. However, the simplicity of the tool and good schema coverage keep it from being incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter (all, page, per_page) having clear descriptions. The tool description adds no extra meaning beyond the term 'paginated', which is already inferred from the schema. Baseline 3 is appropriate given the schema fully documents parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists customers of the store, with a specific verb ('list') and resource ('customers'). It distinguishes from sibling tools like get_customer (single) and update_customer (modification) by indicating a collection retrieval operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for fetching a paginated list of all customers but does not explicitly state when to use it versus alternatives (e.g., get_customer for a single customer, get_customer_orders for a specific customer's orders). No exclusions or when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It notes the static-collection constraint and the need for product_card_ids, but omits critical details: error handling (e.g., duplicates), idempotency, partial failures, permissions, or return behavior. This is insufficient for a mutation tool without annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the core purpose and a key requirement. No filler or redundant information. Every word contributes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has three parameters including a nested object, no output schema, and no annotations. The description covers the basic purpose and a key requirement, but misses operational context: return format, error conditions, and idempotency. It is adequate for triggering an invocation but not fully self-sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds a slight clarification by expressing 'product_card_ids' as 'array of product card UUIDs', but largely repeats what the schema's example already conveys. It doesn't explain nested structure or enums beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the exact action: 'Add product cards to a STATIC collection or remove them from it.' It specifies the resource (collection cards) and clearly differentiates from siblings like update_collection, which handle collection metadata. The mention of 'STATIC' adds precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes it obvious when to use: whenever you need to add or remove cards from a static collection. It also implies a prerequisite by stating 'Requires product_card_ids'. It doesn't explicitly name alternatives or exclusions, but the context is clear enough for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior3/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior3/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, and the description adds pagination and status filter requirement/default. These traits are useful but mostly reiterate schema information. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with clear structure; no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Description adequately covers the tool's behavior for a listing operation, with pagination and status filter. It does not elaborate on the `all` auto-pagination parameter, but the schema covers that. Overall sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers 100% of parameters with descriptions. The description mentions status filter default but does not add significant meaning beyond the schema properties.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists product categories and notes pagination. It distinguishes from sibling tools like get_category (single category) and create/update_category (mutations).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing categories but does not explicitly mention alternatives or when-not-to-use. It provides context (paginated, status filter default) but lacks exclusionary guidance compared to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safety profile is known. The description adds pagination and filter behavior, but these are also documented in the schema. It does not cover response format or edge cases, but the tool is simple enough that this is not a major gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the action, resource, and key features without any filler or repetition. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with full schema coverage and a readOnly annotation, the description is sufficient. It conveys the core purpose and mentions pagination and filters. The lack of an output schema is mitigated by the obvious return type, and the auto-pagination 'all' parameter is documented in the schema, 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.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already explains all parameters. The description mentions 'status and purchase-date filters' but adds no new meaning beyond the schema. Baseline 3 is appropriate when the schema carries the full parameter documentation load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List'), resource ('gift cards'), and scope ('of the store'), with explicit mention of pagination and optional filters. This distinguishes it from get_gift_card (single) and 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.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage as a paginated list operation but provides no explicit when-to-use or alternative guidance (e.g., using get_gift_card for a single card). No exclusions are given, but the context is clear enough for a routine list tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the full behavioral disclosure burden. It adds a useful non-obvious constraint (the either/or mixing rule) but does not disclose permissions, error behavior, or side effects like replacement vs. incremental addition.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the action, then the supported types, then the constraint. Every sentence earns its place with no redundant or vague language.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description covers the core usage but lacks any indication of permissions, response format, or error conditions. It is adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds meaningful detail by specifying the three array keys (product_variant_ids, category_ids, collection_ids) and their UUID types, and clarifies the exclusive constraint. This goes beyond the schema's generic reference to get_operation_schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool attaches or detaches objects to/from a discount, listing supported object types. It is specific and distinct from the promocode equivalent, though it does not explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context for the operation and explicitly states that product_variant_ids must not be mixed with categories/collections in the same request. However, it does not mention when to choose this tool over sibling tools like manage_promocode_objects.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
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.
Conciseness5/5Is 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.
Completeness3/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior2/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safety profile is known. The description adds that the tool is paginated and returns only order IDs, which is useful context, but does not disclose any other behavioral traits such as rate limits or error conditions. This matches the baseline for an annotation-accompanied description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that immediately conveys the action ('List'), the target resource ('order IDs'), the scope ('of a customer'), and the pagination behavior. Every word earns its place, with zero filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only listing tool with full schema coverage and no output schema, the description adequately states what is returned (order IDs) and that it is paginated. It does not explain the response envelope or error handling, but these are less critical for a straightforward list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 three parameters. The description's mention of 'customer ID' and 'paginated' aligns with the schema but does not add new semantic information beyond what is already in the parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'List order IDs of a customer by their customer ID'. It clearly distinguishes itself from siblings like list_orders (which presumably lists all orders) and get_order (which fetches a single order) by scoping to one customer and returning only order IDs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states the context for use: you have a customer ID and want their order IDs. While it does not explicitly name alternatives or exclusions, the condition 'by their customer ID' provides clear context for 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already declares a non-destructive operation. The description adds context about the response contents (line items, delivery chunks, payment, status) which is helpful, but it does not disclose potential error cases, authentication needs, or other behavioral traits. This meets the minimum viable level with annotations present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the core purpose and includes important response details. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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 parameter, a schema that fully documents that parameter, and a readOnlyHint annotation, the description adequately covers what the tool returns. It could mention not-found behavior or more detail about response structure, but the included list of response components makes it sufficiently complete for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides full coverage for the single parameter 'id' with a clear description ('Order ID (UUID)'). The description's phrase 'by its ID' adds no new meaning beyond the schema. With 100% schema_description_coverage, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Get' and the specific resource 'a single order by its ID', and further specifies the included data (line items, delivery chunks, payment, status). This distinguishes it well from sibling tools like list_orders (which lists multiple orders) and get_order_addons (which focuses on addons).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly conveys usage: use this tool when you have an order ID and need a single order. It does not explicitly mention alternatives or exclusions, but the phrase 'single order by its ID' provides clear context. Lacks an explicit 'when not to use' or reference to list_orders, so not a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior3/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior3/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation covers safety, and the description adds meaningful behavioral details: CRITICAL-first ordering, newest-first within severity, pagination behavior, and default status filter. No contradictions 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The first sentence states the core purpose and ordering behavior, and the second clarifies the status filter default. Well-structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with a readOnlyHint, fully described schema parameters, and no output schema, the description provides sufficient behavioral context, including ordering, pagination, and filter defaults. It does not detail return fields, but that is acceptable for a list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All four parameters are fully described in the schema (100% coverage), so the baseline is 3. The description adds slight context for the status default and pagination, but does not significantly expand beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists system alerts, a specific verb+resource. It includes pagination and integrates with sibling tools like resolve_alert, distinguishing this read operation from the mutation tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage as the list operation for alerts, but does not explicitly contrast it with resolve_alert or other list tools. The mention of the status filter default provides some parameter-level guidance rather than tool selection context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already establishes the safety profile, lowering the burden. The description adds useful behavioral context by indicating the operation is paginated, which goes beyond the annotation. However, it stops short of additional behavioral traits like default page size or behavior of the all parameter, though those are captured in the input schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exactly one concise sentence with a leading verb and resource name. It is front-loaded with the core action and provides the key pagination qualifier without any filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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 no required parameters and fully documented parameters, the description correctly conveys the operation and its paging characteristic. While there is no output schema and the description does not detail the exact return attributes, the store-specific 'news articles' phrase provides enough context for an agent to understand what the tool returns without needing deeper documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter (all, page, per_page) already well documented in the input schema. The description's paginated mention loosely relates to these parameters but adds no new semantic detail beyond what the schema already supplies, 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.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' with a clear resource 'store news articles' and notes pagination. This clearly distinguishes it from sibling tools like get_blog, create_blog, and update_blog, which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The word 'List' implies this is the tool for enumerating multiple news articles rather than fetching a single one, providing some context. However, the description offers no explicit guidance on when to choose this tool over alternatives such as get_blog, nor does it mention exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint=true already informs the agent that this is a read-only operation. The description adds value beyond that by explaining the concept of a collection and its STATIC/DYNAMIC nature, which helps the agent understand the data domain. It also mentions pagination, which is a behavioral trait. While it doesn't detail return structure or edge cases, the annotation coverage lowers the burden, and the added context is meaningful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary action and scope ('List collections of the store (paginated)'), followed by a concise domain clarification. Every phrase earns its place, with no redundancy or filler. It is highly efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity, the readOnlyHint annotation, and a fully described schema, the description is largely complete. It provides the essential purpose, pagination context, and domain definition. The lack of an output schema is partially mitigated by the general expectation for list operations, but the description could be slightly richer by mentioning what the returned collection objects contain or any ordering behavior. Still, it is adequate for an agent to select and invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all five parameters, including types, defaults, and purpose. The description adds no additional parameter-level detail beyond restating the pagination behavior. Since the schema fully handles parameter semantics, the description does not need to compensate, and the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List'), the resource ('collections of the store'), and a key behavior (paginated). It also distinguishes the concept from other list tools (e.g., list_categories) by defining what a collection is and its two types (STATIC/DYNAMIC). This makes the tool's purpose unambiguous and differentiates it from siblings like get_collection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage—when you need to list collections—and provides context about collection types, but it does not explicitly state when to use this tool vs alternatives (e.g., get_collection for a single collection or manage_collection_cards for manual cards). There are no exclusions or alternative recommendations, so usage guidance is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already covers the safety profile, but the description adds meaningful context by stating that the status filter is required and that results are paginated. This provides behavioral details 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary purpose, and the second sentence adds a crucial constraint. Every word earns its place with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that this is a read-only list tool with a fully described schema and no output schema, the description covers the essential constraints (required status filter, pagination). It could optionally mention auto-pagination via the 'all' parameter, but the schema handles that. Overall it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 mentions status filtering and pagination, which aligns with the parameters, but it does not add details beyond what the schema already provides. No parameter information is missing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' with the resource 'discounts' and scope 'of the store'. It also mentions the key filter (status) and pagination, which distinguishes it from the sibling get_discount (single discount retrieval).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys that this is the tool for listing discounts, but it does not explicitly mention when to use it over alternatives like get_discount or provide any exclusion criteria. Usage is implied 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already covers the safety profile. The description adds useful behavioral context: pagination and the product-variant-category relationship. It does not contradict the annotation, but it stops short of describing response shape or any potential side effects beyond the read-only hint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise, front-loaded sentences. The first states the action and pagination; the second adds essential domain context. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no output schema, the description covers purpose, pagination, and the product domain structure. However, it omits the return-value shape and does not mention any alternatives or scope limitations, so it is not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% parameter coverage with clear descriptions for page, per_page, and all. The description adds no parameter-specific semantics beyond 'paginated', so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'List products of the store (paginated)', a specific verb+resource with scope. The second sentence clarifies the domain concept (a product groups variants and links to categories), which distinguishes it from sibling tools like list_variants and list_categories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for listing products (paginated) and explains what a product is, but it does not explicitly state when to prefer this over get_product/list_variants or mention exclusions. Usage is implied rather than directed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint=true already communicates that this is a safe read operation. The description adds 'paginated' and notes the required status, but these are already evident from the schema and the tool name. No additional behavioral context (e.g., rate limits, auth requirements) is provided, but no contradictions exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the core purpose. No waste or redundant phrasing. The description is efficient and immediately informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The schema is rich with detailed parameter descriptions and an annotation for safety, so the short description suffices for this straightforward list operation. The lack of an output schema is not a major gap given the simplicity, though a note about the response format would have been ideal.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter (all, page, status, per_page) well-documented. The description adds no extra semantic value beyond the schema, 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.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists promocodes with status filtering and pagination. It distinguishes from sibling tools like get_promocode (single record) and create/update_promocode by emphasizing the list and filter aspect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context that the status filter is required by the API, which aids in correct invocation. It does not explicitly mention alternatives like get_promocode for single lookups, but the name and scope make this obvious. No exclusions are stated, so a 4 is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
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.
Conciseness5/5Is 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.
Completeness3/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior3/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With the readOnlyHint annotation already indicating a safe read operation, the description adds little extra behavioral detail beyond the ID-based lookup. It does not mention what happens if the ID does not exist or the response format, but annotations lower the burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that fully captures the tool's purpose without any superfluous words. It is front-loaded and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter read tool with a complete schema and readOnlyHint annotation, the description is sufficient. There is no output schema to explain, and the description clearly communicates the scope, making the tool contextually complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents the single 'id' parameter with type and description. The description's 'by their ID' adds no additional semantic meaning beyond what the schema already provides, 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.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and a specific resource ('a single customer'), clearly indicating the tool fetches one customer by ID. It effectively distinguishes itself from sibling tools like list_customers (retrieving multiple) and update_customer (mutating).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the use case: fetch one customer when the ID is known. However, it does not explicitly state when not to use it (e.g., 'use list_customers for multiple customers') or name alternatives, 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.
- Behavior3/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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.
Conciseness4/5Is 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.
Completeness4/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It adds important context: it is not merge-patch, and category_ids replacement behavior is a subtle side effect. However, it omits other behavioral aspects such as response format, error conditions, or auth requirements, so it is moderately transparent but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, each earning its place. Front-loaded with the core purpose, then adds a critical behavioral note, then a pointer to further schema. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a nested object parameter and no output schema, so the description should help fill gaps. It references get_operation_schema for request shape, which is helpful, but it does not mention what the response contains or potential errors. Given the tool's moderate complexity, the description covers the most critical behavior but leaves some context incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers both parameters with descriptions, so the baseline is 3. The description adds value by explaining the patch semantics and the category_ids replacement behavior, which go beyond the schema's generic 'Fields to update' note. This helps the agent understand how to construct the product object correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb and resource: 'Update an existing product'. It also distinguishes the patch semantics ('plain JSON PATCH, not merge-patch') and highlights a key behavior (category_ids replacement), making it unmistakable from siblings like create_product or list_products.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on how to use the tool: it explains the patch format and warns that category_ids fully replaces the list. It also directs users to get_operation_schema for exact shape. However, it does not explicitly state when to prefer this over alternatives (e.g., bulk_update_prices) or when not to use it, so it falls short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the full burden. It does disclose two behavioral constraints: URLs must be HTTPS, and setting deactivate=true switches the webhook to INACTIVE. However, it does not explain other side effects, partial update behavior, or how deactivate=false behaves, leaving gaps in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, immediately states the tool's purpose, lists key capabilities, and ends with a useful pointer to the operation schema. Every sentence earns its place with no filler or redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is an update tool with a nested object, no output schema, and no annotations. The description covers updateable fields, the HTTPS constraint, and the deactivate behavior, and points to get_operation_schema for the request shape. However, it omits any mention of the response/return value or side effects, so it is not as complete as a fully documented tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema already describes both parameters, the webhook object's schema is generic (a reference to UpdateWebhookRequest). The description adds concrete examples of updatable fields (url, events, deactivate) and a validation rule (HTTPS only), which gives the agent useful semantic detail beyond the schema's placeholder.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Update an existing webhook' — a clear verb and resource. It then specifies the updateable aspects: url (HTTPS only), subscribed events, and deactivate=true to switch to INACTIVE, which distinguishes it from create/delete/get/validate webhook tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly establishes the use case: modifying an existing webhook, and even provides a pointer to get_operation_schema for the exact request shape. However, it does not explicitly enumerate when not to use this tool or mention alternatives like create_webhook or delete_webhook, so it lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, which matches the safe read-only nature of the operation. The description adds valuable behavioral details beyond annotations: pagination behavior, ordering by oldest upload first, and the default status filter behavior. This gives the agent a good understanding of what to expect without overstating.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: two sentences, front-loaded with the core purpose and immediately followed by an important pagination/status nuance. Every word earns its place; there is no verbose or extraneous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 4 parameters and no output schema. The description explains pagination, ordering, and status filtering, which combined with the fully self-documenting input schema provides a complete picture for usage. It could potentially mention what fields are returned in the response, but given the absence of an output schema and the clarity of 'list videos', the current description is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters with descriptions, including the 'status' default and 'per_page' clamping. The description adds the context that status defaults to all four statuses, which is redundant with the schema. It does not introduce new 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.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List', the resource 'product videos', and the scope 'of the store'. It also specifies pagination and ordering ('oldest upload first'), which distinguishes it from sibling tools like get_video (single video) or upload_video (create). It fully captures 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.
Usage Guidelines4/5Does 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 list product videos with pagination and status filtering. It explicitly notes that a status filter is required but defaults to all four statuses if omitted, which guides usage. It does not explicitly name alternatives or exclusionary cases, but the purpose is distinct enough among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
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 explains the attach/detach action and the exclusivity rule, but does not disclose potential side effects, whether the operation is additive or replaces existing objects, permission requirements, or error behavior. This is adequate but leaves notable gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficient: two sentences that front-load the action, then enumerate supported object types and the key constraint. Every sentence contributes useful information with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with nested objects and no output schema, the description covers the essential usage context: what action to perform, which object types are supported, and a critical API constraint. It does not explain the response format or provide an example, but the description is sufficient for an agent to invoke the tool correctly in most cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes each parameter with 100% coverage, giving a baseline of 3. The description adds meaningful context beyond the schema by clarifying that variant/category/collection IDs are UUIDs and emphasizing the non-mixing rule, which is not evident from the schema alone. This adds real value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Attach...or detach') and resource ('objects to a promocode'). It distinguishes itself from sibling tools by naming the specific object types (product_variant_ids, category_ids, collection_ids) and highlighting that it applies to promocodes, not discounts or collections.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool, including the critical rule about passing either product_variant_ids or categories/collections, and the exclusivity constraint. However, it does not explicitly mention alternatives (e.g., manage_discount_objects) or state when not to use it, so it lacks explicit when-not/alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses the PATCH behavior (only provided fields changed) and the immutability of collection type, but omits details about permissions, error cases, or response format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (three short sentences), front-loads the primary purpose, and each sentence adds distinct value (operation, constraint, and schema reference). No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter update tool with no annotations and no output schema, the description covers the core operation, constraints, and points to get_operation_schema for the exact shape. It doesn't discuss error handling or permissions, but given the simplicity, it's largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for both parameters, providing a baseline of 3. The description adds meaningful semantics by clarifying that the `collection` parameter is a partial update (only provided fields change) and that the type cannot be changed, which goes beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates an existing collection, specifies the PATCH semantics, and notes that only provided fields are changed and the collection type is immutable. This distinguishes it from create/delete/get collection siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool (updating existing collections) and notes an exclusion (cannot change collection type). It also directs users to get_operation_schema for the exact request shape, though it does not explicitly name alternative tools for create/delete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the partial-update behavior via 'plain JSON PATCH' and lists updatable fields, which is useful. However, it does not mention response format, error cases, authorization requirements, or whether omitted fields are retained or reset—common expectations for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences: the first states the action and scope, the second lists fields and provides a pointer for exact shape. No filler, no repetition of schema or annotations, and information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (2 params, nested object, no output schema), the description covers purpose, updatable fields, and a route to the exact schema. It does not describe the return value or side effects, but the explicit pointer to get_operation_schema fills a key gap, making it nearly complete for an update operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema already covers both parameters (100% coverage), the description adds value by explicitly listing allowed updatable fields (note, first_name, last_name, email) and clarifying that the 'customer' object is a PATCH payload. This goes beyond the generic schema description referencing get_operation_schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update a customer') and specifies the HTTP-like semantics ('plain JSON PATCH'), distinguishing it from read-only siblings like get_customer and list_customers. It also enumerates updatable fields, leaving no ambiguity about the tool's scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when an existing customer needs modification and explicitly directs the caller to get_operation_schema("UpdateCustomer") for the exact request shape, serving as a usage prerequisite. However, it does not explicitly say when NOT to use this tool or contrast with alternatives, though none exist for customer updates.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses the PATCH semantics (partial update) and enumerates updatable fields. However, it does not mention response shape, error cases, or permissions. This is moderate disclosure; it adds value but leaves significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action, and no wasted words. Every sentence earns its place—first states the operation and method, second gives field list and schema pointer.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, but the description provides essential operational context (PATCH method, partial update, field list) and a clear pointer to get_operation_schema for exact shape. It omits return value details and error behavior, but for an update tool this is adequate given the pointer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (both params have descriptions), so baseline is 3. The description adds meaningful detail beyond the schema by listing the specific subfields (title, discount_value, discount_dates, status, binding_mode) and emphasizing 'send only the fields to change'. This enhances parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update an existing discount' with a specific verb and resource, and clarifies the HTTP method (plain application/json PATCH). This distinguishes it from sibling tools like create_discount and get_discount.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: it's for partial updates (send only fields to change) and lists the mutable fields (title, discount_value, etc.). It also points to get_operation_schema for exact request shape. It does not explicitly exclude alternatives, but the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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 goes beyond a simple statement of the action by explaining that archive is a soft delete (status becomes ARCHIVED) and that the warehouse can no longer be used for stock, while unarchive sets status back to ACTIVE. This adds meaningful behavioral context, though it does not cover permissions or edge cases like existing stock.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the action and conveys the essential behavior and consequences without any redundancy or irrelevant detail. Every word contributes to understanding the tool's purpose and effects.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple action tool with 2 parameters and no output schema, the description is quite complete. It explains both actions, the resulting status changes, and the business consequence (warehouse cannot be used for stock). It lacks explicit mention of prerequisites or restrictions, but the low complexity of the tool reduces the need for more context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for both parameters (id and action), so the baseline is 3. However, the description adds significant semantic value by explaining the effect of each action value: it details what 'archive' and 'unarchive' actually do to the warehouse status and usability, which the enum values alone do not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs: 'Archive a warehouse ... or unarchive it.' It defines the resource (warehouse) and the distinct outcomes (status becomes ARCHIVED or ACTIVE), which fully distinguishes it from sibling action tools like category_action or variant_action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the usage context (use this tool to archive or unarchive a warehouse) but provides no explicit guidance on when to use this tool versus alternatives like update_warehouse. It does not mention exclusions or prerequisites, so the 'when-to-use' is only self-evident from the action name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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.
Conciseness4/5Is 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.
Completeness4/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, and the description adds that the result includes status, balance, and purchase info, providing useful context about the return content without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
One concise sentence that is front-loaded with the action and includes only relevant details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-resource getter with one fully described parameter and a read-only annotation, the description covers the essential purpose and return information, making it complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'id' is fully described in the schema as 'Gift card ID (UUID)', so the description adds no additional meaning. Baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses 'Get a single gift card by its ID' with a specific verb and resource, and distinguishes from sibling list_gift_cards by indicating this fetches one card by ID. It also names included data fields (status, balance, purchase info).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Clear context that this is for retrieving a single card when an ID is known, but it does not explicitly mention when not to use it or point to alternatives like list_gift_cards. The sibling name provides implicit context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already establishes safety, so the description doesn't need to restate that. It adds useful behavioral details beyond the annotation: pagination behavior and the newest-first sort order, which help set expectations for the returned data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that is front-loaded with the action and resource, then adds scope, pagination, and ordering. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple read-only list operation with complete schema descriptions and a clear scope. The absence of an output schema is fine because the tool name and description make the return type obvious. The description provides all necessary context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents the page, per_page, and all parameters. The description only references pagination generally, adding no semantics beyond what the schema already provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource ('List orders') with clear scope ('of the store') and ordering ('newest first'). This distinguishes it from siblings like get_order (single order) and get_customer_orders (per customer).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly frames when to use the tool: to list all store orders with pagination and newest-first ordering. It does not explicitly mention alternatives or exclusions, but the context is clear enough for an AI agent to differentiate from customer-specific or single-order tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
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 useful behavioral context: it matches operationId, URL path, tag, and Russian descriptions, and notes that all 162 operations are in scope, but it does not mention output size limits or behavior beyond these search details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense, purposeful sentences: the first states the core function, the second explains how search matching works with a practical Russian-language tip, and the third gives the follow-up workflow. Every sentence earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a discovery tool with 100% schema coverage and no output schema, the description is complete. It covers what is searched, how to use the query effectively, and what to do after finding an operation, which is the full context an agent needs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents all three parameters at 100% coverage, so the baseline is 3. The description goes further by explaining what the query actually matches (operationId, URL path, tag, Russian summary/description), which adds meaning beyond the generic 'Search keywords' schema text.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's specific job: searching the full catalog of 162 Yandex KIT API operations by keyword. It distinguishes the tool from execution and inspection tools by explaining that found operations can later be executed via kit_request and inspected via get_operation_schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear workflow context: search first, then inspect with get_operation_schema, then execute with kit_request. It does not explicitly state when not to use this tool, but the discovery role is strongly implied and will guide an agent effectively.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it delivers: it clearly warns that real calls are made against the live store, that write operations take effect immediately, that there is no sandbox, and that body validation happens before sending unless validate=false. This is excellent behavioral disclosure well beyond any structured field.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact yet dense: two sentences plus a short workflow and validation note. Critical warnings (live store, no sandbox) are front-loaded before the workflow, and every sentence earns its place without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a generic escape hatch with no output schema and 162 possible operations, the description covers the critical operational context: safety warning, validation behavior, and the discover-then-call workflow. It doesn't mention that return shape depends on the specific operation, but that is somewhat inherent in an operate-by-operationId tool and is discoverable via get_operation_schema. The lack of annotation coverage is compensated by the rich warning context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already gives descriptions for all five parameters, and schema coverage is 100%, so the baseline is 3. The description references the validate flag and the workflow for getting the body shape, but these do not add substantial meaning beyond the schema's parameter descriptions. No major semantic gap exists.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a strong verb ('executes') and clearly specifies the resource: ANY of the 162 Yandex KIT API operations by operationId. It explicitly distinguishes itself from dedicated tools by covering operations without one, so an agent can tell this is the generic escape hatch.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an explicit workflow (search_operations -> get_operation_schema -> kit_request) and notes it covers operations without a dedicated tool, strongly implying dedicated tools should be used when available. However, it does not explicitly say 'do not use when a dedicated tool exists', and the warning is more about safety than about selecting this tool over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=true, and the description adds value by disclosing pagination behavior and the status filter requirement/default. This goes beyond the schema's optional status field by clarifying the API's actual expectations. While it doesn't detail edge cases like auto-pagination limits, the provided context is useful and not contradictory.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the core purpose and followed by a key behavioral note. Every word earns its place with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters with full schema descriptions and a readOnlyHint annotation, the description covers the essential purpose and a critical API nuance. It doesn't repeat schema details, and while it could mention return structure or auto-pagination, the lack of an output schema makes this an acceptable level of completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does 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 meaningful context for the status parameter by clarifying that the API requires a filter but defaults to ACTIVE, which is not obvious from the schema alone. This nuance enhances understanding beyond the structured definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb ('List') and resource ('warehouses'), and adds 'paginated' to convey scope. This distinguishes it from sibling tools like get_warehouse (single retrieval), create_warehouse, update_warehouse, and warehouse_action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does 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 list warehouses) and notes the API's status filter requirement with a default. While it does not explicitly mention alternatives or exclusions, the sibling tool names make the distinction obvious, and the pagination hint implies use for listing multiple items.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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 the mutating action, the 400 rejection for CRITICAL alerts, and the self-clearing behavior once the underlying problem is fixed. This is significant contextual information beyond what the schema provides, though it doesn't describe success responses or permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences: the first states the core purpose, the second adds crucial constraints and error behavior. Every word earns its place, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter action tool with no output schema, the description covers the essential aspects: purpose, usage constraints, error condition, and body requirements. It doesn't specify the success return value, but this is a minor omission given the tool's simplicity and the detailed schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already thoroughly describes alert_id, including its source (list_alerts response) and semantic string nature. Schema coverage is 100%, so baseline 3 applies. The description adds no parameter-specific details beyond noting the absence of a request body, which is request-level rather than parameter-level info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Mark an alert as resolved,' a specific verb+resource that clearly defines the tool's function. It distinguishes from siblings like list_alerts by focusing on the resolution action, making the purpose immediately clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool: only WARNING alerts can be closed by hand, and active CRITICAL alerts are rejected with 400. This provides clear usage context and a when-not condition, plus the note that no request body is required simplifies invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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 HTTP method (plain application/json PATCH), partial update behavior, and lists the updatable fields. It also directs to get_operation_schema for exact shape. This is useful transparency, but it does not mention error conditions (e.g., promocode not found) or response structure, which would be valuable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the main action, then provides method, partial-update detail, field list, and a pointer to the operation schema. Every clause adds value; there is no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description covers the essential aspects: what the tool does, the HTTP method, partial update semantics, and the exact field names. It explicitly instructs to call get_operation_schema for the full request shape, which addresses schema complexity. Missing are return value/error behavior, but for an update operation with a pointer to the schema, this is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers both parameters with descriptions, so baseline is 3. The tool description adds meaning by listing the exact fields that can be updated (code, title, discount_value, promocode_dates, status, binding_mode, limits), which are not enumerated in the schema itself (schema references an external UpdatePromocodeRequest). This incremental detail helps the agent understand parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: 'Update an existing promocode'. It also specifies the method (PATCH) and partial update semantics ('send only the fields to change'), which distinguishes it from create_promocode and get_promocode. This is a specific, actionable purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says 'Update an existing promocode', implying that the promocode must already exist, which is clear context. It also advises calling get_operation_schema for the exact request shape, helps the agent know how to use it. However, it does not explicitly state when not to use it or compare it to alternatives like create_promocode or manage_promocode_objects, so it lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It reveals merge-patch behavior, null field removal, slug immutability, and points to get_operation_schema for the request shape, which are meaningful behavioral traits beyond the schema. It does not mention permissions or response format, but key behaviors are adequately covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences, front-loaded with purpose and key semantics. It avoids redundancy and each sentence earns its place, including the pointer to get_operation_schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has two parameters with full schema descriptions and a nested object, and the description clarifies merge-patch update behavior and constraints while directing to get_operation_schema for the request shape. It does not explain the response format, but for an update tool with no output schema and good schema coverage, this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters are fully described in the schema, with 'warehouse' marked as a merge-patch record. The description adds semantics by explaining how to use the warehouse object: 'send only the fields to change; setting a field to null removes it' and the slug cannot be changed. This goes beyond the schema's baseline value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Update an existing warehouse via JSON Merge Patch', specifying a distinct verb and resource. This differentiates it from sibling tools like create_warehouse, get_warehouse, and warehouse_action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for use: updating an existing warehouse with merge-patch semantics, including how to send only changed fields and use null to remove. It does not explicitly name alternatives or exclusions beyond slug immutability, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full transparency burden. It discloses content-based deduplication (returns existing file), a 100 MB size limit, and multipart/form-data encoding—specific behavioral traits that meaningfully affect invocation and expectations, going beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, each earning its place: purpose, key behavioral trait, and input constraint. The description is front-loaded and highly scannable, with no redundant wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, and the description covers purpose, dedup, size, and input constraints. However, with no output schema, it does not explain what the call returns on success (e.g., file ID or URL), leaving a minor but relevant gap for an upload operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage of all parameters, including their roles and mutual exclusivity. The description adds the 'exactly one source' rule but no additional semantic depth; hence the schema baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool uploads a file via multipart/form-data and provides a concrete use case (image for variant/collection). This distinguishes it from the sibling upload_video tool and clearly communicates the action and resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers context for when to use the tool ('e.g. an image for a variant or collection') and enforces the 'exactly one source' rule. It does not explicitly name alternatives or exclusions, but the context and dedup behavior make the usage scenario clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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 exact HTTP request sent (POST with event WEBHOOK_VALIDATE), the expected server response (HTTP 2xx with body {"message": "validated_store_{store_id}"}), and the activation condition. This is significant behavioral detail, though it does not cover failure behavior or authentication requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, dense sentence that front-loads the main purpose and then explains the validation behavior. Every clause adds valuable information, with no wasted words or repetition. It is well-structured for an AI agent to quickly grasp the tool's operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's modest complexity (2 parameters, no output schema), the description provides a thorough explanation of the validation process, the expected server response, and the activation condition. It also directs the user to get_store for store_id. The main gap is the lack of explicit return-value documentation (since no output schema exists), and failure behavior is not described, but the core workflow is well covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining the 'activate' parameter's effect: 'With activate=true, the webhook becomes ACTIVE if the server replies HTTP 2xx...' It also references get_store for the store_id, providing context for the response body. The 'id' parameter is sufficiently described in the schema as a Webhook ID (UUID).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Trigger webhook validation.' It describes the mechanism (POST with event WEBHOOK_VALIDATE) and specifies the condition for activation, which distinguishes it from sibling tools like create_webhook or update_webhook. The verb+resource construction is explicit and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: to validate a webhook, especially for activation when activate=true. It does not explicitly name alternative tools or say 'use this instead of X,' but the context of the webhook lifecycle (create, update, delete, list) makes the specific validation step clear. The activation condition provides practical usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior5/5
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.
Conciseness4/5Is 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.
Completeness4/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description adds key behavioral details: results are paginated, and colors are keyed by characteristic value rather than an ID. This helps the agent understand the response structure and the meaning of search_text.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence that includes the essential caveat about keying. No redundant information or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list operation with full schema descriptions and a readOnlyHint, the description is complete. It covers purpose, pagination, and keying behavior; output shape is implied by 'color values with their hex codes'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all parameters with descriptions, so the tool description does not need to explain each parameter. It adds a useful note about keying, which indirectly helps understand search_text, but the schema already carries the burden. Baseline 3 applies due to full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('List'), a specific resource ('color values of the store's characteristics'), and the output includes hex codes. It distinguishes itself from the sibling update_characteristic_color by focusing on reading colors.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage context is clear: this tool lists characteristic colors and is read-only, as reinforced by the readOnlyHint annotation. However, it does not explicitly mention alternatives or when not to use it, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already declares this a safe read operation. The description adds valuable behavioral context by stating that results are not paginated (implying potentially large responses) and by describing the shape of each webhook (URL, event types, status). No contradictions with annotations, though it does not address auth or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: one sentence stating the action and scope, plus one sentence detailing the returned fields. Every word earns its place, and the key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given 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 no parameters and no output schema, the description is sufficient: it explains what is listed, the lack of pagination, and the data included in each entry. This gives an agent everything needed to invoke and interpret the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the schema is trivially complete. Per the rubric, the baseline is 4; the description further clarifies what the returned records contain, but this is output semantics rather than parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' with a clear resource ('all webhooks of the store') and adds scope ('not paginated'), effectively distinguishing it from siblings like get_webhook (single webhook) or create/update/delete/validate. It also summarizes the content of each webhook, 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.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates that this tool returns the full set of webhooks with no pagination, making it evident when to use it for a complete listing. However, it does not explicitly mention alternatives (e.g., get_webhook for a single webhook) or state when not to use it, so it falls short of full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral disclosure and does so thoroughly: deduplication by content, max file size, allowed formats, async queueing, returned video ID, and variant constraints. This is substantial and actionable beyond anything in the JSON schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence in the description earns its place: method, limits, dedup, workflow, attachment constraints, and input exclusivity. It is detailed without redundancy and is well-structured for quick parsing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and the absence of both annotations and output schema, the description covers the essential operational context: upload method, size and format limits, dedup behavior, the polling flow, and downstream media constraints. An agent has enough information to invoke and integrate the result correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents filename, file_path, and content_base64 with mutual exclusivity. The description reinforces the 'exactly one source' rule and preference for file_path, but adds no meaningful new semantic detail beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific action and resource: 'Upload a product video via multipart/form-data and queue it for processing.' This immediately distinguishes it from generic file uploads and URL-based video imports, and the verb-object structure is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear workflow: upload exactly one source, poll with get_video until READY, then attach via media in create_variant/update_variant. It clearly defines the integration path. It does not explicitly name when to prefer upload_video_from_url or upload_file, but operational guidance is otherwise strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses a known KIT API defect where ARCHIVED is silently stripped from the status filter, and explains the tool's detection and error-reporting behavior (STATUS_FILTER_IGNORED, ARCHIVE_READ_UNSUPPORTED, MIXED_ARCHIVED_FILTER_UNSUPPORTED). This adds crucial behavioral context not captured in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a clear purpose, then provides essential behavior details. It is three sentences long and every sentence contributes meaningful information, though the last sentence is quite dense and could be slightly more concise. Overall, it is well-structured and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with six optional parameters and no output schema, the description provides comprehensive context: pagination is mentioned, default filtering behavior is stated, the major API defect is disclosed with error codes, and the alternative for archived variants is given. The readOnlyHint annotation covers safety, so the description is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are fully documented in the schema. The description adds some context (e.g., default statuses and the defect affecting the 'status' filter), but it does not significantly enhance parameter semantics beyond what the schema already provides. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'List variants (sellable items / SKUs) of the store, with optional filters (paginated)'. It identifies the resource (variants/SKUs) and the action (list), and distinguishes itself from the sibling get_variant tool by explicitly noting that archived variants can only be read by ID via get_variant.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool and when not to: it states the default behavior (returns all statuses except ARCHIVED) and gives an alternative (get_variant) for accessing archived variants. It also describes the tool's defensive behavior of failing with specific error codes instead of returning incorrect data, which helps agents avoid misuse.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It explicitly discloses atomicity, the rejection of the whole request if any code fails, the null-to-remove behavior, and the requirement to include the crypto tail. This is unusually transparent for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with zero filler. The core action is front-loaded, and each subsequent sentence adds a critical constraint: item sourcing, null-for-removal, and atomicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description gives what an agent needs to call the tool correctly: resource, ID source, parameter semantics, null behavior, and atomicity. It omits only coarse details like authorization expectations and response format, but no output schema exists, and those gaps are minor for this operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents the parameters at 100% coverage, including null semantics and the source of item IDs. The description adds useful reinforcement: each item must take exactly one code and failures invalidate everything. This exceeds the baseline without duplicating everything verbatim.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource: writing or removing Chestny ZNAK marking codes on order items. It clearly distinguishes itself from the many order status and product-management siblings because it is the only tool about marking codes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear operational guidance: item IDs come from get_order under delivery_chunks[].items[].id, null removes an existing code, and one code per order item. It does not explicitly name a when-not-to-use sibling, but no sibling serves this exact function, so the guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for behavioral disclosure. It explains the merge-patch semantics, details null handling for parent_id and file_id, and warns that null on other fields is rejected. This goes well beyond typical descriptions and prevents misuse.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with no filler. It front-loads the core action, then gives necessary constraints, and ends with a useful pointer to formal schema. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (JSON Merge Patch, specific null constraints), the description covers the key behavioral aspects and provides a clear reference for exact shape. It doesn't mention return values or side effects, but for an update operation this is a minor gap, and the lack of an output schema makes the omission less critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents both parameters, so baseline is 3. The description adds value by clarifying the nested 'category' object's acceptable null behavior and pointing to get_operation_schema for the exact request shape, which compensates for the schema's abstract mention of UpdateCategoryRequest.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states exactly what the tool does: 'Update an existing category via JSON Merge Patch'. The verb 'Update' and resource 'category' are explicit, and the merge-patch detail distinguishes it from create or get operations, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use this tool (updating an existing category, partial updates via merge patch) and provides concrete operational guidance such as which fields accept null. However, it does not explicitly name alternatives like 'create_category' for new categories, so it lacks an explicit exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full transparency burden. It discloses that the operation recolors an existing value rather than creating a new one, which is a key behavioral trait. This provides meaningful context beyond the basic action and addresses the primary behavioral nuance for this operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: the first states the action and clarifies the non-creational nature; the second states required fields. No fluff, front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter update operation, the description covers the purpose, prerequisite, and parameter requirements. Since no output schema is present, the lack of return-value information is acceptable, but it could mention response behavior for full completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds the constraint that the value must already exist, which is not in the schema, and confirms both fields are required. The schema already provides detailed descriptions with examples and special color values, so the description complements rather than repeats, earning a score above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool sets the hex code of a color characteristic value, using the specific verb 'Set' and resource 'color characteristic value'. It explicitly distinguishes from creation by noting it recolors an existing value, which differentiates it from potentially related tools like list_characteristic_colors or create tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description instructs that the value must already exist and references list_characteristic_colors as a way to find such values. It also states this endpoint does not create a value, providing an explicit exclusion for when not to use it. It further notes both fields are required, covering prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
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.
Conciseness4/5Is 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.
Completeness4/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses soft delete, status transitions (ARCHIVED/HIDDEN), storefront visibility, restorability, and the need to publish via update_variant after unarchive. This is rich and transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the main purpose, no filler. Each clause earns its place by explaining the state transitions and the necessary follow-up.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with only 2 params and no output schema, and the description covers the essential behavior, state changes, storefront visibility, and follow-up action. It is complete for selecting and invoking the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters with basic descriptions. The description adds meaning to the action enum by explaining the outcome of each value (archive -> ARCHIVED, unarchive -> HIDDEN), going beyond the schema's 'Action to perform.' Id semantics remain as provided by schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool archives or unarchives a variant with specific behavioral effects. It uses a specific verb+resource and distinguishes from sibling tools by explicitly mentioning the follow-up via update_variant.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the two actions and notes that unarchive requires a subsequent publish via update_variant, naming an alternative tool. It does not explicitly state when not to use the tool, but the context is clear enough for the agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full disclosure burden and succeeds: queued/asynchronous processing, three accepted link types (including the KIT player edge case returning an already uploaded video), an explicit failure mode (400), size and format acceptance, content-based deduplication, the response contract (video ID), and a pollution workflow. This meets the bar that annotations would otherwise have to cover.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Five dense sentences are arranged in a logical narrative (purpose → accepted inputs → failure condition → limits → occupancy). Nothing duplicates schema content and each clause delivers a constraint or next step, so the length is all functional signal rather than padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with no output schema, nothing is missing: input format, failure condition, limitations, and the full downstream playback (poll get_video to READY, attach via media, one video per variant, required co-existing image). An agent can go from a bare URL to a correct API call purely from this text.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description enlarges the schema by adding an agent-relevant constraint: the link must be reachable without authentication or the API answers 400, and it restates the accepted link forms in operational terms. Modest but genuine value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description names a precise verb, resource and method: 'Upload a product video by public link and queue it for processing.' It immediately differentiates itself from the sibling upload_video ('use it instead of upload_video when the file lives on the web'), so an agent can select between the two upload tools without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Reference explicitly states when to use it: instead of upload_video when the file is web-hosted rather than local. It also gives operational preconditions (link must be public, no auth, else 400) and a follow-up protocol (poll get_video until READY, attach through media in create_variant/update_variant). That is a complete when/how routing package.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral burden. It discloses non-nullability, the replacement semantics of media and stocks, the one-video-per-variant rule, the image requirement for videos, and even a documentation bug in the upstream schema. This is exceptionally rich safety-relevant information for an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average, but every sentence supplies unique guidance: alternatives, nullability, media/stocks replacement, video constraints, and an upstream documentation correction. The core merge-patch instruction is front-loaded so the agent immediately understands the central contract.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a nested mutation with no annotations and no output schema, yet the description covers all major failure modes: null rejection, full-list replacement, video-image dependency, and schema misdocumentation. It also directs the agent to get_operation_schema for the unambiguous request shape, making the definition effectively complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers id and variant, but the description adds high-value meaning: JSON Patch semantics, which fields are exceptions to the patch behavior, what nulls mean, and where to get the authoritative shape. This significantly improves agent understanding of the variant parameter beyond what the schema alone communicates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the behavior: update an existing variant via JSON Merge Patch, sending only the fields to change. It identifies the target resource and distinguishes this tool from closely related operations like bulk_update_prices by clarifying which use cases belong to which tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides concrete when-not-to-use guidance: null values are rejected, so to clear a price the agent should use bulk_update_prices. It also tells the agent to consult get_operation_schema for the exact request shape, providing a clear path to validate the payload before invoking.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GitHub Badge
Glama performs regular codebase and documentation scans to:
- Confirm that the MCP server is working as expected.
- Confirm that there are no obvious security issues.
- Evaluate tool definition quality.
Our badge communicates server capabilities, safety, and installation instructions.
Card Badge
Copy to your README.md:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/ztemerbekov/a1-yandex-kit-skills'
If you have feedback or need assistance with the MCP directory API, please join our Discord server