shopify-graphql-mcp

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v1.0.0
Disambiguation3/5
With 314 tools covering the full Shopify API, there are naturally many similar tools (e.g., get_products vs search_products vs product_listings, create_discount vs create_price_rule, get_pixels vs get_custom_pixels). While most target distinct resources/actions, the sheer volume creates selection ambiguity, and some tools have overlapping functionality (e.g., get_all_orders vs get_orders). Descriptions are detailed and help clarify, but the overlap is significant enough to cause potential misselection.
Naming Consistency4/5
The vast majority use a consistent verb_noun pattern (get_*, create_*, update_*, delete_*), with domain-specific verbs (hold_*, release_*, credit_*, debit_*, approve_*, decline_*) fitting the pattern. Minor deviations exist (list_webhook_subscriptions instead of get_*, create_subscription_contract_atomic, upsert_theme_file, toggle_custom_pixel), but these are few and the pattern is predictable overall.
Tool Count1/5
314 tools is extreme, far exceeding the typical well-scoped MCP server (3-15 tools). Even for a broad domain like Shopify, this number is overwhelming and impractical for an agent to navigate, leading to high selection complexity and reduced usability.
Completeness4/5
The server covers an impressively wide range of Shopify resources: products, orders, customers, collections, inventory, fulfillment, discounts, gift cards, returns, checkouts, payments, companies, subscriptions, marketing, themes, webhooks, and more. This is near-comprehensive for the Shopify ecosystem, with only minor gaps like explicit product variant management (handled within product tools) and some niche settings.
Average 3.2/5 across 270 of 314 tools scored. Lowest: 1.7/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 0 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
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.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
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

Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, but it only says 'Update a legal policy'. It does not disclose whether the update is destructive, requires specific permissions, publishes changes, or has any side effects. This is a significant gap 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.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, but this is under-specification rather than effective conciseness. It consists of a single phrase that repeats the tool name and provides no structured information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 2 required parameters, no output schema, and no annotations, the description is completely inadequate. It fails to explain what the update does, what return value to expect, or any operational details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers both parameters (body and handle) with descriptions, so the schema provides the needed parameter semantics. The description itself adds no parameter context, but baseline 3 is appropriate given high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update a legal policy' is a tautology that restates the tool name exactly, providing no additional detail about what updating entails or what a legal policy is. It uses a verb and resource but fails to distinguish itself from sibling tools beyond the obvious update-vs-get contrast.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool vs alternatives, no prerequisites, and no mention of related tools like get_legal_policies. The description offers no situational context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description must carry the full behavioral disclosure burden. It doesn't mention that applying an order edit is likely a mutating irreversible operation, that the order must be in a certain state, or that the edit should be pre-calculated. No side effects, permissions, or failure modes are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence and thus brief, but this is under-specification rather than effective conciseness. It provides no useful structure or content beyond restating the tool name. The brevity doesn't serve the reader's understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This tool has 5 parameters including nested arrays, no output schema, and no annotations. The description provides almost no operational context: no indication of workflow (e.g., calculate first), expected outcome, prerequisites, or side effects. An agent cannot correctly use this tool based on the description alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The schema already describes all five parameters, but the tool description adds no additional meaning about how these parameters form an 'order edit' or how edits, removals, and additions interact. It fully relies on the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Apply an order edit to the order' essentially paraphrases the tool name without adding meaning. It gives a generic verb and resource but fails to specify what an 'order edit' entails or how it differs from related tools like calculate_order_edit or add_line_items_to_order. This borders on a tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description doesn't state when to use this tool versus alternatives such as add_line_items_to_order, remove_line_items_from_order, or calculate_order_edit. There is no context, prerequisite, or exclusion mention.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/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, but it only names the action. It does not state whether cancellation is reversible, what happens to payments or fulfillments, or how the optional refund/restock flags affect the outcome.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, but under-specification is not conciseness. It fails to provide meaningful context or structure and merely repeats the tool name, so it does not earn its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with four parameters and no annotations or output schema, the description is severely incomplete. It omits effects, response format, permissions, and interaction with order states, making it inadequate for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with clear descriptions for all four parameters (id, reason, refund, restock). The description adds no parameter meaning, but the baseline of 3 applies since the schema already handles parameter documentation sufficiently.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Cancel an order' is a tautology of the tool name 'cancel_order', adding no semantic content. It fails to distinguish cancellation from related order operations like close_order or delete_order, which is critical in a large 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use cancel_order versus alternatives (e.g., close_order, delete_order, create_refund). There are no prerequisites, context, or exclusion criteria, leaving the agent without decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/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 describing behavioral traits. It says nothing about side effects, idempotency, permissions, or what happens to published translations when a locale is unpublished, making it behaviorally opaque.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short but under-specified to the point of being a tautology. It is not a model of conciseness because it sacrifices all informative content for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutating tool with no annotations and no output schema, the description is severely incomplete. It fails to explain what unpublishing a locale entails, what resources are affected, or how the agent can verify success, offering no operational context beyond the tool name.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents the only parameter with a clear description ('Locale code to unpublish'), so schema coverage is 100%. The tool description adds no extra meaning beyond this, 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.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Unpublish a locale' directly restates the tool name with no additional context. It does not explain what unpublishing means, what a locale is in this context, or how it differs from sibling tools like publish_locale beyond the verb itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool or when to prefer an alternative. It does not mention prerequisites, side effects, or how unpublishing relates to other locale/translation operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the full burden for behavioral disclosure. It fails to mention any side effects, prerequisites, or post-conditions of creating a theme, such as whether the theme is published or how the source is processed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
While the description is short (six words), it is under-specified rather than concise. The brevity comes at the expense of meaningful information, similar to the 'Process' example.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides minimal context for a create operation with three parameters and no output schema. It does not explain what happens after creation, whether the source must be a valid Shopify theme ZIP, or any return value.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents all three parameters with descriptions for name, role, and source. The tool description does not enhance the understanding of these parameters, so the schema's high coverage warrants a baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create a new theme' essentially restates the tool name without additional context. It identifies the action and resource but does not specify what a theme entails or differentiate from related operations like update_theme or publish_theme.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use or alternative tool references are provided. The description is silent on when to choose create_theme over the many sibling theme tools such as update_theme or publish_theme.
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 provided, the description carries the full burden of explaining behavioral implications. It only states 'update', implying mutation, but does not disclose whether updates are reversible, whether specific permissions are required, or what effects may occur on existing settings. No such details are provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only one short sentence, but this is under-specification rather than effective conciseness. It omits critical context and does not earn its place because it adds no value beyond the tool name. A concise description should be compact yet informative, which this is not.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 5 parameters, no output schema, and no annotations, yet the description provides almost no supporting context. It fails to describe what these privacy settings do, how they are grouped, or any side effects. For a mutation tool with multiple configurable fields, this is severely inadequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage for all five parameters, each with its own description. Therefore, the schema already provides sufficient parameter semantics, and the description does not need to compensate. The description adds no extra parameter information, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update privacy settings' simply restates the tool name without adding any specificity. It does not differentiate from sibling tools like get_privacy_settings or update_legal_policy, nor does it clarify what 'privacy settings' encompasses. This is essentially a tautology, providing no new information beyond the name itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives. There is no mention of prerequisites, typical use cases, or situations where a different tool (e.g., get_privacy_settings) would be more appropriate. The description is silent on usage context entirely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/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, but it only states the action without any consequences, side effects, or prerequisites. It does not mention whether approving a return is irreversible, what state changes occur, or any required permissions. This is a significant transparency gap 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.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short and front-loaded, but it is under-specified rather than appropriately concise. It lacks any contextual details that would help an agent decide when and how to use the tool, making it closer to a label than a functional description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although the tool is simple (one parameter, no output schema), the description provides barely more than the tool name. It does not explain the approval workflow, the impact on the return, or any related steps. The absence of annotations and behavioral details makes the description incomplete for safe and effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with a description for the single parameter 'returnId' (including an example format). The description itself adds no additional parameter semantics, but since the schema fully documents the parameter, a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Approve a return request' clearly states the action (approve) and resource (return request), making the tool's purpose unambiguous. It distinguishes itself from sibling tools like 'decline_return_request' through the verb, though it does not explicitly mention alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus siblings such as 'decline_return_request' or 'close_return'. There are no preconditions, state requirements, or exclusions mentioned. The usage is only implied by the name, offering no decision support for the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose any behavioral traits such as side effects, permissions, return values, or activation state. It merely restates the tool's name with no added context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely brief, but it is under-specified rather than concise. It provides no additional value beyond the tool name and is insufficient for a tool with five parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, no annotations, and a one-line description, the tool lacks context about return values, prerequisites, or post-creation behavior. The schema helps with parameters but does not make the overall usage context complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of the parameters with descriptions, so the baseline is 3. The description adds no parameter-level semantics beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and resource ('custom pixel'), which is specific. However, it does not explicitly differentiate from the sibling tool 'create_pixel' or explain the distinction between custom and regular pixels, so it lacks sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like 'create_pixel' or 'update_custom_pixel'. The description does not provide any context for selection, so it offers no usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations and a minimal description, the tool's behavioral traits are not disclosed. The description only implies a write operation but lacks details about side effects, required permissions, validation constraints, or whether creation is idempotent. This is a significant gap 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.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short and front-loaded, but it is under-specified. It does not provide enough context to be considered well-structured; it reads more as a tautology of the tool name rather than a helpful explanation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there are 9 parameters (6 required), no output schema, and no annotations, the description is woefully incomplete. It does not explain what a location is in the Shopify ecosystem, whether activation is needed, or how it relates to fulfillment options, leaving the agent to infer everything from the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters, so the baseline is 3. The description adds no extra meaning about parameters beyond what the schema already provides, and it does not clarify relationships or edge cases like which fields are optional for online ordering.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create a new location' clearly states the verb (create) and resource (location), distinguishing it from sibling tools like update_location, delete_location, or get_locations. It is specific enough to convey the primary action, though it does not elaborate on what a 'location' entails or any special semantics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention scenarios like creating a new store location or prerequisites such as existing fulfillment services. There is no explicit direction to use get_locations first to check for existing entries.
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 only implies a mutation via 'create' but does not describe side effects, whether duplicates are allowed, permissions required, idempotency, or the response format. This is a significant gap for a create operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short ('Create a resource feedback'), but this is under-specification rather than conciseness. It provides only the basic action and object without any useful elaboration, so it does not earn its place as a sufficient description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 4 required parameters, no output schema, and no annotations. The description does not cover return values, side effects, or usage context. The schema explains parameters, but the overall context is insufficient for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all four parameters, including enum values and an example for resourceId. The description adds no extra meaning beyond the schema, 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.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('create') and the object ('resource feedback'), which distinguishes it from sibling 'get_resource_feedbacks'. However, it does not explain what a resource feedback is, its purpose, or how it relates to the parameters, leaving the purpose somewhat vague.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention the sibling get_resource_feedbacks or any preconditions, making it hard for an agent to decide when to invoke this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full burden of behavioral disclosure. 'Delete a metaobject' merely restates the tool name and provides zero information about irreversibility, required permissions, cascading effects, or confirmation steps. It adds no behavioral context beyond the literal operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, but this is under-specification rather than concise effectiveness. It lacks any structured information that aids the agent. While it avoids fluff, it fails to include essential details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and no annotations, and the description provides only minimal context. Given the complexity of the system with many sibling delete tools, this description is insufficient for an agent to understand the full implications or requirements of the operation. It needs more context about the metaobject resource and deletion semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter 'id' with a description 'Metaobject ID', providing 100% coverage. The tool description does not add any further semantic detail, but since the schema already fully documents the parameter, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete a metaobject' uses a specific verb and resource, clearly identifying the action and target. It distinguishes from siblings like delete_metaobject_definition or delete_product because it explicitly references 'metaobject'. However, it lacks additional context about the scope or kind of metaobject.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites (e.g., metaobject existence), side effects, or situations where another delete tool might be more appropriate. The description offers no usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/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 'Delete a pixel' and does not reveal any consequences, irreversibility, permissions, or side effects. The description adds no behavioral context beyond the name itself.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely brief and front-loaded, with no wasted words, but it is under-specified. While concise, the three-word phrase lacks sufficient detail to be considered appropriately sized for a tool that might have nuances (e.g., distinguishing pixel types). It is not egregious but minimal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one parameter, no output schema), but the description is incomplete for contextual use. It does not mention any differences from similar delete tools, nor any effects of deletion. Given the sibling 'delete_custom_pixel', the description fails to provide enough context for correct selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of the parameter ('id') with a description. The tool description itself adds nothing beyond the schema, so the baseline score of 3 applies. No additional parameter meaning is conveyed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete a pixel' clearly states the action (delete) and resource (pixel). It is specific but does not distinguish between standard pixels and custom pixels, especially given the sibling tool 'delete_custom_pixel'. Thus it is clear but lacks sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'delete_custom_pixel' or other delete tools. It does not mention any prerequisites or context, leaving the agent without usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full behavioral burden. It simply states the action 'update' without any disclosure of side effects, permissions, failure modes, or whether it is a partial or full update. This is inadequate 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded. However, it is so minimal that it borders on under-specification, adding little value beyond the tool name itself.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema and annotations, and the simplicity of the tool, the description should explain what a cart transform is, prerequisites (existing transform ID), and any important behaviors. It fails to do so, leaving significant gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters. The description adds no additional parameter context, but the baseline is 3 due to full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'update' and resource 'cart transform', clearly stating the operation. However, it does not add any scope detail beyond the tool name, and while it distinguishes from create/delete siblings, it lacks specificity about what exactly can be updated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool vs alternatives like create or delete cart transform. The description implies it is for existing cart transforms, but no explicit context or exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for disclosing behavioral traits. 'Close a return' only states the action but does not explain side effects, permission requirements, reversibility, or the resulting return state. This is a significant omission for a mutation operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, using only two words with no fluff. It is front-loaded and efficient, though it may be too terse to be fully useful. For conciseness alone, it earns a high score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that this is a mutation tool with no annotations and no output schema, the description should explain what closing a return entails, possible states, and related operations. It provides none of this, making it incomplete for reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of the parameter (returnId) with a description, so the baseline is 3. The tool description adds no additional parameter context beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb-object structure ('Close a return'), clearly indicating the action and resource. However, it does not distinguish this from related return operations like 'approve_return_request' or 'decline_return_request', and the verb 'close' could have ambiguous meaning in the returns context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description gives no context, prerequisites, or exclusions, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/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 behavioral traits. 'Create a new market' only restates the operation and gives no information about side effects, duplicate handle handling, required permissions, or return values. This is essentially missing transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler or redundancy, and the key action is front-loaded. However, it is so terse that it sacrifices useful context, preventing a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although the tool is simple with only two parameters, there is no output schema and no annotations. The description omits return values, potential errors, usage patterns, and any relationship to other market tools, making it less than minimally viable for an agent to confidently invoke.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents both parameters: 'name' as 'Market name' and 'handle' as 'Unique handle for the market', providing 100% coverage. The tool description adds no extra parameter semantics, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Create' and resource 'market', clearly distinguishing it from sibling operations like get_market, update_market, and delete_market. However, it lacks any detail about what a market is or prerequisites, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as get_markets or update_market. There is no mention of exclusions, prerequisites, or contextual scenarios, leaving the agent to infer usage solely from the verb 'Create'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries full responsibility for disclosure. It only states the action without mentioning side effects, required permissions, idempotency, or return behavior—providing no more than the tool name implies.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no redundant text or filler. It is well-structured and front-loaded, though it is extremely terse and provides only the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 8 parameters, no annotations, and no output schema, the description is insufficiently complete. It does not explain return values, validation, or how this tool fits into workflows, though the schema covers parameter details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all 8 parameters documented in the input schema. The description adds no parameter-level meaning beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create a new marketing event' uses a specific verb and resource, clearly indicating the action for this tool. It distinguishes from update/get/delete siblings, though it doesn't explicitly contrast with alternatives like create_marketing_engagement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives, nor are prerequisites or contextual scenarios mentioned. The usage is only implied by the verb 'create' and the resource name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose any behavioral traits beyond the verb 'create'. It fails to mention side effects, required permissions, return values, or error conditions, placing the full burden on the description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no redundancy. It is front-loaded and to the point, though it could be more structured with additional context. It earns its place but is minimal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is incomplete for a create operation without annotations or output schema. It does not explain the lifecycle of payment terms, what a successful creation returns, or any special considerations. The schema provides parameter details, but the overall context is lacking.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage of parameter descriptions, so the baseline is 3. The description adds no parameter information, but the schema already defines all four parameters adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create new payment terms' clearly states the action and resource. It distinguishes from sibling tools like get_payment_terms and update_payment_terms by using 'create', but does not explicitly mention alternatives. It is clear and specific, but lacks explicit differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as update_payment_terms or delete_payment_terms. There are no prerequisites, contextual cues, or exclusions mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only says 'Delete a cart transform' with no annotations to rely on. It fails to disclose whether deletion is permanent, what happens if the transform does not exist, or any permissions required, which is critical for a mutating operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one short sentence with no fluff, earning a high score for brevity. However, it is so minimal that it misses opportunities to include valuable usage or behavior details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a simple delete operation with one parameter and no output schema, the description is not fully complete. It omits any mention of side effects, failure modes, or prerequisites, making it less useful than expected for a mutating tool with no annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema documents the single 'id' parameter with the description 'Cart Transform ID to delete,' providing full coverage. The tool description adds no additional parameter meaning beyond this.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete a cart transform' clearly states the verb (delete) and resource (cart transform), distinguishing it from sibling tools like get_cart_transforms, create_cart_transform, and update_cart_transform. However, it lacks any additional context about the delete operation's scope or consequences, so it is clear but not exceptional.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not mention when to use this tool versus other cart transform operations, nor does it specify any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility for disclosing behavioral traits. It only states 'Delete a collection' with no mention of permanence, cascading effects, authentication requirements, or error conditions. This is a destructive operation, yet the description fails to warn that deletion is irreversible or that it may fail if the collection is still published.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that states the action and target. It is front-loaded and free of fluff, though it could be considered too sparse given the destructive nature and lack of behavioral details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple deletion tool with one parameter and no output schema, the description should at least mention irreversibility, prerequisites (e.g., needing to unpublish), or side effects. None are provided, making the description incomplete for an agent that must safely invoke deletion operations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters with a description for 'id' including an example (e.g., 'gid://shopify/Collection/123456789'). The description adds no extra meaning beyond the schema, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a clear verb ('Delete') and resource ('collection'), making the primary action unambiguous. It distinguishes from siblings that operate on other resources (e.g., delete_product, delete_order), though it doesn't clarify which type of collection (smart vs. regular) is targeted.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It doesn't mention any preconditions (e.g., collection must be unpublished), restrictions, or contrast with sibling tools like create_collection or update_collection. The agent must infer usage solely from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/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 only states the action with no mention of irreversibility, side effects, permissions, or impact on published themes—critical missing context for a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise, front-loaded sentence with no wasted words. However, it is so minimal that it provides no extra context beyond the tool name, slightly reducing its structural value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter delete tool, the description is incomplete. It omits behavioral context such as whether the deletion is permanent, whether published themes can be deleted, and any related caveats—leaving important operational gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the 'id' parameter clearly described via an example. The description adds no additional parameter information, but the schema already fully documents the parameter, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete a theme' is a specific verb+resource phrase that clearly states the operation and target resource. However, it does not explicitly distinguish this tool from other delete_* siblings, though the resource name itself provides that distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not mention when to use this tool versus alternatives, nor does it address prerequisites or restrictions (e.g., cannot delete a published theme).
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 'fetch', which implies a read operation, but it doesn't state that it returns a paginated list, how status filtering works, or any other behavior. The schema hints at pagination but the description adds no behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short phrase, which is not verbose, but it's essentially a restatement of the tool name. It doesn't earn its place by adding any new information; it could be removed without losing clarity, making it redundant rather than concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description should explain what the tool returns and any pagination behavior. It fails to do so—'Fetch customer merge requests' doesn't indicate that it returns a list, that results are paginated, or that the status filter is available. The schema fills in some gaps, but the description alone is insufficient for complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides descriptions for all three parameters (after, first, status), covering 100% of parameter semantics. The description itself adds no parameter-related meaning, but since the schema is thorough, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a clear verb ('fetch') and resource ('customer merge requests'), making its purpose unambiguous. However, it doesn't add any distinguishing scope or context beyond the tool name itself, so it doesn't fully differentiate from sibling tools like request_customer_merge.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention whether it should be used to list pending merge requests, check merge status, or distinguish from other customer-related endpoints. There's no context or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/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. 'Fetch inventory levels' only states the action, with no information on return format, pagination, permissions, side effects, or error conditions. It adds nothing beyond the tool name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no wasted words. It is front-loaded with the verb and resource, making it structurally efficient despite being minimal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with three optional parameters and no output schema or annotations, this description is too sparse. It does not explain what the response contains, how parameters affect results, or how it differs from inventory mutation tools. Users would need to infer behavior from the name and schema alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description itself adds no parameter semantics beyond the schema, but the schema already documents all three parameters, making the tool adequately specified for parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches inventory levels for products, which is a specific verb+resource. However, it does not mention scope or explicitly distinguish it from sibling tools like get_inventory_shipments or adjust_inventory, though the verb 'fetch' implies a read operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives. It does not mention that this is for reading inventory levels as opposed to set_inventory or adjust_inventory, nor does it specify any prerequisites or contexts where this tool is preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden of behavioral disclosure. It merely restates the tool name without revealing side effects, destructive nature, reversibility, or any other operational traits. This offers no value beyond what the name already implies.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler or repetition. It is front-loaded with the action and resource, making it extremely concise and efficiently structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that this is a mutation tool with no annotations and no output schema, the description is too sparse. It lacks information about return values, side effects, or constraints. The schema descriptions are minimal, and the description adds no contextual completeness beyond a basic action statement.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% parameter coverage with descriptions for each field. The tool description adds no additional parameter semantics, but since the schema already documents the parameters, the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Remove line items from an order' clearly states the action and resource. It uses a specific verb and resource, but it does not differentiate from sibling tools like add_line_items_to_order or update_order, so it earns a 4.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, conditions, or exclusions. Since there is no usage context at all, it scores 2.
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?
The description only restates the basic function without disclosing behavioral details like permanence, required permissions, or what happens to the resource if all translations are removed. With no annotations provided, the description carries the full burden and fails to provide any meaningful safety or side-effect information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words, but it is under-specified rather than appropriately concise. It omits essential details about the removal process, making it too terse to be considered well-structured for an AI agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given 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, yet the description provides no information about return values, side effects, or the scope of what 'remove translations' entails. The description is too sparse to give an agent sufficient context for a mutation operation, especially given the presence of many related sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no additional parameter context beyond naming the resource generically, but the schema already fully documents each parameter (e.g., locales, translationKeys, resourceId), so the tool meets the minimum viability threshold.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the action ('Remove') and object ('translations') clearly, with the qualifier 'from a resource' indicating the scope. However, it does not distinguish itself from sibling tools like 'register_translation' or 'get_translations_for_resource', leaving the exact resource type and removal behavior ambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as registering a new translation or fetching existing ones. It neither states prerequisites nor provides exclusions, so an agent lacks context for choosing this over similar translation-related tools.
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 must carry the burden of behavioral disclosure. It only says 'update an existing customer', but does not mention partial updates, error handling, required permissions, or return values. This is insufficient 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.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
At one sentence, it is brief, but this is under-specification rather than effective conciseness. The phrase 'existing' adds no value beyond the tool name, and the description fails to include essential context for a 6-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 6 parameters, no annotations, and no output schema, yet the description does not explain update behavior, partial-update semantics, or what the response contains. The description is incomplete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for all 6 parameters, so the schema carries the burden. The description adds no parameter-level details, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates an existing customer, which is specific enough to distinguish from get_customer, create_customer, and delete_customer. However, it does not enumerate updatable fields or clarify partial-update semantics, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like create_customer or update_customer_address. No context, prerequisites, or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/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 of behavioral disclosure. It merely states 'Update an existing gift card' without mentioning whether it is a partial or full update, side effects, permission requirements, or idempotency. There is no additional transparency beyond the obvious mutation implication.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no filler words, making it easy to parse. However, it is arguably too terse to be maximally helpful, but for pure conciseness it earns a strong score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 3 parameters and no output schema or annotations, so the description must provide context about update semantics, but it only states the action. It is incomplete for a mutation tool because it leaves open whether unspecified fields are preserved or reset, and it doesn't mention any prerequisites like the gift card existing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: the input schema already documents 'id', 'note', and 'expiresAt' with clear descriptions. The tool description adds no additional semantic meaning beyond what the schema provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (update) and the resource (existing gift card), which distinguishes it from sibling tools like create_gift_card, disable_gift_card, and get_gift_card. However, it does not specify which fields or scope of update beyond the action itself, making it slightly generic.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The sibling list includes create_gift_card, disable_gift_card, and various gift card operations, but the description offers no contextual cues or exclusions to help an agent choose this tool appropriately.
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, so the description carries the burden of behavioral disclosure. It only states 'adjust' without explaining whether adjustments are incremental, how negative deltas are handled, if quantities can become negative, or any side effects. This is a significant transparency gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with no wasted words, but it is a fragment rather than a structured sentence. It under-specifies essential information, though it is not verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 3 required parameters and no output schema, the description is severely under-specified. It does not clarify the nature of the adjustment, the effect on inventory levels, or the expected outcome, leaving the agent with insufficient information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents all three required parameters with clear descriptions and 100% coverage. The description adds no additional parameter context, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'adjust' and resource 'inventory quantities', clearly indicating a modification operation. However, it does not explicitly distinguish from the sibling tool 'set_inventory', which could also modify inventory, so differentiation is lacking.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'set_inventory' or other inventory operations. The description is a bare phrase with no usage context or 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?
With no annotations, the description carries the full burden. It only states the action 'delete' without disclosing irreversibility, required permissions, cascading effects, or any side effects, which is significant for a delete operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and front-loaded with just four words. While efficient, it is arguably too terse; a few clarifying details about deletion behavior would not reduce conciseness significantly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a delete operation with no output schema and no annotations, the description is incomplete. It fails to mention return behavior, confirmation, or the destructive and irreversible nature of the action, which is critical context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (the single 'id' parameter is fully described in the schema), so the baseline is 3. The description adds no extra context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
"Delete a page" clearly states a specific verb and resource, and it distinguishes itself from siblings like get_page, create_page, and update_page. However, it lacks any qualifiers about what qualifies as a 'page' or the deletion scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor does it mention prerequisites, exclusions, or consequences. There is no context about when deletion is appropriate or allowed.
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 provided, the description carries the full burden of behavioral disclosure, but it only states 'Fetch store locations'. It does not mention pagination behavior (despite pagination parameters in the schema), default filtering, inactive location handling, or return format, leaving significant behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with no wasted words, but it borders on under-specification. The three-word phrase is efficient yet fails to provide adequate context, similar to a minimal stub rather than a properly structured description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters, no output schema, and no annotations, the description is too sparse. It does not explain pagination, filtering options, inactive flags, or return value expectations, making the description incomplete for an agent to invoke the tool correctly without additional assumptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents all 4 parameters with descriptions, achieving 100% coverage. The tool description adds no additional parameter semantics, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly uses the verb 'Fetch' with the resource 'store locations', which indicates the core purpose. However, it does not explicitly distinguish this list-style operation from the sibling tool 'get_location' (singular), so it is clear but lacks sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like 'get_location', 'get_collection', or other location-related tools. The description provides no context on appropriate use cases or 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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only says 'Fetch', which suggests a read operation, but does not describe what data is returned, whether it aggregates data, or any side effects. This is insufficient for a tool with no other behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loaded with the verb. It contains no wasted words, but the phrase 'home data and analytics' is somewhat repetitious. Overall, it is appropriately short for a tool with no parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is incomplete because it fails to explain what 'markets home data' actually includes or what 'analytics' refers to. Even for a simple no-parameter tool, the agent needs to know the return value's scope and purpose to select and invoke it correctly. The lack of output schema and annotations makes this gap more severe.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the input schema is trivially complete. There are no parameter semantics to describe, and the description correctly avoids inventing parameter details. Baseline of 4 is appropriate for a no-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Fetch' and identifies a resource ('markets home data and analytics'), but the resource is vague and undefined. It does not clearly distinguish itself from sibling tools like get_markets or get_market, as 'home data' is ambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. It does not mention related tools such as get_markets, get_market, or get_analytics_report, nor does it provide any context or exclusions. The agent must guess the intended use case.
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 bears full responsibility for behavioral disclosure. It only says 'Fetch', implying a read operation, but does not disclose pagination, return format, or how filters interact. The description adds no context about what a payout entails or what details are returned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no wasted words. It is front-loaded and easily parseable. However, it is almost under-specified for a tool with six parameters, so it loses a point for lacking any structural detail beyond the bare purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With six parameters, no output schema, and no annotations, the description is severely incomplete. It does not explain what payouts are, how the query or transactionType filters behave, or what the response contains. An agent would have no idea what data to expect or how to construct an effective request.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all six parameters. The description adds no extra parameter semantics, leaving the agent to rely on the schema. Baseline 3 is appropriate since the schema carries the burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a clear verb ('Fetch') and a specific resource ('Shopify Payments payouts'), making the core purpose unambiguous. However, it does not differentiate this tool from sibling payment tools like get_shopify_payments_balance_transactions or get_shopify_payments_disputes, so the distinction relies solely on the resource name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus its alternatives. The description does not mention query parameters, filtering behavior, or any prerequisites. With many similar Shopify Payments siblings, this lack of direction forces the agent to infer usage from the schema alone.
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 provided, the description carries the full burden of behavioral disclosure. It only says 'update', which implies mutation, but does not explain whether the update is partial or full, whether fields are replaced or merged, if there are any side effects, or what errors might occur. Minimal behavioral context is provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence with no wasted words, but it is under-specified. While concise, it could be slightly expanded to mention key behavioral details without becoming overly verbose. The structure is front-loaded but minimal for a tool with 4 parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This tool has 4 parameters, no output schema, and no annotations, placing the full burden on the description. The description only states the action and resource, omitting return values, the requirement of the id parameter, and how fields are applied. This is insufficient for the tool's complexity and leaves significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for all 4 parameters (100% coverage), so the baseline is 3. The tool description adds no additional parameter semantics beyond what the schema already states, such as relationships between fields or default behaviors.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update an existing collection' clearly states the action (update) and resource (collection), which distinguishes it from sibling tools like get_collection, create_collection, and delete_collection. It is specific enough to convey the core function, though it does not elaborate on which fields can be updated (covered by 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as create_collection or update_product. It does not mention prerequisites, when updating is appropriate, or exclusions. The description is purely a statement of action with no contextual direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits on its own. 'Update an existing discount code' reveals nothing about mutation side effects, required conditions, reversibility, or response behavior, making it inadequate 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence, which is appropriate in size. It is clear and front-loaded, though it could include more substantive context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters, no output schema, no annotations), this one-line description is severely incomplete. It fails to explain return values, updateable fields, or side effects, leaving the agent without essential context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with descriptions for all 7 parameters, so the baseline applies. The description adds no parameter-level meaning beyond what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update an existing discount code' clearly states the action (update) and resource (discount code). It distinguishes from sibling tools like create_discount, delete_discount, and get_discounts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, required fields, or scenarios that warrant updating an existing discount code.
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 provided, the description carries the full burden. It only restates the operation without disclosing behaviors like overwriting existing files, required permissions, or error conditions. The description adds no insight beyond the tool name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, making it concise, but it essentially rephrases the tool name 'upsert_theme_file' without adding new information. It is not poorly structured, but it lacks substantive content to earn a higher score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a mutation tool with no annotations, no output schema, and a minimal description. It fails to set expectations about what the operation does (e.g., whether it creates or updates, what happens to existing content, or what the response contains).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All four parameters are fully described in the input schema (100% coverage), so the description does not need to add parameter details. Baseline 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create or update a theme file' clearly identifies the action (upsert) and the resource (theme file), distinguishing it from read/delete theme file tools. However, it doesn't explicitly differentiate from generic file tools like create_file/update_file.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention when an upsert is appropriate, nor does it reference any sibling tools like create_file or update_theme.
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 full responsibility for disclosing behavioral traits. It only says 'cancel', with no mention of side effects, reversibility, timing (immediate vs end of billing period), or permission requirements. This is insufficient for a mutating operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence that is easily parsed and front-loaded with the key action. It is concise without unnecessary elaboration, though it arguably sacrifices substance for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite being a simple tool with one parameter and no output schema, the description omits critical context about cancellation behavior (e.g., immediate vs scheduled, impact on billing), which is especially important given the many sibling subscription tools. It does not provide enough information for safe and correct use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already fully describes the single parameter (subscriptionContractId) with 100% description coverage. The description does not add extra meaning 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb and resource ('Cancel a subscription contract'), which directly conveys the core action. However, it does not differentiate from sibling subscription tools like expire or fail, which could have similar meanings, leaving room for ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like pause_subscription_contract, expire_subscription_contract, or fail_subscription_contract. The description offers no context for decision-making, leaving the agent to infer usage from the tool name alone.
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 only says 'Close' without explaining side effects (e.g., whether it's irreversible, whether endingCash must match the recorded balance, what happens to the session after closing). This is a significant transparency gap for a state-changing operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no wasted words. It front-loads the core action, which is efficient. However, it is under-specified relative to the tool's complexity, but that is more relevant to completeness than conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given 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 is incomplete. It doesn't clarify the required ending cash, the business meaning of closing a session, return values, or error conditions. Sibling tools like get_cash_tracking_session provide context, but the description itself fails to give an agent enough to invoke correctly with confidence.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with meaningful descriptions for 'id', 'note', and 'endingCash'. The description adds no parameter-level detail, but the schema already documents the parameters sufficiently, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Close a cash tracking session' uses a specific verb ('close') and resource ('cash tracking session'), clearly distinguishing it from sibling tools like get_cash_tracking_session or create_cash_tracking_session. It is not a tautology and accurately states the action, though it lacks detail about the effect of closing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, no prerequisites (e.g., the session must be open), and no exclusions. It merely restates the action without contextualizing it relative to other cash tracking operations like add_cash_transaction or get_cash_tracking_session.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/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 states the action, with no mention of return values, side effects, prerequisites, or error conditions. For a create operation, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that is clear and free of redundant content. However, it is extremely brief and could benefit from additional detail, so it does not earn a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite 100% schema coverage, the description omits crucial context for a create operation: return value, the requirement of an existing company, and any behavioral side effects. With no annotations or output schema, this incompleteness leaves the agent uncertain about the outcome.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover 100% of parameters, so the baseline is 3. The description adds no additional parameter semantics beyond the B2B context, which is already implicit in the tool name and the companyId parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a new contact, scoped to B2B companies. It distinguishes from sibling tools like update_company_contact and delete_company_contact, and from customer contact creation, by the 'B2B company' qualifier.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor any prerequisites such as the company needing to exist. Usage is only implied by the verb 'create' and the required companyId in the schema.
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 provided, the description carries the full burden of behavioral disclosure. It only says 'Create,' implying a mutation, but gives no details on what actually happens, whether the action is reversible, what the return value is, or any side effects. The meaning of 'using a Shopify Function' is vague and unexplained.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that begins with the verb 'Create.' It contains no filler or unnecessary words. While very short, it is structurally concise and to the point, though it could be argued it is under-specified rather than concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema and no annotations to compensate for the sparse description. The tool creates a Shopify Function, but the description does not explain the functionId source, metafield purpose, or how this relates to the get_discounts_allocator_functions sibling. The minimal description is inadequate given the tool's complexity and lack of other contextual scaffolding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description itself mentions no parameters, but the schema already provides descriptions for functionId and metafields. The description adds no additional meaning beyond what the schema provides, so it stays at the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and the resource ('a discounts allocator function'), distinguishing it from sibling get_discounts_allocator_functions. However, the phrase 'using a Shopify Function' is somewhat redundant since a discounts allocator function is itself a Shopify Function, causing slight ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor any prerequisites. For instance, it doesn't mention that a get_discounts_allocator_functions call is needed first to obtain a functionId, nor does it explain the role of metafields. No exclusions or alternative tool references are given.
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 provided, the description must disclose behavioral traits. It merely states 'Create a new draft order' without mentioning any side effects, permission requirements, or how the draft order differs from a regular order. This is a significant gap 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The one-sentence description is concise and front-loaded, with no wasted words. It earns its place by stating the action clearly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create operation with 5 parameters and no output schema, the description is minimal. It does not explain the purpose of draft orders, expected return values, or any special behaviors. This is incomplete for an agent to use effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has full descriptions for all 5 parameters, including lineItems, note, tags, email, and phone. Since schema coverage is 100%, the description does not need to add parameter details; the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create a new draft order' uses a specific verb and resource, clearly indicating the action. However, it does not explicitly differentiate from the sibling tool 'create_order' beyond the name, so it lacks sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no context on when to use this tool versus alternatives such as 'create_order' or 'complete_draft_order'. There are no prerequisites or exclusion criteria mentioned.
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 provided, the description carries the full burden of behavioral disclosure. It only states what the tool does without revealing side effects, permissions, reversibility, or what happens to the order state. The description is too minimal to inform an agent about the consequences of calling this 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that immediately conveys the tool's function. There is no unnecessary verbosity or padding, making it well-structured and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having 4 parameters (including nested objects) and no output schema, the description offers minimal context. It doesn't explain what a fulfillment is, how it affects the fulfillment order, or what the response might contain. This is inadequate for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% description coverage for all parameters, so the schema already documents each field clearly. The description itself adds no parameter-level information, which is acceptable given the high schema coverage, hence a baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('create') and the resource ('a fulfillment for a fulfillment order'), making the tool's purpose unambiguous. However, it doesn't explicitly differentiate itself from similar tools like accept_fulfillment_request, though the verb 'create' provides some distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites such as the fulfillment order being open, or whether it should be used after accepting a fulfillment request. Sibling tools like accept_fulfillment_request and cancel_fulfillment_order exist but no exclusions are given.
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 provided, the description carries the full burden of behavioral disclosure. It only states the action ('Create a new inventory shipment') without mentioning side effects, required permissions, or what the resulting shipment entails. There is no indication of return value or impact on inventory levels, making the tool behaviorally opaque.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no redundancy. It gets directly to the point, but is perhaps too terse to be fully helpful. Given the brevity, it earns a solid score for conciseness, though it could be expanded without losing focus.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and no annotations, so the description is the only source of contextual information beyond parameter names. It explains neither the return value nor any side effects or prerequisites. For a creation tool with conceptually similar siblings, the description is insufficiently complete for reliable agent selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all four parameters, including nested line items, so the schema already documents parameter semantics. The description adds no extra meaning beyond what the schema provides, warranting the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('Create') and resource ('inventory shipment'), but it does not distinguish this tool from the sibling create_inventory_transfer, which is conceptually similar. The scope and specific meaning of 'inventory shipment' are not elaborated, so it lacks the full differentiation expected for 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 Guidelines2/5
Does 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 alternatives. With sibling tools like create_inventory_transfer and receive_inventory_shipment, the absence of usage context leaves the agent to guess which operation is appropriate. No exclusions or preconditions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description offers no behavioral context beyond the action itself. With no annotations, it fails to disclose permissions, uniqueness constraints, or the effect of duplicate handles, leaving the agent to guess about side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence with no filler, clearly front-loaded. It is concise and to the point, though it could be expanded with more context without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the schema covers parameters, the description lacks usage guidance and behavioral transparency. Without an output schema, the agent receives no information about the return value or side effects of creation, making the tool under-specified for reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides descriptions for all three required parameters (type, handle, fields), so the description adds no additional parameter semantics. Schema coverage is 100%, and the description does not enrich the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create a new metaobject' uses a specific verb and resource, clearly distinguishing it from sibling tools like update_metaobject, delete_metaobject, and create_metaobject_definition.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided; the description does not specify when to use this tool versus alternatives such as update_metaobject or create_metaobject_definition. There is no mention of prerequisites, exclusions, or recommended scenarios.
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 states the tool creates a new pixel, implying a mutation, but does not mention required permissions, idempotency, side effects, or what the response contains. For a write operation without annotations, this lack of detail is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence that efficiently conveys the core purpose without unnecessary words. However, it is so brief that it borders on under-specification, though for such a simple tool, brevity is acceptable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with fully documented parameters, but the description lacks contextual information about when to use it, how it differs from creating custom pixels, or any return value expectations. While the schema covers the parameters, the absence of usage guidance and behavioral detail leaves the description minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema describes both parameters (name and apiKey) with clear descriptions, achieving 100% coverage. The tool description adds no additional meaning beyond what the schema already provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create a new pixel' clearly states the action (create) and the resource (pixel), which is specific and unambiguous for a basic create operation. However, it does not explicitly differentiate from the sibling tool 'create_custom_pixel', which could cause confusion since both are creation tools for different pixel types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like 'create_custom_pixel' or 'update_pixel'. The description provides no context about prerequisites, intended use cases, or exclusions, so an agent is left without direction on selecting this tool correctly.
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 convey behavioral traits. It only states that a new price rule is created, but does not disclose side effects, whether the operation is reversible, required permissions, or what the response contains. For a mutation tool, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the core action. It is concise and free of fluff. However, it is so brief that it omits any supplemental context, which prevents a perfect score. Still, it earns a 4 for being appropriately sized and immediately understandable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 10 parameters, no annotations, and no output schema, the description is quite thin. It does not explain what the created price rule will do beyond 'automatic discounts', nor does it mention return values, required fields, or how to configure the rule. The schema provides parameter details, but the overall context is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all 10 parameters with descriptions, so schema description coverage is 100%. The tool description adds no parameter information. Per the rubric, a baseline of 3 is appropriate when the schema does the heavy lifting. The schema descriptions are clear enough, so no deduction is taken.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create a new price rule for automatic discounts' clearly identifies the action (create) and resource (price rule), and adds context that it is for automatic discounts. This distinguishes it from sibling tools like get_price_rule, update_price_rule, and delete_price_rule. It could be more specific about the type of price rules or discount behavior, but it is not a tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives (e.g., update_price_rule for existing rules, or get_price_rules to list). It does not mention prerequisites, scenarios, or exclusions. An agent would have no context on when creating a price rule is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so the description must disclose behavioral traits. It merely states 'Create a new script tag' with no information about side effects, caching behavior, permission requirements, or irreversibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, but it could have included a bit more context without becoming verbose. It is minimally adequate.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations and no output schema, the description is too sparse for a creation tool. It doesn't explain the purpose of script tags, the effect of creation, or the return value, leaving the agent under-informed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers all three parameters with descriptions, so the description adds no additional parameter meaning. Per the rubric, high schema coverage (>80%) warrants a baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'create' with the resource 'script tag,' clearly indicating the action and target. This distinguishes it from sibling tools like get_script_tag, update_script_tag, and delete_script_tag.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool, prerequisites, or alternatives. Context signals show no mention of use cases or 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?
With no annotations provided, the description carries the full burden of disclosing behavioral traits. It only states the action 'Create' (implying mutation) but gives no details about side effects, return values, lifecycle of the staged upload, or any constraints like expiration or file size limits. This is a significant gap for a tool that creates a stateful resource.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that directly states the tool's purpose. It is appropriately sized with no wasted words, earning full marks for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 required parameters, no output schema, and no annotations, the description is insufficient. It does not explain what the 'staged upload target' is, how the response should be used (e.g., for uploading the file), or any associated constraints. This lack of context could lead to incorrect usage or failure to complete the intended workflow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with each parameter described accurately in the schema. The description adds no additional meaning beyond the schema, such as how the parameters relate to the staging process or whether there are interdependencies. Baseline of 3 is appropriate since the schema handles parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and the target ('a staged upload target'), and the purpose ('for file upload'). It distinguishes itself from sibling file tools like create_file by indicating a staging step, though the concept of 'staged upload target' is not further explained.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor any mention of prerequisites or follow-up steps. The description is a single statement without context on the upload workflow, leaving the agent to infer the tool's role.
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 only states 'Create a new subscription contract' without mentioning side effects, permissions, reversibility, or any additional behavioral traits. This is a significant gap for a create operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words. However, it is under-specified and lacks important context, which is penalized in other dimensions. For conciseness alone, it is efficient but could benefit from additional detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations, no output schema, and the complexity of subscription contracts, the description is incomplete. It fails to explain what a subscription contract entails, the significance of required fields, or how this differs from 'create_subscription_contract_atomic'. More context is essential.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage for the three parameters, each with a description. The tool description adds no additional parameter semantics beyond what the schema already defines, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action and resource: 'Create a new subscription contract'. However, it does not distinguish from the sibling tool 'create_subscription_contract_atomic', which also creates subscription contracts, so it lacks differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'create_subscription_contract_atomic' or when not to use it. There is no mention of prerequisites or context, leaving the agent without direction.
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, so the description carries the full burden. It mentions 'single operation' implying atomicity but fails to disclose side effects, required permissions, error behavior, or what 'complete' entails (e.g., billing, collection). This is a significant gap for a creation 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no unnecessary words. It is front-loaded with the action and resource, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the complexity (9 parameters, 8 required, no annotations, no output schema), the description is extremely terse. It does not explain return values, side effects, or how it differs from create_subscription_contract. This is inadequate for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so the schema itself documents all parameters. The description adds no extra semantic value beyond the schema, which meets the baseline but does not improve upon it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Create') and resource ('subscription contract') with qualifiers 'complete' and 'in a single operation', which clearly indicates the tool's function and hints at atomicity. However, it does not explicitly name the sibling tool create_subscription_contract to differentiate, so it is clear but not fully distinguished.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is provided about when to use this tool versus alternatives such as create_subscription_contract. The phrase 'in a single operation' implies a use case, but there is no clear context, prerequisites, or 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?
With no annotations, the description carries full responsibility for behavioral disclosure. It does not mention potential side effects, balance checks, reversibility, or any required permissions, which is critical for a financial mutation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasted words. It is front-loaded and appropriately sized for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
As a financial mutation with no annotations or output schema, this description is insufficiently complete. It lacks warnings about insufficient funds, currency mismatches, or irreversibility, which an agent needs to use the tool safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides full descriptions (100% coverage) for all three parameters. The tool description adds no additional meaning beyond the schema, so it meets the baseline but does not exceed it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Debit') and resource ('store credit account'), clearly indicating the action. It implicitly distinguishes from the sibling 'credit_store_credit_account' but does not explicitly name the alternative, so it doesn't fully meet the 5-point bar.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'credit_store_credit_account'. The description only states what it does, not when or under what conditions it should be used.
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 operation 'Delete a discount code' without disclosing irreversibility, effects on active discounts, associated data, or required permissions. This is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded, and free of unnecessary words. Appropriate for a simple tool, though it lacks extra context that could be added without bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one well-documented parameter, but the lack of annotations and absence of behavioral context means the description is only partially complete. It states what it does but not when to use it, side effects, or prerequisites.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single id parameter that is fully described in the schema. 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Delete' and the resource 'discount code', making the tool's function unambiguous. It distinguishes from sibling delete tools by specifying the discount code resource, though it doesn't elaborate on the distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, such as delete_price_rule or other delete tools. It provides no contextual cues for selection, no prerequisites, or 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 full responsibility. It only states the action without disclosing irreversibility, permission requirements, cascading effects, or response behavior. The verb 'delete' implies destruction, but that's the purpose, not behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no extraneous words. It front-loads the essential information. However, its brevity borders on under-specification, trading detail for concision.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the context of many sibling tools and no output schema, the description is incomplete. It doesn't explain return values, error conditions, or consequences. For a destructive operation, more detail is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents the single 'id' parameter with the description 'Market ID to delete', achieving 100% coverage. The tool description adds no additional parameter semantics or format expectations. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete a market' states a clear verb and resource, distinguishing it from sibling market tools like get_market, create_market, and update_market. The purpose is unambiguous. However, it doesn't elaborate on scope or any special conditions, so it's clear but minimal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not mention prerequisites, when to use this tool versus other delete_* tools, or any side effects. Sibling tools like delete_collection, delete_product, etc., are indistinguishable in terms of usage context.
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 provided, the description carries the full burden of disclosing behavioral traits. It simply says 'Delete a marketing event' without stating that the action is irreversible, whether it requires special permissions, or what side effects may occur. This is a significant gap for a destructive 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with no filler or redundancy. It efficiently communicates the core purpose, which is ideal for a simple delete operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a simple deletion with one parameter and no output schema, but the description is extremely minimal. It does not explain the irreversible nature, potential dependencies, return values, or any error conditions. Given the lack of annotations, the description is insufficient to fully guide an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage: the only parameter 'id' is described as 'Marketing Event ID to delete'. The description adds no additional meaning beyond this, but since the schema fully documents the parameter, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete') and the resource ('a marketing event'), which is specific and distinguishes it from sibling tools like get_marketing_event or update_marketing_event. However, it lacks any additional context that would differentiate it from other delete tools or clarify the scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, whether there are other ways to remove a marketing event, or situations where deletion might be inappropriate. The user is left with no context beyond the tool's name.
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 'delete' without mentioning whether the action is permanent, requires specific permissions, or has cascading effects on related data. This is a significant gap for a destructive 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, grammatically complete sentence with no redundant words. It is appropriately sized for a tool with one parameter and no output schema, 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.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (one parameter, no output schema), the description could be considered adequate in isolation. However, because there are no annotations and no usage guidelines, the description lacks essential contextual safety information for a destructive operation, making it incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers the single parameter 'id' with a clear description ('Payment Customization ID to delete'), achieving 100% coverage. The tool description adds no additional parameter meaning, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete') and the specific resource ('payment customization'), making the purpose unambiguous. It distinguishes from sibling delete tools like delete_payment_terms and delete_delivery_customization through the unique resource name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, no prerequisites, and no mention of scenarios where deletion might be inappropriate. It is a bare statement with no contextual direction.
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 provided, the description must disclose behavioral traits. It only states the action 'delete' without mentioning permanence, required permissions, potential cascading effects, or whether the operation is irreversible. This is a notable gap for a destructive 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a concise single sentence that immediately communicates the action and resource. No filler or redundant information; every word is meaningful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of annotations and output schema, the description should offer more context for a destructive operation. It fails to address consequences like permanence or side effects, making it incomplete for an agent to fully understand the tool's impact.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes the only parameter ('id' as 'Validation ID to delete'), providing 100% coverage. The description adds no extra semantic value beyond the schema, so it is adequate but not enhanced.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('Delete') and the resource ('a validation rule'), which is distinct from sibling delete tools targeting other entities. However, it provides no additional scope or context about what a validation rule is, so it doesn't fully earn a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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, prerequisites (e.g., the rule must exist), or alternatives. It does not mention whether this is for removing invalid or obsolete rules, nor does it direct users to related tools like update_validation.
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 provided, the description must carry the full burden of behavioral disclosure, but it only states the action. It does not mention what happens when a gift card is disabled (e.g., whether it can be re-enabled, if existing balances are affected, or if it's a destructive or reversible operation).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—one sentence, four words—with no wasted words. It front-loads the verb and resource clearly. However, it is arguably too brief to be considered fully helpful, but the conciseness dimension rewards efficiency over completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a state-changing tool on a monetary entity, the description is incomplete. It lacks context on side effects, idempotency, or whether disabling is reversible. There is no output schema, and the absence of annotations makes this minimal description insufficient for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% description coverage; the 'id' parameter is already described as 'Gift Card ID to disable'. The description adds no additional meaning beyond what the schema 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Disable a gift card' clearly states the action (disable) and the resource (gift card). It is specific enough to distinguish it from other gift card tools like create/update/get, but it doesn't explicitly differentiate it from update_gift_card, which could also be used to toggle status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool vs. alternatives. There is no mention of prerequisites, whether this is the preferred method for disabling versus updating a gift card, or any exclusions. Sibling tools like update_gift_card exist but are not referenced.
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 explaining behavior. It only states the action without disclosing effects such as whether the contract ends immediately, impacts billing, or is reversible. For a mutation tool, this is a significant gap 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with zero wasted words, making it concise and front-loaded. However, it could include additional context without becoming verbose, so it is slightly above average but not exceptional.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations, output schema, and clear explanation of side effects, the description is incomplete. It fails to communicate the state change, return value, or any prerequisite conditions, making it insufficient for an agent to understand the full impact of using the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description covers 100% of the parameter (subscriptionContractId) with 'Subscription Contract ID to expire'. The description adds no further meaning, but baseline of 3 is appropriate because the schema already fully documents the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Expire a subscription contract' uses a specific verb and resource, making the tool's purpose clear. It does not explicitly differentiate from siblings like cancel_subscription_contract or pause_subscription_contract, but the verb 'expire' is distinct enough to indicate a specific action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as cancel, pause, or fail subscription contract. The description simply restates the action without any context, exclusions, or references to sibling tools.
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 provided, the description carries the full burden of behavioral disclosure. It implies a read-only fetch but does not mention any limitations, such as required date ranges, pagination, potential errors, or what counts as 'analytics reports and metrics'. This is insufficient for a tool without structured safety hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence, front-loaded with the verb and resource, and contains zero unnecessary words. It is highly concise and easy to parse, though it omits some critical context that would be expected for a tool of this complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has four parameters, no output schema, and no annotations, the description is far too sparse. It does not explain return formats, filtering behaviors, granularity effects, or any operational details. For a report-fetching tool, this leaves the agent with substantial unknowns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for all four parameters, including enum values and ISO format requirements. The tool description adds no additional meaning beyond restating the resource type, so it neither enhances nor detracts from the schema. The baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Fetch' and resource 'analytics reports and metrics from Shopify', making the primary action and target evident. However, it does not distinguish this from siblings like get_reports or run_report, which may overlap in scope, so it lacks explicit differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 alternatives. It does not mention any specific scenarios, exclusions, or relationship to sibling tools like get_report or run_report, leaving the agent to infer usage.
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 the full burden. 'Fetch' implies a read-only operation, but it doesn't disclose pagination behavior (e.g., using 'after' and 'first'), default page size, or that filtering by date/location is supported. It also doesn't mention what the response contains, leaving the agent without essential behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that immediately front-loads the verb and resource. There is no redundant information or fluff; every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 5 parameters, no annotations, and no output schema, so the description must compensate by explaining return values and behavior. It only says 'fetch sessions', omitting pagination defaults, response shape, and the fact that it supports filters. This is insufficient for the agent to understand what the tool returns and how to effectively invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All five parameters are fully documented in the input schema (100% coverage), so the description adds no additional semantic value. The schema already explains each parameter (pagination cursor, page size, date filters, location filter). Therefore, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Fetch') and resource ('cash tracking sessions') for POS. The plural 'sessions' suggests a list operation, distinguishing it from the singular sibling 'get_cash_tracking_session'. However, it does not explicitly say 'list all' or mention alternative tools for single-session retrieval, so it misses full differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. It doesn't mention the singular get_cash_tracking_session for retrieving one session, nor does it explain the intended use case like listing sessions within a date range or for a specific location. The description provides no contextual usage advice.
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 merely states the action without mentioning pagination behavior, return format, ordering, or any filtering limitations. The schema provides some context, but the description adds no behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no unnecessary words. It is appropriately sized and front-loaded for a simple list operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the large sibling set including get_channel, the description is too terse to provide sufficient context. It does not clarify the list nature, pagination, or how it differs from fetching a single channel, making it incomplete for an agent to select confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear descriptions for both 'after' and 'first'. The description adds no additional parameter meaning, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Fetch' and the resource 'sales channels for the store', clearly indicating a read/list operation. The plural form distinguishes it from the sibling 'get_channel', though it does not explicitly contrast the two.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like get_channel. There is no mention of exclusions, prerequisites, or the appropriate scenario for listing channels.
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 provided, the description carries the full burden of behavioral disclosure. While 'Fetch' implies a read operation, the description does not disclose pagination behavior, default results, scoping to specific sales channels, or any other operational details beyond what the schema provides. It adds minimal behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no redundancy or filler. It is front-loaded with the action and resource, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is insufficient for a complete understanding. It does not explain what 'collection listings' refers to, how it differs from 'get_collections', or what the return structure looks like. Given no output schema and the existence of closely related sibling tools, more contextual detail is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% description coverage for both parameters ('after' and 'first'), so the schema already documents their semantics. The description adds no extra parameter information, which is acceptable given the high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Fetch') and resource ('collection listings'), and it is clearly distinct from the broader 'get_collections' or 'get_collection' siblings. However, it does not explicitly differentiate itself from those related tools, and the term 'collection listings' is somewhat ambiguous without additional context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'get_collections' or 'get_product_listings'. There is no mention of typical use cases, prerequisites, or when other tools would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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. 'Fetch' implies a read-only operation, but the description does not mention pagination behavior, response format, or any side effects. It adds minimal context beyond the obvious read nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no unnecessary words. It is front-loaded and to the point, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having 5 parameters and no output schema, the description does not explain what the tool returns or how pagination works. It only states the basic fetch action, which is insufficient for an agent to fully understand the tool's behavior without external knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are well-documented in the schema. The description itself adds no parameter details, but the baseline of 3 is appropriate since the schema handles the semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Fetch collections from the Shopify store' clearly identifies the action (fetch) and resource (collections), and the plural form differentiates it from the sibling tool 'get_collection' (singular). It is specific enough to avoid confusion, though it lacks additional detail about listing or filtering.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'get_collection'. The plural name implies it fetches multiple collections, but the description does not explicitly state that or mention any exclusions or preferred contexts.
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 only says 'Fetch B2B companies', implying a read operation, but does not mention pagination, sorting, filtering, default limits, or what data is returned. This is insufficient for a listing endpoint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no unnecessary words. It is front-loaded with the action and resource. However, given the tool's complexity (5 optional parameters, pagination, filtering), the extreme brevity may border on under-specification.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is too minimal for the tool's complexity. It does not mention return format, pagination behavior, filter syntax, or differentiation from related tools. Since there is no output schema and no annotations, the agent lacks essential context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides detailed descriptions for all five parameters, so the baseline is 3. The description adds no additional meaning beyond the schema, but no compensation is needed given the high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (fetch) and resource (B2B companies), and the plural form implies a list operation. However, it does not explicitly differentiate from the sibling get_company or other query tools like get_products, and does not mention filtering or pagination capabilities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as get_company, search_products, or get_customers. No context is provided about typical use cases or 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 'Fetch', implying a read operation, but does not mention pagination behavior, return format, permissions, or potential rate limits. This is insufficient for a no-annotation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three words with no waste or redundancy. It is front-loaded and efficiently states the core action. However, it is so terse that it borders on under-specification, which slightly reduces the score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should explain what the tool returns, but it only mentions 'fetch delivery profiles' without describing the structure, pagination, or contents of the returned data. Given the low complexity, the description is barely adequate for selecting the tool but lacks crucial return-value context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes both parameters thoroughly: 'after' as a cursor for pagination and 'first' as a number of profiles to fetch (1-250, default 50). Since schema coverage is 100%, the description does not need to add parameter details; it adds no extra meaning but the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Fetch' and the specific resource 'delivery profiles', which distinguishes it from sibling tools like get_delivery_customizations or get_delivery_option_generators. However, it lacks scope details such as what constitutes a delivery profile or how the returned data is structured.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor does it mention any exclusions or contextual scenarios. With many delivery-related sibling tools present, the absence of usage direction leaves the agent guessing.
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 provided, the description carries the full burden of behavioral disclosure. It merely states 'Fetch' without mentioning pagination behavior, default limits, sorting, filtering, or any side effects. This leaves the agent uninformed about important operational characteristics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no redundant wording. It is appropriately front-loaded, though it could be slightly more informative without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and no annotations, the description is incomplete. It does not clarify return format, pagination behavior, or how the optional parameters (e.g., 'query', 'reverse') affect results, leaving significant gaps for a 4-parameter retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all 4 parameters with descriptions, so the baseline is 3. The description adds no additional parameter semantics beyond what the schema already provides, which is acceptable given full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Fetch draft orders from the store' uses a specific verb and resource, clearly indicating the tool retrieves draft orders. The plural 'draft orders' distinguishes it from the sibling 'get_draft_order' (singular), though it does not explicitly state this differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'get_draft_order' or 'get_orders'. The description entirely lacks context about use cases, exclusions, or selection criteria.
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 must disclose behavioral traits, but it only states 'Fetch gift cards' with no mention of read-only nature, pagination, filtering, or any side effects. The tool likely returns a list, but this is not stated, and no details on rate limits or auth are provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, a single sentence of six words, and is easy to parse. However, it is almost too sparse, offering no additional context that could aid tool selection, making it efficient but minimal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite a well-documented schema, the description is incomplete for a tool with pagination and filtering capabilities. It does not mention that it returns a list of gift cards, that results can be paginated, or how it relates to the singular get_gift_card. With no output schema, the agent lacks information about the return value.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with detailed descriptions for all five parameters, including pagination, filtering, sorting, and defaults. The description adds no parameter information 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Fetch gift cards from the store' clearly states the action (fetch) and resource (gift cards), and the plural form distinguishes it from the singular get_gift_card sibling. It is concise and specific, though it does not explicitly mention that it supports listing/pagination.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like get_gift_card or get_gift_card_transactions. The description gives no context about common use cases, prerequisites, or exclusions, leaving the agent to infer usage from the schema.
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 must disclose behavioral traits. 'Fetch' implies a read-only operation, but the description does not mention that results are paginated (cursor 'after', 'first' limit) or what the response structure looks like. It essentially restates the tool name without adding meaningful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence with no fluff or repetition. However, it is so minimal that it borders on under-specification; still, it is concise and front-loaded with the verb and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a list operation with pagination parameters, no output schema, and no annotations. The description fails to communicate that the tool returns a list/collection of transactions, that results are paginated, or any other context needed to understand its full behavior. The schema hints at pagination but the description does not reinforce or explain it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage of all three parameters with descriptions (giftCardId, after, first), so the description does not need to add parameter details. The description adds no extra semantics beyond the schema, securing the baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource ('gift card transactions') and the action ('Fetch'), which distinguishes it from sibling tools that deal with gift cards themselves (e.g., get_gift_cards, credit_gift_card). However, it lacks any scope nuance (e.g., 'all transactions' or 'by gift card'), so it does not fully differentiate within the transactions domain.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives like get_gift_cards, get_gift_card, or credit_gift_card. There is no mention of typical use cases, prerequisites, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description falls short of disclosing behavioral traits. It only says 'fetch,' which implies a read operation, but says nothing about pagination, filtering, sort behavior, or whether it returns all shipments or a subset. The agent is left to infer critical operational details from the schema alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no filler or repetition. It front-loads the key action and resource. However, its brevity borders on under-specification given the tool's parameter complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with five parameters and no output schema, this description is too minimal. It fails to mention that this returns a list, supports pagination/filtering, or clarify relationship to singular get_inventory_shipment. The absence of return-type context and operational details makes it incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for all five parameters, so the schema already documents their meaning. The description adds no parameter semantics, but the baseline of 3 is appropriate since the schema does not require compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Fetch') and resource ('inventory shipments for the store'), making the primary purpose unambiguous. However, it does not explicitly differentiate from the sibling tool 'get_inventory_shipment' (singular), though the plural form implies a list operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as the singular 'get_inventory_shipment' or related inventory transfer tools. The description lacks any context about use cases, prerequisites, or 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. 'Fetch' implies a read operation, but it does not disclose pagination behavior, default limits, filtering semantics, or whether any side effects occur. The schema mentions pagination params, but the description adds no behavioral context beyond the bare action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the main action, and contains no fluff. However, it is so brief that it borders on under-specification, but that is more a completeness issue than conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With three optional parameters and no output schema, the description should provide more context about what 'received items' means, how filtering and pagination work, and what the response looks like. The current text is too minimal to give a complete picture of the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and each parameter (after, first, inventoryItemId) has a clear description in the schema. The tool description adds no additional meaning beyond the schema, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Fetch inventory items received in shipments' clearly states the verb (fetch) and resource (inventory items received in shipments). It is distinct enough from sibling tools like get_inventory_shipments, though it does not explicitly state how it differs from those alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like get_inventory_shipments or receive_inventory_shipment. There are no contextual cues about typical use cases or 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?
With no annotations, the description carries the full burden of behavioral disclosure, but it only states 'Fetch marketing events' which implies a read without detailing pagination, filtering, sort options, or return format. The schema hints at such capabilities, but the description fails to disclose them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no fluff, effectively stating the core action. While it could include more detail, the structure is clean and front-loaded, earning a 4 rather than 5 due to missing useful context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate complexity (5 parameters, no output schema, no annotations), the description is too thin. It neither explains what marketing events are, how to paginate, nor what the response contains, leaving the agent under-informed for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all five parameters clearly described in the input schema. The description adds no parameter information, but the schema already fully documents them, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Fetch marketing events for the store' clearly indicates a read operation for a plural resource, distinguishing it from the singular get_marketing_event sibling. However, it doesn't explicitly say 'list' or clarify that it returns multiple events, leaving slight ambiguity about whether it fetches a single event or many.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description does not mention that get_marketing_event should be used for a single event, nor does it indicate any prerequisites or comparisons with create/update/delete marketing event tools.
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 burden of behavioral disclosure. It only states 'Fetch', implying a read operation, but does not explain what an integrated campaign is, how it differs from marketing events, whether pagination is handled, or any access constraints. This is minimal and insufficient for a tool with such a vague resource concept.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at five words, front-loading the key action and resource. There is no redundant information, but the brevity borders on under-specification rather than efficient communication.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a paginated fetch operation, but with no output schema and no annotations, the description should clarify what 'integrated campaigns' are and what the response contains. It offers only a bare minimum purpose, leaving the agent without enough context to reliably invoke the tool or handle results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for both parameters ('after' and 'first'), so the schema already documents their purpose. The description adds no additional meaning beyond the schema, fitting the baseline of 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Fetch marketing integrated campaigns' uses a specific verb and resource, making it clear that the tool retrieves integrated campaigns. However, it does not distinguish this tool from siblings like get_marketing_events or get_marketing_event, so while the purpose is clear, differentiation from alternatives is missing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool compared to other marketing-related tools in the sibling list. There is no mention of scenarios, prerequisites, or exclusions, leaving the agent to infer usage solely from the name and schema.
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 full weight. It simply says 'Fetch', implying read-only but not stating it. No disclosure about return format, pagination behavior, rate limits, or whether it lists all templates or requires filters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One short, focused sentence with no filler. It is appropriately sized for a simple fetch operation, though slightly under-specified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, but the description omits return value expectations and pagination behavior. No output schema exists, and the description doesn't mention that it returns a list of templates or how pagination works. Minimal information for an agent to fully understand invocation results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover 100% of parameters (after, first). The description adds no parameter context, but the schema already documents cursor and count semantics. Baseline 3 is appropriate when schema handles the details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses a specific verb ('Fetch') and resource ('packing slip templates'), clearly distinguishing it from sibling create/update/delete operations. It doesn't differentiate from other 'get' tools, but the resource is specific enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. It doesn't mention pagination strategy, ordering, or any prerequisites. The context implies read operation, but no explicit 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.
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 basic action without disclosing pagination behavior, response format, or potential side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words. It is concise and front-loaded with the core action, though it lacks additional structural detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has 5 parameters and no output schema, yet description provides only the core action. Missing essential context about pagination, sorting, filtering, and return structure, making it insufficient for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover 100% of the 5 parameters, including defaults and enums, so the schema already provides full parameter semantics. The description adds no extra meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly indicates a read operation for online store pages using the verb 'Fetch' and resource 'pages'. However, it does not distinguish from the sibling tool get_page, which is the singular counterpart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance provided on when to use get_pages versus alternatives like get_page. No context on filtering, sorting, or prerequisites is given.
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 merely states 'Fetch pixels' but does not mention that it is a read-only operation, that it returns a paginated list, or any default behavior. This is insufficient for a tool with no annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. However, it is under-specified and could include more useful context without becoming verbose. For a simple tool, it is concise but not as informative as it could be.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has only 2 parameters with full schema coverage, and no output schema. The description is minimal and does not explicitly state that it returns a paginated list of pixels or clarify the default limit, but the plural 'pixels' and pagination params imply this. It is adequate for a simple fetch but leaves room for improvement.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes both parameters ('after' and 'first') with clear descriptions, so the baseline is 3. The description adds no additional meaning beyond what the schema already provides, which is acceptable given the high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The verb 'Fetch' and resource 'pixels' clearly indicate the action and target. However, it doesn't explicitly differentiate from sibling tools like get_custom_pixels or get_pixel, though the plural 'pixels' and the name itself help. It's clear but lacks scope specificity like 'all' or 'list'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as get_pixel for a single pixel or get_custom_pixels for custom pixels. No use case or exclusions are mentioned, leaving the agent without context for 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?
With no annotations, the description carries the full burden of behavioral disclosure. It implies read-only through 'Fetch' but does not explain pagination, default limits, filtering behavior, or response format, which are critical for an effective agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasted words, front-loading the action and resource. It could be expanded with usage context, but for its length it is appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 5 optional parameters and no output schema, yet the description only states the basic purpose. It omits common usage patterns, return value expectations, or any caveats, making it insufficient for full agent comprehension.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already provides clear descriptions for each parameter (cursor, limit, query, sort, reverse). The tool description adds no additional parameter semantics, but the baseline 3 is appropriate given the schema's thoroughness.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action (Fetch) and resource (price rules) with a specific purpose (for automatic discounts). However, it does not explicitly differentiate between this and the sibling get_price_rule tool, though the plural form hints at a list operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives like get_price_rule, get_discounts, or create_price_rule. The description only states the basic function without any context or 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?
With no annotations, the description carries the full burden of behavioral disclosure. It fails to mention that the operation is read-only, that pagination is available via the 'after' cursor, or that results are limited to product listings rather than all products. This leaves safety and side-effect behavior entirely unspecified.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler or redundancy. It is appropriately concise for the core purpose, though it sacrifices depth for brevity. It earns a 4 rather than 5 because it doesn't fully exploit the available space to add valuable context without becoming bloated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, no annotations, and the presence of many sibling tools, the description is incomplete. It does not clarify what product listings are (vs. products), what the response looks like, or how pagination works. Agents may misselect the tool or fail to use pagination correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides descriptions for both parameters ('after' and 'first'), achieving 100% coverage. The tool description adds no extra semantic context, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Fetch') and the resource ('product listings'), providing a specific verb+resource pair. However, it does not explicitly distinguish this tool from the closely named sibling get_product_listing or the broader get_products, missing an opportunity to clarify the 'listing' scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool vs. alternatives. The description does not mention context (e.g., published products, sales channels), exclusions, or any comparison with related tools like get_product_listing or get_products.
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 only states the core action without disclosing output format, return structure, or any other behavioral traits. The statement largely restates the tool name, adding minimal value beyond the name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no redundancy. It is front-loaded with the verb and resource, fitting the minimal style. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and no annotations, the description should explain what the recommendations contain or how they are related. It does not mention return type or any caveats, leaving the agent under-informed for a read operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, as each parameter (productId, first, intent) has a description. The tool description does not add any meaning beyond the schema, and the baseline of 3 applies since the schema already handles parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('product recommendations') and adds 'based on a product' to clarify the input. It clearly distinguishes this from sibling get_* tools like get_product, though it could be more explicit about the recommendation types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like search_products or get_product. There are no exclusions or context cues, so the agent is left to infer usage from the name alone.
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 only says 'Fetch products... with optional filtering' and omits important traits like pagination behavior (despite 'after' and 'first' in schema), default limits, or whether fetching all products could be expensive. No safety or side-effect information is disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence that is front-loaded with the core action and resource. Every word earns its place, with no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having a rich schema (5 parameters) and numerous sibling tools, the description is minimal. It lacks usage context, pagination caveats, and differentiation from similar list/search tools. No output schema exists, and the description doesn't compensate by explaining what the response will contain or how to handle large result sets.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all five parameters are already documented with meaningful descriptions. The description's phrase 'optional filtering' vaguely echoes the 'query' parameter but adds no additional semantic value beyond what the schema provides, matching the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses a specific verb 'fetch' and resource 'products', clearly indicating it lists multiple products, distinguishing it from 'get_product' (singular). However, it doesn't explicitly differentiate from 'search_products' or other product-related list tools like 'get_product_listings'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as 'get_product', 'search_products', or 'get_product_listings'. The description doesn't state exclusions or preferred scenarios, leaving the agent to infer usage from the name alone.
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 provided, the description carries the full burden for behavioral disclosure. It notes a read operation ('Fetch') but does not mention pagination behavior, response format, or that it returns a collection. The schema reveals optional pagination and filtering parameters, but the description fails to surface these behaviors, leaving the agent with minimal insights beyond the name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no redundant wording. While it is short, it covers the core action and resource. It could be slightly more informative (e.g., mentioning 'list all' or pagination), but it is not bloated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has optional pagination and catalog type filtering, the description is incomplete. It does not explain that this is a list operation, mention pagination, or clarify that publications are for sales channels. With no output schema and a terse description, the agent lacks critical context for effective invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear descriptions for all three parameters ('after', 'first', 'catalogType'). The description adds no additional parameter context beyond the schema, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Fetch') and resource ('publications'), making the basic purpose unambiguous. However, it doesn't explicitly distinguish this plural 'get_publications' from its sibling 'get_publication' or related publication tools, leaving some ambiguity about whether it returns a list or a single entity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'get_publication', 'get_publication_products', or 'get_publication_collections'. With a large sibling set, the lack of explicit usage context or exclusions makes it harder for an agent to select this tool correctly.
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 burden. It only says 'fetch' without disclosing return format, pagination behavior, or any side effects. For a list operation, this is minimal disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no redundant wording. However, it is terse to the point of being generic, lacking detail that would make the structure more informative, so it doesn't earn a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description should explain that this returns a list of script tags, supports pagination, and has a default count. It misses these key contextual details, making it inadequate for a complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for all three parameters (src, after, first) with clear meanings and constraints, covering 100% of parameters. The description adds no additional parameter context, but the schema suffices, keeping the baseline at 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb+resource: 'Fetch script tags from the Shopify store'. This distinguishes it as a retrieval operation. However, it doesn't explicitly differentiate from the sibling get_script_tag (singular), which could be for fetching a single tag, leaving potential ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus get_script_tag or other related tools. The description doesn't mention that this is for listing/retrieving multiple tags or when pagination/filtering would be appropriate.
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 provided, the description carries the full burden of behavioral disclosure. It only says 'Fetch files from a theme' and does not mention pagination, response format, potential errors, or that it is a read-only operation. This is minimal and leaves the agent without important behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that communicates the core purpose without filler. It is appropriately short for a simple fetch operation, though it lacks some contextual details that are covered in other dimensions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters including pagination, no output schema, and no annotations, the description is insufficient. It does not explain return values, pagination behavior, or how the filenames parameter works, leaving significant gaps for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear descriptions for themeId, after, first, and filenames. The description does not add any parameter-level information beyond the schema, so it meets the baseline but does not enhance understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Fetch files from a theme' clearly states the action (fetch) and resource (files from a theme), making it easy to understand. However, it does not explicitly distinguish itself from the sibling tool get_theme_file (singular) or get_files, though the plural 'files' implies a listing operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like get_theme_file, get_files, or other theme-related tools. No context is given about prerequisites, typical use cases, or 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?
With no annotations, the description carries the full burden for behavioral disclosure. It only states 'Fetch themes' without mentioning pagination, filtering behavior, or that a list is returned. The schema documents parameters but not runtime behavior such as default pagination 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It is concise, though it lacks some valuable specifics that could be added without increasing length significantly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, and the description does not explain what the tool returns or how pagination works. Despite having four parameters in the schema, the description does not describe the behavioral context (e.g., default pagination, response format), leaving gaps for a complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all four parameters, each with clear descriptions. The tool description does not add any additional parameter semantics 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches themes from the Shopify store, using the verb 'fetch' and the resource 'themes'. It distinguishes from the singular 'get_theme' by the plural form, but does not explicitly differentiate from other theme-related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like get_theme (for a single theme) or get_theme_files (for theme assets). The description lacks any context about appropriate use cases or prerequisites.
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, so the description carries the full burden. 'Fetch' implies a read-only operation, but the description does not disclose pagination behavior, default limits, filtering semantics, or the meaning of 'translatable resources.' The parameter schema fills some gaps, but the description adds no behavioral context beyond a basic verb.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the verb and object, with no wasted words. It is appropriately sized for a straightforward list-fetch operation, though it sacrifices depth for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description should explain what the tool returns and how to use it. It only states 'Fetch translatable resources from the store,' omitting the response shape, default first value, pagination behavior, and relationships to sibling translation tools. This is insufficient for an agent to fully understand the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% parameter coverage with descriptions for after, first, and resourceType, including an enum for resourceType. The description adds no extra parameter meaning beyond the general concept of fetching translatable resources, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Fetch') with a clear resource ('translatable resources') and source ('from the store'). It distinguishes the tool from siblings like get_translations_for_resource and get_translations, which deal with translation content itself, though it does not explicitly call out that distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives such as get_translations, get_translations_for_resource, or register_translation. The only implied usage is that it fetches resources, but there is no context for how this fits into translation workflows or what scenarios call for it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations and no output schema, the description carries the full burden of disclosing behavioral traits. However, it merely restates the tool name and adds no information about return format, locale handling, pagination, or any side effects. The agent gains no insight beyond the tool's literal name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It is concise, though it largely echoes the tool name, limiting its added value. Nevertheless, it is efficient and not overly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-ID tool, the description is minimal but lacks essential context. It does not mention what the returned translations comprise, whether locale information is included, or how to map this to related tools. Given the absence of an output schema and annotations, the description is insufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides full coverage of the single resourceId parameter, including an example format. Since schema_description_coverage is 100%, the description does not need to elaborate on parameters; it adds no additional meaning but the schema already communicates the necessary semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Get) and the resource (translations) with a specific scope ('for a specific resource'), which distinguishes it from sibling tools like get_translations or get_translatable_resources. The phrasing directly maps to the required resourceId parameter.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description does not mention related tools such as get_translatable_resources for listing resources or get_translations for broader retrieval, leaving the agent to infer usage solely from the name.
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 full responsibility for behavioral disclosure. It only says 'get status' without explaining what the status values are, whether there are side effects, or any privacy considerations. The read-only nature is implied but not explicitly stated, and no detail about the response is given.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no filler or repetitive content. It is efficiently front-loaded and appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool's low complexity, there is no output schema and the description does not explain what 'status' means or what possible return values exist. An agent cannot fully anticipate the tool's response format, making the description incomplete for robust usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the visitorId parameter is already described as 'Visitor ID'. The description adds no additional meaning about the parameter beyond what the schema provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves visitor privacy consent status, which is specific and slightly more detailed than the tool name. However, it does not explicitly distinguish from sibling tools like get_privacy_settings or get_legal_policies, which could also relate to privacy matters.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives, prerequisites, or typical scenarios. The description is purely a statement of function without any contextual use cases or exclusion criteria.
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 provided, the description must carry the burden of disclosing behavioral effects. It merely says 'Pause a subscription contract' without explaining what pausing entails (e.g., billing impact, reversibility, permission requirements). The description adds no context beyond the tool name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a concise, single sentence that is easy to parse and front-loads the action. It contains no unnecessary words, though it is arguably too short to be fully self-contained.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given 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 is incomplete. It fails to explain the implications of pausing, when it should be used, or what the expected outcome is, leaving critical gaps for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides a clear description for the single parameter (subscriptionContractId), so schema coverage is 100%. The tool description does not add any additional meaning or clarify the parameter beyond what the schema already says.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action (pause) on a specific resource (subscription contract). It is distinguishable from sibling tools like cancel or activate by the verb, but it does not explicitly call out the difference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as cancel_subscription_contract or activate_subscription_contract. The description simply states what the tool does without any context on appropriate usage conditions.
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 only says 'Receive items from an inventory shipment.' It doesn't disclose side effects (e.g., inventory updates, shipment status changes), permissions, or return behavior, leaving a significant gap for a mutating operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no wasted words. It is appropriately front-loaded, though it lacks additional structure such as examples or elaborations that could enhance usefulness without bloating.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and no annotations, putting the burden on the description. It fails to explain what 'receiving' entails, what happens to the shipment status, inventory levels, or what the response will be. This is inadequate for a write operation with nested parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with basic descriptions for both parameters (shipmentId, lineItems). The tool description adds no extra meaning beyond the schema, but the schema itself provides adequate parameter-level context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('Receive items') and resource ('inventory shipment'). It is specific enough to distinguish from generic inventory operations, though it doesn't explicitly call out sibling tools like receive_inventory_transfer.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as receive_inventory_transfer or create_inventory_shipment. The description simply states the function without contextualizing it within related inventory workflows.
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?
Since there are no annotations, the description carries the full burden of disclosing side effects, but it only says 'Receive items.' It doesn't mention whether this updates the transfer status, adjusts inventory, partially receives items, or any other behavioral consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that is easy to read and front-loaded with the verb. It doesn't waste words, though it could be slightly more informative without sacrificing brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a write operation with no output schema and no annotations, and the description does not explain return values, prerequisites (e.g., transfer must exist), side effects, or whether partial receiving is supported. For a non-trivial mutation, this is insufficient contextual information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for both parameters, achieving 100% coverage. The description adds no additional meaning beyond what the schema already states, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Receive items') and the resource ('inventory transfer'), making it easy to grasp the tool's purpose. However, it doesn't explicitly differentiate from the closely related 'receive_inventory_shipment' sibling, though the resource names differ.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no information about when to use this tool versus alternatives, no prerequisites, and no exclusions. It merely states what the tool does without any contextual guidance.
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 only reveals that the tool performs an upsert ('create or update'), but does not explain how existing translations are handled, whether marketId is part of the uniqueness key, or any side effects, permissions, 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the action and object. It contains zero filler and is appropriately sized for the tool's straightforward purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and no annotations, so the description must carry the weight. It is too terse to be complete: it fails to explain the uniqueness key (resourceId + locale + key possibly + marketId), the optional nature of marketId, or the behavior when a translation already exists. An agent would lack critical information for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema descriptions cover all five parameters, including the optional marketId and a clear resourceId example. Since schema coverage is 100%, the description adds no additional parameter meaning beyond the schema, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Create or update' with the object 'a translation for a resource,' clearly conveying an upsert operation. It distinguishes itself from sibling translation tools like get_translations_for_resource and remove_translations, though it could be more explicit about the resource scope or locale dimensions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention that it is the tool for adding or modifying translations, nor does it exclude cases like removing translations. The description lacks any situational context.
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, but it only offers a generic action. It doesn't state whether running a report is synchronous, requires specific permissions, has side effects, or what form the results take.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently states the tool's action. However, it misses the opportunity to include useful behavioral context without adding significant length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description needed to clarify what 'results' means (raw rows, a URL, status message), but it only says 'get its results.' Combined with the lack of usage guidance and behavioral transparency, the description is not sufficient for confident invocation and interpretation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% since the only parameter, `id`, includes a helpful example format ('gid://shopify/Report/123456789'). The tool description itself adds no parameter-level meaning, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Run a report and get its results' uses a clear verb+resource construction and avoids being a tautology. However, it doesn't distinguish this tool from closely related siblings like get_report or get_analytics_report, and doesn't specify the scope of 'results'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool vs. alternatives such as get_report, get_analytics_report, or run_shopifyql_query. There are no prerequisites, exclusions, or contextual cues to help an agent choose correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden for behavioral disclosure, but it only states that it searches — not whether it's read-only, returns paginated results, what filters are supported, or any side effects. The phrase 'discovery/search functionality' hints at a specific API but doesn't disclose behavior beyond the basic 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that directly states the tool's purpose. It is appropriately sized and front-loaded with the key verb and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 parameters including pagination and sorting, and no output schema, the description should clarify return format and behavior. It doesn't explain what results look like or how this search differs from other product retrieval tools, leaving significant gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and each parameter has a clear description. The tool description adds no additional semantic context beyond what the schema already provides, so it stays at the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'search' and identifies the resource 'products', and adds 'Shopify's discovery/search functionality' which differentiates it from sibling tools like get_products and get_product. However, it doesn't explicitly contrast with similar tools, so it's not a full 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives like get_products or predictive_search. It doesn't mention when not to use it or any prerequisites.
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, but it provides none. It does not state whether the operation overwrites existing quantity, requires special permissions, is reversible, or what the response contains. The verb 'set' implies mutation but adds no safety or side-effect context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at four words, front-loaded with the action and resource. However, it is so sparse that it sacrifices meaningful context, though every word does contribute to a basic understanding of the operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with three required parameters and no annotations or output schema, the description is incomplete. It lacks information about return values, side effects, error conditions, and how it differs from the sibling 'adjust_inventory'. The minimal description does not adequately support an agent in invoking the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter ('inventoryItemId', 'locationId', 'quantity') having a basic description. The tool description adds no additional parameter semantics 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Set on-hand inventory quantity' uses a specific verb ('Set') and identifies the resource ('on-hand inventory quantity'). It distinguishes from sibling 'adjust_inventory' by implying an absolute overwrite rather than an adjustment, though it doesn't explicitly state the distinction or mention the required item/location context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'adjust_inventory' or 'get_inventory'. There is no mention of prerequisites, typical scenarios, or exclusion criteria, leaving the agent to infer usage from the name alone.
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 only says 'update,' which implies a mutation, but doesn't disclose whether unspecified settings are reset, whether the operation is reversible, what permissions are needed, or what the response contains.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at five words, with no wasted content. It front-loads the verb and resource clearly, though it lacks additional structural elements like lists or examples that could aid scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 8 optional parameters and no annotations or output schema, the one-sentence description is insufficient. It doesn't explain update semantics (e.g., partial update behavior), the relationship to get_checkout_branding_settings, or expected return values, leaving significant gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with each of the 8 parameters documented in the input schema. The description adds no parameter meaning beyond 'checkout branding settings,' so a baseline score of 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update') and the resource ('checkout branding settings'). It distinguishes from the sibling 'get_checkout_branding_settings' by the verb, though it doesn't clarify partial vs. full replacement or the scope of settings affected.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given about when to use this tool versus alternatives. It only states 'Update checkout branding settings,' which implies usage but provides no exclusions, prerequisites, or mention of the sibling read tool (get_checkout_branding_settings).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must bear the full burden of behavioral disclosure, but it provides none. It doesn't mention idempotency, partial vs. full replacement, required permissions, error behavior, or any side effects. This is essentially a restatement of the tool name with 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that immediately states the tool's purpose. No wasted words or fluff, front-loaded and appropriately sized for a simple CRUD operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having a complete schema, the description is too sparse for the tool's context. It doesn't explain the relationship to update_pixel, the significance of the 'events' or 'source' fields, or any operational constraints. With no annotations or output schema, the description leaves the agent with little guidance beyond the raw schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all 5 parameters with descriptions (100% coverage), so the description need not repeat them. However, the description itself adds no parameter-related context beyond what's in the schema, meeting the baseline for complete schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update') and resource ('custom pixel'), and the word 'existing' implies the tool modifies an already-created pixel, distinguishing it from create_custom_pixel. However, it doesn't explicitly differentiate from the sibling update_pixel, so it lacks full sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'existing custom pixel' implies use when modifying an existing pixel rather than creating one, but there is no explicit guidance on when to use this tool versus alternatives like update_pixel or create_custom_pixel. No exclusions or alternative references are 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 provided, the description carries the full burden, but it only states 'Update an existing fulfillment constraint rule' without disclosing mutation semantics, partial vs. full replacement, authorization needs, or response format. It adds no behavioral context beyond the operation implied by the name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with zero wasted words, making it concise. However, it's understandably short for such a tool, and the brevity may sacrifice useful context, but as a pure conciseness measure it's efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having only 2 parameters and a schema, the lack of any explanation about what a fulfillment constraint rule is, what the update does, or what the response looks like, combined with no annotations or output schema, leaves the description incomplete for an agent to confidently invoke it. It only states the basic action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both id and metafields are documented in the schema. The description adds no additional meaning beyond what the schema already provides, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Update') and resource ('fulfillment constraint rule'), and the word 'existing' distinguishes it from create/delete siblings. However, it doesn't clarify that updates are limited to metafields, leaving some scope ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus create_fulfillment_constraint_rule or delete_fulfillment_constraint_rule. The only hint is 'existing', implying the rule must already exist, but there are no explicit exclusions or 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?
With no annotations, the description carries the full burden for behavioral disclosure. It only states 'update', implying mutation, but does not explain whether it performs a partial update, requires special permissions, is idempotent, or what the response contains. This is a significant omission 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no filler or redundancy, making it concise and front-loaded. It could arguably be too terse to offer value beyond the name, but it is appropriately sized for a simple update operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update tool with full schema coverage and no output schema, the description is barely adequate. It lacks usage context, behavioral details, and exclusions, but the simplicity of the operation and schema completeness reduce the burden. Still, more context is expected, especially without annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptive parameter names and descriptions (id, name, handle), so the schema already documents all parameters. The description adds no extra parameter semantics, but the baseline of 3 applies since the schema handles the burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update an existing market' clearly identifies the action (update) and resource (market), distinguishing it from create/delete/get siblings. However, it lacks scope details such as which fields can be updated or any specific market type, preventing a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like create_market or delete_market. It does not mention prerequisites (e.g., existing market ID) or scenarios where this tool is appropriate, leaving the agent without decision-making info.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/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 of behavioral disclosure, but it merely restates the tool's purpose. It does not mention whether the update is partial or full replacement, how missing fields are handled, or any return value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no wasted words. It is front-loaded and direct, though somewhat sparse overall.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
As a mutation tool with no output schema and no annotations, the description is incomplete. It lacks essential context about update semantics (e.g., does it merge or replace fields?), which an agent needs to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides complete descriptions for both parameters (id and fields), achieving 100% schema description coverage. The tool description adds no parameter semantics beyond what the schema already states, 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update an existing metaobject' clearly specifies the action (update) and resource (metaobject), and distinguishes it from sibling tools like create_metaobject, delete_metaobject, and get_metaobjects. It is concise 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, selection criteria, or exclusions, leaving the agent without explicit direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. Saying 'Update an existing page' merely restates the tool name and gives no information about partial update behavior, return values, error handling, permissions, or side effects. It adds zero context beyond the name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no wasted words. It is front-loaded with the verb, but it is perhaps too sparse to be fully helpful; still, it earns its place as a concise summary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no output schema and no annotations, the description should explain what happens on update, return values, and usage constraints. It only says 'Update an existing page,' leaving the agent to infer from schema. The schema helps but does not compensate for missing behavioral/return context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers 100% of parameters with clear descriptions (id, body, title, handle, published). The description itself adds no parameter detail, but the baseline is 3 because the schema already provides full meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (update) and resource (existing page), making it distinct from sibling tools like create_page, get_page, and delete_page. The word 'existing' reinforces that this tool modifies rather than creates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. It does not mention whether to use create_page for new pages, or provide context on idempotency or prerequisites. The only hint is 'existing', which is implicit.
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 provided, the description carries the full burden of behavioral disclosure, but it only states 'Update an existing payment customization.' It does not describe whether the update is partial or full replacement, what happens to omitted fields, or any side effects like invalidation of cached settings. The brevity leaves significant behavioral ambiguities.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler, front-loading the action and resource. It is appropriately sized for a simple update operation, though it could be slightly more informative without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 5 parameters and no output schema, making the description the only source for return behavior. The description doesn't explain what the response looks like, which fields are updatable, or how it relates to set_payment_customization_activation. For a mutation tool with multiple related siblings, this is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides complete descriptions for all 5 parameters (100% coverage), so the high baseline applies. The description itself adds no parameter-level meaning beyond the schema, but it doesn't need to since the schema is self-explanatory.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (update) and the resource (existing payment customization), using a specific verb. However, it does not explicitly distinguish this from related siblings like create_payment_customization or set_payment_customization_activation, so it misses the sibling differentiation opportunity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus its siblings (create, delete, or set activation). There is no mention of prerequisites, such as needing an existing customization ID, or when partial updates are appropriate.
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 full responsibility for behavioral disclosure. It only states 'Update', which implies mutation, but does not mention idempotency, required permissions, side effects, or whether partial updates are supported.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, brief sentence with no wasted words and the key action is front-loaded. It is concise but under-specified, earning a 4 rather than 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no output schema and no annotations, this description is incomplete. It does not explain how updates are applied, whether all fields are optional, what the response contains, or any side effects, leaving significant gaps for the AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema descriptions cover 100% of parameters (id, name, apiKey, enabled), so the baseline is 3. The tool description adds no additional parameter semantics beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Update' and resource 'existing pixel', which distinguishes it from get/create/delete siblings. However, it does not explicitly name alternative tools or differentiate from the similar 'update_custom_pixel' sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use update_pixel versus related tools such as create_pixel or delete_pixel. The description does not offer any context for appropriate usage.
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 full responsibility for behavioral disclosure. It only says 'Update an existing theme' and does not mention idempotency, permissions, partial update semantics, or error behavior. This is a significant gap 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. However, it is too terse to serve as a complete tool description, balancing conciseness against lost informational value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no annotations, no output schema, and only a minimal description, it lacks necessary context about update behavior, prerequisites, and expected outcomes. The description is not self-sufficient for an agent to confidently invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides detailed descriptions for all three parameters (id, name, role) with 100% coverage. The description adds no extra parameter context, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Update') and resource ('theme'), making the tool's purpose clear. It implicitly distinguishes from sibling tools like create_theme and delete_theme, but does not explicitly describe the scope of the update beyond what the schema shows.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like publish_theme or create_theme. The description simply states what it does, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description only reiterates the action without disclosing behavioral traits such as whether a notification is sent, whether the card is immediately active, or what the response contains.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, direct sentence that is front-loaded and contains no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given 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 is too sparse; it fails to mention return data, side effects, or relationships to sibling tools like credit_gift_card.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter is already documented; the one-line description adds no additional parameter semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action ('Create') and resource ('gift card'), distinguishing it from sibling tools like get_gift_card, update_gift_card, and disable_gift_card.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives; for example, no distinction between creating a new gift card and crediting an existing one via credit_gift_card.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/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 merely restates the action ('Create a new payment customization') and does not mention side effects, permissions, activation requirements, or response format. This is essentially a tautology and provides no additional behavioral insight.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no redundant information. It is appropriately sized for a basic create operation and front-loads the key action, making it easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of sibling tools like set_payment_customization_activation, the description should clarify that creating a customization may not automatically activate it. It also fails to explain what a payment customization is or any operational dependencies. The schema covers parameters, but the description omits essential business context, making the description incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides detailed descriptions for all four parameters (100% coverage), so the description adds no extra parameter semantics. The baseline for high schema coverage is 3, and the description does not enrich the understanding of parameters beyond what the schema offers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create a new payment customization' clearly states a specific verb ('create') and resource ('payment customization'), distinguishing it from update/delete/get operations on the same resource. It is unambiguous and directly reflects 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like update_payment_customization or set_payment_customization_activation. It lacks any context about prerequisites, use cases, or exclusions, leaving the agent without direction on appropriate invocation scenarios.
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 provided, the description must disclose behavioral traits. It simply states 'Delete a company contact' without mentioning what happens on deletion (permanence, cascading effects, permissions required), or whether the operation is idempotent. This is a significant gap for a destructive 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise phrase with no unnecessary words. It is front-loaded with the action and resource, making it easy to parse. It earns its place by clearly stating the tool's core purpose without verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only one parameter and no output schema, the description is extremely thin. It lacks critical context about the consequences of deletion, any required permissions, or conditions under which deletion is allowed. The absence of annotations makes this incomplete compared to expectations for a delete operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents the single parameter 'companyContactId' with its type and description, so the schema coverage is 100%. The description adds no extra meaning beyond the schema, which meets the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete a company contact' uses a specific verb ('Delete') and resource ('company contact'), clearly distinguishing it from sibling operations like create_company_contact, update_company_contact, and get_company_contact. It is immediately obvious what this 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 Guidelines1/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives, nor are there any prerequisites, exclusions, or contextual hints. For example, it does not mention that deleting a company contact is irreversible or should only be done when the contact is no longer associated with any orders.
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 and no output schema, the description carries the full burden of behavior disclosure. The verb 'Fetch' implies a read operation, but nothing is said about what legal policies are included, whether the call is safe/read-only, authentication needs, or return format. This is insufficient for a tool with zero annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that immediately states the action and object. It is front-loaded and free of fluff, though it adds only slightly more than the tool name itself.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the existence of similar sibling tools, the description is incomplete. It does not clarify the difference between 'legal policies' and 'shop policies', nor does it explain what the returned data contains. Without annotations or an output schema, the description should provide more context to ensure correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema is trivially 100% covered. Per the rubric, 0 parameters warrants a baseline of 4. The description adds no parameter-specific details, but none are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Fetch legal policies for the store' clearly states the tool's purpose with a specific verb ('Fetch') and resource ('legal policies'). However, it does not distinguish from the sibling tools 'get_shop_policies' or the singular 'get_legal_policy', so it lacks explicit sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as 'get_shop_policies' or 'get_legal_policy'. The description provides no context about scope, prerequisites, or situations where this tool is preferred, leaving the agent to guess.
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 must disclose behavioral traits. The description merely states 'Fetch payment terms configurations', which conveys that it's a read operation but adds no context about response format, pagination defaults, error handling, or rate limits. The schema mentions pagination parameters but the description doesn't elaborate on how they affect behavior. This is a significant gap for a tool with no annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no unnecessary words. It is front-loaded with the verb and resource, making it easily scannable. However, it may be too terse for a tool with pagination, but that is covered under completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple list-style tool with two parameters and no output schema. The description is minimal ('Fetch payment terms configurations') and does not specify what is returned, how pagination works, or whether it lists all or a single item. With no annotations to fill the gap, the description is insufficient for an AI agent to confidently invoke the tool correctly and interpret results. Given the context signals, the tool likely returns a list of payment terms, but the description does not state this.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents both parameters with descriptions: 'after' as a pagination cursor and 'first' as the number of payment terms (1-250, default 50). The description does not add parameter information, but since schema coverage is 100%, this is acceptable per the baseline. The description's lack of parameter explanation is compensated by the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Fetch' with the resource 'payment terms configurations', clearly identifying this as a read operation on payment terms settings. It differentiates from sibling tools like create_payment_terms, update_payment_terms, and delete_payment_terms, as well as get_payment_mandates, by naming the exact resource and action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no information about when to use this tool versus alternatives. There is no mention of exclusions, prerequisites, or alternative tools. For example, it doesn't explain that this is for retrieving configurations as opposed to mandates, or that it complements create/update/delete operations. The user must infer the usage purely from the name and schema.
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 provided, the description must carry the behavioral disclosure burden. It only says 'Fetch resource feedbacks' which implies a read operation, but it does not explicitly state read-only behavior, pagination, filtering capabilities, or any side effects or permissions. This is minimal disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise and front-loaded with the verb. However, the phrase 'from the Shopify store' is redundant given the context, adding minimal value and wasting a few words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with three optional parameters and no output schema, but the description lacks any mention of pagination, filtering by resourceType, or default values. It does not explain what a successful response contains, which would be helpful since there is no output schema. Overall, the description is too sparse for a complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides full descriptions for all three parameters (after, first, resourceType) with 100% coverage. The description adds no additional parameter-specific 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Fetch' with the clear resource 'resource feedbacks', making the tool's purpose immediately obvious. It distinguishes itself from the sibling create_resource_feedback by focusing on retrieval rather than creation, and the resource name is unique among siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention that it is for reading existing feedbacks or contrast it with create_resource_feedback, nor does it indicate any prerequisites or context.
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 provided, the description carries full responsibility for behavioral disclosure. It only states 'Fetch', implying a read operation, but gives no details about response format, pagination behavior, sorting, or any side effects. The absence of an output schema further reduces transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words. However, it is under-specified—it lacks useful context about usage or behavior, making it less helpful than a slightly longer but more informative description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 parameters, pagination, filtering, sorting), no output schema, and no annotations, the one-line description is inadequate. It does not explain what is returned, how to paginate, or any hints about the data structure, making it incomplete for an agent to use effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does 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 'after', 'first', 'query', 'reverse', and 'sortKey'. The tool description adds no parameter-specific information, but the baseline is 3 because the schema already handles parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Fetch' with the resource 'subscription contracts' and scope 'from the store', clearly indicating a list/read operation. It distinguishes from siblings like get_subscription_contract (singular) and create_subscription_contract.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of pagination, filtering, or when to prefer this over the singular get_subscription_contract or other subscription-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/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, but it only states the basic operation. It does not disclose permissions, partial vs. full update semantics, error handling, or response format, leaving critical behavioral traits unknown.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that directly states the operation. It is concise and front-loaded, with no redundant or irrelevant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is minimal and leaves many unknowns. It does not explain what the tool returns, whether updates are partial or full, or what happens if the contact does not exist, making it incomplete for an agent to use confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with all five parameters described in the schema. The tool description adds no additional parameter-specific information, 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Update') and resource ('existing company contact'), clearly distinguishing it from sibling tools like create_company_contact and delete_company_contact. It unambiguously states 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention any context such as prerequisites, when to prefer this over create_company_contact, or 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?
There are no annotations, so the description carries the full burden of behavioral disclosure. It does disclose a precondition (eligible statuses), but it does not explain side effects, reversibility, or what happens after activation, which is a significant gap 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single compact sentence that is front-loaded with the action. It is efficient, though the parenthetical is somewhat awkward and could be clearer.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has only one parameter and no output schema, but the description is too sparse to be complete. It leaves unclear what activation means, exactly which statuses are valid, and any consequences; the ambiguity around 'active' is a notable gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter is fully documented in the schema with 100% coverage, and the schema description matches the tool's mention. The description adds no additional parameter-level meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Activate' and the resource 'subscription contract', clearly distinguishing it from sibling tools like pause, cancel, or expire. The parenthetical adds a precondition about statuses, though the inclusion of 'active' is somewhat ambiguous, reducing full clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by specifying that the contract must be in active, paused, or failed status, providing some context for when to call the tool. However, it does not explicitly state when not to use it or mention alternatives, such as pause or cancel.
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, but it only states the action without disclosing behavioral details. It does not explain whether line items are appended, whether existing line items are affected, how pricing or quantities are handled, or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence of six words, which is appropriately concise and front-loaded. It avoids verbosity, though it is minimal to the point of bordering on under-specification.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description is incomplete. It leaves unclear how the operation behaves (e.g., whether it recalculates totals), what the success/error responses look like, and any constraints on order state. The minimal schema descriptions do not compensate for these gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for all properties (e.g., 'Quantity', 'Custom price (optional)'), so the baseline is 3. The description itself adds no additional meaning beyond what the schema already provides, but it does not detract either.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Add' with direct object 'line items' and target 'to an order', clearly stating the action. It distinguishes itself from the sibling tool 'remove_line_items_from_order' by indicating the opposite operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, such as the order being open, nor any comparison with other order-editing tools like 'update_order' or 'remove_line_items_from_order'.
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 states the resulting state (closed) and its meaning, but does not mention side effects, reversibility, permissions, or the exact impact on the order lifecycle. This is minimal for a state-changing 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with two short sentences that front-load the purpose and state the key behavioral outcome. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one parameter, no output schema), but the description could still provide more context about the order lifecycle, such as the difference from cancel/delete, or any prerequisites. It is minimally adequate but leaves gaps for an agent trying to decide between close_order and sibling mutations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents the only parameter 'id' with the description 'Order ID to close', providing 100% coverage. The tool description adds no additional parameter-specific meaning, so it meets the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('Close') and resource ('an open order'), and adds the semantic meaning that a closed order indicates no further work is required. However, it does not explicitly contrast with sibling tools like cancel_order or open_order, so differentiation is implicit rather than explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for open orders that need no more work, but it does not provide explicit guidance on when to use this tool versus alternatives such as cancel_order, delete_order, or update_order. There are no exclusion criteria or when-not-to-use instructions.
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 provided, the description carries full responsibility for disclosing behavioral traits. It only says 'Create a new B2B company' and does not mention any requirements, side effects, idempotency, or constraints (e.g., duplicate name handling). The mutation is implied but lacks detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded with the core purpose. It avoids redundancy and is efficiently structured, though it may be slightly too brief to provide much additional value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a creation tool with 4 parameters, a nested object, and no output schema, the description is minimal. It does not clarify the return value, any required permissions, or how the mainContact nested object is used. The schema covers parameter structure, but the overall context is under-specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage for parameter descriptions (name, note, externalId, mainContact). The description adds no parameter-specific meaning beyond what the schema already offers, aligning with the baseline of 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and the resource ('B2B company'), distinguishing it from sibling tools like get_company, update_company, and delete_company. The 'B2B' qualifier adds useful context that narrows the scope of the company entity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as create_company_location or create_company_contact. The description only states the action, leaving the agent to infer that it is for creating a company entity, without any context on prerequisites or 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 present, so the description must disclose behavioral traits. It merely states the action without mentioning irreversibility, cascading effects on related data, or permission requirements. This is a significant gap for a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a concise single sentence that is front-loaded and easy to parse. It earns its place by stating the resource and action, though it omits useful behavioral details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with no annotations and no output schema, the description should include at least a note about permanence or side effects. It lacks this, making it incomplete for safe agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers the single parameter with a clear description and an example. Since schema coverage is 100%, the description does not need to add parameter details. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action (delete) on a specific resource (customer) with scope (from the store). It distinguishes from siblings like update_customer or get_customer, so purpose clarity is excellent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives, no prerequisites, and no warnings about consequences. The description provides no context for choosing delete_customer over other customer operations.
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 provided, the description must carry the full burden of disclosing behavioral traits. It only states 'Delete a custom pixel' without indicating whether deletion is permanent, whether there are cascading effects, or any required permissions. This minimal restatement offers no meaningful behavioral context beyond the tool's name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that wastes no words. While concise and well-structured, it could include a bit more context without affecting its brevity, preventing a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema or annotations, so the description must fully contextualize the operation. It fails to mention if deletion is irreversible, what happens to associated resources, or any error conditions. For a destructive mutation, this lacks sufficient context for an agent to use it confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage for the required 'id' parameter with a clear description ('Custom Pixel ID to delete'). The description adds no additional parameter meaning beyond what the schema already provides, 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the operation ('Delete') and the resource ('custom pixel'), which distinguishes it from sibling tools that get, create, update, or toggle custom pixels. It is specific and unambiguous, leaving no doubt about 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is provided on when to use this tool versus alternatives such as delete_pixel or toggle_custom_pixel. The description only states the action, leaving usage context to be inferred from the name. There is no mention of prerequisites, exclusions, or conditions under which deletion should be performed.
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 provided, the description carries the full burden of disclosing behavioral traits. It only states 'Delete a file' and omits critical information such as permanence, required permissions, side effects if the file is in use, or reversibility. This is a significant gap for a destructive 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no unnecessary words. It is front-loaded and easily parsed, earning a perfect score for its efficient structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one fully documented parameter, but the absence of annotations and behavioral details means the description is not fully complete. It could benefit from mentioning the file type (e.g., Shopify Files) or potential consequences of deletion, but given its simplicity, the description is minimally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides full coverage of the sole parameter 'id' with the description 'File ID to delete'. The tool description adds no additional parameter semantics, but since schema coverage is 100%, the schema handles the meaning adequately, warranting a baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete a file' clearly states the verb and resource, making the action unambiguous. However, it doesn't specify what kind of file or distinguish it from other delete operations like delete_custom_pixel or delete_script_tag, though the resource type is implied by the tool name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus other delete tools (e.g., delete_product, delete_custom_pixel). The description only states the action without any context about prerequisites, exclusions, or 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?
With no annotations provided, the description carries the full burden of behavioral disclosure. 'Fetch' implies read-only but does not explicitly state it, nor does it mention pagination behavior, default page size, or that it returns a list. Minimal value is added beyond the tool name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no redundant words. It front-loads the verb and resource effectively, achieving maximum clarity for its length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and the schema covers parameters well. However, the description lacks context about pagination behavior, the distinction from get_all_cart_transforms, and any operational caveats. This leaves the agent uncertain about selection in the presence of a very similar sibling tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters (after, first) fully described. The description does not add any extra meaning to the parameters, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches cart transforms (verb+resource), but it does not differentiate from the sibling get_all_cart_transforms. The phrase 'configured for the store' is generic and does not clarify whether this is a paginated list vs. a bulk fetch.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool vs. alternatives like get_all_cart_transforms. The description does not mention pagination defaults, use cases, or exclusions, leaving the agent without selection criteria.
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 bears sole responsibility for behavioral disclosure. It states only that the tool fetches stored payment methods, with no mention of read-only semantics, response format, pagination behavior, or lack of side effects. This is a minimal restatement of the tool's name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no wasted words. It is front-loaded with the verb and resource. However, it is somewhat terse and could include more useful context without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description should explain return values or pagination details, but it does not. It only states what the tool does, omitting any information about response structure, default page sizes (though 'first' has a default in schema), or the presence of the 'after' cursor for paging. The tool is a simple read, but the description leaves the agent without enough context to anticipate the output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema documents all three parameters with descriptions (customerId, after, first) and covers 100% of parameter semantics. 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Fetch' and names the resource 'stored payment methods for a customer'. It clearly distinguishes from the sibling 'get_customer_payment_method' (singular) by using the plural 'methods', and from mutation tools like 'revoke_customer_payment_method'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus the similar 'get_customer_payment_method' (singular) or when to avoid it. The context is implied only by the name and description, with no alternatives or exclusions mentioned.
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 implies a read operation via 'Fetch' but does not specify what a successful response looks like, whether any special permissions are needed, or any rate limits or pagination behavior. For a fetch operation without an output schema, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that directly states the tool's function with no unnecessary words. It is appropriately sized and front-loaded, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with well-documented parameters, the description is adequate but lacks important context. It does not mention that the tool returns a list of pixels, nor does it reference sibling tools or provide any usage context. The absent output schema and annotations further reduce completeness, but the schema richness partially compensates.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers both parameters (after, first) with descriptions, providing 100% coverage. The tool description adds no additional parameter context. Since the schema already explains the parameters clearly, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Fetch') and the resource ('custom pixels configured for the store'), making the tool's purpose unambiguous. However, it does not explicitly distinguish this from sibling tools like get_pixels or get_custom_pixel, which could cause confusion about which tool to use for different pixel querying needs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There is no mention of when to prefer get_custom_pixels over get_pixels or get_custom_pixel, nor any exclusion criteria. This is a clear gap for a tool within a large sibling family.
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 says 'Fetch' which implies a read, but it does not disclose the list nature, pagination behavior, ordering, or any side-effect-free guarantee. The schema hints at pagination, but the description adds no behavioral context beyond the verb.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words. It front-loads the action and resource effectively. It is appropriately sized for the simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description does not clarify the return structure (e.g., list of carriers, fields included). The schema's pagination params hint at a list, but the description alone is too thin to fully inform an agent. It is minimally adequate but leaves gaps about default behavior and output shape.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (both params have clear descriptions: 'Cursor for pagination' and 'Number of carriers to fetch'). The description adds no parameter details, but with full schema coverage, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a clear verb ('Fetch') and names the resource ('delivery carrier services'). It conveys the core action but does not explicitly differentiate from sibling tools like get_delivery_profiles or get_fulfillment_services, though the name itself is fairly specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives, no mention of context, prerequisites, or exclusions. The description is purely a statement of action without any usage direction.
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 is the sole source of behavior disclosure, but it only restates the core function. It does not mention pagination behavior, return format, or whether it is read-only, leaving significant behavioral traits undisclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler words, efficiently conveying the tool's purpose. It is appropriately sized and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with two optional parameters and no output schema, so the description need not explain return values. However, it lacks any context about what allocator functions are or the pagination behavior beyond the parameter hints, making it minimally adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema describes both parameters (after and first) with clear descriptions, achieving 100% schema description coverage. The tool description adds nothing beyond the schema, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Fetch') and the resource ('discounts allocator functions'), making the purpose evident. It is specific to allocator functions, distinguishing it from the sibling get_discounts, though it does not explicitly mention alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool or how it relates to sibling tools like get_discounts or create_discounts_allocator_function. The description only states what it does, not the context for using it.
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 full burden for behavioral disclosure. It only states 'Fetch' which implies a read, but does not mention pagination behavior (though the schema has pagination params), return format, or any other operational details. It adds no behavioral context beyond the basic 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded with the core purpose. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with only two optional params and no output schema, so the description does not need to explain return values. However, the presence of a near-identically named sibling tool (get_custom_fulfillment_services) creates ambiguity that the description does not resolve, making it incomplete for disambiguation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes both parameters ('Cursor for pagination' and 'Number of fulfillment services to fetch (1-250, default: 50)'), and the description adds no additional parameter semantics. Since schema coverage is 100%, baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Fetch custom fulfillment services configured in the store' clearly identifies the verb (fetch) and resource (custom fulfillment services), and adds context of store configuration. However, a sibling tool named 'get_custom_fulfillment_services' exists, and the description does not distinguish how this tool differs from that one, so it is not fully distinguishing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives like get_custom_fulfillment_services or other fulfillment-related tools. There is no mention of exclusions, prerequisites, or the relationship to sibling tools.
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 bears full responsibility for behavioral disclosure. It only states 'Fetch available locales' with no mention of whether the operation is read-only, what the default return set is, or whether the publishable parameter changes the behavior. The description adds little beyond the tool name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise at one short sentence and gets to the point immediately. While it is minimal, it is not verbose or repetitive. A slightly more informative phrasing would improve it, but it earns high marks for efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of an output schema and annotations, the description should explain what is returned and how the optional parameter affects results. It simply says 'Fetch available locales' without mentioning the publishable filter or any return details, leaving the agent under-informed for a complete invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single optional parameter, and the schema description clearly explains 'Filter to only published locales'. The tool description does not add any parameter information, but per the baseline for high schema coverage, this is acceptable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action ('Fetch') and resource ('available locales') with context ('for the store'). It distinguishes itself from sibling locale-related tools like publish_locale or get_translations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives. The description does not mention the optional publishable parameter or provide any context about scenarios where this tool is appropriate, leaving the agent to infer usage.
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 convey behavioral traits independently. The verb 'Fetch' implies a read-only operation, and the scope is stated, but nothing is disclosed about pagination behavior, return format, or potential side effects. This is a safe but thin disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. It efficiently states the core purpose, though it lacks detail that could enhance utility. It is concise without being tautological.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool, the description is incomplete. It does not explicitly state that a list of markets is returned, mention default pagination or ordering, or clarify the relationship to sibling tools like get_market and get_markets_home. With no output schema and no annotations, more context is needed for safe and correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides complete descriptions for both parameters (after and first), covering 100% of the schema. The description adds no additional parameter semantics beyond what the schema provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Fetch') and resource ('markets'), with a scoping phrase ('configured for the store') that adds specificity. However, it does not explicitly distinguish this from sibling tools like get_market or get_markets_home, leaving some ambiguity about whether this is a list operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as get_market or get_markets_home. There are no exclusions, prerequisites, or contextual hints that would help an agent decide to invoke this tool.
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 provided, the description carries the full burden of behavioral disclosure. It only says 'Fetch orders,' which is a minimal restatement of the name. It does not mention pagination, sorting, or any operational traits beyond what the input schema already specifies.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundant phrasing. It conveys the core purpose efficiently, making every word count.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 5 parameters and no output schema, yet the description is very brief. While the schema provides parameter details, the description does not explain the return format or default behavior, leaving some ambiguity for a list operation. It is adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of the parameters with descriptions, so the baseline is 3. The description adds no extra meaning to parameters—'optional filtering' vaguely references the query parameter but provides no additional insight beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Fetch orders') and the resource ('from the Shopify store'), with a hint at optional filtering. However, it does not differentiate from sibling tools like get_all_orders or get_order, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool versus alternatives. The phrase 'with optional filtering' loosely implies a use case, but the description does not mention get_all_orders or get_order, leaving the agent without clear selection criteria.
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 full responsibility for behavioral disclosure. It only says 'Fetch reports' and omits pagination behavior (despite the 'after' cursor in schema), default limits, or any rate-limiting or scoping 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no redundant content. It is direct and front-loaded, earning full marks for efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
As a simple list tool, the basic action is clear, and the schema covers parameters. However, with no annotations and no output schema, the description could benefit from mentioning pagination defaults and the scope of 'reports' to be fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: both 'after' (cursor for pagination) and 'first' (number of reports, 1-250, default 50) are described. The tool description adds no extra parameter semantics, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Fetch' and resource 'reports', clearly indicating a retrieval operation. It doesn't explicitly distinguish from sibling tools like 'get_report' or 'get_analytics_report', but the plural form and straightforward wording make the purpose broadly 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as 'get_report' or 'run_report'. The description lacks context about report types, prerequisites, or when other report-related tools would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/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 does not state whether the operation is read-only, whether it returns all transactions by default, or any special behavior such as pagination limits beyond what the schema hints. The description is essentially a restatement of the tool name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasted words. It is front-loaded and easy to parse, though it is quite terse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with six optional parameters and no output schema, the description fails to explain the return format, pagination behavior (beyond cursor parameter names), or intended use cases. This leaves a significant gap in understanding what the tool actually does and how to interpret its results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with descriptive text for all six parameters, including defaults and enumerations. The description adds no additional parameter context beyond this, 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Fetch') and a specific resource ('Shopify Payments balance transactions'), clearly distinguishing it from sibling tools like payouts and disputes. There is no ambiguity about what this 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus related payment tools (e.g., get_shopify_payments_payouts or get_shopify_payments_disputes). It only states the action, leaving the agent to infer context.
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. 'Fetch' implies a read operation, but the description doesn't state what data is returned, whether authentication is needed, or any limitations. For a tool with no annotations and no output schema, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no unnecessary words. It is appropriately front-loaded and easy to scan. Nothing extraneous is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite being a simple zero-parameter tool, the description is incomplete. It doesn't explain what 'general shop information' includes, what the response shape looks like, or how this differs from other shop-related endpoints. For a tool with no output schema and no annotations, more context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description adds no parameter information, but none is needed. The schema coverage is 100% vacuously, so there is no missing parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Fetch general shop information' clearly states the action (fetch) and the resource (general shop information). It is unambiguous but somewhat vague, and doesn't distinguish itself from sibling tools like get_shop_policies or get_shopify_payments_account.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention any context, prerequisites, or scenarios. There is no indication of what makes this 'general' information distinct from other shop-related getters.
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 'Execute a ShopifyQL query', which implies a read-like operation but does not explicitly state side effects, permissions, rate limits, or what the response contains. This is a significant transparency gap for a tool with no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It efficiently communicates the core action and purpose, though it could benefit from a bit more detail without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is under-specified. It does not explain return values, any limitations of ShopifyQL (e.g., read-only), or how results are formatted. For a query tool with one parameter, more context about expected output and usage would make it complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the 'query' parameter already including a description and example. The tool description adds no extra meaning beyond the schema, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool executes a ShopifyQL query for custom analytics and reporting, using a specific verb and resource. However, it does not explicitly distinguish itself from the sibling tool named 'shopifyql_query', which could cause confusion, so it doesn't fully earn a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'for custom analytics and reporting' implies usage context, suggesting it is for ad-hoc or custom analytics needs. But there is no explicit guidance on when to use this tool versus alternatives like 'get_analytics_report' or 'run_report', nor any exclusion criteria.
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 only states the action but does not disclose side effects such as whether an email is actually dispatched, any permission requirements, or whether the recipient is derived from the gift card 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that immediately conveys the core action. No wasted words or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description is minimally viable. However, it omits crucial context about the distinction between recipient and customer, and does not mention return values or side effects, leaving the agent with an incomplete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% coverage with the parameter description 'Gift Card ID', so the tool description does not need to add details. The description adds no extra meaning beyond the schema, aligning with the baseline of 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the action (send email) and resource (gift card notification) to a recipient, which is clear. However, it does not differentiate from the sibling tool send_gift_card_notification_to_customer, leaving ambiguity about who the recipient is versus the customer.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus the sibling send_gift_card_notification_to_customer, nor any conditions or prerequisites for sending the notification.
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 behavioral traits. It only states the generic action 'update' without any details on side effects, partial vs full updates, required permissions, or error conditions. This leaves the agent without important context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no unnecessary words. It is appropriately brief, though it sacrifices helpful context for brevity, which is acceptable given the schema coverage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a mutation tool with no annotations or output schema. The description should provide more context about the update behavior, return value, and prerequisites. It does not, making it incomplete for an agent to confidently use the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with each parameter (id, url, subPath, subPathPrefix) already documented. The description adds no additional meaning or usage details for these parameters, so the schema carries the burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Update' and identifies the resource 'an app proxy configuration', clearly indicating this is the update operation. It distinguishes from sibling tools like create_app_proxy, delete_app_proxy, and get_app_proxy by implying modification of an existing proxy.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like create_app_proxy or delete_app_proxy. It does not mention prerequisites, such as needing an existing app proxy ID, nor does it specify scenarios where this tool should be preferred.
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 available, the description carries the full burden of behavioral disclosure. It only says 'update' without explaining whether it performs a partial or full replacement, whether it is idempotent, what permissions are needed, or any side effects. This is a significant gap 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no redundant words, making it concise and front-loaded. However, it omits any mention of updatable fields or behavior, which is efficient but minimal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite full schema coverage, the absence of annotations and an output schema means the description must explain behavioral context, return values, and usage nuances. It does not, leaving the tool under-specified for an agent to invoke confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for all four parameters (100% coverage), so the description does not need to add parameter details. The baseline of 3 applies because the schema already handles parameter semantics effectively.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('update') and resource ('metaobject definition'), clearly distinguishing it from create/delete metaobject definition tools and the separate update_metaobject tool. It is unambiguous and directly states 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like update_metaobject or other update tools. There are no exclusions, prerequisites, or context hints, leaving the agent to infer usage from the name alone.
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 only says 'Update an existing script tag' without explaining update semantics (partial vs. full update, effect on unspecified fields, permissions, side effects, or response format). It gives minimal indication of mutation but lacks actionable behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasted words. It is front-loaded with the action and resource. While it could be expanded with behavioral details, conciseness is effectively achieved.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given 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 is too sparse. It lacks key contextual details such as whether the update is partial or full, what happens if fields are omitted, and what the response/result is. The schema covers parameters, but overall usage context is incomplete for an agent to invoke the tool correctly in varied situations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with descriptive entries for id, src, cache, and displayScope. The description itself adds no parameter-specific meaning, but the schema already provides sufficient semantics. The baseline of 3 is appropriate because the schema handles parameter explanation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Update') and resource ('script tag'), clearly distinguishing it from sibling tools like create_script_tag, get_script_tag, and delete_script_tag. It states exactly 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. While the verb 'Update' implies use for existing script tags, there are no exclusions, prerequisites, or comparisons with sibling tools. The agent must infer usage from the name and schema alone.
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 only says 'accept' without explaining effects, prerequisites, reversibility, or response behavior. For a mutation tool, this is a significant 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that immediately conveys the action. It contains no filler or redundancy, and its front-loaded structure makes it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the simple schema, this is a mutation tool with no annotations and no output schema. The description lacks critical context such as when to use it, what acceptance entails, and any side effects. It is minimally sufficient but leaves the agent without adequate operational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (fulfillmentOrderId and message) are already documented in the schema. The description adds no additional meaning beyond what the schema provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action: 'Accept a fulfillment request for a fulfillment order.' It uses a distinct verb and resource, and the verb 'accept' naturally contrasts with the sibling tool 'reject_fulfillment_request', 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention that this should be used when approving a pending fulfillment request, nor does it reference sibling tools like reject_fulfillment_request or get_fulfillment_order for context.
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 full responsibility for behavioral disclosure. It only says 'add a cash transaction' but does not explain effects such as whether the session total is updated, how different transaction types (ADD, REMOVE, SALE, etc.) affect behavior, or whether the operation is reversible. This is a significant gap for a write 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler. It conveys the core purpose efficiently and is front-loaded with the action verb. Every word contributes meaning, making it an optimal length for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has six parameters, an enum with five transaction types, and no output schema. The description does not explain the different transaction types or how they relate to the amount, nor does it mention required context like the session existing. The description is too sparse for the tool's semantic richness, leaving the agent without critical context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no extra parameter semantics, leaving all meaning to the schema. Since the schema already documents each parameter, the description provides no additional value beyond what the structured data offers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Add a cash transaction to a tracking session' clearly identifies the action (add), the resource (cash transaction), and the target (tracking session). This distinguishes it from sibling tools like create_cash_tracking_session or get_cash_tracking_sessions, which focus on sessions rather than transactions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 alternatives, nor does it mention any prerequisites or exclusions. It only states the basic action, leaving the agent to infer usage from the tool name and schema without any explicit decision support.
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, but it only states the action 'create'. It does not mention side effects, permissions, uniqueness constraints on the handle, or what response the caller should expect, leaving the agent uncertain about the operation's implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with zero filler. It communicates the essential purpose efficiently without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the schema covering parameters, the description lacks necessary operational context: it does not state what the tool returns (no output schema exists), any post-creation effects, or how it fits into the broader fulfillment workflow. This is insufficient for a non-trivial create operation with 8 parameters and no annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema comprehensively describes all 8 parameters, so the description does not need to elaborate on them. The description itself adds no parameter-level detail, but the high schema coverage (100%) keeps this at the baseline acceptable level.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create a new custom fulfillment service' clearly names the action (create) and the specific resource (custom fulfillment service), distinguishing it from sibling tools like update_custom_fulfillment_service and delete_custom_fulfillment_service. It is a precise, unambiguous statement of the tool's core function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as create_fulfillment or get_custom_fulfillment_services. There is no mention of prerequisites, exclusions, or contexts where 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.
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 only states the high-level action and does not disclose side effects, prerequisites (e.g., required permissions), duplicate-code handling, or response behavior. A create operation's basic behavior is implied, but beyond that it is opaque.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no extraneous content. It efficiently conveys the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 10 parameters, 5 required, and no output schema or annotations, the description is too sparse. It does not mention return values, error cases, or how 'basic' relates to the schema's options, leaving the agent with an incomplete picture.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so each parameter has a description. The tool description adds 'percentage or fixed amount', which reinforces the discountType enum, but no additional semantic value beyond the schema is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as creating a discount code with specific types (percentage or fixed amount). It distinguishes itself from siblings like update_discount_code and get_discounts by focusing on creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like create_price_rule or update_discount_code. The word 'basic' hints at limitations but does not explicitly state scenarios or 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 full responsibility for disclosing behavioral traits. It only states the basic create action and does not mention potential side effects, permission requirements, error conditions, or whether the operation is reversible. For a create-type tool, this is a significant 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that is front-loaded with the verb and object. It contains no filler or redundant information, making it concise and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and no annotations, and the description does not explain what the tool returns, what happens after creation, or how fieldDefinitions should be structured beyond the schema. Given the moderate complexity (5 parameters, nested fieldDefinitions), this minimal description is insufficient for complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters are already documented with descriptions. The tool description adds no additional meaning beyond what the schema provides. According to the baseline for high coverage, a score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Create'), the resource ('metaobject definition'), and its purpose ('establishes the structure for custom data objects'). It distinguishes this tool from siblings like update_metaobject_definition and delete_metaobject_definition, and from create_metaobject (which creates instances).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention that update_metaobject_definition should be used for modifying existing definitions, nor any prerequisites or conditions. The agent is left to infer usage from the name and sibling context.
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 states that it creates a product, with no mention of side effects, permissions, reversibility, async behavior (e.g., variants created via bulk API), or response format. This is insufficient 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence with no extraneous information. It is front-loaded with the action and resource, making it concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 parameters, nested variants), the lack of annotations and output schema, the minimal one-sentence description does not provide adequate context about behaviors like bulk variant creation, required fields (title), or return values. Schema covers parameters but not behavioral context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter having a description. The description adds no parameter-level detail, but the schema already documents fields, types, and enums (e.g., status enum). Baseline score of 3 is appropriate when 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Create' with the resource 'product' and scope 'in the Shopify store'. This clearly distinguishes it from sibling tools like update_product and delete_product, and it aligns with the creation intent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions. It only states the literal purpose, leaving usage context entirely implicit.
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 bears full responsibility for disclosing behavioral traits. It only says 'create' without mentioning side effects, required permissions, whether the return is immediately active or pending, or any other operational detail. The description adds no insight beyond the minimal 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence of six words with no filler. It front-loads the verb and object, making the purpose immediately clear. No unnecessary information is included, and the brevity is appropriate for the simple action it describes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is too minimal for a mutation tool with no annotations and no output schema. It does not explain the return lifecycle (e.g., the need to check returnable fulfillments or that returns may require approval), nor does it mention what the response contains. The tool is part of a larger workflow, but the description lacks this context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all three parameters (orderId, returnLineItems, returnShippingFee) having descriptions. The tool description adds no extra parameter meaning, but the schema already provides full semantics, so 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and the resource ('a new return from an order'), which is specific and distinct from sibling tools like get_returns_by_order, approve_return_request, or close_return. The verb and object combination unambiguously identifies 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as create_refund or get_returnable_fulfillments. It does not mention any prerequisites, workflow steps, or situations where this tool is appropriate, leaving the agent to infer usage from the name alone.
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 disclosing behavioral traits. It only states the action without mentioning side effects (e.g., status change), reversibility, permissions, or any post-condition. This is a significant gap 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded and contains no filler. Every word earns its place, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is contextually incomplete. With no annotations or output schema, the description should provide more context about the return process, such as when declining is appropriate or what the outcome is. The schema covers parameters, but the broader behavior is underspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and each parameter has a clear description including the enum for 'reason' and an example for 'returnId'. The description adds no additional parameter semantics, but the schema already provides sufficient detail, hitting the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Decline a return request' uses a specific verb ('decline') and resource ('return request'), clearly distinguishing it from sibling tools like approve_return_request and close_return. It unambiguously states the action performed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as approve_return_request or close_return. The usage context is only implied by the name, with no explicit exclusions or decision criteria.
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 the full burden. It only says 'Delete', implying a destructive operation, but does not disclose consequences like irreversibility, dependent data removal, permissions, or failure scenarios. This is a significant gap 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that states exactly what the tool does. It is concise, has no fluff, and the message is immediately clear, earning a high score for efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter delete, the description is too sparse. It lacks information about return values, side effects, or when to use the tool, and with no output schema or annotations, the burden falls entirely on the description. The tool is not adequately contextualized.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage with 'id' described as 'Channel ID to delete'. The tool description adds no extra meaning beyond this, so a baseline score of 3 is appropriate since the schema handles parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete a sales channel' clearly states a specific action (delete) and a specific resource (sales channel). It distinguishes this tool from other delete_* tools by naming the resource type, and the name aligns with the description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. With many delete_* siblings, the description does not clarify any prerequisites, conditions, or situations where this tool should be chosen over similar delete operations.
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 for behavioral disclosure. It only states the basic delete action but does not reveal consequences such as permanence, related effects, or error behavior. This is a significant gap for a mutation 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no wasted words. It is front-loaded and clearly states the purpose, making it efficiently structured for a simple delete operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description alone is insufficient. It does not cover important contextual elements like deletion side effects, reversibility, failure conditions, or when to use the tool. The tool is simple but the description leaves too many gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the single parameter 'id' already described as 'Delivery Customization ID to delete'. The tool description adds no additional parameter semantics, so it meets the baseline of 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete a delivery customization rule' uses a specific verb (delete) and names the resource (delivery customization rule), clearly distinguishing it from sibling tools like create, update, and get operations on the same resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention prerequisites, whether deletion is irreversible, or any contexts where deletion should be avoided. The description only states the action without any usage context.
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 states that a price rule is deleted, but does not disclose permanence, side effects on active discounts, or permission requirements. The verb 'delete' implies destruction, but lacks 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no filler words. It is appropriately sized for a simple delete operation and front-loads the key action and target.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with no annotations and no output schema, the description is too sparse. It lacks essential context about irreversibility, effects on related resources, or disclaimers about required permissions. A minimal viable description should at least hint at consequences or constraints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage for the single 'id' parameter with a clear description ('Price Rule ID to delete'). The tool description adds no additional parameter meaning, but the schema fully documents the required input, meeting the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete a price rule' uses a specific verb ('Delete') and resource ('price rule'), clearly distinguishing it from siblings like get_price_rule, create_price_rule, and update_price_rule. It is concise 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention preconditions, such as whether the price rule must be inactive or if deletion is preferable to disabling via update.
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 transparency burden, but it only lists event types. It does not mention pagination behavior, default ordering, authentication needs, or what the response contains, which are significant gaps for a data-fetching 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no fluff or redundancy. Every word contributes to explaining the tool's core function, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 7 optional parameters and no output schema, but the description is minimal. It fails to explain return values, pagination expectations, or sorting behavior, leaving the agent under-equipped for correct invocation and response interpretation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds a small amount of extra meaning by enumerating example event types ('page views, product views, searches'), which helps understand the 'query' filter, but it does not substantially augment the schema's own parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource construction ('Fetch customer events') and clarifies the scope with concrete examples (page views, product views, searches). This clearly distinguishes it from sibling tools like get_customer or get_audit_events.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor any exclusions. The description merely states what it does without contextualizing against other event-related or customer-related tools.
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, so the description must disclose behavioral traits. It only states the action without mentioning pagination, return format, side effects, or permissions. 'Fetch' implies read-only but no explicit safety info is given.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It directly conveys the tool's purpose and examples, fitting within the concise length standard.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having 5 optional parameters, no output schema, and no annotations, the description only provides a basic action statement. It fails to mention return values, pagination behavior, filtering options, or any limitations, leaving the agent without enough context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage of parameter descriptions, so the schema already explains each parameter. The description adds no information about parameters, but per the rubric baseline is 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Fetch' with the resource 'files' and scopes it to 'uploaded to the store', clearly distinguishing it from sibling tools like get_file (singular) or get_theme_files. It also gives examples of file types, 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as get_file or get_theme_files. The description doesn't mention any exclusions or prefer conditions, so the agent has to infer usage from the name and context.
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, yet it only states 'Fetch metaobjects of a specific type.' It does not disclose pagination behavior, default page size (50), the fact that the response is a list, or any limitations/permissions. The parameter schema hints at pagination via 'after' and 'first', but the description itself adds no behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with five words, extremely concise and free of redundancy. It front-loads the action and resource, and every word contributes to the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and no annotations, so the description must compensate by explaining the return value and behavior. It does not state that the response is a paginated list of metaobjects, nor does it mention the default limit or cursor usage. The description is minimal and under-specified for a tool with three parameters and pagination support.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are fully documented structurally. The description repeats the 'type' concept but does not add any additional meaning to the parameters (e.g., how pagination works or what the default is). This aligns with the baseline of 3 for complete schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Fetch' with the resource 'metaobjects' and a clear qualifier 'of a specific type', which distinguishes it from sibling tools like get_metaobject_definitions (which fetches definitions) and mutation tools like create_metaobject/update_metaobject. It clearly states what the tool retrieves.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as get_metaobject_definitions, nor does it mention any exclusions or prerequisites. It simply states what it does without contextualizing the choice, leaving the agent without criteria for 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?
No annotations are provided, so the description must carry the behavioral disclosure burden. It only states 'Fetch an order edit by ID' and does not reveal any details about error handling, authentication, rate limits, or the structure of the returned order edit. This is minimal disclosure beyond the obvious read 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is immediately clear and front-loaded with the action and resource. There is no redundant or irrelevant text, making it highly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the tool is simple with one parameter and no output schema, the description lacks essential context about what an 'order edit' is, especially given the presence of related order-edit tools in the sibling list. It also doesn't specify what the response contains. This incompleteness could lead to incorrect usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of the parameter documentation, including a descriptive example ('gid://shopify/OrderEdit/123456789'). The tool description adds no additional parameter semantics beyond what the schema already provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Fetch an order edit by ID' uses a specific verb ('Fetch') and resource ('order edit') with a clear scope (by ID). It distinguishes itself from siblings like get_order, calculate_order_edit, and apply_order_edit, which target different resources or actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no when-to-use guidance or comparison to alternatives. Given related tools like calculate_order_edit and apply_order_edit, some context on when to retrieve an order edit directly would help. Without this, the agent has no explicit direction.
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 only states the action without mentioning pagination behavior, return format, authorization needs, or any side effects. The description is not misleading but omits important behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that directly states the action and resource. It is front-loaded and contains no extraneous information, earning a perfect score for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is too sparse for a tool with no annotations and no output schema. It lacks guidance on pagination, relationship to sibling tools, and expected usage scenarios, making it incomplete for an agent to fully understand the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for all parameters (publicationId, after, first), so the schema already documents parameter meanings. The description adds no extra parameter semantics, meeting the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Fetch' and identifies the resource as 'collections published to a publication', clearly distinguishing it from generic collection listings. The scope is explicit and unambiguous, making it easy to select among sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like get_collections, get_publication_products, or get_collection_listings. It does not mention excluded scenarios or provide context for choosing this tool over others.
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 were provided, so the description carries the full burden. While it implies a read-only operation ('Fetch'), it does not disclose the return shape, whether it returns all policies in one call, or any specific behavioral traits. It adds little beyond the operation name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the primary action and resource, followed by clarifying examples. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (zero params, no output schema), the description is minimally sufficient but lacks details about return value structure and differentiation from the sibling 'get_legal_policies'. It could benefit from a brief note on when to use this tool versus related legal policy tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema coverage is trivially 100%. The description does not need to explain parameters, and the baseline for zero-parameter tools is 4. Examples in the description help clarify expected content but are not required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Fetch' and identifies the resource 'shop policies' with examples (refund, privacy, terms of service). It clearly states what the tool does, but it does not distinguish itself from sibling tools like 'get_legal_policies', which may serve a similar purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. It simply states what it does without mentioning when it should be preferred over similar sibling tools (e.g., get_legal_policies) or any preconditions.
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 only says 'Fetch a specific file from a theme' without explaining what the response includes, whether it returns the file content or metadata, any authentication requirements, or error behavior. This is a significant gap for a read 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It efficiently conveys the core purpose without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool's simplicity, the description lacks essential behavioral details such as return format (file contents vs. metadata), and there is no output schema or annotations to fill in missing context. For a complete tool, more information about what the caller receives or any constraints would be needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for both parameters (themeId and filename) with clear examples. The description adds no additional parameter information, but since the schema fully documents parameters, a 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches a specific file from a theme. The word 'specific' distinguishes it from sibling get_theme_files which retrieves all files, and from get_theme which retrieves theme metadata. This is a specific verb+resource with clear scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives. It does not mention when to prefer get_theme_files or other theme-related operations. The only implied usage is through the word 'specific', but there is no explicit context or 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 full responsibility for behavioral disclosure. It only states the action without explaining side effects, idempotency, whether the order must be in a certain state, or what happens if the order is already open. For a mutating tool, this is a significant 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that communicates the action and state without any fluff or redundant phrasing. It is highly concise and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool's simplicity, the description omits essential context for an agent: the relationship to close_fulfillment_order, when the open action is valid, and any expectations about the order's lifecycle. The tool is a mutation with no annotations and no output schema, so more context is needed for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully describes the only parameter ('id' with 'Fulfillment Order ID'), and the description adds no extra meaning beyond what the schema provides. With 100% schema coverage, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Mark' with a specific resource 'fulfillment order' and target state 'open', clearly distinguishing it from sibling tools like close_fulfillment_order and open_order. The phrase 'ready for fulfillment' adds useful contextual purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention that it is the inverse of close_fulfillment_order, when it should be called relative to acceptance, or any prerequisites for the order's state.
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 implies a state-changing action but offers no details on side effects, reversibility, permissions, or scheduled publishing behavior. It essentially restates the purpose without additional 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single focused sentence, front-loaded with the key verb and object. It is concise with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
As a mutating operation with no annotations and no output schema, the description lacks important context such as return values, prerequisites, and the effect of the optional publishDate. The schema covers parameter types but not behavioral completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover all three parameters with examples and format hints (e.g., id example, publishDate ISO 8601, publicationIds array). The description adds no extra parameter semantics beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (publish), resource (collection), and target (sales channels). It distinguishes from siblings like unpublish_collection and other collection CRUD tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like unpublish_collection, nor any context on prerequisites or how to obtain publication IDs. The description only states the core action without usage context or 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 full responsibility for behavioral disclosure. It does not mention prerequisites (e.g., whether the order must be in a specific status), side effects, or the response format. As a mutation tool, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that directly states the tool's purpose. It is concise, front-loaded with the verb, and contains no superfluous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with moderate complexity, the description is too sparse. It lacks critical context about fulfillment order states (e.g., only 'scheduled' orders can be rescheduled), potential side effects, or expected return values. Given the absence of an output schema and annotations, this is a notable gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers both parameters with descriptions (id and fulfillAt), achieving 100% coverage. The description adds no extra semantic value beyond the schema, but that is acceptable given the high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Reschedule'), the resource ('a scheduled fulfillment order'), and the target ('to a new date and time'). It distinguishes the tool from siblings such as cancel_fulfillment_order and hold_fulfillment_order.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor does it mention preconditions or exclusions. It simply states what the tool does, leaving the agent without enough context to decide if this is the right tool for a given situation.
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 fully disclose behavioral traits. It only states the action 'revoke' but does not mention whether revocation is permanent, what effects it has on future payments or subscriptions, whether any permissions are required, or what the operation returns. This is a significant transparency gap for a destructive/mutating 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no unnecessary words. It is appropriately sized and immediately communicates the core purpose without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given 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 is too sparse. It fails to explain the consequences of revoking a payment method, whether the action is reversible, or how the caller should interpret the result. Given the tool's potential side effects, more context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for both parameters, so the schema already documents 'Payment Method ID' and 'Reason for revocation'. The description adds minimal extra meaning beyond naming the resource, 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Revoke' and a clear resource 'a customer's stored payment method', making the tool's function unambiguous. It is implicitly distinguished from sibling tools like get_customer_payment_method by the action of revoking, which only this tool performs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, no prerequisites (e.g., needing to first retrieve the payment method via a get tool), and no mention of related read operations. There is no explicit context for when revocation is appropriate.
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 provided, the description bears the full burden of behavioral disclosure. It only says 'Update an existing delivery option generator,' which reveals the mutation but nothing about side effects, permissions, idempotency, or error conditions. This is comparable to the 'update_drive' example that received a 2 for lacking such details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no filler. It is appropriately sized and front-loaded with the verb and resource. However, it adds little beyond the tool name itself, making it slightly redundant, but it is grammatically complete and not bloated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has only 2 parameters and no output schema, but the description is extremely minimal. It does not explain the effect of the update (e.g., whether metafields are merged or replaced), the return value, or any prerequisites. The description is adequate for a simple update but leaves meaningful gaps that the schema cannot fill.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of the parameters with descriptions (id and metafields), so the baseline is 3. The tool description adds no additional meaning about the parameters, relying entirely on the schema. Since schema coverage is complete, the description's lack of param-specific info does not lower the score below baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update an existing delivery option generator' clearly states the action (update) and the resource (delivery option generator), and the word 'existing' distinguishes it from create/delete siblings. It is specific and unambiguous, so it fully satisfies the 'specific verb+resource+scope' criterion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as create_delivery_option_generator or delete_delivery_option_generator. It does not mention any prerequisites, typical use cases, or exclusions. The only hint is the word 'existing,' but that is implied rather than 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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only says 'Update an existing location' without explaining update semantics (e.g., partial vs full update), required permissions, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no filler. Every word is meaningful and it is front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 11 parameters, no output schema, and no annotations, this terse description leaves significant gaps. It does not explain return values, update behavior, or usage context, making it minimally viable but far from complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with all 11 parameters having descriptions, so the baseline is 3. The description adds no additional parameter semantics 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Update') and resource ('an existing location'). It distinguishes from sibling tools like create_location, delete_location, get_location, and activate_location.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There are no mentions of prerequisites, exclusions, or relationships to other location-related operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/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 only states 'Update an existing marketing event' with no information about partial vs. full updates, error handling, required permissions, or effects on related data. This is essentially a restatement of the tool's name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. It is front-loaded and immediately conveys the core action, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 8 parameters, no output schema, and no annotations, the description is insufficient for an agent to fully understand the tool's behavior. It lacks detail on return values, expected errors, and whether updates are partial or full. The schema covers parameter syntax, but the overall context remains incomplete for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents all 8 parameters clearly. The description adds no additional parameter semantics beyond what the schema provides, thus 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update an existing marketing event' uses a specific verb ('update') and resource ('marketing event'), clearly distinguishing it from sibling tools like create_marketing_event, get_marketing_event, and delete_marketing_event. It is concise 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for updating existing events, but provides no explicit guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. The context is clear from the name, but no direct comparison is made.
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 full responsibility. It only says 'Update an existing price rule' without disclosing side effects, partial update behavior, idempotency, permissions, or what happens on failure. The mutation aspect is implied but no additional behavioral traits are revealed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that communicates the core purpose in six words. There is zero waste and it is appropriately sized for the tool's straightforward action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given 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 is insufficient. It does not explain whether the update is partial or full, whether missing fields are preserved, what the response contains, or any prerequisites like the price rule needing to exist. The schema covers parameters, but the overall context of the operation is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage, with descriptions for all six parameters including id, title, dates, usage limit, and once-per-customer flag. The description adds no extra 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (update) and the resource (price rule), distinguishing it from create_price_rule and delete_price_rule by specifying 'existing'. This is a specific verb+resource that clearly 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus creating or deleting a price rule. The description only states what it does, leaving the agent to infer usage from the tool name and sibling context.
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 disclosure burden. It only states 'Update', implying mutation, but does not disclose whether updates are partial or full, whether existing metafields are replaced or merged, or any side effects such as irreversibility or required 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence, front-loaded with the verb and object, and contains no unnecessary words. It is appropriately sized for the simplicity of the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given 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 is minimal and relies entirely on the schema for parameter details. It does not explain return values, side effects, or provide any usage context beyond the basic operation, making it incomplete for a meaningful agent selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage for both parameters (id and metafields), including descriptions for each property. The description adds no additional parameter semantics beyond what the schema already provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'update' and identifies the resource as 'validation rule', clearly distinguishing it from sibling tools like create_validation and delete_validation. It is concise and unambiguous about 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives. It does not mention prerequisites like fetching the rule first, nor does it name create_validation or delete_validation as alternatives for other operations. The word 'existing' hints that the rule must already exist, but this is not elaborated.
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 mentions that it targets a manual collection but does not disclose whether products are appended or replaced, how duplicates are handled, whether it's idempotent, or what the return/error behavior is.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no unnecessary words. It clearly states the action and target.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
As a simple two-parameter mutation with no annotations or output schema, the description is adequate for basic understanding but misses important behavioral context such as idempotency, error conditions, and return values, 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/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes both parameters with 100% coverage. The description adds only the 'manual' constraint on collectionId, which is a useful qualifier but does not substantially deepen parameter understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Add') and identifies the resource ('products') and target ('manual collection'), clearly distinguishing it from sibling tools like get_collection or update_collection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as create_collection or update_collection. The description only states the action, not any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 mentions the core state transition (draft to order) but does not disclose side effects (e.g., what happens to the draft, whether payment is captured, or if the action is reversible). This is a significant gap 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It clearly conveys the tool's purpose in minimal space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete enough to understand the basic operation, but it lacks context for the paymentPending parameter's effect, any limitations, or what the response contains. Given no annotations and no output schema, the description should provide more context for an agent to make a fully informed decision.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters. The description adds no additional meaning 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Complete') and resource ('draft order') and clearly states the outcome ('convert it to an order'). It distinguishes this from sibling tools like complete_checkout, which operate on checkouts, not draft orders.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. It only states what it does, leaving the agent to infer usage from context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 only states the obvious mutation ('Create') without mentioning required fields, permissions, idempotency, or success/failure behavior. The agent gets no additional context beyond what a create operation implies.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler or redundancy. It is appropriately sized for the tool's apparent simplicity and front-loads the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create operation with a rich schema, the description is minimally adequate. However, it lacks return value information (no output schema) and does not clarify the relationship to company entities or the meaning of B2B company location. This leaves gaps for a complex nested-address create tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of the 7 parameters with descriptions, so the baseline is 3. The description adds no extra parameter semantics; it only repeats the resource type already implied by the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and the resource ('a new location for a B2B company'), which distinguishes it from generic sibling tools like create_location by specifying the B2B company context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as create_location. It lacks context about prerequisites, scenarios, or exclusions, leaving the agent to infer usage from the name alone.
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 disclosing behavioral traits. It only states the creation action but does not reveal side effects, permissions required, whether the referenced function must exist, or what the response contains. This is a significant gap for a create 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It efficiently communicates the core purpose, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the basic purpose and the schema documents parameters, but it omits contextual details such as what a Shopify Function entails, the expected return value, and any prerequisites or consequences. For a tool with no annotations or output schema, this leaves some gaps in the agent's understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides complete descriptions for both parameters (functionId and metafields), giving 100% coverage. The tool description adds no extra parameter semantics beyond what the schema already states, so a 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Create a new fulfillment constraint rule using a Shopify Function' with a specific verb and resource. It distinguishes this from sibling tools like update_fulfillment_constraint_rule and delete_fulfillment_constraint_rule by emphasizing the create action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, such as needing an existing function, or contrast with update/delete operations. The agent is left to infer usage from the create action alone.
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 full responsibility. It only states the action without disclosing side effects, permission requirements, idempotency, or uniqueness constraints. For a mutation tool, this is a significant 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that is easy to parse and contains no filler. It is appropriately concise for a simple create operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a fully documented schema and no output schema, the description is minimal but adequate for a straightforward create tool. However, it does not mention the return value or any operational context, leaving some gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does 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 unique handle note, so the baseline is 3. The description adds no parameter-level meaning beyond what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create a new navigation menu' uses a specific verb and resource, clearly distinguishing it from sibling tools like update_menu and delete_menu. It does not explicitly name alternatives, but the resource scope 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a new navigation menu is needed, but provides no explicit guidance on when to use this tool versus alternatives or any exclusions. The tool name itself conveys the basic use case.
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 behavioral traits. It only states the create action without revealing any side effects, permission requirements, or behavior on duplicate names. It adds no context beyond the tool name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no filler. It is front-loaded and appropriately sized, even though it is terse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with a fully described schema. However, the description does not mention return values or error conditions, and no annotations exist to cover the mutation's safety profile. It is minimally complete but leaves ambiguity about what happens after creation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all three parameters with descriptions (100% coverage), so the baseline is 3. The description adds no additional parameter semantics, but the schema already provides adequate meaning for name, subject, and body.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Create' and identifies the resource 'packing slip template,' clearly distinguishing it from sibling tools like get_packing_slip_templates, update_packing_slip_template, and delete_packing_slip_template.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives. It does not mention creating a new template as opposed to updating an existing one, nor any prerequisites or use cases.
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 must disclose behavioral context, but it only mentions the creation action. It doesn't state whether the page is published by default, required permissions, or other side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, zero-waste sentence. It is appropriately sized for a simple create operation and contains no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description conveys the core purpose but omits return value expectations and any operational context. Given the simple schema and no annotations, it is minimally complete but not richly informative.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema provides 100% coverage of all four parameters with descriptions, so the description adds no extra parameter meaning. Baseline 3 applies because the schema carries the semantic weight.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'Create' and the resource 'online store page', directly distinguishing it from sibling update/delete/get page tools. 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like create_product or update_page. No context about typical use cases, prerequisites, or when it should be avoided.
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 must disclose behavioral traits, but it only states the action without detailing permanence, side effects, or error behavior. The deletion aspect is implied but not elaborated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with no unnecessary words. It is front-loaded and perfectly concise for the simple operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one parameter and no output schema, so the description is minimally adequate. However, it lacks contextual details like irreversibility or required permissions, which would improve completeness for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides full coverage (100%) with a clear description for the required 'id' parameter. The tool description adds no additional 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action (Delete) and the resource (app proxy), making the tool's purpose explicit. It distinguishes itself from siblings like get_app_proxy and update_app_proxy by specifying deletion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool or when to avoid it. There are no prerequisites, consequences, or alternatives mentioned, leaving the agent without context for 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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It fails to mention that deletion is destructive, likely irreversible, or may affect related data such as company locations, contacts, or orders. No permissions or side effects are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, succinct sentence that immediately states the tool's purpose. There is zero filler or redundant information, making it optimally concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema, no annotations), the description is minimally adequate. However, it leaves out important context such as unrecoverable consequences or any special conditions for B2B company deletion, making it slightly under-specified for a destructive operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with the `id` parameter already described as 'Company ID to delete'. The description adds no additional semantic value beyond the schema, so a 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete a B2B company' clearly states the verb (delete), resource (B2B company), and distinguishes it from sibling tools like create_company, update_company, get_company, and get_companies. It precisely identifies the action and target.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor any prerequisites, exclusions, or warnings. While the delete action is self-explanatory, the description offers no context about potential cascade effects or when deletion is appropriate.
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 must carry full transparency weight. It only states the destructive action ('Delete') without disclosing consequences like irreversibility, permission requirements, or error behavior. Minimal value beyond the tool name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded, no extraneous wording. For a simple delete operation, 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/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity and complete schema, the description is minimally viable. However, it lacks any mention of return values, side effects, or prerequisites, which would enhance completeness even for a simple delete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema provides 100% coverage of both parameters (customerId and addressId) with descriptions. The tool description adds no extra parameter meaning, justifying the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states a specific verb ('Delete') and resource ('a customer's address'), distinguishing it from sibling tools like create_customer_address and update_customer_address. No ambiguity about what action is performed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance provided on when to use this tool versus alternatives (e.g., when to update instead of delete, or prerequisites like address existence). The description gives no context for decision-making.
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 merely states 'Delete' without mentioning irreversibility, required permissions, or downstream effects (e.g., impact on fulfillment orders). The description adds no context beyond the tool name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence: 'Delete a custom fulfillment service.' It contains no unnecessary words or fluff and is appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one well-documented parameter, and the description clearly states its purpose. However, it lacks behavioral transparency and usage guidance, so while it is minimally viable for selection and invocation, it is not fully complete for a destructive operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the single parameter 'id' is already described as 'Fulfillment Service ID to delete' in the schema. The description adds no additional parameter semantics, 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Delete a custom fulfillment service.' It clearly distinguishes this tool from sibling tools like get_custom_fulfillment_services, create_custom_fulfillment_service, and update_custom_fulfillment_service, as well as from delete_fulfillment_order.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, no prerequisites, and no disambiguation from other deletion tools. Usage is only implied by the tool name and description, but there is no explicit 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.
Behavior2/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 only states 'Delete a delivery option generator' without mentioning permanence, potential side effects, or any constraints. For a destructive operation, this lack of context is a significant 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that directly states the tool's purpose. There is no redundancy or unnecessary information, making it efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (one parameter, no output schema), the description is minimally adequate. However, without annotations, it would benefit from noting the irreversible nature of deletion or any required permissions. It is not as incomplete as a tool with undocumented parameters, but it lacks behavioral context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes the 'id' parameter ('Delivery Option Generator ID to delete') with 100% coverage. The description adds no additional semantic value beyond the schema, so 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete') and the resource ('a delivery option generator'), making it distinct from sibling tools like create/update/get delivery option generator. The verb and object are 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus other tools, nor does it mention any prerequisites or context. It simply states the action. While the intent is obvious from the name, there is no explicit usage scenario or alternative guidance.
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 only states the action and does not mention irreversibility, required permissions, side effects on related data, or whether the deletion is permanent/soft. This is a significant gap for a destructive 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with zero waste. It front-loads the action and resource, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation with one parameter, the description is minimally viable. However, the lack of annotations and output schema means the agent receives no information about side effects, irreversibility, or error conditions. The tool is adequately scoped but could benefit from a note about permanence or behavioral constraints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents the single 'id' parameter with description 'Draft Order ID', achieving 100% schema description coverage. The description adds no additional parameter detail, 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete a draft order' uses a specific verb and resource, clearly distinguishing it from sibling tools like get_draft_order, create_draft_order, and complete_draft_order. It unambiguously states the action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like cancel_order or delete_order, nor on any prerequisites or restrictions (e.g., draft order status). The description leaves the agent without contextual decision support.
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 provided, the description carries the full burden of behavioral disclosure. It does not disclose whether deletion is permanent, irreversible, or requires specific permissions. The description merely restates the action implied by the tool name, adding no behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. It is appropriately brief for a simple delete operation, conveying the essential purpose efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with one fully documented parameter, the description is minimally adequate. However, it lacks information about return values, error behavior (e.g., non-existent ID), and reversibility, which would be useful for an agent to use the tool correctly without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: the sole parameter 'id' is described as 'Fulfillment Constraint Rule ID to delete'. The tool description adds no additional parameter information 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete') and the resource ('fulfillment constraint rule'), distinguishing it from sibling tools like get_fulfillment_constraint_rules, create_fulfillment_constraint_rule, and update_fulfillment_constraint_rule. The verb and resource are 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not mention when to use this tool versus alternatives, nor does it state prerequisites or exclusions. The usage is only implied by the verb 'delete', offering no explicit direction.
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 supplied, the description carries the full burden of behavioral disclosure. It only states the action 'Delete a location' without noting that deletion may be permanent, require specific permissions, or have side effects on inventory or orders. This is a significant gap for a destructive 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one concise sentence with no filler. It front-loads the action and resource, making it immediately understandable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one parameter, no output schema), but the description omits important context about the destructive nature of the operation, such as irreversibility or conditions for deletion. It is minimally viable but has clear gaps in consequence disclosure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes the single parameter locationId with a clear description ('Location ID to delete'), and schema coverage is 100%. The description adds no additional meaning beyond what the schema already provides, so 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete a location from the store' uses a specific verb and resource, clearly distinguishing it from sibling tools like get_location, update_location, and activate/deactivate_location. It states exactly what the tool does without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use delete_location versus alternatives like deactivate_location or update_location. It does not mention prerequisites or conditions under which deletion is appropriate, such as whether the location must be empty or inactive.
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 the full burden. It merely says 'Delete a navigation menu' without disclosing that deletion is irreversible, whether special permissions are needed, or if cascading effects (e.g., removing menu items) occur. For a destructive action, this lacks critical 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, 'Delete a navigation menu', which is concise and front-loaded with the action. Every word is necessary, and there is no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one required parameter, no output schema), the description and schema cover the basic action. However, it omits important contextual warnings such as irreversibility, permission requirements, or whether deleting a menu can fail if it is in use. This leaves the agent without guidance on edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with the property 'id' described as 'Menu ID to delete'. The tool description adds no additional semantic meaning beyond what the schema already documents, 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Delete' plus the resource 'navigation menu', which clearly distinguishes it from sibling menu tools like create_menu, update_menu, and get_menu. No ambiguity about what action is performed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool vs alternatives, nor any prerequisites such as checking if the menu is in use or confirming its existence. The presence of many sibling menu tools makes this omission noticeable.
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?
Since no annotations are provided, the description must disclose behavioral traits, but it only says 'Delete'. It does not state that deletion is permanent, irreversible, requires special permissions, or what consequences may occur. The destructive nature is implied but not explicitly communicated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no extraneous words. It is perfectly concise and well-structured, with the core information front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple tool with one parameter fully described in the schema, so the description is minimally viable. However, it omits important context such as the irreversible nature of deletion and what happens after success (e.g., return value). Given no annotations or output schema, a bit more depth would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%—the only parameter 'id' has a clear description ('Template ID to delete'). The description adds no additional meaning beyond the schema, so it meets the baseline but does not enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete a packing slip template' uses a specific verb and resource, clearly distinguishing it from sibling tools like get_packing_slip_templates, update_packing_slip_template, and create_packing_slip_template. The purpose is unambiguous and directly aligned with the tool name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, no prerequisites (e.g., needing to fetch the template first), and no exclusions such as 'cannot delete templates in use'. It simply states the action without contextual usage instructions.
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?
The description simply states the destructive action with no details about permanence, side effects, permissions, or failure modes. With no annotations, the agent gets no additional behavioral context beyond the verb 'delete'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One short sentence, front-loaded and direct, with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple tool, but missing usage guidelines and behavioral caveats. The schema covers the only parameter, and no output schema is present, so some description of expected behavior would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'id' is fully described in the schema, so the description adds no value. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action (delete) and the resource (product) with a specific scope ('from the store'), distinguishing it from the many other delete_* tools for different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives (e.g., unpublishing or archiving a product) or prerequisites. It only states the basic action, leaving the agent to infer context.
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 provided, the description carries the full burden of behavioral disclosure. It only says 'Fetch', which implies a read operation, but does not explicitly state that it is read-only, whether it returns a paginated list, how the 'after' cursor is used for pagination, or any side effects. No details on response format or error behavior are given, which is a significant gap for a mutable store operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no filler or redundancy, front-loading the verb 'Fetch'. However, it is somewhat under-specified for a tool with five parameters; it could benefit from mentioning pagination or filtering, but as a short description it is still efficient and readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 parameters, no output schema) and the minimal description, the description is inadequate. It does not explain that the tool returns a list of checkouts, how pagination works with 'after', or how the 'query' parameter interacts with the 'abandoned or active' scope. The schema covers parameter semantics, but the overall behavior and expected output are left unspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage of all five parameters with clear descriptions (e.g., 'Cursor for pagination', 'Number of checkouts to fetch'), so the description does not need to repeat this. The description adds no additional meaning beyond what the schema offers, hence 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Fetch' and the resource 'checkouts', with an explicit scope of 'abandoned or active' and 'from the store'. This distinguishes it from the singular sibling 'get_checkout' by implying a list operation, and from other checkout-related tools like 'complete_checkout' or 'get_checkout_branding_settings'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for fetching multiple checkouts, but it does not explicitly state when to use this tool versus alternatives such as 'get_checkout' for a single checkout or 'get_returns_by_order' for other resource types. There is no exclusion or alternative guidance provided, leaving the agent to infer context from the plural form.
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 must carry the full burden of behavioral disclosure. It only says 'fetch customers' and does not mention pagination, default page size, return format, or that it is a read-only operation. The schema provides parameter details, but the description lacks key behavioral context like how results are returned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that immediately conveys the tool's purpose. There is no redundant or filler content, making it appropriately concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with 5 optional parameters and no output schema or annotations, the description is adequate but incomplete. It covers the basic purpose but does not explain pagination behavior, default values, or what the response looks like. These gaps could confuse an agent deciding whether to use this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% parameter description coverage, so the schema already documents all five parameters. The description adds no extra parameter semantics beyond mentioning 'optional filtering', so it does not go beyond the schema baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches customers from the Shopify store, using the verb 'Fetch' and the resource 'customers'. It distinguishes from get_customer (singular) by pluralizing 'customers', but does not explicitly name the alternative or clarify that it returns a 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'with optional filtering' implies this tool is suitable for fetching customers with filters, but it gives no explicit guidance on when to use this over get_customer (for a specific customer) or other list tools. No exclusions or alternatives are mentioned.
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 only states 'Fetch discount codes' and doesn't disclose read-only nature, pagination behavior, or return format. For a simple read operation, some context is still lacking, but the minimal action is clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no wasted words. It is front-loaded with the action and resource, making it highly scannable. There is no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The schema fully documents the parameters, but the description lacks usage context, return value expectations, and alternative tool mention. For a straightforward fetch tool, it is minimally adequate, but the missing usage guidance and behavioral details make it incomplete for an agent unfamiliar with the domain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear parameter descriptions for 'after', 'first', 'query', and 'reverse'. The description adds no additional meaning beyond the schema, so baseline 3 applies. It doesn't clarify relationships between parameters or provide examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Fetch discount codes from the store' clearly states a specific action (fetch) on a specific resource (discount codes). It distinguishes from sibling tools like 'get_discount_code' (singular) and 'create_discount' by indicating a plural list operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as 'get_discount_code' or 'create_discount'. It doesn't mention pagination, filtering, or any context for when this tool is appropriate, leaving the agent without strategic selection information.
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 carry the burden of behavioral disclosure. It only says 'Fetch navigation menus,' which implies read-only, but it does not disclose pagination behavior, return format, or any side effects. The schema provides pagination parameters, but the description adds no behavioral context beyond the obvious fetch 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no superfluous information. It efficiently conveys the action, target resource, and context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, but there is no output schema and no annotations. The description does not mention what the return value contains or how pagination works. While 'menus' implies the return, the description lacks details that would be helpful for an agent to fully understand the tool's behavior in the context of many sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents both parameters with descriptions ('Cursor for pagination' and 'Number of menus to fetch'), providing 100% coverage. The description does not add any additional parameter semantics beyond what the schema already provides, 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Fetch' and clearly identifies the resource 'navigation menus' for the online store. It effectively distinguishes this plural list operation from the singular 'get_menu' sibling and other menu-related mutations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as get_menu or create_menu. It simply states what it does without any context on use cases, exclusions, or relationships to sibling tools.
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 provided, the description must carry the full burden of behavioral disclosure. It only states 'Fetch metaobject definitions' and does not disclose pagination behavior, return format, ordering, or whether it is a read-only operation. 'Fetch' implies a read, but no explicit safety or side-effect information is given.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with no filler or redundant content. It is appropriately short for a simple read operation, earning a high score for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has only two documented parameters and no output schema, so the description needs to explain return values or scope, but it does not. It adequately conveys the basic intent but leaves gaps about what a metaobject definition is, what the response contains, and how pagination works beyond the schema's parameter descriptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with descriptions for both parameters: 'Cursor for pagination' for after, and 'Number of definitions to fetch (default: 50)' for first. The description adds no additional meaning beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Fetch metaobject definitions' uses a specific verb ('fetch') and a clear resource ('metaobject definitions'). It distinguishes from sibling tools like get_metaobjects (which fetches instances) and create/update/delete_metaobject_definition, 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool vs alternatives. No mention of when to prefer this over get_metaobjects or the definition CRUD tools, nor any prerequisites or context. The description is purely a statement of action without usage 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?
With no annotations, the description carries the burden. The verb 'Fetch' clearly implies a read-only operation, which is a key behavioral trait. However, it does not disclose what happens on error (e.g., not found), permission requirements, or return format, though for a simple getter this is minimally 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler words. Every word earns its place, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter getter, the description is mainly complete, but it lacks disambiguation from the related get_custom_pixel tool and does not describe the return value (no output schema exists). It is adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the 'id' parameter has a clear description with an example. The description's phrase 'by ID' simply mirrors the schema, adding no extra semantic detail. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Fetch a specific pixel by ID' clearly states a specific action (fetch) and resource (pixel), with scope ('specific... by ID'). It distinguishes from sibling get_pixels (plural listing) but does not explicitly disambiguate from get_custom_pixel, so full distinction is left to the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of when to prefer get_pixel over get_pixels or get_custom_pixel, nor any contextual hints like 'use this when you have a pixel ID'.
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 provided, the description carries the full burden of behavioral disclosure. It only states the basic fetch operation and does not mention pagination behavior, sort order, authorization requirements, or any side effects. This is a minimal disclosure for a read 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the core purpose without superfluous content. It is appropriately sized for a simple read tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple fetch operation with well-documented parameters, the description is minimally adequate. However, with no output schema and no annotations, it lacks context about return format, pagination behavior, or edge cases, which could be valuable for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters clearly. The description adds no extra meaning beyond the schema, providing only the verb and resource. Baseline 3 is appropriate since the schema handles parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Fetch products published to a publication' uses a specific verb (Fetch) and resource (products published to a publication), clearly distinguishing it from sibling tools like get_products (all products) and get_publication (publication details).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as get_product_listings or get_products. There are no exclusions, conditions, or references to sibling tools, leaving the agent to infer usage from the name alone.
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 provided, the description carries the full burden of behavioral disclosure. It only states the basic fetch action and does not reveal whether the operation is read-only, what 'returnable' means in terms of order/fulfillment status, or any potential side effects or permissions needed. This is a significant gap for a tool with no structured annotation 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It communicates the core purpose efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a simple fetch operation with a well-documented schema, but the description lacks context about the return value shape, the meaning of 'returnable', and any limitations. Since there is no output schema and no annotations, the one-line description is minimally viable but leaves notable gaps for an agent to fully understand behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all three parameters (after, first, orderId) already documented clearly. The description adds no additional meaning 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Fetch fulfillments that can be returned for an order' clearly states the action (fetch), resource (fulfillments), and specific filter (returnable for an order). It distinguishes this from sibling tools like get_fulfillment_orders or get_returns_by_order by focusing specifically on returnable fulfillments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, intended scenarios, or contrast with related tools such as get_returns_by_order or create_return. Usage context is left entirely to inference.
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 provided, the description carries the full burden of behavioral disclosure. It only says 'Fetch', which implies a read operation, but does not mention pagination behavior, authentication needs, rate limits, or what is returned. The schema shows pagination params, but the description adds no additional behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, straightforward sentence with no wasted words. It front-loads the essential information and is appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is relatively simple with well-documented optional parameters, and the description adequately conveys the core action. However, there is no output schema and no mention of default behavior or use cases, leaving some gaps. It is adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% since all four parameters have descriptions. The description adds no parameter-specific meaning, so the baseline of 3 is appropriate. It does not compensate for or enhance the schema details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Fetch) and resource (Shopify Payments disputes), distinguishing it from sibling tools like get_shopify_payments_payouts or get_shopify_payments_balance_transactions. It is 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. The name implies its purpose, but the description does not provide context about related tools or scenarios.
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 discloses the required 'read_analytics' scope, which is a useful behavioral trait since no annotations are provided. However, it does not state whether the query is read-only, how results are returned, or any error/rate-limit behavior, leaving much of the behavioral burden unaddressed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence that conveys the core purpose and scope requirement without any wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one parameter and no output schema, the description is minimal but covers the basic purpose and scope. However, the existence of a sibling tool with the same name pattern (run_shopifyql_query) is not addressed, and the return value is not described, leaving the description incomplete for an agent navigating a large toolset.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides full coverage for the single 'query' parameter, so the description adds no additional parameter semantics. It only contextualizes the query as being for analytics, which is a minor addition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool executes a ShopifyQL query for analytics and mentions the required scope. However, it fails to distinguish this tool from the sibling 'run_shopifyql_query', which appears to have the same purpose, so it does not fully differentiate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'run_shopifyql_query' or 'get_analytics_report'. The only contextual information is the scope requirement, which is a prerequisite rather than a usage guideline.
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 only says 'Update an existing sales channel' and omits details about required permissions, reversibility, partial/full update semantics, or response behavior. This is similar to the 'update_drive' case, which scored 2.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single five-word sentence with no filler or redundant information. It is immediately readable and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The schema fully documents the parameters, but the description does not elaborate on update behavior (e.g., whether omitted fields are unchanged or reset), prerequisites, or expected effects. It is minimally viable for a CRUD update tool but leaves gaps that could confuse an agent choosing or invoking it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and all five parameters have individual descriptions, so the schema already provides parameter semantics. The description adds only the contextual hint that the target must already exist ('existing'), which is a minor addition beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Update') and resource ('sales channel'), and the word 'existing' distinguishes it from create/get/delete operations on the same resource. It clearly identifies the intended action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given about when to use this tool versus alternatives like create_channel, get_channel, or delete_channel. The word 'existing' implies it is for modifying already-created channels, but no clear usage conditions or exclusions are 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 carries the full burden of behavioral disclosure. It only says 'Update' without detailing side effects, permissions, or error behavior, mirroring the sparsity seen in the update_drive calibration example.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler or repetition. It is appropriately sized, front-loaded, and every word earns its place in conveying the action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update tool with full schema coverage, the description is minimally adequate but lacks usage guidelines and behavioral transparency. It leaves clear gaps in context, though it is not as inadequate as a tautology.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes all four parameters (id, name, note, externalId) with individual descriptions, so the schema does the heavy lifting. The description adds no extra parameter semantics, which is acceptable given 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Update an existing B2B company' with a clear verb (update) and resource (B2B company). It distinguishes from sibling tools like update_product, update_customer, and create_company by specifying the target resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites (e.g., company must already exist) or exclusions (e.g., use create_company for new companies).
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 provided, the description carries the full burden of behavioral disclosure, but it only states the action and resource. It does not disclose side effects, whether the update is partial or full replacement, error behavior, required permissions, or any other operational details. This is a significant gap 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence with no unnecessary words or filler. It is appropriately sized for the simple purpose, front-loading the verb and resource. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is relatively simple with a complete input schema, and the description gives a clear high-level purpose. However, it lacks behavioral context such as update semantics (patch vs replace), potential side effects, and response expectations. Given the absence of annotations and output schema, this is a minimal but not wholly inadequate description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage, with all five parameters having descriptions. The tool description adds no parameter-specific information, but since the schema already documents them, the baseline of 3 is appropriate. The description does not need to repeat schema details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update an existing custom fulfillment service' uses a specific verb (update) and resource (custom fulfillment service), which clearly distinguishes it from sibling tools like create, get, and delete custom fulfillment services. It is 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, no prerequisites, and no context on how it fits into the broader fulfillment workflow. It does not mention any exclusions or specific scenarios, leaving the agent to infer usage from the name alone.
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 provided, the description carries the full burden of behavioral disclosure. It only states 'update' without explaining side effects, whether it performs a partial or full replacement, permission requirements, idempotency, or the response format. The lack of any behavioral context beyond the verb leaves significant uncertainty 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with no redundant words or fluff. It front-loads the core purpose immediately. While brief, it avoids the tautology seen in under-specified descriptions and earns its place as a concise statement of the tool's function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a simple CRUD update with two parameters, and no output schema. The description covers the basic action but omits details about the update semantics (e.g., whether it replaces all metafields or only those provided), any prerequisites, and the return value. It is minimally viable but leaves gaps for an agent to fully predict behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema documents both parameters (id and metafields) with descriptions, so schema coverage is 100%. The description adds no additional parameter semantics, such as how the metafields are applied or the format expected. Since the schema already provides the baseline, a score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update') and the target resource ('an existing delivery customization rule'). This distinguishes it from sibling tools like create_delivery_customization, delete_delivery_customization, and get_delivery_customizations by indicating a mutation on an existing entity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as creating a new customization or deleting one. It does not mention prerequisites, typical scenarios, or exclusions. The only implied usage is that you update when the rule already exists, which is minimally conveyed by the verb 'update'.
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 provided, the description carries the full burden for behavioral disclosure. It states that the tool updates an existing subscription and avoids recreation, but it does not disclose whether updates are partial or full replacement, any permission requirements, side effects, or what the response contains. For a mutation tool, this is a significant 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loads the primary purpose, and every clause adds value. There is no unnecessary verbosity or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a moderate complexity with no output schema and no annotations. The description adequately states the tool's purpose and lists changeable fields, but it lacks details about partial update semantics, returned data, or error conditions. Given the schema covers parameters, the description provides a minimal but acceptable context, though gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with descriptions for all five parameters, so the schema already documents the parameters well. The description adds synonyms like 'endpoint URL' for uri and 'included fields' for includeFields, which slightly aids comprehension but does not add meaning 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update an existing webhook subscription') and lists the specific fields that can be changed (endpoint URL, filters, included fields, metafield namespaces). This distinguishes it from sibling tools like create_webhook_subscription, delete_webhook_subscription, and get_webhook_subscription, though it does not explicitly name those alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'without recreating the subscription' implies that this tool should be used over recreating, providing some usage context. However, it does not explicitly state when to use this tool versus create or delete, nor does it mention any prerequisites or exclusions. The guidance is implied rather than 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 states that cancellation happens but does not disclose side effects, reversibility, whether the order must be in a particular state (e.g., not shipped), or what the response contains. This is a significant gap for a mutation 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with zero wasted words. It clearly and efficiently states the action and target resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations and no output schema, the description should provide at least some context about cancellation constraints or the result. It only states the action, leaving the agent uninformed about when cancellation is valid and what to expect in the response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with the parameter description 'Fulfillment Order ID', and the description adds no additional meaning beyond the schema. Baseline 3 is appropriate since the schema fully documents the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Cancel' with the resource 'fulfillment order', clearly distinguishing it from sibling tools like open/close/hold fulfillment order and from cancel_order which targets orders. It is unambiguous and precise.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a fulfillment order needs to be cancelled but offers no explicit guidance on when to use this tool versus alternatives, no mention of prerequisites, state constraints, or when not to use it. It is not misleading but minimal.
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 provided, the description carries the full burden of behavioral disclosure. It does disclose the permission requirement, but it omits other important behavioral traits such as idempotency, side effects on existing proxies, error behavior, or reversibility. This is a significant gap 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the action and resource. There is no wasted wording, and the permission note is the only additional context, making it appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having 4 parameters and no output schema, the description provides minimal context beyond the schema. It does not explain what an app proxy is, what the response will look like, or any creation behavior. This is inadequate for a tool with this complexity and no annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all four parameters (url, appId, subPath, subPathPrefix) documented. The description adds no extra parameter meaning, so the baseline of 3 is appropriate since the schema handles the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and the resource ('an app proxy for an app'), which distinguishes it from sibling tools like update_app_proxy, delete_app_proxy, and get_app_proxy. It also adds a relevant permission note, 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (when you need to create an app proxy) but does not explicitly contrast with alternatives or state when not to use it. The permission requirement gives some context, but there is no reference to update/delete/get proxies for existing resources.
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 behavioral traits. It states that the tool creates a customer, which implies a write operation, but provides no additional context such as idempotency behavior, duplicate handling, validation rules beyond the schema, permissions required, or what the response contains. This is minimal 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that conveys the essential purpose. It is front-loaded with the action and resource, with no filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite being a simple create tool, there is no output schema and no annotations. The description does not mention return value, success/failure indicators, or any side effects. For a mutation with 100% schema coverage, this is still inadequate because the agent would not know what to expect after invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with every parameter having a brief description in the schema. The description does not add any parameter-level detail, but the baseline is 3 because the schema already documents the parameters. It does not, however, clarify the required nature of email beyond the schema's 'required' field.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and the resource ('a new customer in the Shopify store'). This distinguishes it from sibling tools like update_customer, get_customer, and delete_customer, which perform different operations on the same resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for creating customers but does not explicitly state when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or relationships to tools like create_customer_address. The intent is clear from the name and verb, but no direct guidance is given.
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 behavioral burden. It only restates the operation ('create') without disclosing side effects, validation behavior, response format, or implications of the setAsDefault parameter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It effectively communicates the core action and target in seven words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given 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 is under-specified. It does not explain return values, the effect of setting a default address, or relationship to existing customer data. Sibling tools performing update/delete are not referenced.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% description coverage for all parameters (customerId, address, setAsDefault). The description adds no parameter-specific meaning beyond what the schema already states, so a 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Create') and a clear resource ('a new address for a customer'). It distinguishes from sibling tools like update_customer_address and delete_customer_address by indicating a distinct add 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through the word 'new' but offers no explicit when-to-use guidance or alternatives. It does not mention prerequisites like existing customer, nor does it contrast with update or delete operations.
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 states that a new rule is created and mentions Shopify Function, but does not disclose validation requirements, side effects, error cases, or any operational constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded with the verb and resource. It contains no fluff and communicates the core action efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is too brief for a create operation. It does not explain what constitutes a delivery customization rule, how metafields are used, whether the function must exist beforehand, or what the response will contain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% as both parameters have descriptions. The description's mention of 'Shopify Function' aligns with the functionId parameter, but it adds no extra meaning 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Create') and resource ('delivery customization rule') and clarifies the use of a Shopify Function. This clearly differentiates it from sibling tools like get_delivery_customizations, update_delivery_customization, and delete_delivery_customization.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when creating a new delivery customization rule but provides no explicit guidance on when to choose this over similar tools like create_delivery_option_generator. It also does not mention prerequisites such as the existence of the function ID.
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 full burden. It states the action 'Create a new...' but does not disclose additional behavioral traits such as required permissions, idempotency, side effects, return format, or error behavior. This is a significant gap for a mutation tool with no 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, concise, and front-loaded with the action and resource. No unnecessary information is present; every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description should explain return values and additional context, but it does not. The tool has two parameters and a clear schema, yet the description fails to clarify what 'delivery option generator' means or what the functionId refers to beyond the schema. This leaves the agent without critical information for successful invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with both functionId and metafields documented. The description adds no extra parameter semantics, but since the schema already explains all parameters, a 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (create) and the resource (delivery option generator), and distinguishes it from sibling tools like update/delete/get delivery option generator. The phrase 'using a Shopify Function' adds useful context about the underlying mechanism.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: use this tool to create a new delivery option generator. However, it provides no explicit guidance on when to use it versus alternatives, no prerequisites, and no exclusions. It falls short of explicitly naming alternatives or conditions, so it only meets the 'implied usage' level.
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 for disclosure. It only mentions the required scope, but omits behavioral consequences such as whether payment is captured, receipts are sent, inventory is adjusted, or if the order is final and irreversible. This is a significant gap 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short sentences, front-loaded with the primary purpose, then use cases, then scope. Every sentence earns its place with no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a complex tool (16 parameters, nested objects, no output schema, no annotations), but the description is extremely sparse. It fails to convey critical context such as the difference between create_order and create_draft_order, the financial impact of creating an order, or parameter interdependencies (e.g., variantId vs sku, customerEmail vs customerId).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all 16 parameters well-described in the input schema. The tool description adds no parameter-level details, but per rubric, high schema coverage warrants a baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'create' and resource 'order', and provides use cases ('importing orders from external systems or creating wholesale orders'). However, it does not explicitly distinguish itself from sibling tools like create_draft_order, so it loses a point on sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives concrete context for when to use this tool (importing external orders, wholesale orders) and states a prerequisite (requires write_orders scope). It does not explicitly mention alternatives or when-not-to-use, but the use cases are clear enough to guide 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?
No annotations are provided. The description only states the action without disclosing side effects, prerequisites (beyond functionId), permissions, or return behavior. It adds minimal behavioral context beyond the tool's name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single concise sentence that front-loads the action and resource. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema and no annotations, yet the description is minimal. It does not mention what the tool returns or any post-conditions, such as whether the validation rule becomes active immediately. This leaves gaps for an agent deciding whether this matches the task.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters with descriptions (functionId and metafields, including nested fields), achieving 100% coverage. The description adds no extra parameter information, so baseline score is 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States 'Create a new cart/checkout validation rule using a Shopify Function' – specific verb (Create), resource (validation rule), scope (cart/checkout), and method (Shopify Function). Distinguishes from siblings like get_validations or create_cart_transform.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use vs alternatives. The description implies usage for creating a validation rule but does not mention exclusions or related tools like create_cart_transform. Compare to get_calls which named an alternative.
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 provided, so description carries full burden. It only lists supported URI formats, but does not disclose side effects, permissions, verification behavior, or what happens after creation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with action, no redundant detail. Efficiently conveys core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description should explain return value and practical usage. It does not mention the response, required fields beyond schema, or any creation caveats.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover all 5 parameters (100% coverage), so baseline is 3. The description repeats the URI type info already in the schema and adds no new parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Create' with resource 'webhook subscription', clearly distinguishing from sibling tools like list/get/update/delete. It also specifies supported endpoint types (HTTPS, Pub/Sub, EventBridge), adding scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the verb 'create' but no explicit when-to-use or alternative guidance is given. The description does not mention when to prefer this over update/delete, nor any prerequisites.
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 provided, the description must carry full behavioral disclosure. It states the primary effect (decreases balance, creates a transaction) but omits important details like prerequisites (e.g., active gift card), error conditions (insufficient balance), reversibility, or authorization requirements. For a mutation tool, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with two short sentences that front-load the primary verb and resource. The second sentence slightly restates the first, but there is no waste or irrelevant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and a mutation operation, the description is minimally sufficient but lacks context about when to use the tool, edge cases, and potential side effects. The high schema coverage compensates for parameter details, but the overall context is not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all parameters (id, note, amount, currencyCode). The description adds no additional parameter context beyond what the schema provides, meeting the baseline for full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Debit (deduct)') and resource ('gift card'), and explains the effect: 'Creates a debit transaction that decreases the gift card balance.' This distinguishes it from sibling tools like credit_gift_card.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the usage context (deducting funds from a gift card) but does not explicitly compare with alternatives like credit_gift_card or provide exclusions. No when-to-use/not-to-use guidance is given, though the operation is straightforward.
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 provided, the description carries the full burden of behavioral disclosure. It only states the action without revealing anything about side effects, reversibility, prerequisites (e.g., required current state), or impact on billing. For a mutating operation, this is a significant 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The entire description is a single, front-loaded sentence with zero filler. Every word contributes to explaining the tool's purpose, making it an exemplary model of conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although the tool is simple with only one parameter, the description provides no context about when to use it relative to similar subscription contract state-transition siblings (cancel, expire, pause). Given the low complexity, this sparse description is still insufficient for an agent to reliably select this tool over alternatives without additional clues.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully covers the single parameter with a description ('Subscription Contract ID to mark as failed'), and the tool description provides no additional parameter-level detail. Since schema coverage is 100%, the baseline of 3 applies; the description adds no extra semantic meaning beyond what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('mark') and a specific resource ('subscription contract') with a targeted state ('as failed'), making it unmistakably distinct from sibling operations like cancel, pause, or expire. It clearly conveys the operation's intent in a single concise phrase.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies that it should be used when a subscription contract needs to be marked as failed, but it offers no explicit guidance on when to choose this over cancel_subscription_contract, expire_subscription_contract, or pause_subscription_contract. No when-not or alternative tools are mentioned.
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 mentions fetching all including inactive, but fails to disclose pagination behavior (despite the 'after' and 'first' parameters), default return format, or whether the call is read-only. The term 'all' is misleading given pagination parameters exist, suggesting it may not actually return all results in a single response.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the primary purpose. It contains no fluff or redundant information, earning a perfect score for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and no annotations, so the description should compensate by explaining what is returned and any important behaviors. It only states the fetch scope, omitting details about response structure, pagination, or how 'all' interacts with the 'first' parameter. This leaves the agent with insufficient context to use the tool correctly for complex scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter clearly documented (cursor, count, includeInactive). The description adds no additional meaning beyond the schema, so a 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches all cart transforms, including inactive ones. This distinguishes it from sibling tool get_cart_transforms, which likely returns a filtered or default set. The verb 'Fetch' and resource 'cart transforms' are 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for retrieving the complete set of cart transforms, including inactive ones, but does not explicitly state when to use this over get_cart_transforms or other alternatives. There are no exclusion criteria or scenario-based guidance, so usage is only implied.
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 full responsibility for behavioral disclosure. It only says 'Fetch', which hints at a read operation, but does not explicitly state that this is safe, non-mutating, or describe pagination behavior, default sort order, or any permissions needed. This is a significant gap for a 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It efficiently conveys the core purpose without verbose explanations or redundancy. This is appropriately concise for a simple listing tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and four parameters, the description is too thin. It does not mention the return format, pagination behavior (despite having pagination-related parameters), or any default sorting. The agent is left without enough context to understand the tool's full behavior or expected output, which is particularly problematic for a listing endpoint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All parameters have full descriptions in the schema (100% coverage), so the baseline is 3. The description adds no additional parameter meaning or context beyond what the schema already provides. It does not explain how parameters interact or any defaults beyond the schema's 'first' default of 50.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Fetch installed apps for the store' uses a specific verb (Fetch) and clearly identifies the resource (installed apps) and scope (the store). It distinguishes from the sibling tool 'get_app' by specifying the plural form, indicating it lists multiple apps. This is clear 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context that this tool fetches installed apps for the store, implying it is for listing. However, it does not explicitly state when to use this tool versus alternatives like 'get_app' (for a single app) or other get_* tools. No when-not-to-use guidance is provided, 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.
Behavior2/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. The verb 'fetch' implies a read-only operation, but the description adds no further context (e.g., pagination behavior, required scopes, or that it returns a list). It essentially restates the tool name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded and directly states the tool's action. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple listing tool with optional filters (all documented in the schema) and no output schema, the description adequately conveys its purpose. It could slightly enhance completeness by explicitly mentioning 'list' or 'all requests', but it is functionally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all three parameters, so the schema provides sufficient semantics. The description does not mention parameters or add any extra meaning, leading to the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('fetch') and resource ('customer data erasure (GDPR) requests'), making the tool's function clear. It also distinguishes from sibling tools like request_customer_data_erasure and cancel_customer_data_erasure by indicating retrieval only.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given on when to use this tool versus alternatives. The description does not mention that this is for fetching existing requests or that request/cancel tools are for creating/canceling, leaving the usage context implicit.
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 provided, the description carries the full burden of disclosing behavioral traits. 'Fetch' implies a read-only operation, but the description does not mention pagination behavior, return format, or any side effects. It adds minimal context beyond the verb and resource, leaving the agent without information about what to expect from the call.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no unnecessary words. It efficiently conveys the core purpose without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and no annotations, so the description should explain what is returned and any relevant context like pagination. It does not mention the return value, what a custom fulfillment service is, or how the 'after' and 'first' parameters affect results. This is a minimal description that leaves significant gaps for a tool with optional pagination params.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for both parameters ('after' as cursor, 'first' with range and default). The description does not add any parameter information beyond what the schema already provides, so a 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Fetch custom fulfillment services for the store' uses a specific verb ('Fetch') and clearly identifies the resource ('custom fulfillment services') and scope ('for the store'). It clearly distinguishes this from the sibling tool 'get_fulfillment_services' by explicitly referring to 'custom' fulfillment services.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for fetching custom fulfillment services, but provides no explicit guidance on when to use it versus alternatives like 'get_fulfillment_services' or other fulfillment-related tools. There are no exclusions or alternative recommendations, so usage context is only implied by the resource name.
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 only says 'Fetch configurations' without mentioning that results are paginated (despite 'after' and 'first' params), that it returns a list, or any other behavioral traits. The description adds no context beyond the tool name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no fluff or redundancy. It is efficient and front-loaded, though it sacrifices some helpful detail for brevity, preventing a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list endpoint with fully documented params, the description is minimally adequate. However, with no output schema, it fails to state what is returned (e.g., an array of configuration objects) or that it supports pagination. Additional context about the response shape would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with both 'after' (cursor for pagination) and 'first' (number to fetch) already documented. The description adds no extra parameter meaning, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Fetch delivery option generator configurations' uses a specific verb ('Fetch') and resource ('delivery option generator configurations'), making the action unmistakable. It clearly distinguishes from sibling tools such as create/update/delete_delivery_option_generator and get_delivery_customizations by naming the specific resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use guidance is provided, but the name and sibling set (create/update/delete) imply this is the read/list operation for delivery option generators. There are no alternatives or exclusions stated, so usage is only implicitly clear.
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 full responsibility for behavioral disclosure. 'Fetch' implies a read operation, but there is no mention of errors, permissions, rate limits, or response structure. Minimal transparency beyond the basic 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded, with no redundant words. It is concise and to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given 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 full schema coverage and no output schema, the description is adequate. It could mention that it returns a single price rule object, but the simplicity of the operation keeps it reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the 'id' parameter is fully described with an example. The description's 'by ID' aligns with the schema but adds no additional meaning beyond what the schema already provides. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Fetch'), a specific resource ('price rule'), and a distinguishing qualifier ('by ID'). This clearly differentiates it from get_price_rules (plural) and other price-rule tools in the sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 alternatives like get_price_rules, create_price_rule, or update_price_rule. It simply states what it does without indicating context or 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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only states 'Fetch', implying a read operation, but does not mention return format, authorization requirements, or the specific scope of 'privacy settings'. This is insufficient for a tool with no schema or output schema to clarify 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One short, front-loaded sentence communicates the core purpose without any wasted words. For a zero-parameter tool, this level of conciseness is ideal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimal and does not provide enough context for a complete understanding. It does not describe what the returned privacy settings contain, nor does it distinguish itself from contextually related tools like 'get_visitor_privacy_consent'. Given the absence of an output schema and annotations, this is a significant gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema covers 100% of them (none). Per rubric, the baseline for 0 params is 4. The description adds no parameter-specific information, but there is nothing to compensate for, so a 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Fetch') and the target resource ('privacy settings') with a scope ('from the Shopify store'). It is easily distinguishable from the sibling 'update_privacy_settings' and 'get_visitor_privacy_consent', which target different operations or resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'get_visitor_privacy_consent' or 'update_privacy_settings'. It lacks any explicit context, prerequisites, or exclusions, leaving the agent to infer usage from the name alone.
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, and the description does not disclose any behavioral traits such as safety profile, permissions, or side effects. As a read operation it is likely safe, but the description does not confirm this, leaving the agent to assume.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of six words, front-loaded with the action and resource. It is appropriately concise, though it could include more context without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-ID operation with one fully documented parameter, the description is minimally sufficient. However, it lacks any mention of the return value format, usage alternatives, or prerequisites, making it less complete than it could be given no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single 'id' parameter is fully documented in the schema with a clear description and example. The tool description adds no additional meaning, but the schema coverage is 100%, 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the verb 'Fetch', the resource 'a specific report', and the method 'by ID'. This clearly distinguishes it from siblings like get_reports (plural) and run_report. It is a specific and unambiguous definition.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving a single report when the ID is known, but does not explicitly mention when to use get_reports for lists or run_report for executing a report. No exclusions or alternatives are 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 carries full responsibility for behavioral disclosure. It only says 'Fetch all' which implies read-only, but it does not disclose pagination behavior (despite 'first' and 'after' params) or that the response may require multiple requests. It also omits any mention of permissions or filtering via 'query'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence (12 words) that immediately conveys the core purpose. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description should explain return shape, pagination limits, and filtering. It only states the core action, leaving the agent to infer behavior from parameter names. This is insufficient for a tool with 4 parameters and no external structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description does not add meaning beyond the schema; 'for a customer or company location' echoes the ownerId schema description. No additional parameter context or examples are provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Fetch', the resource 'store credit accounts', and the scope 'for a customer or company location'. This distinguishes it from the singular sibling 'get_store_credit_account' and from credit/debit 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you need all accounts for a given owner, but it does not explicitly compare to alternatives or state when not to use this tool. There is no mention of singular get_store_credit_account for individual lookups, so 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.
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 says 'Get' without disclosing return format, error behavior (e.g., 404 if not found), or any side effects. For a read operation, 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded with the verb and resource. Every word earns its place with no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema or annotations, the description does not explain what the response contains, how to handle not-found cases, or when to use this over list_webhook_subscriptions. For a simple getter, it is minimally sufficient but lacks important context about the return value.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully describes the only parameter 'id' with type and example (100% coverage). The description adds no additional parameter semantics, 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get'), the resource ('webhook subscription'), and the scope ('specific... by ID'). It distinguishes from sibling tools like list_webhook_subscriptions (which retrieves all) and create/update/delete 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have a specific webhook subscription ID, but it does not explicitly mention alternatives like list_webhook_subscriptions for retrieving all subscriptions. The guidance is implied rather than 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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the basic purpose ('Get predictive search results') without revealing any additional behavior such as response format, filtering scope, or whether it includes all types by default. This is minimal disclosure, though the read-only nature is inferred from 'Get'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the essential purpose in as few words as possible. There is no wasted language, and the parenthetical efficiently adds key context about the nature of the results.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, no annotations, and only a minimal description, yet it has 3 parameters including a complex 'types' enum. The description does not explain what predictive search returns, whether results are limited to products, collections, etc., or how the 'first' and 'types' parameters interact. More detail is needed to make the tool usable without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% parameter descriptions, so the baseline is 3 per the rubric. The description adds no information about parameters beyond the schema; it does not mention 'query', 'first', or 'types' or how they behave, but the schema already fully documents them. Thus the description neither enhances nor detracts from parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' with a clear resource 'predictive search results' and adds the clarifying parenthetical '(autocomplete)', which directly states the tool's function and distinguishes it from sibling search tools like search_products and get_product_recommendations. This is a precise and unambiguous statement of purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the use case for autocomplete/typeahead through the parenthetical, but it does not explicitly state when to use this tool versus alternatives such as search_products or get_product_recommendations. No exclusions or alternative tool names are provided, so guidance is only implied rather than 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?
With no annotations, the description carries the full burden of disclosing behavioral traits. It only states the action without explaining side effects, reversibility, authorization needs, or what happens to the fulfillment order after rejection. This is a state-changing operation, and the description provides no safety or impact 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the action, and contains no filler. Every word contributes to defining the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a mutation tool with no annotations and no output schema. The description fails to provide context about the fulfillment request lifecycle, what rejection entails, or any constraints. For a state-changing operation, more context is needed to guide correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters (fulfillmentOrderId and message). The description adds no extra semantic information beyond what the schema provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Reject') and the resource ('a fulfillment request for a fulfillment order'). It is specific and distinct from sibling tools like accept_fulfillment_request or cancel_fulfillment_order.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is implied by the verb, but there is no explicit guidance on when to use this tool versus alternatives (e.g., accept_fulfillment_request) or any prerequisites such as the request being in a pending state. The description does not mention exclusions or conditions.
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 disclosing behavior. It mentions combining order history and addresses, but it fails to disclose that the source customer will be deleted, the operation is likely irreversible, or that this is a 'request' (possibly async). These are important side effects for an agent to understand before invoking.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that directly states the action and scope. It is concise with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema and annotations, the description should provide more context about return values, side effects, and the request nature of the operation. It does not explain what the response looks like or that this may be an asynchronous request, leaving the agent underinformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds context about what merging does (combines order history, addresses) but does not add parameter-specific meaning beyond what the schema already states about source and target customer IDs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Merge one customer into another') with the resource (customers) and scope (combines order history, addresses, etc.). It distinguishes from sibling tools like delete_customer and update_customer by emphasizing the merging behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool should be used when you want to combine two customer records, but it does not explicitly mention when not to use it or provide alternatives. There is no comparison with related tools such as delete_customer or get_customer_merge_requests.
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, so the description carries the full burden. It discloses the action (sending an email) and recipient (customer), but provides no information about side effects, prerequisites (e.g., existence of customer email), failure modes, or irreversibility. This is a significant gap for a side-effecting 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-formed sentence that directly states the action and recipient. It is front-loaded with the verb and contains no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a mutation (sends an email) with no annotations and no output schema. The description is too terse to cover crucial context such as return value, potential errors, or dependencies on customer contact info. For a comparable mutation tool, this is insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides a complete description for the sole parameter ('Gift Card ID') with 100% coverage. The tool description adds no further meaning beyond implying the gift card is used to identify the customer, so the schema baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Send') and resource ('gift card notification email') and clearly specifies the recipient as 'the customer associated with the gift card'. This distinguishes it from the sibling tool 'send_gift_card_notification_to_recipient', which likely targets the gift card recipient instead.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for notifying the customer, which is differentiated by the sibling tool name. However, it does not explicitly state when to prefer this over the recipient variant, nor does it provide any exclusions or conditions of use.
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 without disclosing side effects, reversibility, permission requirements, or impact on the collection record. This is a significant gap 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the verb and resource. It contains no filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two parameters and no output schema, the description is minimal but lacks behavioral context, like whether unpublishing is reversible or affects only the specified publications. This makes it incomplete for an agent to predict the full impact.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage with clear descriptions for both 'id' and 'publicationIds'. The tool description adds no additional parameter semantics beyond what the schema states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Unpublish' with the resource 'collection' and target 'sales channels,' clearly distinguishing it from sibling tools like publish_collection or delete_collection. It concisely states the operation 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives like publish_collection or update_collection. The usage context is implied by the action name, but there is no guidance on prerequisites, exclusions, or consequences.
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 full burden. It merely states the action 'update existing payment terms' without disclosing whether missing fields are unaffected, whether it's a partial update, error behavior, or dependency on the id. This ambiguity is significant 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with no redundant words, making it easy to parse. It is appropriately concise for a simple update tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the core purpose is clear, the description omits essential behavioral context: it doesn't state whether update is partial (other fields remain unchanged) or full replacement, nor what the response contains. For a tool with no output schema and no annotations, this is a notable gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for id, name, dueInDays, and discountPercentage, so the description adds no parameter-level detail. The baseline of 3 is appropriate since the schema fully documents parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'update' and the resource 'payment terms', clearly distinguishing from sibling tools like create_payment_terms, get_payment_terms, and delete_payment_terms. The word 'existing' clarifies that it modifies only already-created payment terms.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Existing' implies this is for modifying previously created payment terms, but no explicit guidance on when to use versus create/get/delete is provided. The description does not mention any alternatives or prerequisites.
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, and the description only states 'Update an existing product'. It does not disclose partial update semantics, whether unspecified fields are preserved or reset, permission requirements, side effects, or error behavior. The description carries the full burden of behavioral disclosure and fails to provide meaningful 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence that is front-loaded and contains no unnecessary words. It is appropriately sized for a straightforward CRUD operation, and the structure is clear and direct.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a mutation tool with no annotations and no output schema. The description provides only the most basic purpose and fails to elaborate on update behavior, return values, or any special considerations. For a 7-parameter tool, this is under-specified and leaves significant gaps for an agent trying to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides detailed descriptions for all 7 parameters, achieving 100% coverage. The description itself adds no parameter information. Since schema coverage is high, the baseline is 3, and the description does not enhance parameter understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'update' with the resource 'existing product', clearly distinguishing this from sibling tools like create_product, delete_product, and get_product. It clearly states the tool's function 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The word 'existing' implies this tool is for modifying already-created products, not creating new ones, but no explicit guidance is given on when to use this tool versus alternatives like create_product or update_order. Usage 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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the action and does not reveal side effects, whether it triggers proration, what happens if both optional parameters are provided or neither, permission requirements, or the nature of any returned data. This is a mutation tool and requires more behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no irrelevant details. It is appropriately concise and the core message is communicated clearly without wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given 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 is insufficiently complete. It does not clarify whether the operation updates a specific line item, what the expected response is, or the conditions under which the optional parameters should be used. The lack of context relative to the sibling subscription contract tools makes this hard for an agent to invoke confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with each parameter documented. The tool description adds no additional meaning about how parameters interact, such as whether at least one of the optional parameters must be supplied or how they combine. Baseline 3 is appropriate since the schema fully documents individual parameters but the description does not enrich the semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action: 'Change a product or product price in a subscription contract.' It identifies the verb (change), the resource (product/product price within a subscription contract), and distinguishes this from sibling tools such as cancel, pause, or activate subscription contracts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies its use for updating an existing subscription contract line, but it does not provide explicit guidance on when to use it versus alternatives, nor does it mention any prerequisites or exclusions. The intended usage is inferred from the name and description rather than explicitly 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, and the description only restates the creation intent without disclosing side effects, permissions, idempotency, or return behavior. It does not add behavioral context beyond the action itself.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single concise sentence that is front-loaded with the action and resource, with no wasted words. It earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create tool with a fully described schema, the description is minimally adequate. However, it lacks usage guidance and behavioral transparency, and the absence of an output schema means return values are unexplained, but the low complexity keeps the gap moderate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for both functionId and metafields, so the baseline is 3. The description's phrase 'using a Shopify Function' maps to functionId but adds no additional semantics or format details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Create' with resource 'cart transform' and adds 'using a Shopify Function', clearly distinguishing from sibling update/delete/get cart transform tools. It is direct 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for creating new cart transforms but does not explicitly state when to choose it over update_cart_transform or delete_cart_transform. No alternatives are named, and prerequisites like needing an existing functionId are not mentioned.
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 merely states 'create' without disclosing permissions, prerequisites, idempotency, or side effects. It does not mention whether the location must exist or what happens if a session already exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded with the action and object. There is no wasted wording or unnecessary filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create tool with full schema coverage, the description is adequate but not complete. It does not explain return values (no output schema) or preconditions, but the simplicity of the operation reduces the need for extensive context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema fully documents locationId, startingCash, and note. The description adds no additional meaning beyond what the schema provides, hitting the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Create') and resource ('cash tracking session') with a clear scope ('for a location'). It distinguishes from siblings like get_cash_tracking_session and close_cash_tracking_session by its creation intent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by stating it creates a new session, but it does not explicitly say when to use it versus alternatives like closing or adding transactions. No exclusions or alternative references are provided, so guidance is minimal.
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 behavioral traits. It highlights a key requirement ('requires app installation') but omits other important details such as expected response, side effects, permissions, or failure modes. It adds minimal transparency beyond the basic 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that clearly states the purpose and a key requirement. Every word earns its place; there is no redundancy or unnecessary detail, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create operation with three documented parameters, the description is minimally adequate. It lacks explicit usage guidance and return value information, but since there is no output schema, a brief description may be acceptable. However, given the absence of behavioral detail and alternatives, it is not fully contextualized for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for all three parameters, giving 100% coverage. The tool description does not add any extra parameter meaning beyond what the schema already offers. Baseline of 3 is appropriate since the schema fully documents the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and the resource ('a new sales channel'). It also adds a prerequisite ('requires app installation') which helps distinguish it from related tools like get_channel or update_channel. Although it doesn't explicitly name sibling tools, the verb and resource make 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: one would call this to create a sales channel. It does not explicitly mention alternatives or when not to use it. The prerequisite hints at a condition but does not explain when a user should choose this over other channel-related operations, so guidance is basic but not misleading.
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 restates the purpose and names the collection types; it does not mention side effects (e.g., that the collection is saved to the store), required permissions, or behavior differences between manual and smart collections (e.g., smart collections require rules).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no filler. It efficiently conveys the tool's function and the key distinction between collection types, earning a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward create tool with fully described parameters, the description is minimally adequate. However, it lacks any context about what the API will return, whether additional rules are required for smart collections, or any setup considerations. Given no output schema exists, the description could have offered more guidance on the expected result or workflow, so it falls short of being complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema describes 100% of the parameters including types, enums, and a description for each, so the baseline is 3. The description adds no parameter-specific meaning beyond saying 'manual or smart collection', which is already covered by the collectionType enum description. Thus it neither enhances nor detracts from schema information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and the resource ('collection'), and further specifies the two types (manual or smart). This distinguishes it from sibling tools like update_collection or delete_collection, which have different verbs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for creating a new collection, but provides no explicit guidance on when to use this tool versus alternatives, or any exclusions. There is no mention of prerequisites or when a manual vs smart collection would be appropriate, leaving the agent to infer from the type name.
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 must disclose effects. It mentions payment methods and refund scope but does not state side effects on order state, permissions required, or restocking implications, leaving the agent under-informed 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action, then a compact list of capabilities. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although the schema is well-described, the tool has 5 parameters and no output schema; the description lacks information about return values, prerequisites (e.g., order must be paid), and edge cases, making it only partially complete for a non-trivial refund operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover all parameters and nested fields, so the baseline is met. The description adds broad capability language ('line items, shipping costs') that loosely maps to refundLineItems/shippingAmount but does not detail syntax beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states 'Create a refund for an order' with a specific verb and resource, and enumerates supported dimensions (line items, shipping, payment methods), making the tool's role clear and distinguishable from sibling return/order-cancel 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use vs alternatives like create_return or cancel_order; the 'refund for an order' phrasing implies post-order context but does not exclude or compare 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 provided, so the description carries the full burden of behavioral disclosure. It merely restates the action ('Create') without mentioning side effects, permissions, reversibility, or any impact on the Shopify Payments balance. This is insufficient for a mutating 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with the verb first and no wasted words. It is concise without sacrificing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two flat parameters and no output schema, the description covers the core purpose but omits any behavioral context or expected outcome. It is adequate but lacks depth beyond the minimal requirement.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for both parameters (currency, accountId), so the description adds no additional meaning. The schema already provides clear descriptions, earning the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Create') and resource ('alternate currency payout') targeting a Shopify Payments account. It clearly distinguishes this creation action from sibling tools like get_shopify_payments_payouts, which retrieves payouts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for when a user needs to create an alternate currency payout, but it offers no explicit when-to-use guidance, prerequisites, or alternatives. Without any context about when not to use this tool, it falls at the 'implied usage' level.
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 discloses key behavioral effects: deactivation triggers movement of inventory, pending orders, and transfers. However, it does not mention reversibility, required permissions, whether the location remains accessible, or what happens if no destination is provided. With no annotations, the description carries the full burden but only partially fulfills it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler, but the grammar is slightly awkward ('moves inventory, pending orders, and transfers') which could cause minor misinterpretation. Still, it is efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has significant side effects and no output schema or annotations. The description does not clarify whether destinationLocationId is required (schema lists it as optional), nor does it mention error conditions, idempotency, or how to undo the action. The missing details are critical for a deactivation operation that moves data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters with descriptions, but the tool description adds meaning by clarifying that the destination location is for moving inventory, pending orders, and transfers—not just inventory as the schema implies. This extra context helps the agent understand the relationship between parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Deactivate a location' and specifies the associated side effects (moves inventory, pending orders, transfers). This distinguishes it from sibling tools like delete_location and activate_location.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool instead of alternatives like delete_location or update_location. The description does not mention use cases, prerequisites, or exclusions, so the agent must infer when deactivation is appropriate.
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 for behavioral disclosure. The description only states the operation itself and does not mention whether deletion is permanent, irreversible, requires certain permissions, or affects associated records. This is a significant gap for a destructive 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise phrase 'Delete payment terms' with no unnecessary words. It is front-loaded and to the point, perfectly sized for a simple delete operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema), the description is minimally viable but lacks any context about consequences, return values, or error conditions. Without annotations, the description does not fully address what an agent should expect behaviorally, though the operation itself is clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers the single 'id' parameter at 100% coverage with a clear description ('Payment Terms ID to delete'). The tool description adds no extra parameter information, but the schema already provides sufficient semantics, meeting 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete payment terms' uses a specific verb ('Delete') and a clear resource ('payment terms'), distinguishing it from sibling operations like get_payment_terms, create_payment_terms, and update_payment_terms. It unambiguously states 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the verb and resource: use when you need to remove a payment term. However, the description provides no explicit guidance on when to use this tool versus alternatives, and no mention of prerequisites or conditions (e.g., cannot delete if in use).
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 carry the full burden of behavioral disclosure. It only says 'Delete' without mentioning that deletion is permanent, irreversible, or what happens on success/failure. No side effects, permissions, or impact are described, leaving the agent with minimal behavioral insight beyond the verb itself.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with no padding. It is appropriately concise for a simple delete operation, placing the core action front and center without any waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one required parameter, and the schema covers it fully, but the lack of behavioral context (permanence, side effects) makes the description only minimally complete. Without annotations or an output schema, a bit more context would help an agent understand the full consequences of the operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with a useful example for the 'id' parameter. The description adds nothing about the parameter, so the baseline of 3 applies since the schema already documents the parameter well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete a script tag' clearly states the action with a specific verb and resource. It distinguishes itself from sibling tools like get_script_tag, create_script_tag, and update_script_tag by explicitly indicating it removes an existing script tag.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool instead of alternatives. It is implied that it is used when deleting a script tag, but there are no notes on prerequisites, exclusions, or when to prefer update_script_tag over deletion.
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 says 'fetch' without disclosing pagination behavior, sort defaults, or any other nuances related to the 5 optional parameters. The examples of event types add some context, but key behavioral aspects like cursor-based pagination are not mentioned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded with the main action ('Fetch audit events') and provides useful examples without unnecessary verbosity. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core purpose and gives examples, but with 5 optional parameters and no output schema, it leaves some gaps. It does not explicitly state that the result is a list of events, nor does it mention filtering or pagination capabilities, though the schema covers these details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 5 parameters have descriptions in the schema, achieving 100% coverage. The tool description itself adds no parameter-specific information, but the schema fully documents each parameter, so the description does not need to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches audit events for the store, with specific examples (staff actions, app installations) that differentiate it from sibling tools. The verb 'fetch' and resource 'audit events' are 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context about what kind of events are included (staff actions, app installations), implying when this tool would be useful. However, it does not explicitly state alternatives, exclusions, or when not to use it, so guidance is implied rather than 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 full burden for behavioral disclosure. It only states 'Fetch' with no mention of read-only nature, required permissions, error handling, or response format. It adds no transparency beyond the action itself, leaving the agent without safety or side-effect 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. Every word is informative, and it is appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one param, no output schema), and the description covers the basic operation. However, with no output schema, it does not mention what the response contains or any error behavior, leaving the agent slightly underinformed. It is adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% — the single 'id' parameter has a clear description and example. The tool description itself adds no parameter meaning, but the schema fully compensates. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Fetch a specific sales channel by ID' uses a specific verb ('Fetch'), names the resource ('sales channel'), and specifies the lookup method ('by ID'). This clearly distinguishes it from sibling tools like get_channels (list) and aligns with get_collection/get_product patterns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context: use this tool when you have a specific channel ID and need that single channel. However, it does not explicitly mention alternatives (e.g., 'use get_channels to list all') or when-not-to-use scenarios. The context is clear but understated.
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 full responsibility for disclosing behavior. While 'Fetch' indicates a read operation, it doesn't mention pagination, default limits, or return shape. The description adds little beyond what the tool's name already implies.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, concise sentence that communicates the core purpose with no superfluous words. Well-structured and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple GET tool with two optional params and no output schema, the description is minimally adequate. However, it lacks any mention of pagination behavior, default values, or what the response contains, 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with clear descriptions for 'after' (pagination cursor) and 'first' (count, default 50). The description adds no additional parameter context, but the schema fully covers 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Fetch') and resource ('delivery customization rules'), making it distinct from sibling tools like create/update/delete_delivery_customization. It's 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage as a read operation for delivery customizations, but provides no explicit guidance on when to use it versus alternatives (e.g., get_delivery_option_generators). No exclusion criteria or context are given.
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 full responsibility for behavioral disclosure. It only says 'fetch' without mentioning pagination, filtering, or that it is a read-only operation. This is a significant gap for a tool with 5 parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no unnecessary words. It is front-loaded and appropriately sized for a simple fetch operation, though it could benefit from a bit more detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description should explain what is returned and any behavioral nuances. It only states the basic operation, leaving out return format, pagination behavior, and default limits, making it incomplete for an agent to rely on.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes all 5 parameters with 100% coverage, so the baseline is 3. The description adds no extra meaning beyond the schema, which is acceptable but not exceptionally helpful.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches inventory transfers between locations, using a specific verb and resource. It distinguishes itself from sibling tools like get_inventory_transfer (singular) and create/receive inventory transfer operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clear: this is a read/list operation for inventory transfers. However, it does not explicitly mention when to use it vs. alternatives, though the naming and simple verb make 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden of behavioral disclosure. It only states 'Fetch a specific order by ID' and does not confirm read-only status, return format, error handling, or any side effects. This is minimal and could mislead an agent about what to expect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One concise, front-loaded sentence with no filler. It efficiently states the action and target, making every word meaningful for a get-by-ID operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 1-parameter tool, this is minimally viable, but it lacks explicit return value expectations, not-found behavior, or a read-only confirmation—important when annotations and output schema are absent. More context would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: the single 'id' parameter already includes an example value and description. The tool description adds no extra meaning beyond what the schema provides, 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Fetch' and clearly targets 'a specific order by ID', which unambiguously distinguishes it from list-oriented siblings like get_orders and get_all_orders. The resource and scope are 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving a single order by ID, but offers no explicit guidance on when to prefer this over get_orders/get_all_orders or what to do when the ID is unknown. It lacks explicit exclusions or alternative recommendations.
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?
Without annotations, the description carries the burden of behavioral disclosure. It indicates a read operation via 'Fetch', but does not mention pagination behavior, response format, or limitations. The schema hints at pagination via 'after' and 'first', but the description adds no extra context beyond the verb.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no superfluous words. It is front-loaded and appropriately sized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a simple fetch operation, and the schema covers parameter meanings, but the description lacks any detail on return values, pagination, or use cases. It is minimally viable but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides complete descriptions for all three parameters (after, first, paymentMethodType) with 100% coverage. The description adds no additional parameter-specific meaning, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Fetch) and the resource (payment mandates), distinguishing it from sibling tools like get_payment_terms and get_payment_customizations. It is specific and not a tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No information is provided about when to use this tool versus alternatives, or any prerequisites such as store context or pagination. The description is just a simple statement with no guidance on use cases.
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 carry the full burden. It only says 'Fetch a specific product by ID' and does not disclose behaviors such as required permissions, error handling for invalid IDs, or whether the operation is read-only (though 'Fetch' implies non-destructive). Lacking these details, the agent has insufficient behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that states the core function without unnecessary words. It is appropriately front-loaded and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one required parameter, no output schema), and the description minimally covers the core purpose. However, it omits details about return values, error conditions, or any special behaviors, which could be expected given the absence of an output schema and annotations. The description is adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage for the only parameter 'id', with a helpful example format (gid://...). The description adds no extra meaning beyond what the schema provides, 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Fetch') and the resource ('specific product by ID'). It distinguishes this tool from siblings like get_products (which fetches multiple products) and search_products, and the 'by ID' specifies the scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: fetch a single product when you have its ID. However, it does not explicitly mention alternatives (e.g., get_products for listing) or provide when/not-to-use guidance. The usage context is clear from the phrase 'by ID', but exclusions are absent.
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 carry the behavioral disclosure burden. It only states the action 'Fetch' and gives no detail about response shape, error handling, or side effects. As a read operation, the risk is low, but the description adds no context beyond the tool name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, succinct sentence that states the action and target without wasted words. It is front-loaded and appropriately brief for a simple getter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and complete schema, the description is minimally sufficient, but it omits any information about the return value or possible errors. There is no output schema, so the description could have added a brief note on what is returned, but it doesn't.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully documents the 'id' parameter with type, description, and an example (100% coverage). The description adds no parameter semantics beyond what the schema already provides, so a baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the verb 'Fetch' and names the specific resource 'product listing' with the qualifier 'by ID', clearly indicating it retrieves a single listing. This distinguishes it from the sibling 'get_product_listings' (plural) and other get 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used when you have a specific product listing ID, but it does not explicitly compare with alternatives like 'get_product_listings' or 'get_product'. There is no when-not-to-use guidance.
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, and the description only states the fetch action. It does not disclose return format, permission requirements, or side effects, though the read-only nature is somewhat inferred from 'Fetch'. This is a significant gap in behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that clearly states the action and target with no unnecessary words. It is appropriately sized for a simple getter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one fully documented parameter, the description is adequate. However, there is no output schema and no annotations, so the agent must infer the return structure and any operational details. Slightly more context would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes the required 'id' parameter with a type and example, achieving 100% coverage. The description adds no additional meaning beyond the schema, so a 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Fetch' and identifies the resource 'publication' with 'by ID', which clearly distinguishes it from list operations like get_publications. The purpose is unambiguous and requires no additional context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a specific publication ID is available, but it does not explicitly state when to prefer alternatives like get_publications for listing. There are no exclusions or alternative tool references, so 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.
Behavior2/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 only says 'Fetch', which implies a read operation, but it does not disclose response format, potential pagination, filtering logic, or any edge cases (e.g., returns with different statuses). This is a significant gap for a tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. It conveys the core purpose without any fluff, making it highly concise and well-structured for quick parsing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with one fully documented parameter, the description is adequate but minimal. It does not specify the return structure (list vs. single object) or any limitations, but given the tool's name and the presence of related sibling tools, the purpose is reasonably clear. It falls short of being fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, with the orderId parameter fully documented (including an example). The description adds no additional meaning beyond the schema; it only reinforces that the scope is a specific order, which is already evident from the schema and tool name. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Fetch'), the resource ('returns'), and the scope ('for a specific order'), which distinguishes it from the sibling 'get_return' (which likely fetches a single return by ID) and other order-related tools. It is direct 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'for a specific order' implies the tool is used when returns are needed for a given order, but it does not explicitly compare with alternatives like 'get_return' or mention when not to use it. No prerequisites or exclusions are provided, leaving the guidance implicit rather than 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?
With no annotations, the description carries the full burden. It merely says 'Fetch', implying read-only, but does not disclose return format, pagination, or any other behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no redundancy. It is front-loaded with the essential action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with no parameters or output schema, but the description lacks context about what 'available' means or whether filtering applies. It is minimally complete but leaves room for interpretation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline score is 4. The description does not need to add parameter details, as the schema accurately shows no inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Fetch available shipping countries' uses a specific verb and resource, clearly stating the tool's function. It distinguishes itself from siblings like get_shipping_zones by targeting countries specifically.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of context, prerequisites, or 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?
With no annotations, the description must carry the full burden of behavioral disclosure. It only says 'Fetch,' which implies a read, but does not disclose whether it returns a list, how pagination works, or any other behavioral traits. This leaves important context missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no unnecessary words. It front-loads the verb and resource, making it highly concise and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with only optional pagination parameters, but with no annotations and no output schema, the description should clarify that it returns a list of bank accounts and how pagination is handled. It is minimally viable but leaves these gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes all three parameters (after, first, reverse) with clear descriptions, so the description adds no additional parameter semantics. The high schema coverage justifies the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Fetch') and a clear resource ('bank accounts configured for Shopify Payments'), distinguishing it from sibling tools like get_shopify_payments_account or get_shopify_payments_payouts. It is straightforward 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by naming the resource, but provides no explicit guidance on when to use this tool versus alternatives, nor any exclusions or when-not-to-use scenarios.
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 burden. The verb 'fetch' implies a read-only operation, and no side effects are mentioned. However, it does not disclose the return format, pagination, or other behavioral 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One short sentence with no extraneous words. It is efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with 2 parameters and no output schema, the description is minimal but adequate. It lacks information about the response structure, but the operation is straightforward. More detail on the return value would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents both parameters with clear descriptions (locale and namespace). The description adds no extra meaning beyond the word 'locale', which is already in the schema. Since schema coverage is 100%, a score of 3 is baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Fetch' and identifies the resource 'translations' scoped to 'a locale'. This clearly distinguishes it from sibling tools like 'get_translations_for_resource' and 'get_locales'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as 'get_translations_for_resource'. There are no explicit context or exclusion statements.
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 'Fetch' and does not mention pagination behavior, scope of returned rules, ordering, or any rate limits or permissions. The schema hints at pagination via 'after' and 'first', but the description does not explain the 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence ('Fetch cart and checkout validation rules') with zero filler. Every word contributes to the meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple list tool with two optional parameters and no output schema. The description is adequate but leaves gaps: it does not explain what a validation rule is, whether it returns cart rules and checkout rules separately or combined, or what the response structure looks like. The lack of output schema increases the burden on the description, which it only partially meets.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the two parameters ('after' and 'first'), so the schema fully documents them. The description adds no additional parameter context, which aligns with the baseline of 3 when schema coverage is high.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Fetch') and the resource ('cart and checkout validation rules'), which distinguishes it from sibling tools like create_validation, update_validation, and delete_validation. The verb+resource combination is 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool versus alternatives. The name and description imply it is the read operation for validation rules, and sibling tools suggest create/update/delete counterparts, but no direct alternatives or exclusions are mentioned.
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 available, so the description carries the full burden. It only states the action with no details on side effects, prerequisites, order state requirements, or reversibility, leaving the agent unaware of important behavioral constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that directly states the action without any unnecessary words or filler. It is appropriately concise for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the two-parameter schema is fully documented and the action is simple, the description omits contextual details such as when the move is allowed, constraints on the fulfillment order or destination location, and what the response contains. It is minimally viable but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers both parameters (id and newLocationId) with 100% description coverage, so the description adds little beyond what the schema already provides. It does reinforce the purpose ('different location for fulfillment') but no additional syntax or format details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'move' with a clear resource 'fulfillment order' and destination 'different location for fulfillment'. This clearly distinguishes it from sibling fulfillment tools like cancel_fulfillment_order, hold_fulfillment_order, or reschedule_fulfillment_order.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit usage guidance is provided, but the action is specific enough that the intended use case (moving a fulfillment order to a new location) is implied. It does not mention alternatives or exclusions, so it offers limited differentiation from other fulfillment operations.
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 must carry the full burden of describing behavior, but it only states the immediate effect. It does not disclose any prerequisites (e.g., locale existence), reversibility, or side effects, leaving significant behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded with the action and purpose. It contains no redundant information and is appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with no output schema, the description is adequate but minimal. It does not mention error conditions, relationship to other locale tools, or workflow steps, leaving some gaps in contextual completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'locale' is fully described in the schema ('Locale code to publish'), and the description adds no additional parameter-level detail. With 100% schema description coverage, a 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the action 'Publish a locale' and the outcome 'make it available on the storefront'. This distinguishes it from siblings like unpublish_locale, with a specific verb 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when you want to publish a locale to the storefront, but offers no explicit guidance on when not to use it or alternatives. There is no mention of prerequisites or exclusions, so guidance is merely implied.
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 must carry the full burden of behavioral disclosure. It indicates the action is to 'submit a request' (implying it is not the actual deletion), but it does not disclose side effects, async behavior, reversibility, permissions needed, or what happens after submission. This is a significant gap for a privacy-sensitive 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, succinct sentence that is front-loaded with the main action and resource. Every word adds value; there is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema, no annotations), the description provides a minimum viable understanding of the purpose and context. However, it lacks crucial behavioral details (e.g., whether the erasure is immediate, reversible, or requires special permissions), so it is not fully complete for an agent to confidently invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents the only parameter (customerId) with a clear description ('Customer ID to erase data for'), giving 100% coverage. The description adds no additional parameter context, 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Submit') and the resource ('customer data erasure request'), with a clarifying GDPR context. It effectively distinguishes this tool from siblings like 'get_customer_data_erasure_requests' (view) and 'cancel_customer_data_erasure' (cancel).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The GDPR reference implies when to use this tool (when handling a right-to-be-forgotten request), but it does not explicitly mention when not to use it or how it differs from related tools. No alternative tools are referenced, so guidance is primarily implied rather than 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 full responsibility for behavioral disclosure. It only states the action without mentioning side effects, idempotency, error handling, or permission requirements. For a bulk mutation tool, this is notably lacking.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that delivers the core message without fluff. It is concise and easily parsed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple two-parameter schema and straightforward operation, the description is minimally adequate. However, it omits any note on batch behavior, partial failures, or side effects, leaving some gaps for an agent to consider.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% descriptions for both parameters (ids and enabled), so the schema carries the semantic load. The description adds nothing beyond this, aligning with 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('activate or deactivate') and the resource ('payment customizations'), with 'multiple' indicating a bulk operation. This distinguishes it from sibling tools like get/create/update/delete payment customizations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied for bulk activation/deactivation, but there is no explicit guidance on when to choose this over update_payment_customization or mention of any prerequisites/exclusions. The context is inferable from the name and description but not 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 carries the full burden. It only says 'set' without disclosing side effects, whether the contract must be active, whether changes are reversible, or how billing schedules are affected. This is a significant lack of behavioral transparency 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It is concise and immediately communicates the core action and target resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The operation is simple and both parameters are fully documented, making the invocation clear. However, the lack of behavioral context (e.g., contract state requirements, side effects, what happens to prior billing date) leaves the description minimally acceptable but not complete for a mutation tool without annotations or output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers both parameters with clear descriptions (ISO 8601 format for date, contract ID). The description adds no extra parameter meaning, but the baseline of 3 applies because schema description coverage is 100%.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Set the next billing date for a subscription contract' uses a specific verb and resource, making the action unambiguous. It clearly distinguishes this from sibling subscription contract operations like cancel, pause, or activate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when the next billing date needs to be changed, but it does not explicitly state when to use this tool versus alternatives or provide exclusions. Among many subscription contract sibling tools, no when-not-to-use guidance is given.
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 provided, the description carries the full burden of behavioral disclosure. It states the action (enable/disable) but does not reveal any side effects, prerequisites (e.g., pixel must exist), permission requirements, or reversibility. This is a mutation operation with minimal transparency, similar to the calibration example for 'update_drive'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that says exactly what the tool does with no wasted words. It effectively communicates the core purpose without verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params, no output schema, no annotations), the description provides the essential purpose but lacks any contextual details about prerequisites, return values, or error conditions. It is minimally viable but leaves gaps for an agent to fully understand the behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters, each with clear descriptions (Custom Pixel ID, whether to enable or disable). The description adds no additional meaning beyond what the schema 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Enable or disable') applied to a specific resource ('a custom pixel'). This unambiguously distinguishes it from sibling tools like create_custom_pixel, update_custom_pixel, and delete_custom_pixel, and aligns with the tool name 'toggle_custom_pixel'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clear that this tool changes the enabled state of a custom pixel, but there is no explicit guidance on when to use it versus alternatives such as update_custom_pixel. No when-to-use or when-not-to-use instructions are provided, leaving usage largely implied.
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 full burden. It only names the action without disclosing whether the alt text is replaced, whether the file must exist, or what the response contains. This lack of behavioral detail is a significant gap 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded and contains no extraneous words. Every part is useful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with two well-documented parameters, and the schema covers all parameter semantics. However, the description provides no usage context or behavioral details, making it minimally viable but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with clear parameter descriptions ('File ID' and 'New alt text'), so the baseline is 3. The description adds no further semantic meaning 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates file metadata, specifically alt text, using a specific verb and resource. It distinguishes itself from sibling operations like create_file, delete_file, and get_file by focusing on the alt text update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage is implied by the name and description, but there is no explicit when-to-use guidance or mention of alternatives. It doesn't state prerequisites like requiring an existing file, nor does it contrast with other update tools.
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 full burden for behavioral disclosure. It only states the action without explaining whether updates are partial or full, permissions required, side effects, or response format. This is a significant gap for a mutating 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of six words, front-loaded with the action and resource. Every word earns its place, with zero redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update tool with fully documented schema, the description is minimally viable but lacks behavioral context such as whether missing fields are left unchanged, return value, or required permissions. It does not compensate for the absence of annotations or output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptive parameter names and descriptions (id, body, name, subject). The description adds no additional parameter meaning beyond the schema, 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Update') and resource ('packing slip template'), and the word 'existing' distinguishes it from creation/deletion. It aligns with the sibling tools create_packing_slip_template and delete_packing_slip_template, making its role unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for modifying an existing template but provides no explicit guidance on when to use it versus alternatives, nor does it mention exclusions or prerequisites. It falls short of clearly differentiating from sibling tools like get_packing_slip_templates or create_packing_slip_template.
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 only states the creation of a transfer and does not mention side effects, permissions, reversibility, or what the response contains. For a mutation tool, this is a significant gap, similar to the update_drive calibration example.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clean sentence with no redundant words. It communicates the action, resource, and context efficiently, earning every word.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is relatively simple with three fully documented parameters and no output schema. The description is sufficient for basic usage but could benefit from noting whether inventory levels are affected immediately or if this is just a pending transfer record, especially given the absence of annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with descriptions for all three required parameters, so the baseline is 3. The description adds no additional parameter semantics beyond the schema's existing originLocationId, destinationLocationId, and lineItems definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Create') and identifies the exact resource ('inventory transfer') along with the scope ('between locations'). It clearly distinguishes from sibling tools like get_inventory_transfer or receive_inventory_transfer, as this is the creation 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for creating a transfer between locations but does not explicitly state when to use this tool versus alternatives such as receive_inventory_transfer or get_inventory_transfer. No exclusions or alternative guidance is provided, but the context is understandable from the name.
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 required write_marketing_events scope, which is a useful auth prerequisite, and the act of creation implies mutation. However, it does not explain idempotency, duplicate handling, response behavior, or other side effects beyond the scope requirement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, comprising three short sentences that front-load the purpose, add a brief list of tracked metrics, and state the required scope. Every sentence contributes useful information without redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite being a complex tool with 26 parameters, no output schema, and no annotations, the description is incomplete. It does not explain how to choose between activity-level and channel-level engagements, the mutual exclusion of remoteId and marketingActivityId, the preference for non-cumulative data, or what a successful creation returns. The description provides insufficient high-level context for an agent to use the tool correctly beyond basic purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description mentions tracked interaction types that map to some parameters (e.g., clicks, impressions, sales), but it does not add syntax, format, or relationship details beyond what the schema already provides. The mutually exclusive remoteId/marketingActivityId and channelHandle are documented in the schema, not the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a marketing engagement for a marketing activity or channel, and lists the tracked interaction types (clicks, impressions, conversions, sales, orders). This distinguishes it from related marketing tools like create_marketing_event by focusing on engagement metrics and specifying the resource and scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool by mentioning it is for marketing activities or channels, but it does not explicitly address alternatives like create_marketing_event or provide exclusions. It also notes the required scope, giving some context, but lacks clear when-to-use versus alternative guidance.
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 provided, the description carries the full burden of behavioral disclosure. It only restates the basic fetch action and does not mention read-only behavior, error handling, or response details. 'Fetch' mildly implies a read operation, but this is not explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one short sentence that immediately conveys the tool's purpose with no unnecessary words. It is optimally front-loaded and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter getter, the description combined with the schema is largely sufficient. It identifies the resource and the required identifier, though the absence of an output schema and behavioral notes leaves some gaps about the return format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% coverage for the single `id` parameter, including a descriptive example. The description adds no additional parameter semantics beyond what the schema already documents, 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the action ('Fetch') and the resource ('a specific collection by ID'), clearly distinguishing it from sibling tools like get_collections, which lists collections. It is concise 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'by ID' implies the tool is for retrieving a single known collection, but it does not explicitly state when to use this tool versus get_collections or other collection-related tools. No alternatives or exclusions are mentioned.
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, and the description is minimal. It does not disclose response format, error behavior, or the scope of data returned. 'Fetch' implies a read-only operation, but this is not explicit, and the description carries the full burden for behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the action and resource. No redundant information is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read tool, the description is mostly adequate. However, since there is no output schema, the agent lacks guidance on what the tool returns (e.g., customer fields) and potential error conditions. This slight gap keeps it from a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides complete description for the only parameter 'id', including an example. The description adds no additional parameter semantics, so with 100% schema coverage, 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Fetch' and clearly identifies the resource as 'a specific customer by ID'. This unambiguously distinguishes it from sibling tools like get_customers (likely list) and other customer-related 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have a known customer ID, but provides no explicit guidance on when to use this vs. alternatives like get_customers or search. There is no mention of exclusions or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. 'Fetch' implies a read operation, but the description gives no details about return structure, error handling, required permissions, or any side effects. It is not misleading, but it lacks behavioral context beyond the verb.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no filler. Every word contributes to the core meaning, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of this tool (one parameter, no nested objects, no output schema), the description is essentially complete for its intended purpose. It states what it does and the required input; additional detail about return values is implicitly unnecessary for a get-by-ID operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes the 'id' parameter with an example, giving 100% coverage. The description's 'by ID' adds no new semantic detail beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Fetch') and a clear resource ('a specific fulfillment order by ID'). It unambiguously differentiates this tool from siblings like get_assigned_fulfillment_orders (which lists orders) and get_returnable_fulfillments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have a specific fulfillment order ID, but it does not explicitly state when to use this over listing endpoints or mention that other tools exist for queries without an ID. Context is clear enough for a simple fetch, but no alternatives are referenced.
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 carry the full burden. It only says 'Fetch' which implies a read operation, but does not disclose behaviors such as return format, not-found handling, or required permissions. This is minimal beyond the function name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no filler, front-loading the action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter GET tool, the description and schema together are mostly sufficient. However, the lack of any reference to alternative listing tools or edge-case behavior leaves a slight gap for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage with a clear description for the 'id' parameter, including an example GID. The tool description adds no additional parameter information, 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Fetch'), the resource ('inventory shipment'), and the scope ('by ID'). It distinguishes from sibling 'get_inventory_shipments' which likely lists multiple shipments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving a single shipment by ID, but does not explicitly mention alternatives like 'get_inventory_shipments' for listing all shipments. No exclusions or prerequisites are provided.
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 burden of disclosure. 'Fetch' clearly implies a read-only operation, but it does not mention pagination behavior, return format, or any side effects. It is minimally transparent but not misleading.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, short, front-loaded sentence that states the resource and action without filler. Every word is necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a straightforward list operation with four well-documented parameters and no output schema. The description conveys the core purpose, though it omits mention of pagination defaults or return value composition, which the schema partially covers.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description adds no parameter details. All parameters are already well-documented in the schema, 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Fetch') and a specific resource ('payment customizations'), clearly distinguishing this list operation from the singular sibling 'get_payment_customization' and other payment tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as get_payment_customization. The description only states what it does, leaving the agent to infer usage context.
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 provided, the description carries the full burden of disclosing behavioral traits. 'Fetch' implies a read operation, but it does not clarify permissions, error behavior, whether related data is included, or the shape of the response. This is a minimal disclosure for a tool with no structured safety 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states exactly what the tool does without any filler. It is appropriately sized for a simple read-by-ID operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one well-documented parameter and a simple read-by-ID purpose, the description is sufficiently complete. There is no output schema, but a 'fetch' operation on a specific return implies the return object is provided; additional detail might be helpful but is not necessary for basic selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage of the single 'id' parameter, including a clear example ('gid://shopify/Return/123456789'). The description adds no additional parameter meaning beyond restating that the ID identifies a specific return, so 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Fetch a specific return by ID' uses a specific verb and resource, clearly indicating the operation reads one return by its unique identifier. It distinguishes itself from sibling tools like get_returns_by_order and get_returnable_fulfillments by emphasizing 'specific' and 'by ID'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for fetching a single return when the ID is known, but it does not explicitly state when to use it over alternatives such as get_returns_by_order. There are no exclusions or alternative tool mentions, though the 'by ID' phrasing gives some directional guidance.
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 provided, the description carries the full burden for behavioral transparency, but it only states the action without explicitly confirming read-only behavior, side effects, or limitations. There is no contradiction with annotations since none 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, perfectly concise and front-loaded with the action verb. Every word contributes to the meaning without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, zero-parameter getter, the description adequately identifies the resource being fetched. It does not enumerate return structure or edge cases, but the simplicity of the tool makes this acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema is empty, so there are no parameter semantics to document. The description correctly avoids adding unnecessary parameter details, earning the baseline score for zero-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Fetch' and clearly identifies the resource 'shipping zones from the Shopify store', distinguishing it from sibling tools like get_shipping_countries or get_delivery_profiles.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, and there are no explicit usage scenarios or exclusions mentioned. It does not reference any of the sibling tools for comparison.
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 provided, the description bears full responsibility for disclosing behavioral traits. It only restates the basic fetch operation and offers no additional context such as whether transactions are included, pagination behavior, or permission requirements. This is a significant gap for a tool that has pagination parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the core purpose. Every word earns its place, and there is no unnecessary filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the simplicity of the operation, the description leaves out key context such as what data the account object contains, whether transactions are returned, and how this relates to other store credit account tools. The lack of an output schema and annotations further increases the need for descriptive context, which is absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% description coverage for all three parameters, including an example ID format and pagination details. The description adds no extra parameter context, but the baseline score of 3 is appropriate given the schema's thoroughness.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Fetch) and the resource (store credit account) with the identifier method (by ID). This distinguishes it from the sibling tool get_store_credit_accounts_by_owner, which fetches by owner rather than ID.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context for use is clear: use this tool when you have a specific store credit account ID. However, it does not explicitly mention exclusionary cases or direct users to alternative tools like get_store_credit_accounts_by_owner for owner-based lookups.
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 provided, the description carries the full burden of disclosing behavioral traits, but it only states the action and a minimal consequence. It does not mention that if holdIds is omitted, all holds are released, whether the action is reversible, or how it affects the fulfillment order's state. The phrase 'allowing it to be fulfilled' is vague about what actually changes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the action ('Release the fulfillment hold...') and avoids unnecessary detail. There is no redundancy or filler, making it appropriately concise for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a mutation tool with no annotations and no output schema, yet the description does not provide a complete behavioral picture. It omits important nuances like the optional holdIds behavior (releases all if not provided) and whether holding affects fulfillment automatically. While the schema covers the parameters, the description alone is insufficient for an agent to understand all side effects and prerequisites.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% description coverage for both parameters (id and holdIds), so the baseline is 3. The tool description itself adds no additional parameter semantics beyond what the schema already states; it merely references 'a fulfillment order' which aligns with the schema's 'Fulfillment Order ID'. No extra clarity is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states exactly what the tool does: 'Release the fulfillment hold on a fulfillment order, allowing it to be fulfilled.' It uses a specific verb (release) and resource (fulfillment hold on a fulfillment order), and the outcome is clear. This distinguishes it from sibling tools like hold_fulfillment_order, which performs the opposite 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use this tool: whenever a fulfillment order is on hold and needs to be released to allow fulfillment. However, it does not explicitly mention alternatives (e.g., hold_fulfillment_order) or state preconditions/exclusions. It's clear but without explicit comparison.
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 provided, the description carries the full burden. It states the tool claims reserved money, but does not disclose side effects such as irreversibility, partial capture behavior, or required permissions. For a financial mutation, this is a significant transparency 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and contains 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.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the core use case but lacks workflow details such as how partial captures work, the role of finalCapture, or what the response contains. The schema covers parameters, but the tool is complex enough that more behavioral context would be valuable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all five parameters have descriptions in the input schema. The description does not add extra meaning beyond what the schema already provides, 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool captures payment for an authorized transaction, using a specific verb and resource. It distinguishes itself from sibling tools like mark_order_as_paid and create_refund by explicitly framing the action as claiming previously reserved funds.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: use this after an authorization to claim the reserved money. It does not explicitly mention exclusions or alternatives, but the standalone usage context is clear enough for an agent to select this tool over related ones.
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 full burden. It states the conversion but does not disclose side effects, prerequisites (e.g., checkout must be abandoned), reversibility, or permission requirements. This is insufficient 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with the action and resource, no superfluous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has only one parameter and no output schema, so description needn't explain returns. However, as a state-changing operation without annotations, it lacks details on post-conditions and constraints, making it minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with checkoutId described as 'Checkout ID to complete'. The tool description adds no further parameter detail, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'Convert' and resource 'abandoned checkout to a draft order', with purpose '(for recovery)'. This distinguishes it from sibling 'complete_draft_order' which operates on draft 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the use case of recovering abandoned checkouts. However, it does not explicitly mention alternatives or when not to use, though the name and description clearly separate it from complete_draft_order.
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 that it creates a file from a URL and mentions the staging/external URL distinction. It does not disclose side effects, permission requirements, idempotency, error behavior, or whether the staged upload token is consumed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the core action ('Create a file') and adds a useful qualifier about the source. Every word contributes, with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description does not mention return values or side effects. It hints at the staging workflow but does not explain how to obtain a staged upload or what the created file contains. For a mutation with no annotations, this is a moderate gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 5 parameters have schema descriptions (100% coverage), so the schema already documents each field. The description adds no parameter-specific meaning beyond the source URL context already implied by the parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create a file') and the source ('from a URL'), and distinguishes it from sibling tools like create_staged_upload (which stages uploads, not files) and get_file/update_file/delete_file. The parenthetical 'after staged upload or external URL' adds specific 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear contextual guidance: it is used after a staged upload or with an external URL. This implies the workflow and when to use it, though it does not explicitly name alternatives or exclusionary cases.
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 main effect (increases balance) and an additional behavior (creates a credit transaction), but lacks details on prerequisites, reversibility, errors, or what the response contains. It's adequate but not rich 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no wasted words. The first sentence is a clear action statement, and the second adds context about the balance effect. Perfectly sized and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with 4 parameters and no output schema, the description covers the core action but does not explain return values or any edge cases. Since there is no output schema, the description could have provided more context about the response, making it incomplete but not severely lacking.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description adds no extra meaning beyond what is in the schema, such as the relationship between amount and currencyCode or the optionality of note. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Add credit') and resource ('gift card'), and explicitly mentions the effect ('increases the gift card balance'). This distinguishes it from siblings like debit_gift_card, which does the opposite.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when adding credit to a gift card, but provides no explicit guidance on when to use this tool versus alternatives (e.g., debit_gift_card for decreasing balance). There are no exclusions or alternative tool references.
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 behavioral disclosure burden. It does disclose an important side effect (auto-creation of the account), but it does not mention permissions, reversibility, idempotency, or what happens on success/failure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no redundancy. It front-loads the primary action and uses the second sentence to highlight the key auto-create behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description, combined with full schema coverage, is minimally sufficient for selecting and invoking the tool. However, there is no output schema and the description does not mention the return value, possible errors, or other operational context, leaving some gaps for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides descriptions for all 5 parameters (100% coverage), including the polymorphic id and optional notify/expiresAt fields. The description adds no parameter-specific detail beyond what the schema offers, 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add funds to a store credit account') and identifies the specific resource. It also includes a distinctive behavioral detail ('Creates the account automatically if it doesn't exist') that separates it from sibling tools like debit_store_credit_account or get_store_credit_account.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used for crediting store credit accounts, but it does not explicitly state when to use it versus the debit or get variants. There is no when-not-to-use guidance or mention of alternative 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?
No annotations are present, so the description carries the full burden. It discloses that the operation is a fetch (read) and that it targets 'installed' apps, adding a scope constraint. However, it does not explain error behavior, permissions, or return format. This is adequate for a simple read but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence: 'Fetch a specific installed app by ID.' It is concise, front-loaded with the verb, and contains zero waste. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one parameter and no output schema. The description provides enough to understand the core action, but it does not mention return details, alternatives, or any context like permissions. Given no annotations or output schema, a bit more context could be beneficial, but for a simple fetch it is minimally viable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents the 'id' parameter with a clear example. The description only says 'by ID', which does not add new meaning beyond the schema. With 100% schema description coverage, the baseline is 3, and no additional value is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Fetch'), the resource ('a specific installed app'), and the scope ('by ID'). This distinguishes it from sibling tools like get_apps (which would list apps) and get_app_proxy, 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: use this tool when you have an app ID and need a specific installed app. However, it does not explicitly mention alternatives or when not to use it (e.g., for listing use get_apps). No clear exclusion or alternative 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 provided, the description carries the full burden for behavioral disclosure. It states only that it fetches a resource, which is largely a restatement of the tool's name. It does not mention error behavior (e.g., 404 if not found), permissions, read-only guarantees, or any expansion/return details. This is a minimal gap for a read operation but still lacking meaningful context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words. It is slightly redundant with the tool name but adds 'specific' and 'by ID' which help scope the operation. It could benefit from a bit more context, but it is appropriately short for a simple get-by-ID tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has low complexity (one parameter, no output schema, no nested objects) and the schema fully documents the sole parameter. Combined with the description, it is clear what the tool does. The absence of annotations and output schema is not a major gap for a simple read operation, though adding notes about not-found behavior would make it complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% coverage with a clear description for the single parameter `id` including an example format. The description's 'by ID' adds no new information beyond the schema, 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Fetch a specific draft order by ID' uses the specific verb 'Fetch' and clearly identifies the resource ('draft order') and the scope ('specific', 'by ID'). This distinguishes it from sibling tools like get_draft_orders (plural) and other get_* 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have a specific draft order ID and need that single entity. It clearly contrasts with listing/getting all draft orders, but it doesn't explicitly name alternatives or state when not to use it, so it misses the top score.
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 states 'Fetch' (implying read-only) but does not mention what happens when the ID is not found, required permissions, or response format. This is a significant gap for a tool with no annotation safety net.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the essential purpose without any wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one parameter, no output schema), but the description fails to explain return values or error behavior. Since there is no output schema, the description could have noted that it returns the gift card object or clarifies not-found behavior. Still, it adequately covers the primary action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with a clear description and example for the 'id' parameter. The description's 'by ID' phrase adds no new meaning beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb (Fetch), identifies the resource (gift card), and scopes it by ID. This clearly distinguishes it from siblings like get_gift_cards (plural) and other gift card operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a specific gift card ID is known, and the schema reinforces this with a required 'id' parameter. However, it does not explicitly mention alternatives or exclusions, though the intent is clear.
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. It conveys a read-only operation via 'Fetch', which is non-destructive, but it does not disclose details such as return format, error behavior, or any prerequisites. For a simple retrieval tool, 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of eight words, front-loaded with the action verb and resource. Every word adds value, with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter read tool, the description states the core purpose and parameter usage. However, with no output schema, it does not explain what the response contains (e.g., the policy text or metadata), leaving a minor but notable gap for agents unfamiliar with the API.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage for the single parameter 'handle', including an enum of valid values. The description only repeats 'by handle' without adding extra semantics, so it does not exceed 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Fetch a specific legal policy by handle' uses a specific verb ('Fetch'), identifies the resource ('legal policy'), and clarifies the scope ('specific' and 'by handle'), clearly distinguishing it from sibling tools like get_legal_policies (plural) and get_shop_policies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a specific policy handle is known, but it does not explicitly mention alternatives or provide when-not-to-use guidance. The context is clear but not fully explicit, and the sibling get_legal_policies could have been referenced for listing all policies.
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 carry the full burden. It only says 'Fetch a specific market by ID' and does not disclose read-only nature, permission requirements, error behavior, or side effects. While 'Fetch' implies a read, it lacks the richer behavioral context expected 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the verb and resource. Every word is purposeful, with no redundant or irrelevant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and fully documented parameter, the description adequately explains what it does. However, without an output schema or annotations, it does not specify the return value structure or error handling, leaving some gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage for the 'id' parameter, including an example format. The description adds no extra parameter semantics beyond restating that the tool fetches by ID, so a 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Fetch' and identifies the resource 'market' with a clear scope ('by ID'). It distinguishes itself from the sibling tool get_markets (which lists markets), so the purpose 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when you have a specific market ID and need a single market. It provides clear context but does not explicitly state when to avoid this tool (e.g., using get_markets for multiple markets) 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?
With no annotations provided, the description carries the full burden of disclosing behavior. It only says what the tool checks, not what it returns, whether it has side effects, or what 'configured' means. This leaves significant behavioral ambiguity 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that directly states the tool's purpose. Every word is relevant, with no wasted content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple zero-parameter health check, but without an output schema, the description should ideally hint at the return value or success criteria. It does not, leaving the agent uncertain about what a healthy response looks like. Still, given the minimal complexity, it is not severely incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema coverage is 100%. Per the rubric, a zero-parameter tool receives a baseline of 4. The description adds no parameter details, but none are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Check') and resource ('Shopify GraphQL MCP server'), with the scope 'running and configured'. This unambiguously identifies the tool's purpose and distinguishes it from the many sibling 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used to verify server status, but it does not explicitly state when to use it (e.g., before other operations) or mention any alternatives. Without exclusions or suggested contexts, it falls at the implied-usage level.
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 provided, the description bears full responsibility for disclosing behavioral traits. It only says 'pause fulfillment,' omitting important details like reversibility, side effects, prerequisites, or impact on downstream processes. The existence of a separate release_fulfillment_hold sibling suggests holds are reversible, but this is not mentioned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler. It front-loads the core action and then adds practical usage context. Every sentence contributes value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the basic purpose and use cases, but for a mutation tool with 4 parameters and no output schema, it does not explain the full lifecycle impact (e.g., that holds can be released later, or how the hold affects order status). It is adequate but has clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameter descriptions, so the baseline is 3. The description's mention of reasons ('inventory issues, customer requests') aligns with the enum but adds no meaning beyond the schema's own descriptions. No extra parameter context is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Apply a fulfillment hold') and the target resource ('on a fulfillment order'). It also signals the intended effect ('pause fulfillment'), which distinguishes it from related tools like release_fulfillment_hold.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly lists use cases ('inventory issues, customer requests, or other reasons'), providing clear context for when to apply a hold. However, it does not mention alternatives or explicitly state when not to use this tool, so it falls just short of full guidance.
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 alone must disclose behavioral traits. It explains that a payment transaction is recorded for the outstanding amount but omits important side effects: whether it's reversible, if it can be called on an already-paid order, prerequisites for order status, or any failure modes. This is insufficient 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences long, each earning its place: the first states the core action and mechanism, the second gives usage context. No fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one required parameter, no output schema), and the description explains the primary behavior and when to use it. However, the lack of annotations and missing behavioral caveats (e.g., idempotency, order status requirements) leave gaps that are especially relevant for a payment-affecting operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters, and the schema description for 'id' ('Order ID to mark as paid') is clear. The tool description adds no additional parameter details, 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Mark an order as paid') with a specific mechanism ('recording a payment transaction for the outstanding amount'). It also hints at the tool's niche ('manual payment methods'), which helps distinguish it from similar tools like capture_order_payment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Useful for manual payment methods' provides clear context on when to use this tool, but it does not explicitly mention alternatives or when not to use it. This is a minor gap given the crowded order-related sibling set.
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 states the core action (reopen) but omits side effects, permission requirements, reversibility, and behavior when the order is not closed. This is a significant gap 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single four-word sentence that is front-loaded with the action verb 'Reopen'. Every word is essential, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description plus schema provide the essential details to invoke it. However, the lack of annotations and minimal behavioral context leaves gaps around error handling and side effects, so it is only minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully documents the only parameter 'id' as 'Order ID to reopen', and the description adds no additional meaning beyond that. With 100% schema coverage, 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Reopen a closed order' uses a specific verb ('reopen') and resource ('closed order'), clearly conveying the tool's function. It distinguishes from sibling tools like close_order and cancel_order by focusing on the reopening 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'closed order' provides clear context that this tool is used when an order is in the closed state. However, it does not explicitly mention alternatives or exclusions (e.g., not for cancelled orders), so it stops short of full guidance.
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 only says 'Update' without explaining whether the update is partial or full replacement, or what happens to fields not provided. The setAsDefault parameter's effect is also not described.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that immediately states the action and target. It contains no wasted words and is easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate complexity (nested address object, 4 params) and the absence of annotations/output schema, the description is somewhat thin. It lacks clarification on update semantics (e.g., whether all required sub-fields must be provided) but the schema covers parameter definitions adequately. The setAsDefault declaration is self-explanatory.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for top-level parameters, so the baseline is 3. The description adds no extra parameter semantics beyond the schema, but the schema already provides clear descriptions like 'Address ID to update' and 'Set as default address'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does 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 customer's existing address'. It clearly distinguishes from sibling tools like create_customer_address and delete_customer_address by specifying 'existing address'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates this tool is for modifying an already-existing address. It does not explicitly name alternatives, but the context makes it obvious that this is not for creating or deleting addresses, which are covered by sibling tools.
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 states the outcome (enables stocking) but does not mention prerequisites (e.g., location must exist or be inactive), reversibility, permissions, or error cases. This is a notable gap for a mutation-style 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler or redundant information. Every word contributes to the intended action and purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter activation tool without annotations or output schema, the description is largely complete: it explains what, why, and the key resource. It falls short of a 5 only because it omits preconditions or edge-case behavior, but the low complexity mitigates this.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameter is already well-documented. The description adds minimal extra meaning ('at the location') but does not provide additional guidance on ID format or how to obtain it. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource pair ('Activate a location') and clarifies the intended effect ('so that you can stock inventory at the location'). This distinguishes it from related siblings like deactivate_location and update_location.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context: use when you need to enable a location for inventory stocking. It clearly communicates the trigger but does not explicitly mention alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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. It discloses a key behavioral consequence ('stop all future webhooks to its endpoint'), which is useful. However, it doesn't mention permanence, permissions, or potential impact on other resources, so it's only partially 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that gets straight to the point. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter delete operation, the description is adequate. It explains the action and its main effect. However, it doesn't mention what happens after deletion (e.g., return value or errors), but for this tool that may not be necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents the single 'id' parameter with a clear description, achieving 100% coverage. The tool description adds no additional parameter information, 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Delete' and identifies the exact resource 'webhook subscription', clearly distinguishing it from sibling tools like get_webhook_subscription or update_webhook_subscription. It also adds the consequence 'stop all future webhooks to its endpoint', 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly conveys when to use the tool: when you want to delete a webhook subscription and cease delivery. However, it provides no explicit guidance about alternatives or when not to use it, such as pausing instead of deleting.
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 provided, the description carries the full burden of disclosing behavior. It only states 'Fetch app proxy configuration' and adds no context about return format, permissions, side effects, or whether the configuration is for the current store. The word 'Fetch' implies a read-only operation, but this is not explicit and lacks behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence, front-loaded with the action verb and resource. It contains no filler or redundant information, and every word is meaningful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple zero-parameter getter with no output schema, the description is reasonably complete. It identifies exactly what is fetched (app proxy configuration for the store). However, it does not describe the shape of the returned configuration or any prerequisites, which would make it more complete, but given the simplicity, it is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so schema coverage is trivially 100%. The description correctly adds no parameter details, and with 0 params the baseline is 4. It does not misleadingly imply any parameters that don't exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb (Fetch) and a specific resource (app proxy configuration for the store). It clearly distinguishes this read operation from sibling write operations like create_app_proxy, update_app_proxy, and delete_app_proxy.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage as a getter for the app proxy configuration, but provides no explicit guidance on when to use it instead of alternatives (e.g., get_apps or get_app). No exclusions or alternative mentions are present, so usage is only 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?
No annotations are provided, so the description carries the full burden. 'Fetch' implies a non-destructive read, but no additional context is given about return format, permissions, or error handling. It is minimally transparent but not misleading.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no unnecessary words. It is front-loaded with the verb and resource, making it easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a very simple tool with one parameter and no output schema. The description adequately states the tool's purpose. While it does not mention return values, the low complexity and clear name make this acceptable; a fully complete description might specify 'returns the session'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents the single 'id' parameter with a clear description and example, achieving 100% schema coverage. The description adds no additional parameter semantics, 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Fetch a specific cash tracking session by ID' uses a specific verb and resource, clearly indicating a read operation for a single entity. It distinguishes itself from sibling tools like 'get_cash_tracking_sessions' (which likely lists sessions) and 'create_cash_tracking_session'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use guidance or alternatives are mentioned. The intended use is implied by the tool name and the required ID parameter, but it does not clarify when to choose this over 'get_cash_tracking_sessions'.
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 of behavioral disclosure. The verb 'Fetch' implies a read-only operation, but the description does not mention any other behavioral traits such as required permissions, error behavior, or return 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It conveys the core purpose efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-ID tool with full schema coverage, the description is adequate but not rich. It could explicitly mention that it returns a single checkout or reference the get_checkouts list endpoint, but given the 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/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description covers 100% of the parameter ('id') with a clear example. The tool description adds no additional parameter semantics, 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Fetch' with the resource 'checkout' and the scope 'by ID', clearly distinguishing it from the plural 'get_checkouts' sibling. 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for retrieving a single checkout when an ID is known, but it does not explicitly state when to use it versus alternatives like get_checkouts, nor does it mention any exclusions or prerequisites.
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 conveys a read-only fetch operation, but does not disclose error behavior, permissions, or return format. For a simple get-by-ID tool, this is minimally transparent but leaves some 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
At six words, the description is extremely concise and front-loaded, with no wasted words. It communicates the purpose efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has one parameter and no output schema, the description is adequate for a straightforward fetch operation. It does not explain return values or error handling, but the simplicity of the tool keeps it reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'id' is fully described in the schema with an example format. The description adds no additional semantics beyond confirming the lookup is by ID, so it provides no extra value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Fetch a specific payment method by ID' clearly states the action (fetch), resource (payment method), and the scope (specific by ID), distinguishing it from the plural sibling get_customer_payment_methods. This is precise 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives, but the phrase 'specific... by ID' implies it is for retrieving one payment method when the ID is known. No alternatives or exclusions are mentioned, so 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the behavioral disclosure burden. The verb 'fetch' implies a read-only operation, but the description provides no additional behavioral traits such as return format, error behavior, permissions, or side effects. It is minimally adequate but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence that is front-loaded and directly states the tool's purpose. There is zero wasted text or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter getter, the description plus schema are largely complete. However, it could mention that get_locations is the alternative for fetching multiple locations, and it doesn't describe the output shape (though no output schema exists). Still, given the tool's simplicity, the coverage is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage for the single parameter 'id' with a helpful example ('gid://shopify/Location/123456789'). The description adds no additional semantic meaning beyond restating that it fetches by ID, so 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Fetch a specific location by ID' uses a specific verb ('fetch') and resource ('location') and clearly identifies the selector (by ID). It distinguishes from sibling tools like get_locations (plural) and other location-related 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a specific location ID is known, but it doesn't explicitly mention alternatives such as get_locations for listing all locations, or contrast with create/update/delete location tools. There is no when-not-to-use guidance.
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 says 'Fetch', which is synonymous with the name and adds no behavioral context beyond implying read-only. It does not disclose error behavior, return format, or any edge cases, making this a minimal disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, concise sentence that is front-loaded with the verb and resource. There is no redundancy or unnecessary detail; every word contributes to clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter read operation, the description is adequate. An output schema is absent, but this is not critical for a straightforward fetch tool. The description is complete enough given the tool's simplicity, despite not specifying return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with a descriptive `id` parameter including a concrete example ('gid://shopify/Menu/123456789'). The tool description adds no further parameter meaning beyond 'by ID', but the schema already sufficiently documents the parameter, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Fetch a specific menu by ID' uses a specific verb and resource, clearly distinguishing this from get_menus (plural, for listing) and from other menu-related operations like get_menu_item. It unambiguously states 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies usage when a specific menu ID is available, setting context for one-off retrieval. However, it does not explicitly mention alternatives such as get_menus for listing all menus or when not to use this tool, so it's clear but 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?
With no annotations, the description carries the full burden. It correctly indicates a read operation ('fetch') without claiming side effects. However, it adds no detail about error behavior, return format, or any prerequisites beyond the parameter IDs. For a simple getter this is acceptable but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that immediately states the action and resource. There is zero wasted wording, and the information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter getter with fully documented schema and no output schema, the description is mostly sufficient. It clearly states what the tool does and what identifiers are needed. A minor gap is that it doesn't explicitly state the return value (e.g., 'Returns the menu item object'), but this is easily inferred.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both menuId and menuItemId thoroughly described including examples. The tool description adds no extra parameter semantics, so the baseline of 3 applies; the schema already does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Fetch a specific menu item by ID from a menu' uses a specific verb ('fetch'), identifies the resource ('menu item'), and scopes it by ID and menu. It clearly distinguishes from sibling tools like get_menu (which fetches a menu) and get_menus (which lists menus), making its 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The tool name and description imply it is for retrieving a single menu item by ID, but there is no explicit guidance on when to use it versus alternatives. No exclusions or alternative tool mentions are provided, leaving the decision to the agent based purely on the name/description pattern.
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 provided, the description carries the full burden of behavioral disclosure. It only says 'Fetch' and does not mention error handling, return format, permission requirements, or side effects. This is a significant gap for a tool without annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with a clear verb and object, front-loaded with the core action. There is zero wasted wording, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter getter, the description is adequate: it identifies the operation and the schema fully documents the parameter. However, with no output schema, it does not describe the return structure, but the tool is straightforward enough that this is not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% because the 'id' parameter has a detailed description with an example. The description adds no extra parameter semantics beyond 'by ID', which is already implied by the tool's name and schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Fetch' with the resource 'payment customization' and the qualifier 'by ID', making it clear this tool retrieves a single object. This distinguishes it from siblings like get_payment_customizations (plural, list) and create/update/delete operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'by ID' qualifier establishes a clear context for single-object retrieval. However, it does not explicitly mention alternatives (e.g., 'use get_payment_customizations to list all') or when-not-to-use conditions, so a small gap remains.
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 discloses the primary behavioral effect: the theme becomes the main theme. However, it does not mention potential side effects, such as replacing the current main theme or whether the action is reversible. With no annotations to fall back on, the description carries the full burden but only covers the basic outcome.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, brief sentence with a parenthetical clarification. Every word serves a purpose, and the structure is front-loaded with the action and resource. There is zero redundancy or wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description sufficiently explains the purpose and effect. However, it could be more complete by noting that publishing a theme replaces the current main theme, which is an important contextual detail. Given the simplicity of the tool, it is nearly complete but misses that small behavioral nuance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description covers 100% of the parameter 'id' with a clear example ('gid://shopify/OnlineStoreTheme/123456789'), so the schema already provides the necessary semantic meaning. The description does not add any additional parameter details, which keeps it at the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Publish' and identifies the resource 'theme', with a clarifying parenthetical 'make it the main theme' that fully explains the action. This clearly distinguishes it from sibling tools like update_theme or delete_theme, which target different operations on themes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool should be used when the user wants to make a theme the main theme, but it does not explicitly state when to use it versus alternatives. There is no mention of alternatives or exclusions, leaving the usage context somewhat 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. 'Fetch' indicates a read-only operation, but it does not disclose pagination behavior, return format, or any potential side effects. However, for a simple read operation, the description is adequate and does not contradict any annotations (none 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loaded with the verb and resource, and contains no wasted words. It is well-structured for quick scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no annotations or output schema, so the description is the sole source of behavioral context. It covers the core purpose but omits pagination defaults, filtering options (though in schema), or expected return shape. It is minimally viable but lacks depth for a tool with multiple optional parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameter descriptions, so the description adds no additional meaning beyond what the schema already provides. The baseline of 3 applies because the schema is thorough, and the description does not compensate with extra context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Fetch') and the resource ('fulfillment orders') with a specific scope ('assigned to a fulfillment service'). This distinguishes it from sibling tools like get_fulfillment_order (which retrieves a single order) and get_fulfillment_services (which lists services).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for fetching assigned fulfillment orders, which provides clear context for when it should be used. It does not explicitly mention alternatives or exclusions, but the resource scope makes it evident that this is for filtering by assignment status and location, as supported by the parameters.
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 full responsibility for disclosing behavior. The verb 'Fetch' indicates a read-only operation, but the description does not mention pagination behavior, ordering, or what happens if no rules exist. It is adequate but lacks richer behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence that front-loads the action ('Fetch') and clearly states the resource. Every word contributes to clarity, with no redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple fetch tool with only two optional pagination parameters, both fully described in the schema. The description alone sufficiently communicates the tool's purpose and scope, making it complete for an agent to select and invoke correctly despite lacking an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both 'after' and 'first' clearly documented in the input schema. The description adds no additional meaning 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Fetch' and clearly identifies the resource as 'fulfillment constraint rules' with scope 'for the store'. It distinguishes itself from sibling tools like create/update/delete_fulfillment_constraint_rule and other fulfillment 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies its usage as a read operation for listing fulfillment constraint rules, but it does not explicitly state when to use it versus alternatives or mention any exclusions. Since there are no obvious alternatives for fetching rules, the context is clear but not elaborated.
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 explains the semantic outcome (closing as incomplete) and the reason (cannot ship remaining items), adding value beyond the tool name. However, it does not disclose any side effects, reversibility, or preconditions, leaving some behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that directly states the action and condition, with no extraneous words. It is front-loaded with the verb 'Close' and efficiently communicates the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with two well-documented parameters and no output schema. The description adequately covers the purpose and condition for closing. While it could benefit from distinguishing between close, cancel, and other fulfillment order actions, it is sufficiently complete for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides full coverage of both parameters (id and message) with descriptions. The tool description does not add additional parameter semantics, but given the high schema coverage, 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'close' with the resource 'fulfillment order', and specifies the state 'incomplete' and the condition 'cannot ship remaining items'. This clearly distinguishes it from sibling tools like cancel_fulfillment_order and close_order.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: when the fulfillment service cannot ship remaining items. However, it does not explicitly mention alternatives or exclusions, such as when to use cancel_fulfillment_order instead, so it lacks when-not 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 burden. It discloses the cascade and asynchronous execution, which are key behavioral traits. It doesn't cover permissions or reversibility, but deletion implies irreversibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the primary action, followed by the key side-effect. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter delete with no output schema, the description covers the main effect and the async nature. It could mention the response behavior, but this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds no extra parameter semantics beyond the schema's 'Metaobject Definition ID to delete'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action (delete) and resource (metaobject definition), and distinguishes from sibling delete_metaobject by noting it also deletes related metafield definitions, metaobjects, and metafields.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this vs alternatives like delete_metaobject. The cascading note implies this is for removing a definition and all related data, but it doesn't state exclusions or conditions.
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 must disclose behavioral traits. It explicitly states the action is 'permanent' and 'irreversible', and reveals a conditional restriction on order types. However, it does not explain what happens to associated resources or whether authorization is required, leaving some 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, front-loaded with the primary action and followed by key qualifiers. No unnecessary words or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with one parameter and no output schema, the description covers the essential purpose, irreversibility, and eligibility constraint. It could be more complete by specifying error behavior or what happens when deletion is not permitted, but it is sufficient for an agent to understand the tool's basic function.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers the sole parameter 'id' with a description ('Order ID to delete'). The tool description adds no additional parameter semantics beyond this, so with 100% schema coverage, a 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('delete') and resource ('order'), and adds scope ('permanently') plus a constraint ('only certain order types'), distinguishing it from cancel/close operations on orders.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is not applicable to all orders ('Only certain order types can be deleted') but does not explicitly state when to use this tool vs alternatives like cancel_order or close_order. No exclusions or alternative tool names are provided.
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 of behavioral disclosure. It adds that archived and cancelled orders are included, which is useful, but it does not mention pagination behavior, potential large result sets, or that it is a read-only operation. The schema hints at pagination via 'after' and 'first' parameters, but the description itself is sparse on behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the essential purpose without redundancy. Every word adds value, and it is appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with 5 optional parameters and a thorough schema, the description provides the key differentiator (archived/cancelled inclusion) and is otherwise supplemented by the schema's rich parameter documentation. It lacks an explicit note on return format or pagination, but these are inferable from the schema, making the overall package sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter ('after', 'first', 'query', 'reverse', 'sortKey') having a clear description. The tool description adds no additional parameter context, so per the rubric baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Fetch') and identifies the resource ('all orders'), clearly distinguishing it from the sibling 'get_orders' by emphasizing comprehensive data including archived and cancelled orders. This is a precise and unambiguous statement of 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: use this when you need all orders, including archived and cancelled ones. It does not explicitly name alternatives or provide exclusions, but the differentiating feature is clear enough for an agent to infer when to choose this over 'get_orders'.
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. 'Fetch' implies a read-only operation, and the tool is simple with no parameters, but the description does not explicitly state that it is non-destructive or require any special permissions. It also does not describe what is returned or any side effects, leaving some ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with precise wording. It effectively front-loads the purpose without wasting words, making it easy to scan and understand quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (no parameters, no output schema), the description is adequate for basic understanding. It clearly names the resource and action. However, it could have mentioned that it returns the current settings or that it is a safe read, but these are not critical given the straightforward nature of the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema description coverage is 100% (vacuously). The baseline for 0 params is 4, and the description adds no param information because none is needed. This is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Fetch') and the resource ('checkout branding settings for the store'). It is specific and easily distinguished from sibling tools like update_checkout_branding_settings and get_checkout.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (when you need to retrieve checkout branding settings) but provides no explicit guidance on when to use this tool versus alternatives, nor any exclusions. There is no mention of the update counterpart or any context on when to prefer this over other getters.
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 for behavioral disclosure. It says 'Fetch', which implies a non-mutating read, but it does not disclose behavior such as error handling, return format, or access requirements. The description is minimal and leaves some ambiguity, though the operation is simple.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that immediately communicates the purpose. There is no redundancy or unnecessary detail, making it well front-loaded and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (one parameter, no output schema), the description provides sufficient context for an agent to understand the tool's basic function. It could be more complete by detailing the return value or error cases, but those are not essential for such a straightforward read operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes the only parameter 'id' with a clear example, achieving 100% schema description coverage. The description merely references 'by ID' without adding new semantics, 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Fetch a specific B2B company by ID' clearly states the action (fetch), the target resource (specific B2B company), and the discriminator (by ID). This distinguishes it from the plural get_companies and mutation tools like create_company or update_company.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for retrieving a single company when you have its ID, which differentiates it from listing or creating companies. However, it does not explicitly mention when not to use it or provide alternative tool names, so it stops short of full 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 provided, the description carries the burden. 'Fetch' implies a read-only operation, which adds some transparency, but it does not disclose any behavior beyond that, such as return format or potential errors. This is minimal but acceptable for a simple getter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler or redundancy. Every word earns its place, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-id fetch with one parameter, the description is adequately complete: it states the action, target, and scoping. It omits explicit return details, but this is not critical given the simplicity and lack of output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (the 'id' parameter already includes a detailed example). The description only repeats 'by ID' without adding new meaning, so it does not exceed the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Fetch') and clearly identifies the resource ('specific custom pixel') and scope ('by ID'). This distinguishes it from sibling tools like get_custom_pixels (plural) and get_pixel, which are list/other-purpose operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'by ID' clearly implies the tool is for retrieving a single known pixel, providing clear context for when to use it. However, it does not explicitly mention alternatives or exclusions (e.g., 'use get_custom_pixels to list all'), 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.
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 this is a read operation ('Fetch'), implying non-mutating behavior, but it does not mention permission needs, response format, or error handling, leaving some ambiguity about what happens if the ID is invalid or not found.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exactly one sentence with an active verb and no wasted words. It is front-loaded and immediately conveys the core action and target.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter getter, the description provides adequate context: the action and input are clear, and the sibling context indicates it is the singular counterpart to 'get_discounts'. However, there is no output schema and the return format is not described, which would be helpful for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description covers the single 'id' parameter with a clear example (e.g., 'gid://shopify/DiscountCodeNode/123456789'), achieving 100% coverage. The tool description adds no value beyond saying the fetch is by ID, which is already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Fetch a specific discount code by ID' uses a specific verb ('Fetch') and resource ('discount code') with clear scope ('by ID'), making the function unmistakable. It also distinguishes itself from the sibling tool 'get_discounts' which lists 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'a specific... by ID' clearly indicates usage when an individual discount code's ID is known, contrasting with listing all codes. However, it doesn't explicitly name alternatives like 'get_discounts' or state exclusions, relying on sibling naming for 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?
No annotations are provided, so the description carries the burden. The verb 'Fetch' indicates a read-only operation, and the ID example clarifies the expected format. However, it does not disclose error behavior, authorization requirements, or return format, which would be valuable for a tool with no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. Every word contributes to meaning, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one required parameter fully described in the schema) and the absence of an output schema, the description is adequate for invocation. It could mention the return value or error conditions, but the minimal scope makes it reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already fully describes the 'id' parameter (100% coverage) with an example. The description merely restates 'by ID', adding no additional semantic value beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Fetch a specific file by ID' clearly states the action (fetch), the resource (file), and the scope (by ID). This distinguishes it from sibling tools like get_files, which is plural and likely for listing, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'by ID' implies the tool should be used when the caller has a specific file ID, which differentiates it from listing tools like get_files. However, it does not explicitly state when not to use it or mention alternative tools, 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. 'Fetch' implies a read-only operation, but the description adds no extra context such as return behavior, error handling, or permissions. This is adequate for a simple getter 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundant information. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-fetch tool with one well-documented parameter and no output schema, the description is sufficiently complete. It could mention the return value, but this is implied by the getter nature and sibling patterns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with a detailed id description, so the description adds no additional parameter semantics. Baseline of 3 is appropriate when the schema fully documents parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Fetch') and resource ('marketing event') with a clear scope ('by ID'), which unambiguously differentiates it from the plural get_marketing_events tool and other marketing event management 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies this tool is for retrieving a single marketing event when the ID is known, which is enough context given the sibling naming convention. However, it does not explicitly exclude alternatives or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the disclosure burden. 'Fetch' signals a read-only operation, but it does not disclose error behavior, required permissions, or return format. Minimal but not misleading for a simple read.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence of five words, front-loaded with the action and resource. No unnecessary information or padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (one parameter, no output schema), the description is adequate for an agent to select and invoke it correctly. It could mention the return value, but the tool name and description make the operation clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with the only parameter 'id' fully described including an example. The description's 'by ID' adds no new meaning beyond what the schema already provides, warranting the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Fetch' with a clear resource ('a specific page') and scope ('by ID'), making it unambiguous and distinguishing it from sibling tools like get_pages (which lists pages), create_page, update_page, and delete_page.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'specific page by ID' clearly implies this tool is for retrieving a single page when an ID is available. It does not explicitly name get_pages as the alternative for listing, but the context is clear enough with 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?
With no annotations provided, the description carries the full burden of behavioral disclosure. The verb 'Fetch' implies a read-only operation, which is useful, but the description does not mention error handling, return format, or whether a missing ID yields an error or null. It is minimally sufficient for such a simple getter, but lacks the depth that would merit a higher score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence with no filler or repeated information. It directly conveys the action and target, earning full marks for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward get-by-ID tool with one parameter and no output schema, the description is adequately complete. It covers the purpose and the required input, though it could be marginally more helpful by noting the native Shopify ID format or typical use case, but this is not essential given the schema example.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage for the single parameter 'id', including an example format. The description repeats the notion of 'by ID' but adds no new semantic detail beyond the schema, 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Fetch') and resource ('script tag') with the qualifier 'by ID', clearly indicating this is a single-resource retrieval. This distinguishes it from sibling tools like get_script_tags (likely list all) and create/update/delete script tag operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'by ID' provides clear context that this tool is used when you have a specific script tag identifier. However, it does not explicitly mention alternatives or exclusions (e.g., 'for multiple script tags, use get_script_tags'), leaving the user to infer the differentiation from the sibling tool naming.
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. 'Fetch' implies a read-only operation, and the description is straightforward. However, it adds no extra behavioral context beyond the name itself, such as what happens if the ID doesn't exist, whether unpublished themes are returned, or any rate limits. For a simple getter, 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence with no filler words. It is appropriately concise for the operation it describes, conveying the essential information without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple get-by-ID tool with one well-documented parameter and no output schema. The description covers the core purpose sufficiently. It could mention what is returned or error behavior, but the simplicity and clarity of the operation make the description nearly complete. Minor gaps prevent a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage for the single parameter 'id' with a clear description and example. The tool description simply repeats 'by ID' without adding any additional meaning or format specifics. Since the schema already handles the parameter semantics, 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Fetch a specific theme by ID' uses a specific verb (fetch), clearly identifies the resource (theme), and specifies the scope (by ID). This effectively distinguishes it from sibling tools like get_themes (plural, likely listing all) and get_theme_files (which fetches files, not the theme object itself).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies the use case: call this when you have a specific theme ID and need that exact theme. It does not explicitly mention alternatives or when not to use it, but the 'by ID' phrase and existence of get_themes make the context clear. Lacks explicit exclusions, 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.
Behavior2/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 does not explain whether updates are partial or full, whether tags are replaced or merged, or any side effects. The mutation is implied but insufficiently detailed for an agent to predict the outcome confidently.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences front-loaded with the core action and resource, followed by a precise exclusion. Every word earns its place, making it easy to scan and action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description covers the essential purpose and the key limitation (no line items), which is sufficient for basic decision-making. It could mention return values or update semantics, but the alternative note substantially completes the contextual picture.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for all parameters (100% coverage), so the baseline sits at 3. The description merely echoes the schema's attribute names without adding additional semantic nuance like merge behavior or field formatting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it updates order attributes and lists concrete examples (email, shipping address, tags, notes). It clearly distinguishes itself from line item editing tools in the sibling list, leaving no ambiguity about 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 Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly instructs users to use 'order editing' for line item changes, providing a clear alternative and setting a precise boundary. This is exactly the kind of when-to-use vs. when-not-to-use guidance that helps an agent select correctly.
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 critical behavioral trait that it does not apply changes, which is essential for an agent to know it's a non-mutating operation. It does not elaborate on other aspects like output format or side effects, but the most important safety-relevant behavior is addressed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the verb 'Calculate' and contains no wasted words. Every word conveys necessary information about the tool's purpose and non-applying behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The schema thoroughly documents all four parameters and their nested structures, but there is no output schema or annotations to flesh out expectations. The description does not mention what the tool returns or how it connects with apply_order_edit, leaving the agent to infer the output and workflow. Given the moderate complexity and missing output information, a score of 3 is reasonable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with all parameters having meaningful descriptions in the schema (e.g., 'Order ID to edit', 'Items to add'). The tool description itself adds no extra parameter semantics beyond what the schema already provides, so a 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Calculate') and resource ('order edit') and clearly distinguishes itself from sibling tools like apply_order_edit by stating it operates 'without applying them'. This makes the tool's 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'without applying them' provides clear context that this tool is for previewing changes rather than committing them, which informs when to use it. However, it does not explicitly name alternatives or state exclusions, so it lacks full guidance on when to choose it over apply_order_edit.
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. 'Fetch' clearly indicates a read-only, non-destructive operation, adding some behavioral transparency. However, it does not disclose error behavior, response format, or any prerequisites beyond the ID, which are important for a tool with no annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence of eight words. It states the action and the resource with no waste, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-ID tool with one well-documented parameter and no output schema, the description is complete. It adequately implies the return value (the subscription contract) and does not need to explain complex behavior. The sibling tool list provides further context if needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage: the 'id' parameter includes a description and example format. The description itself adds no parameter information beyond what the schema already provides, so it meets the baseline but does not exceed it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches a specific subscription contract by ID, using a specific verb ('Fetch') and resource ('subscription contract') with the scope ('by ID'). This distinguishes it from the sibling tool get_subscription_contracts, which presumably lists contracts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool: when you have a specific ID and need a single contract. It does not explicitly mention alternatives or exclusions, but the opposed sibling get_subscription_contracts provides context for list-vs-single usage. The guidance is clear enough for a simple fetch operation.
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 explicitly discloses a critical limitation (only pending requests can be cancelled) and introduces the GDPR context, which implies a sensitive data-handling operation. This is adequate for a simple cancellation tool, though it could mention side effects or error 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the action verb, and contains zero filler. Every word contributes meaning, efficiently conveying the purpose and the key precondition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (one parameter, no output schema, no nested objects), the description adequately covers the essential aspects: what it does and when it can be used. The GDPR context adds necessary framing. It does not explain return values, but for a cancellation action this is usually implied and not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage with a clear description for the single parameter 'customerId'. The tool description adds no extra meaning about the parameter beyond what the schema states, 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly uses a specific verb 'Cancel' and identifies the resource as 'pending customer data erasure request (GDPR)', distinguishing it from sibling tools like 'request_customer_data_erasure' (which creates such requests) and 'get_customer_data_erasure_requests' (which lists them). It unambiguously states 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear usage constraint: 'Can only cancel requests that haven't started processing yet.' This tells the agent when to use the tool (pending requests only) and implies when not to (already processing). It does not explicitly name alternative tools, but the condition is practical and contextually 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?
No annotations are provided, so the description must convey the tool's safety. 'Fetch' clearly indicates a non-mutating read operation. It does not detail permissions or error behavior, but for a simple read tool, 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with zero unnecessary words. Perfectly concise and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-ID tool with a well-documented parameter and clear sibling context, the description combined with the schema provides enough for an agent to select and invoke correctly. It could mention the return format, but the verb 'Fetch' implies the response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully describes the single 'id' parameter with a detailed description and example, so the description adds no extra parameter information. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Fetch a specific inventory transfer by ID' uses a specific verb (Fetch), names the resource (inventory transfer), and scopes by ID. It clearly distinguishes from sibling get_inventory_transfers (plural) which lists transfers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'by ID' implies this is for retrieving a single known transfer, contrasting with the plural sibling. It does not explicitly name alternatives or exclusions, but the context is clear enough for a simple getter.
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 burden. It clearly indicates a read operation ('Fetch') and outlines what the response covers (balances and configuration). No side effects or special behaviors are expected for a simple get, so the description 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one concise sentence, front-loaded with the main verb and resource, and contains no unnecessary words. It efficiently conveys the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple zero-parameter fetch tool with no output schema or annotations, the description provides enough information for an agent to select and invoke it correctly. It mentions the key return topics (balances, configuration) but could have added a note distinguishing it from related payment tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema description coverage is 100% by default. The description does not need to explain any parameters, and none are present. Baseline for 0 parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Fetch') and clearly identifies the resource ('Shopify Payments account') with additional detail on what is included ('balances and configuration'). This distinguishes it from sibling tools like get_shopify_payments_payouts or get_shopify_payments_balance_transactions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for account-level information, but it does not explicitly state when to use it versus sibling tools such as get_shopify_payments_payouts or get_shopify_payments_disputes. No alternatives or exclusions are mentioned.
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. It discloses a crucial behavioral trait: only shop-scoped subscriptions are returned, not app-scoped subscriptions. This adds meaningful context beyond the schema, though it omits other behaviors like read-only status or pagination, which are partially implied by the name and schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the primary action and immediately adds a critical scope caveat. Every word serves a purpose, with no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward list operation with optional filters and no output schema, the description provides the essential scope distinction and is sufficiently complete for an agent to select and invoke the tool. It doesn't describe return fields, but that is not necessary given the simple nature and well-covered schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema descriptions cover 100% of parameters, so the baseline of 3 applies. The description adds no extra parameter details beyond stating 'list all', but the schema's parameter descriptions are self-explanatory, making this sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all webhook subscriptions for the current app and shop, using a specific verb ('List') and resource ('webhook subscriptions'). It distinguishes from siblings like get_webhook_subscription (singular) by emphasizing the collection scope and the shop-scoped filter.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context that this tool returns shop-scoped subscriptions and explicitly excludes app-scoped ones, preventing misuse. However, it does not explicitly name alternative tools for retrieving a single subscription, so it misses the top score for explicit 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden. It discloses that the tool modifies only the children of a given menu item, leaving the rest of the menu unchanged, and notes the benefit of avoiding full reconstruction. It does not explicitly state that existing children are replaced, but the schema's children parameter description already covers that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two brief, informative sentences with no unnecessary wording. The first states exactly what the tool does; the second provides a practical use case.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a focused update tool with three well-documented parameters and no output schema, the description gives sufficient context about its purpose and when to use it. It lacks some detail about the replacement behavior, but that is already in the schema, so the overall tool definition is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with each parameter having a clear description. The tool description adds no additional parameter-specific details beyond what the schema already provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Update'), exact scope ('only the children of a specific menu item'), and clearly distinguishes this from the sibling update_menu tool by emphasizing partial update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states the use case ('useful for updating a submenu without needing to reconstruct the entire menu structure'), which implies when to prefer this over update_menu. It doesn't list exclusions, but the context is 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 provided, the description carries the full burden. It discloses that data is 'Marks data such that it no longer appears in reports' (a soft-delete behavior), requires a specific scope, and cannot delete activity-level data. This is meaningful context beyond the name, though it does not clarify irreversibility or side effects on related 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: it leads with the core action, then provides the important soft-delete nuance, an explicit alternative for activity-level data, and the required scope. Each sentence adds value with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description covers purpose, behavioral nuance, limitation, and auth requirement. It lacks details on parameter selection (e.g., how channelHandle and deleteEngagementsForAllChannels interact) and reversibility, but these are minor given the schema covers parameter semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters (channelHandle and deleteEngagementsForAllChannels) with clear descriptions. The tool description adds general scope context but does not explain parameter interactions, 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete all channel-level marketing engagement data' with a specific verb, resource, and scope. It also distinguishes from activity-level deletion by noting 'Activity-level data cannot be deleted directly - delete the MarketingActivity instead,' which sets it apart from sibling tools like delete_marketing_event.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly explains when not to use this tool (for activity-level data) and directs the user to an alternative: 'delete the MarketingActivity instead.' It also states the required scope 'write_marketing_events,' providing clear context and prerequisites.
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. It discloses the critical behavioral constraint that the entire menu structure must be passed, including existing item IDs. However, it does not explicitly state whether omitted items are deleted, whether this is a destructive/replacement operation, or any authorization requirements, leaving some behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (three short sentences) and front-loaded with the core action. It efficiently combines a clear statement of purpose, a critical usage constraint, and a pointer to a simpler alternative without any fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (nested menu structure) and lack of output schema, the description covers the essential aspects: what it does, how it must be invoked (full structure), and when to choose an alternative. It does not explain the return value or what happens to omitted items, but the core guidance is sufficiently complete for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already describes all parameters in detail. The description adds important semantics beyond the schema by emphasizing that the entire menu structure must be provided (making 'items' effectively required) and that existing items need IDs. This transcends the schema's mere property descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates an existing navigation menu, using a specific verb ('Update') and resource ('navigation menu'). It explicitly contrasts with the sibling tool update_menu_item_children, which helps differentiate its purpose from that alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: it requires passing the entire menu structure including all items and IDs, and suggests using the sibling tool update_menu_item_children for simpler partial updates. This gives clear 'when to use this vs. alternatives' context.
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:

[![shopify-graphql-mcp MCP server](https://glama.ai/mcp/servers/UVU-Store/shopify-graphql-mcp/badges/card.svg)](https://glama.ai/mcp/servers/UVU-Store/shopify-graphql-mcp)

Score Badge

Copy to your README.md:

[![shopify-graphql-mcp MCP server](https://glama.ai/mcp/servers/UVU-Store/shopify-graphql-mcp/badges/score.svg)](https://glama.ai/mcp/servers/UVU-Store/shopify-graphql-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

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/UVU-Store/shopify-graphql-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server