MCP VTEX Server

Server Quality Checklist

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

Latest release: v1.0.0
Disambiguation5/5
Every tool has a clearly distinct purpose with no ambiguity. Tools are organized by resource (e.g., brand, category, product) and action (e.g., create, get, update, delete), making it easy to distinguish between them. For example, vtex_get_product and vtex_search_products serve different functions without overlap.
Naming Consistency5/5
Tool names follow a consistent verb_noun pattern throughout, all using snake_case with a 'vtex_' prefix. The verbs are standardized (e.g., create, get, update, delete, list), and nouns clearly identify the resource, ensuring predictability and readability across all 84 tools.
Tool Count2/5
With 84 tools, the count is too high for typical agent use, making the server feel heavy and potentially overwhelming. While VTEX is a complex e-commerce platform, this many tools could lead to confusion or inefficiency in agent workflows, suggesting it might be better scoped into smaller, more focused sets.
Completeness5/5
The tool set provides complete CRUD/lifecycle coverage for the VTEX e-commerce domain, including resources like products, orders, promotions, and inventory. There are no obvious gaps; tools cover creation, retrieval, updating, deletion, listing, and specific operations like invoicing or handling orders, ensuring agents can handle full workflows without dead ends.
Average 2.9/5 across 84 of 84 tools scored. Lowest: 2.3/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

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. 'Update a review' implies a mutation operation, but it fails to describe critical traits such as required permissions, whether the update is reversible, potential side effects (e.g., on review status or visibility), rate limits, or error conditions. This leaves significant gaps in understanding the tool's behavior and risks.
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 just three words, 'Update a review', which is front-loaded and wastes no space. While this brevity contributes to under-specification in other dimensions, it meets the criteria for conciseness by avoiding unnecessary verbiage and maintaining a clear, if minimal, structure.
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 as a mutation operation with no annotations, no output schema, and a nested object parameter ('updates'), the description is inadequate. It lacks essential context such as behavioral details, usage guidelines, and clarification of parameter semantics beyond the schema. For a tool that modifies data, this minimal description fails to provide the completeness needed for safe and effective use by 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 input schema has 100% description coverage, with parameters 'reviewId' and 'updates' clearly documented. The description adds no meaning beyond the schema—it does not explain what constitutes valid updates, provide examples, or clarify the structure of the 'updates' object. Given the high schema coverage, a baseline score of 3 is appropriate, as the schema does the heavy lifting without additional value from the description.
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 review' is a tautology that merely restates the tool name 'vtex_update_review'. It provides no additional specificity about what 'update' entails (e.g., which fields can be modified, what the operation affects) or distinguishes it from sibling tools like 'vtex_approve_review' or other update operations in the list. This minimal statement fails to clarify the tool's purpose beyond its name.
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 offers no guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., needing an existing review ID), exclusions, or comparisons to related tools like 'vtex_approve_review' or other update operations. Without any context or usage instructions, the agent lacks 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.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden but discloses nothing beyond the basic action. It doesn't indicate if this is a read-only operation, requires authentication, has rate limits, returns structured data or raw content, or handles errors. For a tool with no annotations, this lack of behavioral detail is inadequate.
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, efficient sentence with zero wasted words. It's front-loaded with the core action and resource, making it easy to parse quickly. Every word earns its place by conveying the essential 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?
Given no annotations and no output schema, the description is incomplete for a tool that likely returns complex email template data. It doesn't explain what 'Get' yields (e.g., JSON structure, HTML content, or metadata), error conditions, or authentication needs. For a retrieval tool with rich sibling context, this minimal description 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?
Schema description coverage is 100%, with the parameter 'templateId' fully documented in the schema as 'Template ID'. The description adds no additional meaning beyond implying ID-based retrieval, which is already clear from the schema. With high coverage, the baseline score of 3 is appropriate as the description doesn't compensate but doesn't detract.
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 'Get email template by ID' clearly states the verb ('Get') and resource ('email template'), but it's vague about what 'Get' entails—whether it retrieves metadata, content, or both. It distinguishes from siblings like 'vtex_list_email_templates' (which lists multiple) and 'vtex_create_email_template' (which creates), but doesn't specify scope beyond ID-based retrieval.
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 prerequisites (e.g., needing a valid template ID), contrast with 'vtex_list_email_templates' for browsing, or specify use cases like editing or sending emails. The description alone 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.
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. 'Archive a coupon' implies a mutation (likely destructive or state-changing), but it doesn't disclose behavioral traits such as whether this action is reversible, requires specific permissions, affects related data, or has side effects like making the coupon inactive. For a mutation tool with zero annotation coverage, this leaves critical gaps in understanding its behavior.
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, 'Archive a coupon', which is appropriately sized and front-loaded with the core action. There's no wasted text, making it efficient. However, it could be more structured by including key details, but as-is, it's concise without being 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?
Given the tool's complexity as a mutation with no annotations and no output schema, the description is incomplete. It lacks details on what archiving entails, the outcome (e.g., does it return a confirmation?), and how it fits within the sibling ecosystem. For a tool that likely changes system state, more context is needed to be fully 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 description coverage is 100%, with the parameter 'couponCode' fully documented in the schema. The description adds no additional meaning beyond what the schema provides, such as format examples or constraints. With high schema coverage, the baseline is 3, as the description doesn't compensate but also doesn't detract from the schema's documentation.
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 'Archive a coupon' states a clear verb ('archive') and resource ('coupon'), which provides basic purpose. However, it doesn't differentiate from sibling tools like 'vtex_unarchive_promotion' or explain what 'archive' means in this context versus deletion or deactivation. It's vague about the specific action beyond the basic terminology.
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 siblings like 'vtex_delete_coupon' (not listed but implied by other delete tools) or 'vtex_get_coupon', there's no indication of when archiving is preferred over deletion or how it differs from simply retrieving coupon data. The description offers no context for usage decisions.
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 this is a creation operation, implying it's a write/mutation, but doesn't address permissions, side effects, error conditions, or what happens on success. For a mutation tool with zero annotation coverage, 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 extremely concise at just three words, which is efficient and front-loaded. However, it's arguably too brief for a mutation tool with no annotations, as it leaves critical behavioral information unspecified. Every word earns its place, but more words might be needed for 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?
Given this is a mutation tool with no annotations and no output schema, the description is incomplete. It doesn't explain what happens after creation, what values are returned, error handling, or system constraints. The agent lacks sufficient context to use this tool effectively beyond 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%, with both parameters ('name' and 'warehouseDocks') having descriptions in the schema. The tool description adds no additional parameter information beyond what's already in the structured schema. According to the rules, when schema coverage is high (>80%), the baseline is 3 even with no param info in the description.
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 'Create a new warehouse' clearly states the action (create) and resource (warehouse), which is better than a tautology. However, it doesn't differentiate from sibling tools like 'vtex_create_brand' or 'vtex_create_category' beyond the resource name, and it lacks specificity about what constitutes a warehouse in this 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 doesn't mention prerequisites, when this operation is appropriate, or how it relates to sibling tools like 'vtex_update_warehouse' or 'vtex_delete_warehouse'. The agent must 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?
No annotations are provided, so the description carries the full burden. It states it 'gets' facets and filters, implying a read-only operation, but doesn't disclose behavioral traits like whether it requires authentication, rate limits, what the output format is (e.g., JSON structure), or if it's idempotent. For a tool with no annotations, this leaves significant gaps in understanding its behavior.
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, making it appropriately concise. However, it's not front-loaded with critical details (e.g., it could start with 'Retrieve search filter attributes'), and the brevity contributes to gaps in other dimensions like guidelines and transparency.
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 moderate complexity (retrieving search facets), lack of annotations, and no output schema, the description is incomplete. It doesn't explain what facets and filters are, how they're used, or what the return values look like, leaving the agent to guess. Siblings like 'vtex_search_products' suggest this is part of a search system, but the description fails to provide necessary context for 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 has 100% description coverage, with one parameter 'categoryId' documented as 'Category ID for facets'. The description adds no additional meaning beyond this, as it doesn't explain parameter usage (e.g., optional vs. required, default behavior if omitted) or provide examples. With high schema coverage, the baseline score of 3 is appropriate, as the schema does the heavy lifting.
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 'Get facets and filters for search' states the action (get) and resource (facets and filters) with a clear purpose. However, it lacks specificity about what facets and filters are (e.g., product attributes for filtering search results) and doesn't distinguish it from siblings like 'vtex_search_products' or 'vtex_autocomplete', which are related to search functionality.
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 prerequisites (e.g., needing a search context), exclusions, or compare it to siblings like 'vtex_search_products' (which might return actual products) or 'vtex_autocomplete' (which might suggest search terms). The description implies a search-related use but offers no explicit 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 burden for behavioral disclosure. 'Get gift card by ID' implies a read-only operation, but it doesn't specify whether this requires authentication, returns structured data or raw output, handles errors (e.g., invalid ID), or has rate limits. The description lacks any behavioral context beyond the basic action, which is insufficient for a 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise ('Get gift card by ID')—a single, front-loaded sentence with no wasted words. However, it's arguably too brief, bordering on under-specification, as it lacks necessary context for effective use. It earns a 4 for efficiency but loses points for not including critical details that would enhance usability.
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 simplicity (1 parameter, no output schema, no annotations), the description is incomplete. It doesn't address what the tool returns (e.g., gift card details, balance, status), error handling, or how it fits into the broader VTEX ecosystem with siblings like 'vtex_get_gift_card_by_code'. For a retrieval tool, this leaves significant gaps in understanding its full behavior and 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 has 100% description coverage (parameter 'giftCardId' is documented as 'Gift Card ID'), so the baseline score is 3. The description adds no additional parameter semantics beyond what the schema provides—it doesn't explain the ID format, source, or validation rules. This meets the minimum viable level given the schema's completeness.
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 'Get gift card by ID' clearly states the verb ('Get') and resource ('gift card'), but it's vague about what 'Get' entails (e.g., retrieve details, fetch data). It distinguishes from sibling 'vtex_get_gift_card_by_code' by specifying 'by ID', but doesn't clarify how it differs from 'vtex_list_gift_cards' or other retrieval tools. This is a basic but functional purpose statement.
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 when to choose 'vtex_get_gift_card' over 'vtex_get_gift_card_by_code' (e.g., for ID vs. code lookup) or 'vtex_list_gift_cards' (e.g., for bulk retrieval). There's no context about prerequisites, error conditions, or typical use cases, leaving usage 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?
No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Get transaction details' implies a read-only operation, but it doesn't specify authentication requirements, rate limits, error conditions, or the format of returned data. For a tool with no annotation coverage, 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, efficient sentence with no wasted words, making it easy to parse. However, it's overly terse and could benefit from slightly more detail to improve clarity 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?
Given the lack of annotations and output schema, the description is incomplete. It doesn't explain what 'transaction details' include, potential errors, or behavioral traits like idempotency. For a tool in a complex e-commerce context with many siblings, more context is needed to guide 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 has 100% description coverage, with the single parameter 'transactionId' documented as 'Transaction ID'. The description doesn't add any meaning beyond this, such as format examples or sourcing instructions. With high schema coverage, the baseline score of 3 is appropriate, as the schema handles the parameter documentation adequately.
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 'Get transaction details' clearly states the verb ('Get') and resource ('transaction details'), making the basic purpose understandable. However, it doesn't specify what constitutes 'transaction details' (e.g., payment status, amount, date) or differentiate it from sibling tools like 'vtex_get_order' or 'vtex_get_gift_card_transaction', leaving room for ambiguity about the 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 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 (e.g., needing a transaction ID), exclusions, or comparisons to related tools like 'vtex_get_order' or 'vtex_get_gift_card_transaction', leaving the agent to infer usage based solely on 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 provided, the description carries full burden for behavioral disclosure. 'List all gift cards' implies a read-only operation but doesn't specify authentication requirements, rate limits, pagination behavior (despite pagination parameters in schema), error conditions, or what 'all' means in practice (e.g., all in a store, all active, etc.). The description is too minimal for a tool that likely interacts with sensitive financial data.
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 just three words, which is efficient. However, it's arguably too minimal - a single additional sentence could provide valuable context without sacrificing conciseness. The description is front-loaded with the core purpose but lacks any supporting information that would help an agent use it effectively.
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 annotations and no output schema, the description is insufficiently complete. It doesn't explain what information is returned about gift cards, how results are structured, whether there are filtering options beyond pagination, or any behavioral characteristics. Given that this likely returns financial instrument data, more context about security, permissions, and result format 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?
The input schema has 100% description coverage with clear parameter documentation, so the baseline is 3. The description doesn't add any parameter information beyond what's in the schema - it doesn't explain pagination behavior, default values, or constraints. However, since the schema fully documents both parameters, this meets minimum requirements.
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 'List all gift cards' clearly states the verb ('List') and resource ('gift cards'), making the purpose understandable. However, it lacks specificity about scope or filtering capabilities, and doesn't differentiate from sibling tools like 'vtex_get_gift_card' or 'vtex_get_gift_card_by_code' which retrieve specific gift cards rather than listing them all.
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 are multiple sibling tools related to gift cards (vtex_get_gift_card, vtex_get_gift_card_by_code, vtex_create_gift_card, vtex_create_gift_card_transaction), but the description doesn't explain when this list operation is appropriate versus retrieving specific gift cards or performing other gift card 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 states 'List orders with filters', which implies a read-only operation, but doesn't disclose critical behaviors such as pagination handling (implied by parameters but not explained), rate limits, authentication requirements, error conditions, or what the output looks like (e.g., list format, fields). For a tool with no annotations, 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 very concise ('List orders with filters'), consisting of a single, front-loaded sentence that efficiently conveys the core action. There's no wasted verbiage or redundancy. However, it could be slightly improved by adding a bit more context without losing conciseness, such as specifying the system (VTEX).
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 complexity (a list operation with filters and pagination), no annotations, and no output schema, the description is incomplete. It doesn't explain the return format (e.g., JSON array of orders), error handling, or behavioral nuances like how empty results are handled. For a tool with 4 parameters and no structured output documentation, this leaves significant gaps for an agent 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?
Schema description coverage is 100%, meaning all parameters are documented in the input schema with clear descriptions (e.g., date format, page defaults). The description adds no additional parameter semantics beyond what the schema provides—it doesn't explain how filters combine, provide examples of status values, or clarify pagination behavior. With high schema coverage, the baseline score of 3 is appropriate as the description doesn't add value here.
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 'List orders with filters' clearly states the verb ('List') and resource ('orders'), making the basic purpose understandable. However, it lacks specificity about what kind of orders (e.g., e-commerce orders in VTEX) and doesn't distinguish it from sibling tools like 'vtex_get_order' (singular) or 'vtex_search_documents' which might also retrieve order data. This makes it vague in the broader 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. It doesn't mention when to prefer it over 'vtex_get_order' (for a single order) or 'vtex_search_documents' (for more complex queries), nor does it specify prerequisites like authentication or context. This leaves the agent with no usage context beyond the basic action.
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. 'Search products in catalog' implies a read-only operation, but it doesn't specify whether this is a safe, non-destructive action, what the response format might be (e.g., paginated results), or any rate limits or authentication requirements. For a tool with 8 parameters and no annotation coverage, this lack of behavioral 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no wasted words, making it easy to parse. However, it's arguably too concise given the tool's complexity (8 parameters and no annotations), as it could benefit from additional context about usage or behavior to be fully helpful.
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, no output schema, and no annotations), the description is incomplete. It lacks information on behavioral traits (e.g., read-only nature, response format), usage guidelines compared to siblings, and any prerequisites. While the schema covers parameters well, the description fails to provide the broader context needed for effective tool 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%, meaning all 8 parameters are documented in the input schema with descriptions. The description adds no additional parameter semantics beyond what's in the schema (e.g., it doesn't explain how 'query' interacts with 'fq' or provide examples). Since the schema does the heavy lifting, the baseline score of 3 is appropriate, as the description doesn't compensate but also doesn't detract.
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 'Search products in catalog' clearly states the verb ('Search') and resource ('products in catalog'), making the purpose understandable. However, it doesn't differentiate from sibling tools like 'vtex_list_products' or 'vtex_get_product', which also retrieve product information, leaving ambiguity about when to use this specific search functionality versus other product retrieval methods.
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. With siblings like 'vtex_list_products' (likely for listing all products) and 'vtex_get_product' (likely for retrieving a specific product), there's no indication that this tool is for filtered searches based on query parameters. This omission could lead to incorrect tool selection by an AI agent.
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 burden but offers minimal behavioral insight. It implies a write operation ('Send') but doesn't disclose critical traits like authentication needs, rate limits, error handling, or what happens on success/failure. For a mutation tool with zero annotation coverage, 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, efficient sentence with no wasted words. It's front-loaded with the core action, though it could be more specific. While concise, it risks under-specification given the tool's 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 mutation tool with no annotations and no output schema, the description is incomplete. It lacks details on behavioral expectations, error cases, or return values, leaving significant gaps for an agent to invoke it correctly. The high schema coverage doesn't compensate for missing 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 parameters are documented in the schema. The description adds no additional meaning beyond implying template usage, which is already covered by the 'templateName' parameter. Baseline 3 is appropriate as the schema does the heavy lifting, but the description doesn't compensate with extra context like template variable examples or provider specifics.
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 'Send an email using template' clearly states the verb ('Send') and resource ('email'), but it's vague about scope and doesn't distinguish from siblings. While it mentions 'using template', it doesn't specify what kind of email (e.g., transactional, marketing) or how it relates to sibling tools like 'vtex_create_email_template' or 'vtex_get_email_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?
No guidance on when to use this tool versus alternatives is provided. The description doesn't mention prerequisites (e.g., needing an existing template), exclusions, or how it differs from other email-related operations in the sibling list, leaving the agent with no 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?
No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Update an existing dock' implies a mutation operation, but it doesn't specify required permissions, whether changes are reversible, potential side effects, or response format. For a mutation tool with zero annotation coverage, this leaves critical 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.
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's front-loaded with the core action, though it could be more specific to improve clarity 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?
Given this is a mutation tool with no annotations and no output schema, the description is incomplete. It doesn't address behavioral aspects like permissions, idempotency, or error handling, nor does it explain what the update entails or the expected outcome. For a 3-parameter update operation, 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%, with clear parameter descriptions in the schema (dockId, name, priority). The description adds no additional meaning beyond implying that these parameters are used to update a dock, which is already evident from the schema. Baseline 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.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update an existing dock' clearly states the verb (update) and resource (dock), but it's vague about what specific aspects are updated. It doesn't distinguish from sibling update tools like vtex_update_brand or vtex_update_category beyond the resource name, nor does it specify if this updates settings, configuration, or other dock properties.
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 prerequisites (e.g., needing an existing dock ID), when not to use it, or how it differs from other update tools in the sibling list. The agent must 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?
No annotations are provided, so the description carries full burden. 'Update an existing SKU' implies a mutation operation, but it doesn't disclose behavioral traits like required permissions, whether changes are reversible, rate limits, or what happens to unspecified fields. For a tool with 7 parameters and no annotations, 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 waste—'Update an existing SKU' is front-loaded and to the point. However, it's arguably too concise for a mutation tool with no annotations, as it under-specifies critical context. It earns a 4 for efficiency but loses a point for potential 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 the tool's complexity (mutation with 7 parameters), lack of annotations, and no output schema, the description is incomplete. It doesn't explain what the update entails, what values are returned, or how it differs from sibling tools. For a mutation in a rich e-commerce context, more guidance is needed to be 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 descriptions for all 7 parameters (e.g., 'SKU ID', 'Height in cm'). The description adds no additional parameter semantics beyond what the schema provides. According to rules, with high schema coverage (>80%), the baseline is 3 even with no param info in the description.
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 'Update an existing SKU' clearly states the action (update) and resource (SKU), but it's vague about what specifically gets updated. It doesn't differentiate from sibling tools like vtex_update_product or vtex_update_inventory, which also update related e-commerce entities. The purpose is understandable but lacks specificity about 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 on when to use this tool versus alternatives. With siblings like vtex_create_sku, vtex_get_sku, vtex_update_product, and vtex_update_inventory, the description doesn't indicate this is for modifying SKU attributes specifically, nor does it mention prerequisites or exclusions. The agent must 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, so the description carries the full burden of behavioral disclosure. 'Create a new category' implies a write operation, but it doesn't specify permissions required, whether the operation is idempotent, rate limits, or what happens on failure (e.g., duplicate names). For a mutation tool with zero annotation coverage, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with a single sentence ('Create a new category'), which is front-loaded and wastes no words. While it may be under-specified, it's not verbose or poorly structured, 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 complexity of a creation tool with 5 parameters, no annotations, and no output schema, the description is incomplete. It doesn't explain what a 'category' entails in VTEX, the expected return value, error handling, or usage context. This leaves significant gaps for an agent to understand the tool fully.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 clear parameter names and descriptions (e.g., 'Category name', 'Parent category ID (null for root)'). The description adds no additional parameter information beyond what's in the schema. According to the rules, with high schema coverage (>80%), the baseline score is 3, as the schema does the heavy lifting.
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 'Create a new category' clearly states the verb and resource, making the basic purpose understandable. However, it lacks specificity about what a 'category' means in this context (e.g., product category in VTEX) and doesn't differentiate from sibling tools like 'vtex_create_brand' or 'vtex_create_product' beyond the resource name. It's not tautological but remains 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?
The description provides no guidance on when to use this tool versus alternatives. There's no mention of prerequisites (e.g., needing parent category IDs), when to use it over similar creation tools (like 'vtex_create_product'), or any exclusions. This leaves the agent with minimal 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?
With no annotations provided, the description carries full burden for behavioral disclosure. 'Create a new coupon' implies a write operation but doesn't disclose permissions needed, whether creation is idempotent, rate limits, or what happens on success/failure. For a mutation tool with zero annotation coverage, this leaves significant 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 maximally concise at three words with zero wasted language. It's front-loaded with the essential action and resource, though this brevity comes at the cost of 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 creation tool with no annotations and no output schema, the description is insufficient. It doesn't explain what a successful creation returns, error conditions, or how the created coupon integrates with the broader system. The minimal description leaves too many contextual questions unanswered.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 parameters clearly documented in the schema. The description adds no additional parameter information beyond what's already in the structured schema. This meets the baseline expectation when schema does the heavy lifting.
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 'Create a new coupon' clearly states the action (create) and resource (coupon), but it's generic and doesn't differentiate from sibling tools like vtex_create_promotion or vtex_create_gift_card that also create promotional resources. It lacks specificity about what distinguishes a coupon from other promotional mechanisms.
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's no mention of prerequisites, when coupons are appropriate versus promotions or gift cards, or any contextual constraints. The description is purely functional without 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 full burden for behavioral disclosure. It states this is a creation operation but doesn't mention permission requirements, whether it's idempotent, what happens on conflicts, or what the response contains. For a mutation tool with zero annotation coverage, this is inadequate.
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, efficient sentence with no wasted words. It's appropriately sized for what it communicates, though what it communicates is limited.
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 doesn't explain what happens after creation, what validation occurs, or provide any context about Master Data. Given the complexity implied by the nested 'document' parameter, more guidance 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%, so the schema already documents both parameters. The description doesn't add any meaning beyond what's in the schema - it doesn't explain what a 'Master Data entity' is, provide examples of entity acronyms beyond what's hinted in the schema, or clarify the document data structure.
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 states the action ('Create') and resource ('document in Master Data entity'), which provides a basic understanding. However, it doesn't specify what type of document or differentiate from similar creation tools like vtex_create_brand or vtex_create_product, 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. There's no mention of prerequisites, when this is appropriate versus other creation tools, or any context about Master Data entities that would help an agent decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states 'create' which implies a write operation, but lacks details on permissions needed, whether it's idempotent, error handling, or what happens on success (e.g., returns a provider ID). This leaves significant gaps for an agent to understand the tool's 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, direct sentence with no wasted words, making it highly concise and front-loaded. It efficiently conveys the core purpose without unnecessary elaboration, which is ideal for quick understanding.
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 complexity of creating a payment provider (a write operation with nested configuration objects) and the lack of annotations and output schema, the description is insufficient. It doesn't explain the expected output, error conditions, or behavioral nuances, leaving the agent with incomplete context for proper 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 (name, connector, configuration). The description doesn't add any meaning beyond the schema, such as examples or constraints, but since the schema is well-documented, a baseline score of 3 is appropriate as it doesn't compensate for gaps.
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 'Create a payment provider configuration' clearly states the action (create) and resource (payment provider configuration), which is adequate. However, it doesn't differentiate from sibling tools like 'vtex_update_payment_provider' or 'vtex_get_payment_provider', leaving the specific scope of creation unclear compared to updates or retrievals.
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 doesn't mention prerequisites, such as whether this is for initial setup or replacing existing configurations, nor does it reference sibling tools like 'vtex_update_payment_provider' or 'vtex_delete_payment_provider' for context on usage 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 carries the full burden of behavioral disclosure. 'Delete a dock' implies a destructive, irreversible mutation, but it doesn't specify permissions required, side effects (e.g., impact on associated resources), error conditions, or what happens upon success. This leaves significant gaps in understanding the tool's 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 extremely concise at three words, with zero wasted language. It's front-loaded with the core action and resource, making it easy to parse quickly. This is an example of efficient communication without unnecessary elaboration.
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 deletion tool with no annotations and no output schema, the description is insufficient. It lacks critical context such as what a dock is, the implications of deletion, required permissions, or what the tool returns. Given the complexity and risk associated with deletion operations, more completeness is needed to guide 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 has 100% description coverage, with the single parameter 'dockId' documented as 'Dock ID to delete'. The description doesn't add any meaning beyond this, such as format examples or where to find the ID. Given the high schema coverage, a baseline score of 3 is appropriate as the schema handles the parameter documentation adequately.
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 'Delete a dock' clearly states the action (delete) and resource (dock), which is better than a tautology. However, it doesn't differentiate from sibling deletion tools like vtex_delete_brand or vtex_delete_category, nor does it specify what a 'dock' is in this 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. There's no mention of prerequisites (e.g., needing an existing dock ID), consequences, or when not to use it (e.g., if the dock is in use). The description offers only basic functional information without 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 provided, so the description carries the full burden of behavioral disclosure. While 'Delete' implies a destructive mutation, the description doesn't specify whether this action is reversible, what permissions are required, if it affects associated data (e.g., inventory), or what happens on success/failure. For a destructive tool with zero annotation coverage, this is a significant gap in safety and operational 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 extremely concise ('Delete a warehouse')—a single, front-loaded sentence with zero wasted words. It efficiently communicates the core action without unnecessary elaboration, 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?
Given the tool's destructive nature, lack of annotations, and no output schema, the description is incomplete. It fails to address critical context like irreversible effects, error handling, or dependencies (e.g., ensuring the warehouse is empty first). For a mutation tool with high stakes, this minimal description leaves too many operational questions unanswered.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 (warehouseId is described as 'Warehouse ID to delete'), so the schema already documents the parameter fully. The description adds no additional meaning beyond what the schema provides, such as format examples or sourcing guidance. With high schema coverage, a baseline score of 3 is appropriate as the description doesn't enhance parameter understanding.
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 'Delete a warehouse' clearly states the action (delete) and resource (warehouse), which is specific enough to understand the basic function. However, it doesn't distinguish this tool from other delete operations in the sibling list (like vtex_delete_brand, vtex_delete_category, etc.) beyond the resource type, making it somewhat generic within the delete tool family.
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 (e.g., needing an existing warehouse), consequences (e.g., irreversible deletion), or related tools (like vtex_get_warehouse to check before deletion or vtex_create_warehouse to replace). This leaves the agent with minimal 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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states it's a read operation ('Get'), implying non-destructive behavior, but doesn't mention any behavioral traits such as error handling (e.g., what happens if the order ID is invalid), authentication requirements, rate limits, or response format. This leaves significant gaps for a tool that likely interacts with a critical system like orders.
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 a single sentence 'Get order details by ID', which is front-loaded and wastes no words. Every part of the sentence is essential, making it efficient 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?
Given the complexity of order systems and the lack of annotations and output schema, the description is incomplete. It doesn't explain what 'details' include, error conditions, or response structure, which are crucial for an agent to use this tool effectively in a real-world context like e-commerce.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 description adds no parameter semantics beyond what the input schema provides. Since schema description coverage is 100% (the 'orderId' parameter is documented as 'Order ID'), the baseline score of 3 applies. The description doesn't clarify the format of the order ID or any constraints, so it doesn't add value over the schema.
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 'Get order details by ID' clearly states the verb ('Get') and resource ('order details'), but it's somewhat vague about what 'details' includes. It distinguishes from obvious siblings like 'vtex_cancel_order' or 'vtex_list_orders' by focusing on retrieval of a specific order, but doesn't explicitly differentiate from other getters like 'vtex_get_product' beyond the resource type.
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. For example, it doesn't mention using 'vtex_list_orders' for browsing orders or 'vtex_get_order' for specific ID-based retrieval, nor does it cover prerequisites like authentication or order existence.
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 mentions pagination (a behavioral trait), but doesn't disclose other critical behaviors: whether this is a read-only operation, what authentication is required, rate limits, error handling, or what the output format looks like (since no output schema exists). The description adds minimal 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?
Extremely concise single sentence with zero waste. Front-loaded with the core action ('List all prices') followed by the key behavioral detail ('with pagination'). Every word earns its place, 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?
Given no annotations and no output schema, the description is incomplete for a list tool. It doesn't explain what 'prices' means in this context (e.g., product prices, promotion prices), what fields are returned, how pagination works in practice, or error conditions. For a tool with 2 parameters and no structured output documentation, more context is needed to be fully usable.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 parameters ('page' and 'pageSize') well-documented in the schema. The description adds no additional parameter semantics beyond implying pagination exists. Baseline score of 3 is appropriate since the schema does the heavy lifting, but the description doesn't compensate with any extra context about parameter usage or constraints.
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 'List all prices with pagination' clearly states the verb ('List') and resource ('prices'), but it's vague about scope and doesn't distinguish from siblings like 'vtex_get_price' (singular) or 'vtex_get_computed_price'. It specifies 'all prices' but doesn't clarify if this includes archived, inactive, or filtered prices.
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 'vtex_get_price' (for a single price) or 'vtex_get_computed_price' (for calculated prices). The description implies it's for listing all prices, but doesn't mention prerequisites, filtering capabilities, or when pagination is necessary versus other list 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 full burden but only states the basic action. It doesn't disclose behavioral traits such as whether this is a read-only operation, if it requires authentication, rate limits, pagination behavior, or what the output format looks like. This is inadequate for a 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 extremely concise with just three words, front-loaded and zero waste. It efficiently communicates the core purpose without unnecessary elaboration.
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 and no output schema, the description is incomplete. It doesn't explain what 'list all promotions' returns, how results are structured, or any behavioral context needed for proper use. This leaves significant gaps for an AI agent to understand the tool's full functionality.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 'archived' parameter is fully documented in the schema), so the baseline is 3. The description adds no additional parameter information beyond what the schema already provides.
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 'List all promotions' clearly states the action (list) and resource (promotions), but it's vague about scope and doesn't differentiate from sibling tools like 'vtex_get_promotion' (singular) or 'vtex_archive_promotion'. It lacks specificity about what 'all' means in this 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 'vtex_get_promotion' for a single promotion or 'vtex_search_documents' for filtered searches. The description offers no context about 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 full burden. It states this is an update operation, implying mutation, but doesn't disclose behavioral traits like required permissions, whether changes are reversible, error handling, or rate limits. For a mutation tool with zero annotation coverage, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero waste. It's appropriately sized and front-loaded, directly stating the tool's purpose without unnecessary elaboration. 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?
Given this is a mutation tool with 4 parameters, no annotations, and no output schema, the description is incomplete. It doesn't cover behavioral aspects, error cases, or what the tool returns. For a tool that modifies data, more context is needed to ensure safe and 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%, with all parameters (brandId, Name, Text, Active) documented in the schema. The description doesn't add any meaning beyond what the schema provides—it doesn't explain parameter interactions, defaults, or constraints. Baseline 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.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update an existing brand' clearly states the action (update) and resource (brand), but it's vague about what aspects can be updated. It distinguishes from sibling tools like vtex_create_brand and vtex_delete_brand by specifying 'existing', but doesn't differentiate from other update tools like vtex_update_category or vtex_update_product beyond the resource type.
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 doesn't mention prerequisites (e.g., needing a brandId), when not to use it (e.g., for creating new brands), or how it relates to sibling tools like vtex_get_brand (for reading) or vtex_delete_brand. Usage is implied by the action 'update' but not 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?
With no annotations provided, the description carries full burden but only states the basic action without behavioral details. It doesn't disclose permission requirements, whether updates are reversible, rate limits, error conditions, or what happens to unspecified fields (partial vs. full updates). This is inadequate for a mutation tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no wasted words. It's appropriately sized for the tool's complexity and front-loads the core action, though it could benefit from more detail given the lack of annotations.
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 explain what the update entails (e.g., partial updates, validation rules), success/failure responses, or error handling, leaving significant gaps for an AI agent 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?
Schema description coverage is 100%, so the schema fully documents all parameters (categoryId, Name, Description, IsActive). The description adds no additional semantic context beyond implying updates involve these fields, meeting the baseline for high schema coverage without extra value.
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 'Update an existing category' clearly states the action (update) and resource (category), but it's vague about what specific aspects can be updated. It doesn't differentiate from sibling tools like 'vtex_update_brand' or 'vtex_update_product' beyond the resource type, and lacks detail about scope or constraints.
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 prerequisites (e.g., needing an existing category ID), compare to 'vtex_create_category' for new categories, or specify contexts where updates are appropriate versus deletion or other 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 carries the full burden of behavioral disclosure. It states the tool performs an update operation, implying mutation, but doesn't disclose any behavioral traits such as required permissions, whether changes are reversible, rate limits, or what happens on success/failure. For a mutation tool with zero annotation coverage, this leaves significant gaps in understanding its 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 extremely concise at four words, with zero wasted language. It's front-loaded with the core action and resource, making it easy to parse quickly. Every word earns its place, though this brevity comes at the cost of 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?
Given this is a mutation tool with no annotations, no output schema, and a nested object parameter, the description is incomplete. It doesn't address what the update operation entails, what data can be modified, how to structure the template object, or what to expect in return. The agent lacks sufficient context to use this tool effectively beyond basic inference.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 both parameters (templateId and template) clearly documented in the schema. The description adds no additional meaning beyond what the schema provides—it doesn't explain what templateId refers to, the structure of template data, or provide examples. Baseline 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.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update an email template' clearly states the verb ('update') and resource ('email template'), making the basic purpose understandable. However, it lacks specificity about what aspects can be updated and doesn't differentiate from sibling tools like vtex_update_document or vtex_update_product, which follow the same pattern 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?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an existing template ID), when not to use it, or how it relates to sibling tools like vtex_create_email_template or vtex_get_email_template. The agent must 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 provided, the description carries full burden for behavioral disclosure. While 'update' implies a mutation operation, it doesn't specify required permissions, whether changes are reversible, error handling for invalid configurations, or rate limits. For a configuration update tool with zero annotation coverage, this leaves significant 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, efficient sentence with zero wasted words. It's appropriately sized for a tool with clear naming and good schema documentation, though this conciseness comes at the cost of missing contextual 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 no annotations and no output schema, the description is insufficient. It doesn't explain what happens after the update, what validation occurs, error conditions, or relationship to sibling tools. The combination of mutation operation + zero annotation coverage + no output schema requires more comprehensive description than provided.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 (providerId and provider object). The description adds no additional parameter semantics beyond what's in the schema - it doesn't explain what constitutes valid configuration in the provider object or provide examples. This meets the baseline for high schema coverage.
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 'Update payment provider configuration' clearly states the action (update) and target (payment provider configuration), which is specific enough to understand the basic purpose. However, it doesn't differentiate this from sibling tools like 'vtex_update_brand' or 'vtex_update_category' beyond the resource type, and it lacks detail about what aspects of configuration 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?
The description provides no guidance on when to use this tool versus alternatives. There's no mention of prerequisites (e.g., needing an existing provider), comparison to 'vtex_create_payment_provider' for initial setup, or when to use 'vtex_get_payment_provider' instead. The agent must 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?
No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Update an existing product' implies a mutation operation, but it doesn't describe permissions required, whether updates are partial or complete, error handling, or side effects. For a mutation tool with zero annotation coverage, this leaves critical behavioral traits unspecified.
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 wasted words: 'Update an existing product.' It's front-loaded and efficiently communicates the core purpose without unnecessary elaboration, 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.
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 (a mutation operation with 5 parameters) and lack of annotations and output schema, the description is insufficient. It doesn't cover behavioral aspects like permissions or side effects, nor does it provide usage guidelines. For a tool that modifies data, more context is needed to ensure 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 has 100% description coverage, with each parameter clearly documented (e.g., productId, Name, Description). The description doesn't add any semantic details beyond what the schema provides, such as explaining relationships between parameters or usage examples. Given the high schema coverage, a baseline score of 3 is appropriate as the schema does the heavy lifting.
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 'Update an existing product' clearly states the action (update) and resource (product), which is adequate. However, it doesn't differentiate from sibling tools like vtex_create_product or vtex_delete_product, nor does it specify what aspects of a product can be updated beyond the generic term. This makes it vague compared to more specific descriptions.
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 (e.g., needing a productId), exclusions, or comparisons to tools like vtex_create_product for new products or vtex_delete_product for removal. Without such context, users must 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 provided, the description carries the full burden of behavioral disclosure. 'Update an existing promotion' implies a mutation operation, but it doesn't disclose any behavioral traits: no mention of required permissions, whether changes are reversible, rate limits, error conditions, or what happens to unspecified fields. This leaves significant gaps 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, efficient sentence with zero wasted words. It's appropriately sized for a simple update operation and front-loads the core purpose immediately. 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 mutation tool with no annotations and no output schema, the description is incomplete. It doesn't explain what the tool returns, error handling, or behavioral constraints. While the schema covers parameters well, the overall context for safe and effective use is lacking, especially given this modifies existing data.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 all parameters clearly documented in the schema itself. The description adds no additional parameter semantics beyond what's already in the schema (it doesn't explain the relationship between parameters or provide examples). This meets 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.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update an existing promotion' clearly states the verb ('update') and resource ('promotion'), but it's vague about what specifically gets updated. It doesn't distinguish this tool from sibling update tools like vtex_update_brand or vtex_update_product, which all follow the same 'update an existing X' pattern.
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 (like needing an existing promotion ID), when not to use it, or how it differs from related tools like vtex_create_promotion or vtex_archive_promotion. The agent must 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 provided, the description carries full burden for behavioral disclosure. 'Approve a review for display' implies a mutation operation that changes review visibility, but it doesn't specify permissions required, whether the action is reversible, side effects (e.g., notifications), or error conditions. For a mutation tool with zero annotation coverage, this leaves significant gaps in understanding the tool's 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, efficient sentence that states the core functionality without unnecessary words. It's front-loaded with the essential action and resource, making it immediately scannable. Every word earns its place in this minimal but complete statement of 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 mutation tool with no annotations and no output schema, the description is insufficiently complete. It doesn't explain what 'approve' entails operationally, what the expected outcome is, or any behavioral constraints. Given the complexity of a review approval operation in an e-commerce context, more context about permissions, state changes, and typical usage would be needed for an agent to use this tool 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?
Schema description coverage is 100%, with the single parameter 'reviewId' clearly documented in the schema. The description doesn't add any parameter-specific information beyond what's in the schema, which is acceptable given the high coverage. The baseline score of 3 reflects adequate parameter documentation through the schema alone.
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 ('approve') and resource ('review'), making the purpose immediately understandable. It distinguishes from sibling tools like 'vtex_update_review' by focusing specifically on approval rather than general updates. However, it doesn't specify what 'approve' entails beyond 'for display,' leaving some ambiguity about the exact effect.
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 'vtex_update_review' or other review-related operations. There's no mention of prerequisites (e.g., review must be in a pending state), exclusions, or typical workflow context. The agent must 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?
No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Archive a promotion' implies a mutation operation that likely changes the promotion's status, but it doesn't specify whether this action is reversible, what permissions are required, or what happens to archived promotions (e.g., if they remain accessible). For a mutation tool with zero annotation coverage, this is inadequate.
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 at three words, with zero wasted text. It's front-loaded with the core action and resource, making it easy to parse. Every word earns its place by conveying essential information 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?
Given that this is a mutation tool with no annotations and no output schema, the description is incomplete. It doesn't address behavioral aspects like reversibility, permissions, or system impact, nor does it explain what happens after archiving (e.g., error handling or confirmation). For a tool that modifies state, more context is needed to ensure safe and 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?
The input schema has 100% description coverage, with the single parameter 'promotionId' clearly documented as 'Promotion ID to archive'. The description doesn't add any additional semantic context beyond what the schema provides, such as format examples or where to find the ID. With high 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Archive a promotion' clearly states the verb ('archive') and resource ('promotion'), making the purpose immediately understandable. It distinguishes from siblings like 'vtex_delete_promotion' by specifying archiving rather than deletion, though it doesn't explicitly contrast with 'vtex_unarchive_promotion'.
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 when archiving is appropriate versus deleting or unarchiving, nor does it reference prerequisites like needing an existing promotion ID. With siblings like 'vtex_delete_promotion' and 'vtex_unarchive_promotion' available, this lack of context is a significant gap.
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. 'Cancel an order' implies a destructive mutation, but it doesn't disclose behavioral traits like whether cancellation is reversible, what permissions are needed, how it affects related entities (e.g., inventory, payments), or error conditions. For a mutation tool with zero annotation coverage, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise ('Cancel an order') with zero wasted words, making it front-loaded and easy to parse. Every word earns its place by directly conveying 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?
Given this is a destructive mutation tool with no annotations and no output schema, the description is incomplete. It lacks crucial context like what the tool returns (e.g., success confirmation, error details), side effects, or operational constraints. The agent has insufficient information to use this tool safely and 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?
Schema description coverage is 100%, with both parameters ('orderId', 'reason') clearly documented in the schema. The description adds no additional meaning about parameters beyond what the schema provides (e.g., format of orderId, examples of valid reasons). Baseline 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Cancel an order' clearly states the verb ('cancel') and resource ('order'), making the purpose immediately understandable. It doesn't specifically differentiate from siblings like 'vtex_delete_product' or 'vtex_archive_coupon' which perform different destructive operations on different resources, but the specificity is adequate for basic understanding.
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's no mention of prerequisites (e.g., order status requirements), consequences, or when not to use it (e.g., vs. 'vtex_start_handling' or 'vtex_invoice_order'). The agent must 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, so the description carries full burden for behavioral disclosure. It states 'Create a new brand', which implies a write/mutation operation, but doesn't disclose any behavioral traits like required permissions, whether the creation is idempotent, error handling, or what happens on success (e.g., returns a brand ID). This leaves significant gaps for safe and effective tool invocation.
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, efficient sentence with zero wasted words. It's front-loaded with the core action and resource, making it immediately scannable. Every word earns its place by conveying essential 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?
Given this is a mutation tool (create operation) with no annotations and no output schema, the description is incomplete. It doesn't address critical context like what the tool returns (e.g., brand ID, success confirmation), error conditions, or system behavior post-creation. For a tool that modifies state, this lack of information could lead to incorrect usage or misinterpretation of 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 description coverage is 100%, with all parameters clearly documented in the schema (Name, Text, Keywords, Active). The description adds no parameter-specific information beyond what's in the schema, such as examples, constraints, or usage notes. However, with complete schema coverage, the baseline score of 3 is appropriate as the schema adequately 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 resource ('new brand'), making the purpose immediately understandable. It distinguishes from siblings like 'vtex_update_brand' (update vs. create) and 'vtex_delete_brand' (create vs. delete). However, it doesn't specify what constitutes a 'brand' in this context, leaving some ambiguity compared to more detailed descriptions.
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 (e.g., authentication requirements), when not to use it (e.g., for updating existing brands), or refer to related tools like 'vtex_update_brand' or 'vtex_list_brands'. The agent must 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 full burden for behavioral disclosure. It states this is a creation operation but provides no information about permissions required, whether docks are immediately active, what happens on duplicate names, or what the response contains. For a mutation tool with zero annotation coverage, this leaves significant behavioral questions unanswered.
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 just two words that directly convey the core action. There's zero waste or unnecessary elaboration, making it perfectly front-loaded and 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?
For a mutation tool with no annotations and no output schema, the description is insufficiently complete. It doesn't explain what happens after creation, what permissions are needed, whether there are constraints beyond the parameters, or how this tool relates to the broader dock management workflow. The minimal description leaves too many contextual questions unanswered.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 three parameters with clear descriptions. The description adds no additional parameter information beyond what's in the schema, which is acceptable given the comprehensive 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 verb ('create') and resource ('new dock/loading dock'), making the purpose immediately understandable. It doesn't explicitly distinguish from sibling tools like 'vtex_update_dock' or 'vtex_delete_dock', but the 'create' action is distinct enough in this 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 about when to use this tool versus alternatives. There's no mention of prerequisites, when creation is appropriate versus updating existing docks, or how this relates to sibling tools like 'vtex_list_docks' or 'vtex_update_dock'.
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 burden for behavioral disclosure. 'Create' implies a write operation, but the description doesn't mention required permissions, whether this operation is idempotent, what happens on duplicate names, or what the response contains. This leaves significant behavioral gaps 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 extremely concise at just three words, with zero wasted language. It's front-loaded with the essential action and resource, making it efficient for quick 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?
For a mutation tool with no annotations and no output schema, the description is inadequate. It doesn't explain what happens after creation, what the return value might be, error conditions, or how this tool relates to sibling operations. The high schema coverage helps with parameters, but overall context is 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 four parameters with basic descriptions. The description adds no additional parameter information beyond what's in the schema, providing no syntax examples, format requirements, or constraints. This meets the baseline 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 clearly states the action ('create') and resource ('email template'), providing a specific verb+resource combination. However, it doesn't differentiate from sibling tools like 'vtex_update_email_template' or 'vtex_get_email_template' beyond the basic action, missing 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?
The description provides no guidance on when to use this tool versus alternatives. There are clear sibling tools for updating and retrieving email templates, but the description doesn't mention these or provide any context about prerequisites, constraints, or appropriate 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 provided, the description carries full burden for behavioral disclosure but only states the basic action. It doesn't mention whether this is a write operation (implied but not explicit), what permissions are required, whether gift cards are immediately active, what happens on failure, or what the response contains. For a creation tool with zero annotation coverage, 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, efficient sentence that states exactly what the tool does with zero wasted words. It's appropriately sized for a straightforward creation 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 creation tool with no annotations and no output schema, the description is inadequate. It doesn't explain what happens after creation, what format the response takes, whether there are side effects, or how this fits into the broader gift card management workflow. The agent would be left guessing about important behavioral aspects.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 all parameters are documented in the schema itself. The description adds no additional parameter information beyond what's already in the schema descriptions. This meets the baseline expectation when schema coverage is complete.
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 ('gift card'), making the purpose immediately understandable. However, it doesn't differentiate this tool from its sibling 'vtex_create_gift_card_transaction', which could cause confusion about when to use each.
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 'vtex_create_gift_card_transaction' or other gift card-related tools. There's no mention of prerequisites, typical use cases, or relationship to other operations in the gift card lifecycle.
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 burden for behavioral disclosure. It states this is an 'Add' operation (implying mutation) but doesn't cover important aspects like required permissions, whether transactions are reversible, rate limits, error conditions, or what happens to gift card balance after the operation. The description is minimal and lacks 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 extremely concise - a single sentence that directly states the tool's purpose. There's zero wasted language or redundancy. It's front-loaded with the core action and could serve as a model of efficiency for simple tools.
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 inadequate. It doesn't explain what happens after the transaction is added, what the response looks like, error handling, or important behavioral constraints. Given the complexity of financial transactions and lack of structured safety information, the description should provide more context about the operation's implications.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 well. The description adds minimal value beyond what's in the schema - it mentions 'credit or debit' which aligns with the operation enum, but doesn't provide additional context about parameter usage, relationships, or business rules. Baseline 3 is appropriate when 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 ('Add transaction') and resource ('to gift card'), specifying it can be credit or debit. It distinguishes from sibling tools like vtex_create_gift_card (which creates the card itself) and vtex_get_gift_card (which retrieves information), but doesn't explicitly mention these distinctions in the description text.
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 (e.g., needing an existing gift card), when to choose credit vs. debit operations, or how this differs from related tools like vtex_get_transaction. Usage context is implied 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?
With no annotations provided, the description carries full burden but only states the action without behavioral details. It lacks information on permissions needed, whether it's idempotent, error handling, or side effects (e.g., impact on inventory or orders), which is critical 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, efficient sentence with zero waste, clearly front-loading the core action. It's appropriately sized for the tool's function, 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?
For a mutation tool with no annotations and no output schema, the description is incomplete. It doesn't explain return values, error conditions, or behavioral nuances, leaving significant gaps in understanding how to use it effectively in 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 schema fully documents parameters like 'skuId' and 'basePrice'. The description adds no extra meaning beyond implying price manipulation, meeting the baseline score of 3 without compensating for any gaps.
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 or update') and resource ('price for a SKU'), making the purpose understandable. However, it doesn't differentiate from sibling tools like 'vtex_get_price' or 'vtex_delete_price', which would require explicit comparison to achieve a score of 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. There are no mentions of prerequisites, conditions, or comparisons to sibling tools like 'vtex_get_price' for checking existing prices or 'vtex_delete_price' for removal, leaving usage context unclear.
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. 'Create a new product' implies a write operation, but it doesn't mention authentication requirements, potential side effects (like inventory creation), rate limits, error conditions, or what happens on success. For a mutation tool with zero annotation coverage, this is a significant gap in 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, efficient sentence that states the core purpose without any wasted words. It's appropriately sized for a tool with a clear primary function and gets straight to the point.
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 doesn't explain what happens after creation, what permissions are needed, how to handle errors, or the relationship to sibling tools. The 100% schema coverage helps with parameters, but the overall context for using this tool effectively 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?
Schema description coverage is 100%, so the schema already documents all 8 parameters with clear descriptions. The tool description adds no additional parameter information beyond what's in the schema. According to scoring rules, when schema coverage is high (>80%), the baseline is 3 even with no param info in the description.
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 ('new product in VTEX catalog'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like vtex_create_sku or vtex_update_product, which would require more specific context about when to create a product versus other catalog entities.
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. With siblings like vtex_update_product, vtex_create_sku, and vtex_list_products, there's no indication of prerequisites, typical workflows, or when this creation tool is appropriate versus other operations on products or related entities.
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. 'Create a new promotion' implies a write operation but doesn't mention required permissions, whether promotions are immediately active, if there are rate limits, or what happens on success/failure. This is inadequate for a mutation tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero wasted words. It's appropriately sized and front-loaded, immediately conveying the core purpose without unnecessary elaboration.
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 8 parameters, no annotations, and no output schema, the description is insufficient. It doesn't address behavioral aspects like permissions, side effects, or response format, leaving significant gaps in understanding how to use this tool 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?
Schema description coverage is 100%, so the schema already documents all 8 parameters thoroughly with descriptions, enums, and defaults. The description adds no parameter information beyond what's in the schema, meeting 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.
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 ('promotion'), making the purpose immediately understandable. However, it doesn't differentiate this from sibling tools like 'vtex_create_coupon' or 'vtex_create_product', which follow the same 'Create a new X' pattern, 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 guidance on when to use this tool versus alternatives. With siblings like 'vtex_create_coupon' and 'vtex_update_promotion', there's no indication of when promotions are appropriate versus coupons or when to create versus update. No 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.
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. 'Create a new SKU' implies a write/mutation operation, but the description doesn't mention permissions required, whether the operation is idempotent, what happens on failure, or what the response contains. For a creation tool with zero annotation coverage, this leaves significant 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, efficient sentence that states the core purpose without any unnecessary words. It's perfectly front-loaded and wastes no space, 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?
For a creation/mutation tool with no annotations and no output schema, the description is insufficient. It doesn't explain what happens after creation, what the return value might be, error conditions, or behavioral constraints. The combination of mutation operation, zero annotation coverage, and missing output schema creates significant contextual gaps that the description doesn't address.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 all 8 parameters clearly documented in the schema itself. The description adds no additional parameter information beyond what's already in the schema. According to scoring rules, when schema coverage is high (>80%), the baseline score is 3 even with no parameter details in the description.
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 ('new SKU for a product'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'vtex_create_product' or 'vtex_update_sku', which would require more specificity about what distinguishes SKU creation from product creation or SKU updates.
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's no mention of prerequisites (e.g., needing an existing product), when not to use it, or how it differs from related tools like 'vtex_create_product' or 'vtex_update_sku' in the sibling list.
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 burden for behavioral disclosure. 'Delete a brand' implies a destructive, irreversible mutation, but it doesn't specify permissions required, side effects (e.g., impact on associated products), error conditions, or response format. This is inadequate for a destructive operation 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 extremely concise at three words, with zero wasted language. It's front-loaded with the core action and resource, making it immediately scannable. Every word earns its place by directly conveying the tool's function.
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 mutation tool with no annotations and no output schema, the description is incomplete. It lacks critical context: what happens after deletion (confirmation, error handling), dependencies, or system-specific behaviors. The high schema coverage doesn't compensate for the missing behavioral guidance 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?
Schema description coverage is 100%, with the single parameter 'brandId' clearly documented in the schema. The description adds no additional parameter information beyond what the schema provides, such as format examples or validation rules. This meets the baseline of 3 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete a brand' clearly states the action (delete) and resource (brand), making the purpose immediately understandable. It distinguishes from sibling tools like 'vtex_create_brand' and 'vtex_update_brand' by specifying the destructive operation. However, it doesn't explicitly mention the scope or system context beyond what's 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?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an existing brand), consequences (e.g., irreversible deletion), or relationships with sibling tools like 'vtex_list_brands' for selection or 'vtex_get_brand' for verification. The agent must 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, so the description carries full burden for behavioral disclosure. 'Delete' implies a destructive mutation, but the description doesn't specify whether this is permanent, requires specific permissions, has side effects (e.g., on related products), or provides confirmation. This leaves critical behavioral gaps 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, efficient phrase with zero wasted words. It's appropriately sized for a simple operation and front-loads the essential action, 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?
For a destructive mutation tool with no annotations and no output schema, the description is insufficiently complete. It lacks critical context such as success/error behavior, return values, permissions required, or irreversible consequences, leaving the agent with significant uncertainty about tool 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 has 100% description coverage, with the single parameter 'categoryId' documented as 'Category ID to delete.' The description adds no additional parameter information beyond what the schema provides, so it meets the baseline of 3 for adequate but not additive semantic value.
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 category' clearly states the action (delete) and resource (category), making the tool's purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'vtex_delete_brand' or 'vtex_delete_product' beyond the resource type, which prevents 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?
The description provides no guidance on when to use this tool versus alternatives. With sibling tools like 'vtex_update_category' and 'vtex_get_category' available, there's no indication of prerequisites (e.g., whether the category must be empty) or when deletion is appropriate versus archiving or updating.
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 burden but only states the action without behavioral details. It doesn't disclose that this is a destructive operation (implied by 'Delete'), potential side effects (e.g., data loss, permissions required), error conditions, or response format, leaving significant gaps 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, efficient sentence with zero wasted words. It's front-loaded with the core action and resource, making it easy to parse quickly without unnecessary elaboration.
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 is incomplete. It lacks critical context such as behavioral traits (e.g., irreversibility, auth needs), usage prerequisites, and what to expect upon success or failure, making it inadequate for safe and effective use by 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 description coverage is 100%, with both parameters ('entity' and 'documentId') clearly documented in the schema. The description adds no additional meaning beyond what the schema provides, so it meets the baseline of 3 without compensating or enhancing parameter 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 clearly states the action ('Delete') and resource ('a Master Data document'), which is specific and unambiguous. However, it doesn't differentiate from sibling tools like 'vtex_delete_brand' or 'vtex_delete_category' beyond the resource type, missing explicit 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?
No guidance is provided on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing a document ID from 'vtex_get_document' or 'vtex_search_documents'), exclusions, or comparisons with other deletion tools like 'vtex_delete_product'.
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. While 'Delete' implies a destructive mutation, it doesn't specify whether this action is reversible, requires special permissions, has side effects (e.g., affecting existing orders), or what happens on success/failure. This leaves critical behavioral traits 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, direct sentence with no wasted words. It's front-loaded with the essential action and resource, making it highly efficient 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?
For a destructive tool with no annotations and no output schema, the description is insufficient. It lacks critical context such as error handling, return values, permissions required, or impact on related data (e.g., whether deletion affects payment processing). This leaves the agent with significant gaps in understanding 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 input schema has 100% description coverage, with the single parameter 'providerId' clearly documented. The description doesn't add any semantic details beyond what the schema provides (e.g., format examples or where to find the ID), so it meets the baseline for high schema coverage without adding value.
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 payment provider'), which is specific and unambiguous. However, it doesn't distinguish this tool from other deletion tools like vtex_delete_brand or vtex_delete_category, which follow the same pattern.
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 (e.g., needing the provider ID from vtex_get_payment_provider or vtex_list_payment_providers), nor does it warn about consequences of deletion or suggest alternatives like vtex_update_payment_provider for modifications.
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 burden but offers minimal behavioral insight. 'Delete' implies a destructive mutation, but it doesn't specify whether this is permanent, requires specific permissions, affects related data, or has rate limits. The description lacks crucial context 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 extremely concise at just four words, with zero wasted language. It's front-loaded with the core action and target, making it efficient despite its 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?
For a destructive mutation tool with no annotations and no output schema, the description is inadequate. It doesn't explain what happens after deletion (success response, error conditions), whether the action is reversible, or how it interacts with other price-related tools. The context is 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 has 100% description coverage, with skuId clearly documented. The description adds no additional parameter context beyond implying a price is deleted for that SKU. This meets the baseline for high schema coverage, but doesn't enhance understanding of the parameter's role.
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 target resource ('price for a SKU'), making the purpose unambiguous. However, it doesn't differentiate from sibling deletion tools like vtex_delete_brand or vtex_delete_product, which follow the same pattern but target 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 guidance is provided on when to use this tool versus alternatives. There's no mention of prerequisites (e.g., needing an existing price), consequences of deletion, or when to choose this over related tools like vtex_create_or_update_price or vtex_get_price for price management.
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. 'Delete a product' implies a destructive, irreversible mutation, but it doesn't specify critical details like required permissions, whether deletion is permanent or soft, what happens to associated SKUs or inventory, or any rate limits. This leaves significant gaps 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 extremely concise at three words, with zero wasted language. It's front-loaded with the core action and resource, making it easy to parse quickly. Every word earns its place by conveying essential information 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?
Given the tool's complexity (a destructive deletion operation), lack of annotations, and absence of an output schema, the description is incomplete. It doesn't address behavioral risks, success/failure responses, or system impacts, which are crucial for safe invocation. The high schema coverage doesn't compensate for these missing contextual elements.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 the single parameter 'productId' clearly documented. The description doesn't add any additional semantic context beyond what the schema provides (e.g., format examples or sourcing instructions), so it meets the baseline for high schema coverage without compensating value.
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 target resource ('a product'), which provides a specific verb+resource combination. However, it doesn't distinguish this tool from other deletion tools in the sibling list (like vtex_delete_brand, vtex_delete_category, etc.), which would require mentioning it's specifically for products rather than other entity 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?
The description provides no guidance on when to use this tool versus alternatives. There's no mention of prerequisites (like needing the product ID), when not to use it (e.g., if the product has dependencies), or what alternatives exist (like vtex_archive_promotion for non-destructive removal). The agent must 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, so the description carries full burden. 'Get brand details by ID' implies a read-only operation, but it doesn't disclose behavioral traits like authentication requirements, rate limits, error responses (e.g., what happens if the brand ID doesn't exist), or data format of returned details. This leaves significant gaps for an agent to understand how to invoke it safely.
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, efficient sentence with zero waste: 'Get brand details by ID'. It's front-loaded with the core action and resource, making it easy to parse. No extraneous words or redundant information are 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?
Given the tool's simplicity (1 parameter, 100% schema coverage) and lack of annotations or output schema, the description is incomplete. It doesn't explain what 'brand details' include (e.g., name, description, status), potential errors, or how results are structured. For a read operation without annotations, more context is needed to guide an agent 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?
Schema description coverage is 100%, with the single parameter 'brandId' documented as 'Brand ID' in the schema. The description adds no additional meaning beyond this, such as format examples (e.g., numeric vs. string ID) or where to find brand IDs. With high schema coverage, the baseline is 3, as 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 'Get brand details by ID' clearly states the action (get) and resource (brand details), specifying retrieval by ID. It distinguishes from sibling tools like 'list_brands' (which lists all brands) and 'create_brand'/'update_brand'/'delete_brand' (which modify brands). However, it doesn't explicitly contrast with 'vtex_get_category' or other 'get_' tools, keeping it at 4 rather than 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. It doesn't mention when to choose 'vtex_get_brand' over 'vtex_list_brands' (for a single brand vs. all brands) or other retrieval tools like 'vtex_get_product'. There's no context about prerequisites, error conditions, or typical 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 provided, the description carries the full burden of behavioral disclosure but offers minimal information. It implies a read-only operation ('Get'), but doesn't specify authentication requirements, rate limits, error handling, or response format. For a tool with zero annotation coverage, this leaves significant gaps in understanding how it behaves in practice.
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 at just four words, with zero wasted language. It's front-loaded with the core purpose ('Get category details') followed by the key constraint ('by ID'). Every word serves a clear purpose, 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?
Given the lack of annotations and output schema, the description is insufficiently complete. It doesn't explain what 'category details' includes, how errors are handled, or what authentication is required. For a tool that likely returns structured data about categories, more context about the response format and potential limitations would be helpful for effective 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 description mentions 'by ID' which aligns with the single 'categoryId' parameter in the schema. With 100% schema description coverage, the schema already documents this parameter adequately. The description adds marginal value by reinforcing the ID-based lookup but doesn't provide additional context about valid ID formats or examples beyond what the schema offers.
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 ('Get') and resource ('category details by ID'), making the purpose immediately understandable. It distinguishes from sibling tools like 'vtex_list_categories' by specifying retrieval of a single category rather than listing multiple. However, it doesn't explicitly contrast with other 'get' tools like 'vtex_get_product' or 'vtex_get_brand', which follow the same pattern.
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 sibling tools like 'vtex_list_categories' for browsing categories or 'vtex_create_category' for creating new ones. There's no context about prerequisites, error conditions, or typical use cases, leaving the agent with minimal 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?
No annotations are provided, so the description carries full burden. It states it's a 'get' operation, implying read-only, but doesn't disclose behavioral traits like authentication needs, rate limits, error handling (e.g., invalid codes), or response format. For a tool with no annotation coverage, this leaves significant gaps in understanding how it behaves.
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, efficient sentence with zero waste. It's front-loaded with the core purpose and uses clear language. Every word earns its place, making it easy to parse quickly without unnecessary elaboration.
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 and no output schema, the description is incomplete for a tool that likely returns structured data. It doesn't explain what 'details' include (e.g., discount amount, expiration), error cases, or any side effects. For a read operation with missing structured context, more descriptive content is needed to fully inform 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 description adds minimal meaning beyond the input schema. It mentions 'by code', aligning with the 'couponCode' parameter, but the schema already has 100% coverage with a clear description ('Coupon code'). No additional details on format or constraints are provided. With high schema coverage, the baseline is 3, and the description doesn't significantly enhance parameter 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 'Get coupon details by code' clearly states the action (get) and resource (coupon details), with the specific identifier (code). It distinguishes from siblings like 'vtex_list_coupons' (list all) and 'vtex_create_coupon' (create). However, it doesn't specify what 'details' include (e.g., validity, discount), making it slightly less specific than a perfect 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/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 (e.g., needing a valid coupon code), exclusions (e.g., not for archived coupons), or comparisons to siblings like 'vtex_list_coupons' for bulk retrieval. Usage is implied by the name but not 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?
With no annotations provided, the description carries full burden but offers minimal behavioral information. It doesn't disclose whether this is a read-only operation (implied by 'Get' but not explicit), authentication requirements, rate limits, error conditions, or what happens if the document doesn't exist. For a retrieval tool with zero annotation coverage, this leaves significant 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, clear sentence with zero wasted words. It's front-loaded with the essential action and resource. Every word earns its place, making it highly efficient for an AI 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?
For a retrieval tool with no annotations and no output schema, the description is insufficient. It doesn't explain what 'Master Data' refers to in this context, what format the document returns in, whether fields filtering is optional, or any error scenarios. Given the complexity of document retrieval systems and the lack of structured metadata, 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%, so the schema already documents all three parameters (entity, documentId, fields) with basic descriptions. The description adds no additional parameter context beyond what's in the schema - no examples, format details, or explanation of how fields array works. Baseline 3 is appropriate when 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 ('Get') and resource ('a document from Master Data'), making the purpose immediately understandable. It distinguishes itself from siblings like vtex_search_documents (which searches) and vtex_create_document/update_document/delete_document (which modify). However, it doesn't specify that this retrieves a single document by ID, which would make it fully distinct.
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 doesn't mention that vtex_search_documents should be used for searching/filtering multiple documents, or that vtex_get_document is for retrieving a specific known document by ID. There's no context about prerequisites 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.
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 'search' but doesn't disclose behavioral traits: whether it's read-only (likely, but not confirmed), if it requires authentication, error handling (e.g., invalid codes), or response format. The description adds minimal context beyond the basic action, leaving gaps in understanding how the tool behaves.
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, efficient sentence with zero waste: 'Search gift card by redemption code'. It's front-loaded with the core action and parameter, making it easy to parse. No unnecessary words 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?
Given no annotations, no output schema, and a simple input schema, the description is incomplete. It lacks behavioral details (e.g., read-only nature, error responses), usage context vs. siblings, and any mention of return values. For a tool with 1 parameter, it's minimal but misses key contextual elements needed for effective 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?
Schema description coverage is 100%, with the parameter 'redemptionCode' fully documented in the schema. The description adds no additional meaning beyond what the schema provides (e.g., format examples or constraints). Baseline is 3 since the schema does the heavy lifting, but the description doesn't compensate with extra insights.
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 'Search gift card by redemption code' clearly states the action (search) and resource (gift card), with the parameter 'redemption code' specifying the search key. It distinguishes from siblings like 'vtex_get_gift_card' (likely by ID) and 'vtex_list_gift_cards' (list all), though not explicitly named. However, it could be more specific about what 'search' entails (e.g., retrieval vs. lookup).
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. Siblings include 'vtex_get_gift_card' (likely by ID) and 'vtex_list_gift_cards', but the description doesn't mention these or clarify use cases (e.g., use this for code-based lookup vs. ID-based). Usage is implied by the parameter but not 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?
With no annotations provided, the description carries full burden but offers limited behavioral insight. It implies a read-only operation ('Get'), but doesn't disclose potential side effects, authentication needs, rate limits, or error handling. For a tool in an e-commerce context, this leaves gaps in understanding how it behaves in practice, such as whether it returns real-time or cached 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, direct sentence with no wasted words, making it highly concise and front-loaded. It efficiently communicates the core purpose without unnecessary elaboration, which is ideal for quick understanding in a list of many tools.
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 incomplete for effective use. It doesn't explain what 'inventory information' entails (e.g., quantities, warehouse details), potential return formats, or error scenarios. For a tool with one parameter but unknown output structure, more context is needed to ensure the agent can interpret results 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 description coverage is 100%, with the single parameter 'skuId' clearly documented as 'SKU ID' in the schema. The description adds no additional semantic context beyond this, such as format examples or validation rules. Since the schema does the heavy lifting, the baseline score of 3 is appropriate, but there's no extra value from the description.
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 ('Get') and resource ('inventory information for a SKU'), making the purpose immediately understandable. It distinguishes itself from siblings like 'vtex_list_inventory_by_warehouse' by focusing on a single SKU rather than bulk listing. However, it doesn't specify what 'inventory information' includes (e.g., stock levels, locations), keeping it from 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. For example, it doesn't mention when to choose this over 'vtex_list_inventory_by_warehouse' for bulk data or 'vtex_get_sku' for SKU details without inventory. The description lacks context on prerequisites or typical use cases, offering minimal help 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 states the action ('Get') but doesn't clarify whether this is a read-only operation, what permissions are required, potential rate limits, error conditions (e.g., invalid provider ID), or the format of returned data. For a tool with no annotation coverage, this leaves significant gaps in understanding its 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, efficient sentence with zero wasted words. It's front-loaded with the core action and resource, making it immediately scannable. Every word ('Get', 'payment provider', 'configuration') contributes directly to understanding 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?
Given the lack of annotations and output schema, the description is incomplete for effective tool use. It doesn't explain what 'configuration' includes (e.g., JSON structure, fields), error handling, or authentication requirements. For a tool that likely returns complex provider settings, more context is needed to help the agent interpret results or handle failures.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 the single parameter 'providerId' documented as 'Provider ID'. The description doesn't add any meaning beyond this (e.g., explaining where to find the ID, format examples, or valid values). With high schema coverage, the baseline score of 3 is appropriate, as 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 ('Get') and resource ('payment provider configuration'), making the purpose immediately understandable. It distinguishes itself from siblings like 'vtex_list_payment_providers' (which lists multiple providers) and 'vtex_create_payment_provider' (which creates new providers). However, it doesn't specify what 'configuration' entails (e.g., settings, credentials, status), leaving some 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. The description doesn't mention prerequisites (e.g., needing a provider ID), compare it to 'vtex_list_payment_providers' for discovery, or indicate typical use cases (e.g., troubleshooting, setup verification). The agent must infer usage from the tool name and parameter 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 the full burden. It states it's a 'Get' operation, implying read-only, but doesn't disclose behavioral traits such as pagination, rate limits, authentication needs, or what happens if no filters are applied. The description is minimal and lacks critical operational 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, efficient sentence that is front-loaded with the core purpose. There is zero waste, making it appropriately sized for the tool's 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's complexity (2 parameters, no output schema, no annotations), the description is incomplete. It lacks details on return format, error handling, or how it interacts with sibling tools. The mention of 'useful for indexing' adds some context, but overall, it doesn't provide enough information for an agent to use it effectively 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?
Schema description coverage is 100%, so the schema already documents both parameters ('categoryId' and 'brandId') with descriptions. The description doesn't add any meaning beyond what the schema provides, such as explaining how filtering works or default behavior. Baseline 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get all product and SKU IDs') and the resource, with a specific use case ('useful for indexing'). It distinguishes from siblings like 'vtex_get_product' or 'vtex_get_sku' by focusing on IDs rather than full details, but doesn't explicitly compare to 'vtex_list_products' or 'vtex_list_skus' which might overlap.
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 'vtex_list_products' or 'vtex_list_skus' is provided. The description mentions 'useful for indexing' which hints at a context, but doesn't specify prerequisites, exclusions, or clear alternatives among the many 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 full burden but only states it 'gets' details without behavioral context. It doesn't disclose if this is a read-only operation, what permissions are needed, rate limits, error handling, or the format of returned details, leaving significant gaps for a tool that likely queries a database.
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, efficient sentence with zero waste—'Get promotion details by ID'—front-loading the core action and key constraint (ID-based). It's appropriately sized for a simple lookup 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 and no output schema, the description is incomplete. It doesn't explain what 'details' include, potential response formats, or error behaviors, making it inadequate for a tool that likely returns structured data. More context is needed for 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?
Schema description coverage is 100% with one parameter 'promotionId' fully documented in the schema. The description adds no additional meaning beyond implying retrieval by ID, which is already clear from the schema. Baseline 3 is appropriate as 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 'Get promotion details by ID' clearly states the verb 'Get' and resource 'promotion details', specifying it retrieves information by ID. It distinguishes from siblings like vtex_list_promotions (list all) and vtex_create_promotion (create new), but doesn't explicitly mention these distinctions in the text.
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 prerequisites (e.g., needing a valid promotion ID), contrast with vtex_list_promotions for browsing, or specify error cases like invalid IDs, leaving usage context unclear.
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 burden but lacks behavioral details. It doesn't disclose whether this is a read-only operation, potential side effects, authentication requirements (despite an optional sessionToken parameter), rate limits, or response format. The description is minimal and fails to compensate for missing 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 extremely concise—a single phrase with no wasted words—and front-loaded with the core action. It efficiently communicates the tool's purpose without unnecessary elaboration, 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.
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 incomplete. It doesn't explain what 'segment data' entails, how results are returned, or any behavioral traits. For a tool with one parameter but no structured context, this minimal description leaves significant gaps in understanding its full usage and implications.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 the optional sessionToken parameter. The description adds no additional parameter context beyond implying segment data retrieval, which aligns with the tool's purpose but doesn't enhance parameter understanding beyond the schema's 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 verb 'Get' and the resource 'segment data', with specific examples (campaigns, UTM, location) that clarify scope. It distinguishes from siblings like vtex_get_product or vtex_get_order by focusing on segment data, though it doesn't explicitly contrast with similar tools like vtex_get_client_by_email.
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 is provided. The description doesn't mention prerequisites (e.g., authentication needs), context for segment data retrieval, or comparisons to other get_* tools in the sibling list, leaving usage unclear.
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 burden but only states the basic action without disclosing behavioral traits. It doesn't mention if this is a read-only operation, requires authentication, has rate limits, or what the output format might be (e.g., JSON structure, error handling). The description is minimal and lacks critical context for safe invocation.
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, efficient sentence with zero waste. It's front-loaded with the core purpose and appropriately sized for a simple retrieval tool, 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?
Given the tool's simplicity (1 parameter, 100% schema coverage) but lack of annotations and output schema, the description is incomplete. It doesn't address behavioral aspects like safety, response format, or error conditions, which are essential for an agent to use it effectively in a VTEX e-commerce 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 description adds no parameter details beyond what the schema provides. With 100% schema description coverage (the 'skuId' parameter is documented as 'SKU ID'), the baseline is 3. The description doesn't elaborate on format, validation, or examples, so it meets but doesn't exceed the minimum.
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 'Get SKU details by ID' clearly states the action (get) and resource (SKU details) with a specific identifier (by ID). It distinguishes from siblings like 'vtex_get_sku_by_refid' by specifying ID-based retrieval, though it doesn't explicitly contrast with all similar tools like 'vtex_get_product_and_sku_ids'.
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 prerequisites, when not to use it, or compare with siblings like 'vtex_get_sku_by_refid' or 'vtex_get_product_and_sku_ids', leaving the agent to infer usage from context 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 full burden for behavioral disclosure. It states this is a read operation ('Get'), but doesn't mention authentication requirements, rate limits, error responses, or what 'SKU details' includes. For a retrieval tool with zero annotation coverage, this leaves significant 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, efficient sentence with zero wasted words. It's front-loaded with the core functionality and appropriately sized for a simple lookup tool. 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 retrieval tool with no annotations and no output schema, the description is insufficient. It doesn't explain what 'SKU details' includes, potential error cases, authentication needs, or how this differs from similar sibling tools. The context signals indicate this is a simple tool, but the description should provide more complete 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?
The schema description coverage is 100%, with the single parameter 'refId' clearly documented as 'SKU reference ID' in the schema. The description adds no additional parameter information beyond what's already in the structured 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 the verb ('Get') and resource ('SKU details') with the specific lookup method ('by reference ID'), making the purpose unambiguous. It doesn't explicitly differentiate from sibling tools like 'vtex_get_sku' or 'vtex_get_product_and_sku_ids', but the reference ID focus provides implicit 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 like 'vtex_get_sku' (which likely uses SKU ID instead of reference ID) or 'vtex_get_product_and_sku_ids'. There's no mention of prerequisites, error conditions, or comparison with sibling retrieval 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 full burden for behavioral disclosure. 'Get warehouse details by ID' implies a read operation, but it doesn't specify authentication requirements, rate limits, error conditions, or what 'details' includes. For a tool with zero annotation coverage, this leaves significant 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, efficient sentence that states exactly what the tool does with zero wasted words. It's appropriately sized for a simple retrieval operation and front-loads the essential 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 tool with no annotations and no output schema, the description is insufficiently complete. It doesn't explain what 'warehouse details' includes, the response format, error handling, or authentication requirements. Given the lack of structured metadata, the description should provide more 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?
Schema description coverage is 100%, so the schema already fully documents the single 'warehouseId' parameter. The description adds no additional parameter information beyond what's in the schema, which meets the baseline expectation when schema coverage is complete.
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 ('Get') and resource ('warehouse details by ID'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'vtex_get_warehouse' vs 'vtex_list_warehouses' or other get operations, which would require explicit distinction for 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?
The description provides no guidance on when to use this tool versus alternatives. There's no mention of when to use 'vtex_get_warehouse' versus 'vtex_list_warehouses' or other warehouse-related tools, nor any context about prerequisites or constraints for retrieving warehouse details.
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. 'Add invoice' implies a write/mutation operation, but it doesn't disclose behavioral traits like required permissions, whether this is reversible, rate limits, or what happens if an invoice already exists. The description is minimal and lacks essential context 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, efficient sentence with zero waste. It's 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.
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 6 parameters, no annotations, and no output schema, the description is inadequate. It lacks context on behavior, error conditions, return values, and usage guidelines. The high parameter count and mutation nature demand more completeness than provided.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 parameters documented in the schema. The description adds no parameter-specific information beyond what the schema provides, so it meets the baseline of 3 where 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 ('Add invoice') and target resource ('to an order'), providing a specific verb+resource combination. It doesn't distinguish from siblings like 'vtex_cancel_order' or 'vtex_get_order', but 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 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. With siblings like 'vtex_cancel_order', 'vtex_get_order', and 'vtex_start_handling', there's no indication of appropriate contexts, prerequisites, or exclusions for invoice addition.
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. 'List all coupons' implies a read-only operation, but it doesn't specify if it's paginated, rate-limited, requires specific permissions, or what the output format is. This is inadequate for a tool with zero annotation coverage, as key behavioral traits are 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 'List all coupons' is extremely concise—three words that directly convey the core action. It's front-loaded with no unnecessary elaboration, making it efficient and easy to parse 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?
Given the complexity (a list operation with no parameters) and lack of annotations and output schema, the description is incomplete. It doesn't address behavioral aspects like pagination, sorting, or output format, which are crucial for proper tool invocation. This leaves significant gaps in understanding how the tool behaves.
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 0 parameters with 100% coverage, so no parameter documentation is needed. The description doesn't add parameter details, which is appropriate here. A baseline of 4 is applied since the schema fully covers the parameters (none), and the description doesn't need to compensate.
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 'List all coupons' clearly states the verb ('List') and resource ('coupons'), making the purpose understandable. However, it lacks specificity about scope or format, and doesn't differentiate from sibling tools like 'vtex_get_coupon' (singular) or 'vtex_archive_coupon', which is a gap in 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?
No guidance is provided on when to use this tool versus alternatives. For example, it doesn't specify if this should be used for bulk retrieval versus 'vtex_get_coupon' for single coupon details, or mention any prerequisites like authentication or context. This leaves 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.
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 ('List all docks') without detailing behavioral traits like whether it's a read-only operation, if it requires authentication, potential rate limits, pagination behavior, or what the output format might be. This leaves significant gaps for an AI agent to understand how to invoke it safely and effectively.
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 'List all docks' is extremely concise and front-loaded, consisting of a single, clear sentence with no wasted words. It efficiently communicates the core action without unnecessary elaboration, 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?
Given the tool's simplicity (0 parameters, no annotations, no output schema), the description is minimal. However, for a list operation, it lacks context such as the format of returned data (e.g., list of objects, pagination details), any dependencies, or error handling. This makes it incomplete for an AI agent to fully understand the tool's behavior and output.
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 0 parameters, and schema description coverage is 100%, so there are no parameters to document. The description does not need to add parameter semantics beyond the schema, and it correctly implies no inputs are required. A baseline of 4 is appropriate as it aligns with the schema's lack of parameters.
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 'List all docks' clearly states the verb ('List') and resource ('docks'), making the purpose understandable. However, it lacks specificity about what 'docks' are in this context (e.g., shipping docks, inventory docks) and does not differentiate from sibling tools like 'vtex_get_dock' (singular) or other list tools (e.g., 'vtex_list_warehouses'), leaving some 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. It does not mention when to prefer 'vtex_list_docks' over 'vtex_get_dock' (for a single dock) or other list tools, nor does it specify any prerequisites or contextual usage scenarios, such as needing authentication or specific permissions.
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 burden but only states the basic operation. It doesn't disclose whether this is a read-only operation, whether it requires specific permissions, if there are rate limits, what format the inventory items are returned in, or if there are pagination details beyond the 'page' parameter. For a list operation with zero annotation coverage, 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, clear sentence with zero wasted words. It's front-loaded with the core purpose and appropriately sized 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?
For a list operation with no annotations and no output schema, the description is too minimal. It doesn't explain what 'inventory items' include (SKUs, quantities, etc.), doesn't mention pagination behavior despite having a page parameter, and provides no context about authentication requirements or error conditions.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 (warehouseId and page) adequately. The description adds no additional parameter information beyond what's in the schema, so it meets the baseline for high schema coverage without compensating value.
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 ('List all inventory items') and resource ('in a warehouse'), making the purpose immediately understandable. It doesn't specifically differentiate from sibling tools like 'vtex_get_inventory' or 'vtex_list_skus', but the warehouse-specific focus is reasonably clear from the description 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?
The description provides no guidance on when to use this tool versus alternatives like 'vtex_get_inventory' or 'vtex_list_skus'. There's no mention of prerequisites, limitations, or comparison with sibling tools that might serve similar purposes.
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. 'List products with pagination' implies a read-only operation but doesn't disclose critical behavioral details like authentication requirements, rate limits, error conditions, or what the output format looks like (especially important since there's no output schema). The mention of pagination is helpful but insufficient for full 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, efficient sentence with zero wasted words. It's front-loaded with the core purpose and includes a useful behavioral qualifier ('with pagination'). 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?
Given no annotations and no output schema, the description is incomplete for a tool that likely returns complex product data. It doesn't explain what 'products' includes (e.g., fields, structure), how pagination works in practice (e.g., total count, next page tokens), or any prerequisites. For a list operation in a rich e-commerce context, this 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?
Schema description coverage is 100%, with both parameters ('page' and 'pageSize') clearly documented in the schema. The description adds no additional parameter semantics beyond implying pagination exists, which the schema already covers through parameter names and descriptions. This meets the baseline score 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 'List products with pagination' clearly states the verb ('List') and resource ('products'), and the 'with pagination' qualifier adds specificity about the operation's behavior. However, it doesn't explicitly differentiate from sibling tools like 'vtex_search_products' or 'vtex_get_product', which might offer alternative ways to retrieve product data.
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. With siblings like 'vtex_search_products' (likely for filtered searches) and 'vtex_get_product' (likely for single product retrieval), the agent has no indication of when this paginated list is preferred over those options.
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 is 'search,' implying a read-only operation, but doesn't clarify authentication requirements, rate limits, error handling, or what 'Master Data' entails. The description is minimal and lacks critical operational 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, direct sentence with zero wasted words. It's front-loaded and efficiently conveys the core purpose without unnecessary elaboration, 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?
For a search tool with 6 parameters, no annotations, and no output schema, the description is insufficient. It doesn't explain what 'Master Data' is, how results are returned, or any behavioral traits like pagination or filtering nuances. The context signals indicate complexity that the description doesn't address.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 6 parameters. The description adds no additional parameter semantics beyond what's in the schema, such as examples for 'entity' or 'where' syntax. This meets the baseline for high schema coverage but doesn't 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 'Search documents in Master Data' clearly states the action (search) and the resource (documents in Master Data), which is specific and unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'vtex_search_products' or 'vtex_get_document', leaving some room for confusion about 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 doesn't mention when to choose this over 'vtex_get_document' (for retrieving a single document) or 'vtex_search_products' (for searching products instead of documents), nor does it specify 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 burden but only states the status change. It lacks details on permissions required, side effects (e.g., notifications), reversibility, or error conditions. 'Start handling' implies a mutation, but behavioral context 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero waste, clearly front-loaded with the tool's purpose. Every word contributes directly to understanding the 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 incomplete. It doesn't cover behavioral aspects like success/failure responses, idempotency, or integration with sibling tools, leaving gaps for agent decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 the 'orderId' parameter. The description adds no additional meaning beyond implying it's used to identify the order for status change, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Start handling') and the resource ('an order'), specifying it changes the status to 'handling'. It distinguishes from siblings like 'cancel_order' or 'invoice_order' by focusing on status transition, though it doesn't explicitly contrast with them.
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 prerequisites (e.g., order must be in a certain state), exclusions, or related tools like 'vtex_cancel_order' or 'vtex_invoice_order' for different 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?
With no annotations, the description carries full burden but only states the action without behavioral details. It doesn't disclose if this is a mutation (implied by 'unarchive'), permission requirements, side effects (e.g., reactivating promotions), or error conditions, leaving significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with just three words, front-loading the core action. There is no wasted text, making it efficient, though this brevity contributes to gaps 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?
For a mutation tool with no annotations and no output schema, the description is incomplete. It lacks details on behavior, outcomes, error handling, and relationships to sibling tools, making it insufficient for safe and effective use by an agent.
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 description has no parameter information, but schema description coverage is 100% with one well-documented parameter ('promotionId'). Since the schema fully covers the single parameter, the baseline is high, and the description doesn't need to compensate, though it adds no extra value.
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 'Unarchive a promotion' clearly states the action (unarchive) and target resource (promotion), providing basic purpose. However, it doesn't differentiate from sibling tools like 'vtex_archive_promotion' or explain what 'unarchive' means in this context, making it 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 doesn't mention prerequisites (e.g., promotion must be archived first), related tools like 'vtex_archive_promotion', or typical use cases, leaving the agent with no 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 full burden for behavioral disclosure. 'Update' implies mutation, but the description doesn't address permissions needed, whether changes are reversible, rate limits, error conditions, or what happens to fields not included in the update. This leaves significant behavioral gaps 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, efficient sentence with zero wasted words. It's appropriately sized for a basic tool description and front-loads the essential 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 no annotations and no output schema, the description is inadequate. It doesn't address behavioral aspects like permissions, side effects, or error handling. While concise, it fails to provide the contextual completeness needed for an agent to understand how to properly invoke this update 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?
With 100% schema description coverage, the schema already documents all three parameters. The description doesn't add any meaningful context beyond what the schema provides - it doesn't explain what 'entity acronym' means, how to obtain document IDs, or the structure of the 'document' object. The baseline 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.
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 ('a Master Data document'), providing a specific verb+resource combination. However, it doesn't differentiate from sibling tools like 'vtex_update_brand' or 'vtex_update_category' beyond specifying 'Master Data document' as the target resource type.
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's no mention of prerequisites (like needing an existing document ID), when not to use it, or how it differs from other update tools in the sibling list.
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 this is an update operation, implying mutation, but doesn't disclose behavioral traits like required permissions, whether changes are reversible, rate limits, or what happens to existing inventory data. For a mutation tool with zero annotation coverage, 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, efficient sentence that front-loads the core purpose. There's zero waste or redundancy, making it appropriately sized for the tool's function.
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 this is a mutation tool with no annotations and no output schema, the description is incomplete. It lacks information on behavioral aspects (e.g., permissions, side effects), usage context, and what the tool returns, which are critical 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?
Schema description coverage is 100%, so the schema already documents all four parameters (skuId, warehouseId, quantity, unlimitedQuantity) with clear descriptions. The description adds no additional parameter semantics beyond what's in the schema, but the baseline is 3 when schema coverage is high.
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'), resource ('inventory quantity'), and scope ('for a SKU in a warehouse'). It distinguishes itself from siblings like vtex_get_inventory (read vs. write) and vtex_list_inventory_by_warehouse (list vs. update), though it doesn't explicitly name these 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 on when to use this tool versus alternatives like vtex_get_inventory or vtex_list_inventory_by_warehouse. The description implies usage for setting inventory quantities but doesn't specify prerequisites, constraints, or typical 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 carries the full burden of behavioral disclosure. 'Update an existing warehouse' implies a mutation operation but doesn't specify required permissions, whether changes are reversible, rate limits, or what happens on success/failure. It lacks critical context for safe and effective use in an automated environment.
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, efficient sentence with zero wasted words. It's front-loaded with the core action ('Update') and resource ('warehouse'), making it immediately scannable 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?
For a mutation tool with no annotations and no output schema, the description is incomplete. It doesn't address behavioral aspects (permissions, side effects), usage context, or expected outcomes. Given the complexity of updating a warehouse and the lack of structured metadata, more descriptive content is needed for effective 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?
Schema description coverage is 100%, with both parameters ('warehouseId', 'name') clearly documented in the schema. The description doesn't add any meaning beyond the schema (e.g., format examples, constraints like name length). 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 'Update an existing warehouse' clearly states the verb ('Update') and resource ('warehouse'), making the purpose immediately understandable. It distinguishes from sibling tools like 'vtex_create_warehouse' (creation) and 'vtex_delete_warehouse' (deletion), though it doesn't explicitly differentiate from other update tools (e.g., 'vtex_update_product').
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 (e.g., needing an existing warehouse ID), constraints (e.g., which fields can be updated), or compare it to similar tools like 'vtex_update_dock' or 'vtex_update_inventory'. Usage is implied but not 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, so the description carries full burden for behavioral disclosure. While 'Get' implies a read operation, it doesn't specify whether this requires authentication, has rate limits, returns structured data, or has any side effects. For a tool with zero annotation coverage, this leaves significant behavioral questions unanswered.
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 zero wasted words. It's perfectly front-loaded with the core functionality and appropriately sized for this 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?
For a simple read operation with one well-documented parameter, the description is minimally adequate. However, without annotations or an output schema, it doesn't address what format the suggestions come in (e.g., JSON array, structured objects), whether there are limits, or authentication requirements. The description meets basic needs but leaves contextual 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 description doesn't add any parameter information beyond what's already in the schema. However, with 100% schema description coverage (the single parameter 'searchTerm' is fully documented in the schema), the baseline score of 3 is appropriate. The description doesn't need to compensate for schema gaps.
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 purpose: 'Get autocomplete suggestions for search'. It specifies the verb ('Get') and resource ('autocomplete suggestions'), making it immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'vtex_search_products' or 'vtex_search_documents', which prevents 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?
The description provides no guidance on when to use this tool versus alternatives. With siblings like 'vtex_search_products' and 'vtex_search_documents' available, there's no indication whether this tool is for preliminary search suggestions versus full searches, or what context triggers its 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 full burden for behavioral disclosure. 'Get client data' implies a read operation, but it doesn't specify whether this requires authentication, what happens if the email isn't found (error vs. empty response), rate limits, or the format/structure of returned data. For a tool with zero annotation coverage, this leaves significant behavioral unknowns.
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, efficient sentence with zero wasted words. It's appropriately sized for a simple lookup tool and front-loads the essential information (get client data by email). 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?
For a simple single-parameter lookup tool with no output schema, the description is minimally adequate but incomplete. It states what the tool does but lacks behavioral context (especially given no annotations), usage guidance relative to siblings, and details about the returned data. The high schema coverage helps, but overall completeness is limited.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 description mentions 'by email' which aligns with the single 'email' parameter in the schema. With 100% schema description coverage (the schema already documents 'email' as 'Client email'), the description adds minimal value beyond what the schema provides. The baseline 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get client data by email' clearly states the verb ('Get') and resource ('client data'), with the specific lookup method ('by email') providing reasonable specificity. However, it doesn't distinguish this from potential sibling tools like 'vtex_get_client_by_id' (if such existed) or explain what 'client data' encompasses compared to other get 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 provides no guidance on when to use this tool versus alternatives. With many sibling tools available (like vtex_get_order, vtex_get_product, etc.), there's no indication of whether this is the primary way to retrieve client information or if other methods exist. No prerequisites, exclusions, or comparison to similar 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?
No annotations are provided, so the description carries full burden. It states it 'gets' computed price, implying a read-only operation, but doesn't disclose behavioral traits like whether it requires authentication, has rate limits, returns real-time or cached data, or handles errors. For a tool with no annotation coverage, this leaves significant gaps in understanding how it behaves.
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, efficient sentence with zero waste. It's front-loaded with the core purpose and includes essential scope details (promotions and taxes) without unnecessary elaboration. 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?
Given no annotations and no output schema, the description is minimally adequate for a read operation but lacks completeness. It doesn't explain what the computed price includes (e.g., breakdowns), return format, or error conditions. For a tool that likely involves business logic (promotions/taxes), more context would help the agent 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?
Schema description coverage is 100%, so the schema already documents all three parameters (skuId, tradePolicy, regionId) with basic descriptions. The description adds no additional parameter semantics beyond implying the computation includes promotions and taxes, which relates to output rather than inputs. Baseline 3 is appropriate when 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 'Get' and the resource 'computed price for a SKU', with specific scope about including promotions and taxes. It distinguishes from siblings like 'vtex_get_price' (which likely returns base price) by emphasizing computed/processed pricing. However, it doesn't explicitly name the sibling alternative, keeping it at 4 rather than 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 'vtex_get_price' or 'vtex_get_sku'. It doesn't mention prerequisites, trade-offs, or specific scenarios where computed pricing is needed versus raw pricing. The agent must infer usage from the name and description 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 states 'Get dock details by ID,' implying a read-only operation, but doesn't specify if it requires authentication, rate limits, error handling, or what 'details' include. This leaves significant gaps for an AI agent to understand the tool's 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, efficient sentence with zero waste. It's front-loaded and appropriately sized for a simple tool, 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?
Given the tool's low complexity (1 parameter, no output schema, no annotations), the description is minimally adequate. However, it lacks details on return values or behavioral context, which could help an AI agent use it correctly, especially with no output schema to clarify what 'dock details' entails.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 'dockId' clearly documented as 'Dock ID.' The description adds no additional meaning beyond this, such as format examples or constraints. Since the schema does the heavy lifting, 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 ('Get') and resource ('dock details'), making the purpose understandable. However, it doesn't differentiate itself from sibling tools like 'vtex_list_docks' or 'vtex_get_warehouse', which follow similar patterns for other resources, 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?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, context, or exclusions, such as when to prefer 'vtex_list_docks' for listing all docks instead of fetching a specific one by 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 states it's a read operation ('Get'), implying it's non-destructive, but doesn't mention any behavioral traits like authentication requirements, rate limits, error conditions, or what the output includes (e.g., base price, discounts). This leaves significant gaps for an agent to understand how to use it effectively.
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's front-loaded with the core purpose, making it highly efficient and easy to parse. Every word earns its place by conveying essential information without 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 the tool's low complexity (single parameter, no output schema, no annotations), the description is minimally adequate but incomplete. It covers the basic purpose but lacks behavioral details and usage guidelines. For a simple read tool, it's passable but could be more helpful by adding context like what price data is returned or when to use alternatives.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 'skuId' fully documented in the schema. The description adds no additional semantic context beyond implying the SKU is used to fetch price information, which is already clear from the schema. This meets the baseline of 3 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get price information for a SKU' clearly states the action ('Get') and resource ('price information for a SKU'), making the purpose immediately understandable. It distinguishes from siblings like 'vtex_get_computed_price' by focusing on a specific SKU rather than computed pricing, though it doesn't explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage 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 'vtex_get_computed_price' or 'vtex_list_prices'. The description lacks context about prerequisites, such as needing a valid SKU ID, or when this tool is appropriate compared to other price-related tools in the sibling list.
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 a read operation ('Get'), implying it's likely safe and non-destructive, but doesn't disclose behavioral traits such as authentication needs, rate limits, error handling, or response format. For a tool with zero annotation coverage, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero waste—'Get product details by ID'—front-loading the core purpose. It's appropriately sized for a simple lookup tool, earning a perfect 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?
Given the tool's low complexity (single parameter, 100% schema coverage) and lack of output schema, the description is minimally adequate but incomplete. It doesn't explain return values or behavioral context, which is needed since annotations are absent. However, for a basic read operation, it's just enough to avoid a lower score, aligning with a minimum viable 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?
Schema description coverage is 100%, with the single parameter 'productId' clearly documented in the schema. The description adds no additional meaning beyond implying the parameter is used for lookup, so it meets the baseline of 3 where the schema does the heavy lifting without extra value from the description.
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 ('Get') and resource ('product details'), specifying it's by ID. It distinguishes from siblings like vtex_list_products (list all) and vtex_get_product_by_identifier (alternative lookup method), though not explicitly. However, it's not fully specific about what 'details' includes, keeping it at 4 rather than 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 on when to use this tool versus alternatives like vtex_get_product_by_identifier or vtex_search_products is provided. The description implies usage for retrieving a specific product by ID, but lacks explicit context, prerequisites, or exclusions, leaving the agent to infer from tool names 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 the full burden of behavioral disclosure. It states it's a read operation ('Get'), implying it's likely safe and non-destructive, but doesn't cover aspects like authentication requirements, rate limits, error handling, or the format of returned data. This leaves significant gaps for a tool with no 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, efficient sentence with zero wasted words. It front-loads the core action ('Get product') and directly specifies the search criteria, 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?
Given the tool's moderate complexity (2 required parameters, no output schema, and no annotations), the description is adequate but incomplete. It clearly states what the tool does but lacks usage guidelines, behavioral details, and output information, which could hinder an agent in invoking it 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 description coverage is 100%, with clear descriptions for both parameters, including an enum for 'field'. The description adds minimal value by listing the field types (ID, EAN, Reference ID, SKU), which aligns with the enum but doesn't provide additional syntax or usage details beyond what the schema already documents.
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 ('Get') and resource ('product'), and specifies the search methods ('by ID, EAN, Reference ID, or SKU'), making the purpose unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'vtex_get_product' or 'vtex_search_products', which could provide similar functionality, so it doesn't reach the highest 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?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'vtex_get_product' (which might fetch by a single ID) or 'vtex_search_products' (which might support broader queries), leaving the agent without context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states it's a 'Get' operation, implying it's likely read-only and non-destructive, but doesn't confirm this or add details like rate limits, authentication needs, or error handling. This is a significant gap for a 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, efficient sentence that directly states the tool's purpose without unnecessary words. It's front-loaded with the core action and resource, making it easy to parse quickly. Every word earns its place, achieving optimal 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?
Given the tool's low complexity (one parameter, no output schema), the description is adequate but not complete. It lacks behavioral details that would be crucial without annotations, such as what the output includes (e.g., average rating, review count) or any limitations. However, it's sufficient for a basic read operation in 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?
The input schema has 100% description coverage, with the single parameter 'productId' clearly documented. The description doesn't add any extra semantic context beyond what the schema provides (e.g., format examples or sourcing guidance), so it meets the baseline of 3 where 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 tool's purpose with a specific verb ('Get') and resource ('review summary and rating statistics for a product'), making it immediately understandable. However, it doesn't explicitly differentiate from potential sibling tools like 'vtex_get_product' or 'vtex_get_sku', which might also provide product-related information, though it's distinct enough in its focus on reviews.
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. For example, it doesn't mention if this should be used instead of other 'get' tools for product data or if there are prerequisites like needing a product ID from another source first. This leaves the agent with minimal 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 full burden. 'List all warehouses' implies a read-only operation returning multiple items, but it lacks critical behavioral details: pagination, sorting, filtering capabilities, rate limits, authentication requirements, or error conditions. For a list operation with zero annotation coverage, 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, efficient sentence with zero wasted words. It's front-loaded with the core action ('List all warehouses') and contains no unnecessary elaboration. Every word earns its place, making it maximally concise while still conveying the basic 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?
Given the tool's simplicity (0 parameters) but lack of annotations and output schema, the description is incomplete. It doesn't address behavioral aspects like pagination, return format, or error handling. For a list operation that might return large datasets, more context is needed to guide the agent effectively.
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 0 parameters with 100% description coverage, so the schema fully documents the absence of parameters. The description doesn't need to add parameter semantics, but it correctly implies no filtering parameters (just 'all warehouses'). Baseline for 0 parameters is 4, as the description aligns with the schema's emptiness.
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 'List all warehouses' clearly states the verb ('List') and resource ('warehouses'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'vtex_get_warehouse' (singular retrieval) or 'vtex_create_warehouse' (creation), which would require explicit comparison for 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?
The description provides no guidance on when to use this tool versus alternatives. With siblings like 'vtex_get_warehouse' (retrieve specific warehouse) and 'vtex_create_warehouse' (create new warehouse), the agent must infer usage from the name alone. No explicit when/when-not or alternative recommendations 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?
No annotations are provided, so the description carries full burden. 'List all brands' implies a read-only operation, but it doesn't disclose behavioral traits like pagination, rate limits, authentication requirements, sorting, or what 'all' entails (e.g., active only, includes archived). For a list operation with zero annotation coverage, this leaves significant gaps in understanding how the tool behaves.
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 'List all brands' is extremely concise—three words that directly convey the core action. It's front-loaded with no wasted words, making it easy to parse quickly. Every word earns its place by specifying the verb 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?
Given the tool's simplicity (0 parameters, no output schema, no annotations), the description is minimally adequate. It states what the tool does but lacks context about behavior, output format, or usage guidelines. For a list operation, more details on pagination or scope would improve completeness, but the basic purpose is covered.
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 0 parameters with 100% description coverage, so no parameter documentation is needed. The description doesn't add parameter details, which is appropriate. A baseline of 4 is applied since there are no parameters to document, and the description doesn't introduce unnecessary complexity.
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 'List all brands' clearly states the verb ('List') and resource ('brands'), making the purpose immediately understandable. It distinguishes from siblings like vtex_get_brand (singular retrieval) and vtex_create_brand/update_brand/delete_brand (mutations), though it doesn't explicitly mention these distinctions. The description is specific but 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?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention scenarios like retrieving all brands for browsing versus using vtex_get_brand for a specific brand, or when filtering might be needed. There's no context about prerequisites, limitations, or typical 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 carries full burden for behavioral disclosure. 'List all email templates' implies a read-only operation but doesn't specify whether it returns all templates at once (potentially overwhelming), uses pagination, requires authentication, has rate limits, or includes metadata like template IDs or names. For a list operation with zero annotation coverage, this leaves critical behavioral traits undocumented.
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, efficient sentence ('List all email templates') that front-loads the core action and resource. There's zero waste—every word contributes directly to understanding the tool's purpose without unnecessary elaboration.
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 (0 parameters, no output schema, no annotations), the description is minimally adequate. It states what the tool does but lacks context on behavioral traits (e.g., pagination, authentication) and doesn't differentiate from siblings. For a simple list tool, this is borderline viable but leaves gaps that could hinder an agent's effective use.
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 0 parameters with 100% coverage, meaning no parameters need documentation. The description doesn't add parameter details, which is appropriate here. A baseline of 4 is given since the schema fully covers the absence of parameters, and the description doesn't need to compensate for any gaps.
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 'List all email templates' clearly states the verb ('List') and resource ('email templates'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'vtex_get_email_template' (which presumably retrieves a single template) or 'vtex_create_email_template' (which creates one), leaving some ambiguity about when to use this specific list operation versus individual retrieval.
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. With siblings like 'vtex_get_email_template' (for single template retrieval) and 'vtex_search_documents' (which might include templates), there's no indication of whether this tool is for bulk listing, filtered queries, or paginated results. The agent must 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 states it's a list operation, implying read-only behavior, but doesn't cover aspects like pagination, rate limits, authentication requirements, or what data fields are returned. 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, efficient sentence with no wasted words. It's front-loaded with the core action ('List all payment providers/gateways'), 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?
For a simple list tool with no parameters and no output schema, the description is minimally adequate but lacks completeness. It doesn't explain the return format, pagination, or any behavioral constraints, which are important for an agent to use it correctly. The absence of annotations exacerbates this 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 0 parameters with 100% schema description coverage, so the schema fully documents the lack of inputs. The description adds no parameter information, which is appropriate since none exist. A baseline of 4 is applied for zero-parameter tools when the schema coverage is complete.
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 ('List') and resource ('all payment providers/gateways'), making the purpose unambiguous. It doesn't explicitly differentiate from sibling tools like 'vtex_get_payment_provider' (singular) or 'vtex_create_payment_provider', but the plural 'all' implies a comprehensive 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?
No guidance is provided on when to use this tool versus alternatives. The description doesn't mention prerequisites, filtering options, or compare it to sibling tools like 'vtex_get_payment_provider' for single provider retrieval or 'vtex_create_payment_provider' for creation.
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 lists SKUs, which implies a read-only operation, but doesn't specify whether it's paginated, rate-limited, requires authentication, or what the output format looks like (e.g., JSON list). For a tool with no annotation coverage, this leaves significant behavioral gaps, though it correctly indicates a non-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 single, efficient sentence ('List SKUs, optionally filtered by product') that is front-loaded with the core purpose and includes the key optional feature. There is no wasted language, making it highly concise and well-structured for quick comprehension.
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 (1 optional parameter, no nested objects) and high schema coverage, the description is minimally adequate. However, with no annotations and no output schema, it lacks details on behavioral aspects like pagination, authentication needs, or return format. For a list operation, this leaves gaps in completeness, though the simplicity of the tool mitigates some concerns.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 the single parameter 'productId' documented as 'Filter by Product ID.' The description adds marginal value by mentioning 'optionally filtered by product,' which aligns with the schema but doesn't provide additional syntax, format details, or examples. Given the high schema coverage, a baseline score of 3 is appropriate as the description doesn't significantly enhance parameter understanding 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 ('List SKUs') and resource ('SKUs'), with an optional filtering capability ('optionally filtered by product'). It distinguishes from siblings like 'vtex_get_sku' (singular retrieval) and 'vtex_list_products' (different resource), but doesn't explicitly contrast with other list tools like 'vtex_list_inventory_by_warehouse' which might overlap in scope. This makes it specific but not fully differentiated from all siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through the phrase 'optionally filtered by product,' suggesting it's for listing SKUs with or without product-based filtering. However, it lacks explicit guidance on when to use this versus alternatives like 'vtex_list_products' or 'vtex_get_sku_by_refid,' and doesn't mention prerequisites or exclusions. This provides some context but falls short of comprehensive 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?
No annotations are provided, so the description must fully disclose behavioral traits. It states the tool lists categories in a tree structure, which implies a read-only operation, but doesn't specify whether it's paginated, requires authentication, has rate limits, or returns errors. For a tool with zero annotation coverage, this leaves significant gaps in understanding its behavior and 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, efficient sentence that front-loads the core purpose ('List all categories') and adds necessary detail ('in a tree structure'). There is no wasted verbiage, repetition, or unnecessary elaboration, making it highly concise and well-structured for quick understanding.
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 complexity (simple list operation), no annotations, no output schema, and 0 parameters, the description is minimally adequate. It covers the basic purpose and output format but lacks details on behavioral aspects like pagination, authentication, or error handling. Without annotations or output schema, more context would improve completeness for safe agent use.
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 0 parameters with 100% coverage, meaning no parameters are documented in the schema. The description doesn't mention any parameters, which is appropriate since none exist. It adds value by specifying the output format ('tree structure'), but doesn't detail the tree's properties or depth. Baseline is 4 for 0 parameters, as there's nothing to compensate for.
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 ('List all categories') and the resource ('categories'), and specifies the output format ('in a tree structure'). It distinguishes from sibling tools like 'vtex_get_category' (singular retrieval) and 'vtex_create_category' (creation). However, it doesn't explicitly mention the scope (e.g., all categories in the system vs. filtered), which prevents 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving all categories in a hierarchical format, but provides no explicit guidance on when to use this tool versus alternatives like 'vtex_get_category' (for a single category) or 'vtex_search_documents' (for filtered searches). There's no mention of prerequisites, exclusions, or specific contexts, leaving usage inferred rather than clearly defined.
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:

[![mcp-vtex MCP server](https://glama.ai/mcp/servers/leosepulveda/mcp-vtex/badges/card.svg)](https://glama.ai/mcp/servers/leosepulveda/mcp-vtex)

Score Badge

Copy to your README.md:

[![mcp-vtex MCP server](https://glama.ai/mcp/servers/leosepulveda/mcp-vtex/badges/score.svg)](https://glama.ai/mcp/servers/leosepulveda/mcp-vtex)

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/leosepulveda/mcp-vtex'

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