Tienda Nube MCP Server

Server Quality Checklist

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

Latest release: v1.17.0
Disambiguation4/5
Most tools have distinct purposes, but there are a few potentially confusing pairs like 'list_payment_providers' and 'list_payment_providers_dedicated', and 'get_store_info' vs 'get_store_settings'. Overall, descriptions help clarify differences.
Naming Consistency4/5
Tool names follow a consistent 'tiendanube_verb_noun' pattern with snake_case. Most verbs are standard CRUD (create, get, list, update, delete), though a few use synonyms like 'apply', 'add', 'search', and 'generate', creating minor inconsistency.
Tool Count1/5
With 121 tools, the server is far beyond the typical well-scoped range. This extreme number is overwhelming for agents and suggests lack of focus, even though each tool may serve a specific endpoint.
Completeness4/5
The tool set covers most major e-commerce resources (products, orders, customers, categories, coupons, webhooks, etc.) with full CRUD operations. Some minor gaps exist (e.g., no delete product image, no update/delete for transactions) but overall it's comprehensive.
Average 3.3/5 across 116 of 121 tools scored. Lowest: 2.4/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. It does not disclose whether metafields are unique per key/namespace, what happens on duplicate keys, or side effects on the owner resource.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (13 words) but lacks structure. It reads like a title rather than a helpful description, sacrificing clarity for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 6 parameters, no output schema, no annotations, and 0% schema description coverage, the description is severely incomplete. An agent would lack critical information to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description adds no explanation for any of the 6 parameters (owner_resource, owner_id, key, value, namespace, value_type). It only vaguely mentions 'owner resource/id' without specifying allowed values or data types.
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 (metafield) and mentions the owner resource/id. It distinguishes from sibling tools like get_metafield, update_metafield, and delete_metafield, but could be more specific about what a metafield is.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps 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 custom fields (tiendanube_create_product_custom_field) or when to update vs create. No prerequisites or constraints mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only says 'delete by ID' without mentioning irreversibility, side effects, permissions, or return value. 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one short sentence, which is concise but lacks necessary detail. It earns its place but could be expanded without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a deletion tool with no output schema, the description is incomplete. It does not explain success/failure behavior, permanence, or any related constraints. The agent cannot understand the full impact.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds only 'by ID' to the parameter name, which is already implied. No explanation of what 'ID' refers to or how to obtain it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (delete) and resource (metafield) with a specific identifier (by ID). It is distinct from sibling tools like create, update, or list metafields.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, nor any prerequisites (e.g., needing to obtain the metafield ID first) or exclusions. The description is purely functional.
Agents often have multiple tools that could apply. Explicit usage guidance like "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. It only states 'retrieve' with no disclosure of side effects, permissions, or rate limits. For a read operation, this is minimal but not informative.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short but functional. It is concise but lacks structure to guide usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 2 params, no output schema, and many siblings. The description fails to provide necessary context about return values or parameter format, making it incomplete for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, and the description adds no meaning to the two parameters (location_id, fields). This fails to compensate for the lack of 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 verb 'retrieve' and resource 'single location by ID', distinguishing it from list tools. However, it doesn't explicitly differentiate from other get tools like tiendanube_get_store_info.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not indicate when to use this tool vs alternatives such as tiendanube_list_locations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must communicate behavior. It only mentions pagination support but does not disclose whether the operation is read-only, what happens with no results, or any default pagination behavior. The missing variant ID context is a significant transparency gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is concise and front-loaded. However, it could be slightly longer to include critical missing info without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool lacks an output schema and has no annotations. The description fails to explain how the variant is identified (either via a missing parameter or context), and does not describe pagination defaults or result structure. This is insufficient for a list tool with multiple siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes both parameters (per_page, page) with their ranges and meanings. The description adds no new semantic information beyond stating pagination support, so it does not compensate beyond the schema's 100% 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 states it lists product variant custom fields with pagination, but it fails to specify which variant (likely requires a variant ID that is not in the schema). This ambiguity makes it unclear how to use the tool correctly. It also does not differentiate from sibling tools like list_product_custom_fields.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., get_product_variant_custom_field for a single field, or list_product_custom_fields for product-level fields). Prerequisites such as needing a variant ID are not mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only says 'read-only.' No annotations provided, so it fails to disclose pagination behavior, rate limits, empty responses, or other side effects beyond the read-only hint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely short but at the expense of useful information. 'LIST DISCOUNTS' is redundant with the tool name. Not concise in a helpful way.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, no parameter descriptions, and minimal behavioral info, the description is far from complete. It omits key details about how to use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
0% schema coverage and description provides no explanation of the four parameters (page, per_page, fields, since_id). The agent has no clue what they mean or how to use them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves store discounts and is read-only. The verb 'list' matches the tool name and distinguishes from sibling tools like 'get_discount' (individual) and 'list_coupons' (different entity).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives (e.g., use 'get_discount' for a single discount, or 'list_coupons' for coupons). No context for filtering or pagination.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only says 'Create a new product custom field' with no behavioral context. Without annotations, the description fails to disclose any side effects, required permissions, relationships (e.g., link to specific product), or constraints. This is insufficient for a write operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, but it is too brief to be helpful. While it avoids verbosity, it lacks necessary structure (e.g., front-loading key details). It could include more context without becoming overly long.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters, no output schema, and no annotations, the description is insufficiently complete. It does not explain what a custom field is, how it relates to a product, or what happens after creation (e.g., returns the field ID). A more complete description would include at least the product association requirement.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with clear descriptions for each parameter (name, description, value_type, values). Since the schema already documents the parameters, the description adds no additional semantic value beyond the schema. 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 ('Create') and the resource ('product custom field'). While it doesn't explicitly differentiate from sibling tools like create_product_variant_custom_field, the resource name in the tool name clarifies the scope. The description is specific enough to indicate what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., create_product_variant_custom_field, update_product_custom_field). There are no conditions, prerequisites, or exclusions mentioned, leaving the agent to infer usage context 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. It states 'retrieve' implying read-only, but lacks details on output format, pagination behavior, rate limits, or whether all locations are returned. Parameters like 'fields' and 'since_id' are unexplained, leaving 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, concise but too terse. The all-caps 'LIST LOCATIONS' adds noise. It front-loads the purpose but sacrifices detail. Could be split into two sentences for clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 8 parameters, no output schema, and no annotations, the description is insufficient. It does not explain parameter interactions (e.g., pagination with date filters), expected return data, or potential limits. A complete description would address these gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for all 8 parameters. The description only vaguely references 'pagination and date filters', covering page, per_page, and date fields but omitting 'fields' and 'since_id'. This adds minimal value; the schema does not help, so the description should compensate but does not.
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 'Retrieve' and resource 'store locations', and mentions pagination and date filters, distinguishing it from sibling list tools that target different entities (orders, products, etc.). However, it does not explicitly differentiate from the singular get_location tool, though the plural 'locations' implies listing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like get_location for a specific location or other list tools. No context on prerequisites or appropriate scenarios (e.g., 'Use this to list all locations; use get_location for a single location').
Agents often have multiple tools that could apply. Explicit usage guidance like "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 fully bears the burden of behavioral disclosure. It only states 'dedicated endpoint' but omits traits like read-only nature, default pagination, or any side effects. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise, using a title-like structure and one sentence. It is front-loaded and efficient, though it sacrifices detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema or annotations, and 4 undocumented parameters, the description is incomplete. It does not explain return values, pagination behavior, or parameter usage, which are critical for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description adds no meaning to the four parameters (page, per_page, fields, since_id). The tool requires parameter explanation, which is absent.
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 'LIST PAYMENT OPTIONS' indicating a verb+resource pattern and adds 'Dedicated endpoint for payment options', which clarifies the tool's purpose. However, it does not differentiate from sibling tools like tiendanube_get_payment_option or tiendanube_list_payment_providers, lacking explicit distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., get_payment_option for single, list_payment_providers for providers). No context about pagination, filtering, or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only repeats 'LIST' and 'dedicated endpoint' without explaining pagination, rate limits, authentication requirements, or what 'dedicated' entails. The behavioral implications are unclear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (one line), which is not necessarily a sign of conciseness when it omits critical information. It could be restructured to include key details without adding length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the four optional parameters with no descriptions, no output schema, and no annotations, the description is severely incomplete. It does not equip the agent to understand the tool's inputs, outputs, or appropriate usage scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has four parameters (page, per_page, fields, since_id) with 0% description coverage in the schema. The description does not explain any of these parameters, failing to add meaning beyond the schema's raw definitions.
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 it lists payment providers ('LIST PAYMENT PROVIDERS') and indicates it's a dedicated endpoint. However, it does not differentiate from the sibling tool 'tiendanube_list_payment_providers', which likely has overlapping functionality, leading to potential confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps 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 dedicated endpoint versus the regular list or other tools. There is no mention of prerequisites, context, or exclusions, leaving the agent to guess based on the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden but only indicates a read operation. It fails to disclose any behavioral traits such as response format, the effect of the 'fields' parameter, or any authentication needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, but it lacks essential details. It is not overly verbose, but it underserves 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 lack of output schema and parameter explanations, the description is insufficient for an agent to confidently invoke the tool. Key context like response content and field behavior is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no meaning beyond the schema. The 'fields' parameter is unexplained despite being optional and likely important for controlling the response.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (GET/retrieve), the resource (payment option), and the identifier (by ID). It effectively distinguishes from sibling tools like tiendanube_list_payment_options and tiendanube_get_payment_provider.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps 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. No mention of prerequisites like needing an option_id from a list call. The agent is left without context for proper invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It only states the basic action (create draft order) without disclosing side effects, idempotency, permissions, or post-creation behavior (e.g., does it reserve inventory?).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (one sentence) but lacks structure. It is concise but does not earn its space with additional useful detail. The all-caps 'CREATE DRAFT ORDER' is redundant.
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 (10 parameters, nested objects, no output schema, no annotations), the description is minimal. It does not explain return values, required fields beyond the schema, or how it differs from the many sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds no extra meaning beyond the schema; it only generically mentions 'customer and product information'.
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 creates a 'draft order (quote)' with customer and product info. It distinguishes from siblings like tiendanube_create_order (actual order) and tiendanube_confirm_draft_order (confirm draft), but does not 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 vs alternatives (e.g., tiendanube_create_order, tiendanube_confirm_draft_order). No prerequisites or when-not-to-use information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility for behavioral disclosure. It fails to mention side effects (e.g., inventory deduction, triggering events) or whether the fulfillment order is processed immediately. It only restates the action without behavioral details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, making it concise but too brief to convey necessary context. It is well-structured but does not earn its place with additional valuable information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, no output schema, and no annotations, the description is incomplete. It does not explain the return value, validation rules, or prerequisites like order existence or fulfillment capacity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so the baseline is 3. The description adds no additional meaning beyond what the schema provides; it simply echoes 'specific line items' which is already detailed in 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 verb 'create' and the resource 'fulfillment order', specifying 'for specific line items'. This differentiates it from sibling tools like 'tiendanube_create_fulfillment_event' and 'tiendanube_get_fulfillment_order', though it could be more explicit about what constitutes 'specific line items'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as 'tiendanube_create_fulfillment_event' or 'tiendanube_update_fulfillment_order'. It lacks prerequisites (e.g., required order status) and does not mention when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only states 'Delete a business rule', without mentioning irreversibility, required permissions, or effects on related entities. This is insufficient for a destructive action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but lacks important context. It is not verbose, but could be better structured with additional details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with one required parameter and no output schema, the description should at least hint at irreversibility or impact. It fails to provide this context, making it incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'business_rule_id' is fully described in the schema (100% coverage). The description adds no additional meaning beyond what the input schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a business rule', specifying the action (delete) and the resource (business rule). It distinguishes from sibling delete tools like 'tiendanube_delete_category' by 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 on when to use this tool versus alternatives, such as when to delete a business rule versus updating or getting it. No prerequisites or side effects are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fails to disclose read-only nature, required permissions, or typical response structure. The single sentence adds no behavioral context beyond the obvious.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but omits valuable context. It could include usage hints or a note about the parameter without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description does not explain what 'details' are returned. For a simple get tool, it should at least mention the expected output or that it returns the rule object.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes the parameter (business_rule_id). The tool description adds no additional meaning beyond 'specific', which is implied. Baseline 3 given 100% 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 (Get) and resource (business rule), and 'specific' implies it operates on a single rule, differentiating it from list_business_rules. However, it lacks explicit mention of using the business_rule_id parameter.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., list_business_rules). No prerequisites or context about when it is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description does not disclose behavioral traits such as error handling, idempotency, or data format. It only states the basic function.
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, concise and front-loaded. However, it could be slightly more structured to include key details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and only one parameter, the description should explain what the response contains (e.g., discount details). It is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description does not explain what 'discount_id' is or how to obtain it, adding no value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (retrieve) and resource (discount by ID), distinguishing it from sibling 'tiendanube_list_discounts' which retrieves all discounts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'tiendanube_list_discounts' or other get tools. Missing context on prerequisites or limitations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It fails to disclose any behavioral traits such as mutability, idempotency, permissions, or side effects beyond the basic update action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but lacks substance. It is not verbose, but the brevity limits its informativeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description is incomplete. It does not explain the effect of updating, whether fields are optional, or how the custom field relates to the product.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 4 parameters have descriptions in the input schema, so schema coverage is 100%. The description adds no additional meaning beyond the schema, resulting in a baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb 'Update' and resource 'existing product custom field' clearly. However, it does not differentiate from the sibling tool 'tiendanube_update_product_custom_field_values', which could cause confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like create, delete, or the values-only update tool. No exclusions or context are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must fully disclose behavior. It states 'associate or disassociate' but does not explain whether values are replaced, appended, or removed. There is no mention of side effects, permissions, or state changes beyond a generic mutation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but extremely brief. It conveys the core purpose without any structural elements (e.g., bullet points, context). While not verbose, it could be expanded slightly without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of associating/disassociating multiple custom field values, the lack of annotations, and the absence of an output schema, the description is insufficient. It does not clarify whether the operation is additive or destructive, nor does it mention response behavior 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?
The input schema has 100% coverage with descriptions for each parameter. The description adds minimal value beyond the schema—only implying that passing empty values might disassociate, but this is not explicit. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (associate or disassociate) and the resource (custom field values with a specific product variant). It is specific enough to convey the purpose, but does not differentiate from similar sibling tools like tiendanube_update_product_variant_custom_field, which might update a single custom field value on a variant.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as tiendanube_create_product_variant_custom_field or tiendanube_delete_product_variant_custom_field. The description lacks usage context or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It fails to mention side effects, required authentication, cart existence prerequisites, or behavior when both cart_id and cart_token are provided. The description is too brief for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, concise and front-loaded with the tool name. It avoids unnecessary words but could be slightly restructured to remove 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 4 parameters, the description is inadequate. It does not explain return behavior, error cases, or validation rules (e.g., required cart identifier). The tool's role among many siblings is not clarified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and each parameter has a basic description. The tool description adds minimal value (e.g., 'by id or token' hints at cart identification but does not clarify exclusivity or precedence). Baseline of 3 is appropriate as 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: adding a variant to a cart by id or token. It is specific and distinguishes from siblings like 'remove_cart_item' and 'update_cart_item_quantity'. However, it does not explicitly mention alternatives or exclude other cart modifications.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidelines are provided. The description does not indicate when to use this tool versus other cart-related siblings such as 'tiendanube_clear_cart', 'tiendanube_apply_cart_coupon', or 'tiendanube_create_draft_order'. There is no context on prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It only states the action without disclosing side effects, reversibility, permissions, or state changes. This is insufficient for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise with no wasted words. However, it is so brief that it omits useful information, but that is more a completeness issue than conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description should provide more context about the effect of closing an order, how it differs from canceling, and whether it is reversible. The current description is too minimal.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter description 'Order ID'. The description adds no extra meaning beyond the schema, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool closes/archives an order, using specific verb and resource. However, it does not distinguish from the sibling tool 'tiendanube_cancel_order' which might have a different effect, but the inclusion of 'archive' in parentheses adds specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool vs alternatives like 'tiendanube_cancel_order' or 'tiendanube_reopen_order'. The description lacks any context about prerequisites or appropriate 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 present, so the description must carry the burden. It only implies a mutation ('Create') but does not disclose side effects, authorization needs, or whether the operation is reversible. The description adds no behavioral context beyond the obvious.
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, front-loading the purpose with 'CREATE INVOICE'. It consists of a single sentence with no wasted words, though it could be slightly more informative without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema and annotations, the description should explain what happens when the tool is called (e.g., return values, errors, state changes). It fails to provide these details, making it incomplete for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of the single parameter (order_id) with a description. The tool description does not add meaning beyond the schema, but the schema is sufficient. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create an invoice') and the target resource ('for an order'), using a specific verb+resource construction. It distinguishes from sibling tools like create_order or create_draft_order, though it lacks nuance about what the invoice entails.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, such as requiring the order to exist or be in a specific state. There are no exclusions or context cues for appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral traits. It only says 'Create' without indicating any side effects, permissions, or whether it overwrites 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?
One concise sentence with no redundant information, though it could benefit from brief usage context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 11-parameter create tool with no output schema, the description is too sparse. It omits return value, required relations (like product_id must exist), and potential errors.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description's list of example fields adds little beyond the schema. It does not introduce new constraints or format details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it creates a new product variant and lists example fields (price, stock, sku), distinguishing it from sibling tools like create_product or create_product_image.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like create_product_variant_custom_field. No prerequisites or conditions 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 provided. The description does not disclose any behavioral details such as idempotency, error handling, authorization needs, or side effects (e.g., whether it overwrites existing fields). Minimal risk disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, focused sentence with no unnecessary words. Efficiently communicates the core 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?
Despite low complexity, the description omits essential context: it does not explain that a variant ID is implicitly required (likely through tool context or a separate parameter), nor does it describe what happens on success (no output schema). The relationship to product variant custom fields is assumed.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 has 100% parameter description coverage, so baseline is 3. The description adds no additional meaning beyond the schema field descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and the resource ('new product variant custom field'), distinguishing it from product-level custom field tools (e.g., tiendanube_create_product_custom_field). It is specific but lacks contextual depth.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps 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 (e.g., update vs create, product-level vs variant-level custom fields). No prerequisites or conditions 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 full responsibility for behavioral disclosure. It fails to mention whether deletion is permanent, what happens to related data, or any required permissions. The minimal description leaves agents uninformed.
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 short (one sentence) and avoids unnecessary words. However, the upfront repetition of the tool name and method is not ideal, but it is still concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with no output schema, the description should explain the effects of deletion (e.g., permanent, return value, role in workflow). It does not provide enough context for an agent to use it safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the only parameter (draft_order_id), so the schema already explains it. The description adds no additional meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete') and resource ('draft order'), matching the tool name. However, it does not distinguish from similar sibling tools like tiendanube_cancel_order or tiendanube_close_order, which could cause confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, context, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully convey behavioral traits. It only states the generic action 'get details', without disclosing any side effects (likely none), permissions needed, rate limits, or what the returned details include. This minimal disclosure fails to inform the AI beyond the tool name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at six words, with no superfluous content. However, while efficient, it lacks necessary detail to be fully self-contained, but it is not verbose or poorly 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 simplicity of a single-parameter read operation, the description is insufficient. It does not explain what details are returned, any expected behavior (e.g., error handling), or how it integrates with other tools like tiendanube_list_disputes. The lack of output schema amplifies this gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single required parameter 'dispute_id' described as 'Dispute ID'. The description adds no additional meaning about the parameter's format, constraints, or usage beyond what the schema already provides, resulting in no extra 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 verb 'Get' and resource 'details of a specific dispute', which distinguishes it from sibling tools like tiendanube_list_disputes (list all) and tiendanube_update_dispute (modify). However, it does not explicitly say it retrieves a single dispute by ID, which would be slightly clearer.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as listing disputes first or using other get_* tools. There is no mention of prerequisites, typical use cases, or exclusions, leaving the AI without context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behaviors. It only states retrieval, omitting details like rate limits, authentication, or output structure. Minimal additional 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?
Single sentence, front-loaded with the verb, no wasted words. Highly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, no annotations, and low schema coverage, the description lacks completeness. It omits return format, parameter details, and usage context necessary for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description mentions 'by ID' hinting at provider_id but does not explain the 'fields' parameter or provide any semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Retrieve a provider by ID', specifying the action and resource. It distinguishes from sibling tools like list_payment_providers and other get_* tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as list_payment_providers or other get_* tools. No when-not or prerequisite information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It does not disclose pagination behavior, result format, authentication requirements, or idempotency. For a list operation with pagination parameters, 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no fluff. Efficient but lacks structured detail; however, for a simple description it is acceptable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so description should explain return values. It does not mention what the response contains or how pagination works. The tool's complexity is low, but the description lacks completeness for a list endpoint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter descriptions already present. The description does not add extra meaning beyond what the schema provides, so baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (list), resource (product variants), and filter (associated with a specific custom field). It is specific and distinguishable from siblings like tiendanube_get_custom_field_owners, though not explicitly differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps 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 (e.g., tiendanube_get_custom_field_owners or tiendanube_list_product_variant_custom_fields). No mention of prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as read-only nature, pagination behavior, rate limits, or any side effects. The description carries the full burden but only states basic functionality.
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, concise and to the point. It is front-loaded with the key action. However, it lacks detail that could be added without much verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without an output schema, the description should provide hints about return structure or pagination. It fails to mention that results are paginated or what the response contains. Additionally, it does not differentiate from many sibling list tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for each parameter. The description adds no extra semantic value beyond stating 'filtering options', but it does not contradict or mislead. It 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 verb 'list' and the resource 'business rules', with a hint about filtering. It distinguishes from sibling tools like 'tiendanube_get_business_rule' implicitly by using 'list' instead of 'get', but does not explicitly differentiate from other list tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 'tiendanube_get_business_rule' or other list tools. There is no mention of prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description should disclose behaviors like pagination, rate limits, or idempotency. It only states 'list all disputes' without any 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?
Single sentence, front-loaded with action and resource, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite 6 optional parameters and no output schema, the description is minimal. It does not explain pagination behavior, default values, or the structure of the response, making it incomplete for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds no extra meaning beyond what the schema already provides for each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'disputes', and mentions 'filtering options'. It distinguishes from sibling 'tiendanube_get_dispute' (get single) but does not explicitly differentiate from other list tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives like listing orders or customers. 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?
No annotations provided; description does not disclose behavioral traits such as pagination defaults, rate limits, or what happens if no filters are supplied.
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?
Two concise sentences with no unnecessary words, but could include more information in the same space without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks explanation of pagination, output format, and optional filters key/namespace, which are critical for effective use of a list tool with 6 parameters and no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and description only mentions owner_resource and owner_id; key, namespace, page, per_page are left undocumented, adding minimal value beyond parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (LIST) and resource (metafields), and distinguishes from sibling tools like tiendanube_get_metafield that retrieve a single metafield.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Only describes filtering options; no guidance on when to use this tool versus alternatives like tiendanube_get_metafield or when to apply filters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose any behavioral traits such as read-only nature, pagination, rate limits, or response format. For a list operation, this is a significant gap. The description carries the full burden, which it fails to meet.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that immediately conveys the tool's purpose. However, it could be improved with additional context without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with no output schema, the description should at least hint at what is returned (e.g., array of image objects). It fails to do so, leaving the agent unsure of the output structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, and the description does not add meaning beyond 'Product ID'. Baseline of 3 is appropriate since the schema is sufficiently clear.
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) and resource (images for a product), but does not provide explicit differentiation from sibling tools like tiendanube_get_product_image (if exists) or other list tools. It is specific enough to avoid confusion with create/update/delete image tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool vs alternatives. There is no mention of prerequisites (e.g., product existence) or exclusions. The description simply states what it does 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?
No annotations provided; description lacks details about pagination (page, per_page), filtering capabilities, or that it is a read-only operation. Does not disclose return format or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise single sentence, but may be too terse for an agent to understand pagination behavior. Still, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 9 optional parameters and no output schema or annotations, the description is too minimal. Does not explain result format, pagination, or how parameters affect the listing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all 9 parameters with descriptions; the description adds no additional meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states action (LIST/retrieve) and resource (script tags), and implies multiplicity ('all script tags'), distinguishing from singular get_script_tag sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives like get_script_tag for a single tag, nor any context about filtering or pagination.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only says 'retrieve shipping carriers', lacking details on pagination, authentication, rate limits, or default behavior. With no annotations, this is insufficient for an agent to fully 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, front-loaded sentence with no wasted words, perfectly concise for the tool's simple purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks information about pagination parameters and output format, making it incomplete for an agent to effectively use the tool, especially given no output schema or annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not mention any parameters (page, per_page, fields), providing no additional meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (list/retrieve) and resource (shipping carriers configured for the store), distinguishing it from siblings like 'tiendanube_get_shipping_carrier' and 'tiendanube_list_shipping_providers'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor any context about required conditions or limitations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It only states the action without detailing side effects (e.g., whether it changes order status, triggers notifications, or requires specific permissions).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—one sentence. It is not verbose and front-loads the purpose. However, it is essentially redundant with the tool name, which slightly reduces its value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that this is a state-changing operation with no output schema and minimal description, it lacks essential context. It does not explain what happens after the operation, error conditions, or how it relates to other order processing tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single required parameter 'order_id' already described as 'Order ID' in the schema. The description adds no additional meaning or context for the parameter, so baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Mark an order as paid' and identifies the resource (order). However, it is essentially a repetition of the tool name and does not distinguish the tool from similar sibling tools like 'close_order' or 'create_transaction'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites (e.g., order must be unpaid), or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states it updates an order, without mentioning side effects (e.g., customer notification, idempotency, or permissions). Important 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?
A single, concise sentence with no redundancy. It is appropriately front-loaded and communicates the core purpose efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 8 parameters and lack of output schema, the description is too sparse. It provides no information about return values, side effects, or constraints (e.g., valid status transitions), which are crucial for 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 coverage is 100% with clear descriptions for each parameter, so baseline is 3. The description adds no additional meaning beyond the schema, but the schema itself is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (update) and the resource (fulfillment order), distinguishing it from related tools like create and delete. However, it doesn't specify which fields can be updated, which is partially covered by the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, such as selecting different status transitions or handling prerequisites. The description is too minimal to guide 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, the description should disclose behavioral traits like side effects, permissions, or partial updates. It only states the basic action, failing to add context beyond what the name implies.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short but the first line 'UPDATE METAFIELD' is redundant with the tool name. It could be more informative without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of output schema and low schema coverage, the description does not suffice. It omits return behavior, prerequisites, and differences from sibling metafield tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage (no schema descriptions), and the description does not explain what metafield_id refers to or how to obtain it, nor does it clarify the expected values. The description adds minimal meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update'), the resource ('metafield'), and the method ('by ID'). It effectively distinguishes this tool from siblings like create_metafield and delete_metafield.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention when an update is appropriate compared to creation or deletion, nor any prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only states 'associate or disassociate' without explaining whether it replaces or updates, error behavior, or side effects. Lacks depth for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, but the phrase 'associate or disassociate' is slightly vague. Could be more direct.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description is minimal and does not cover expected behavior, return value, or error handling. Incomplete for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions, so baseline is 3. The description adds no additional meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it associates or disassociates custom field values with a product, distinguishing it from sibling tools like create_product_custom_field or update_product_custom_field. However, it could be more precise about the operation (e.g., additive vs replacement).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps 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 tiendanube_update_product_variant_custom_field_values. No prerequisites or conditions 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?
Without annotations, the description must disclose behavioral traits. It only says 'Update', implying mutation, but doesn't specify whether it replaces or merges fields, or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is easy to parse and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description should provide more context about the update behavior, but it offers minimal information beyond the action and resource.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes each parameter (e.g., 'Custom field UUID' for custom_field_id). Since schema coverage is 100%, the description adds no new meaning, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (update) and the resource (product variant custom field). However, it doesn't differentiate from the sibling 'tiendanube_update_product_variant_custom_field_values', which might cause confusion about which tool to use for updating only values.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps 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 'tiendanube_update_product_variant_custom_field_values'. It also lacks prerequisites, such as needing the custom_field_id.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and description only says 'Create' without disclosing side effects (e.g., whether events are additive, if they trigger notifications, or if duplicates are allowed). Schema enum hints at status values but no behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is concise but lacks structure or front-loading of key details. Could be improved by including prerequisite or usage context without much length increase.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 11 parameters, 4 required, no output schema, and no annotations, the description is too brief. It does not explain what happens upon creation (e.g., response), or how events interact with fulfillment lifecycle, making it incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% description coverage for all 11 parameters, so baseline is 3. Description adds no extra meaning beyond the schema; no parameter-specific details or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Create' and resource 'tracking event for a fulfillment order', distinguishing it from sibling tools like 'create_fulfillment_order' which creates the entire order.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives like 'update_fulfillment_order' or 'get_fulfillment_order'. No prerequisites mentioned, such as needing an existing fulfillment order.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden. It only states 'Retrieve' with no details on side effects, data freshness, authentication, or rate limits, which is minimally transparent for a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single short sentence with no wasted words. It is appropriately concise, though the 'GET SHIPPING CARRIER' prefix is somewhat redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks details about the return value and any usage context. For a simple get tool without output schema, more context on what the response contains would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no meaning beyond the schema. It merely restates that the carrier is retrieved by ID, which is already conveyed by the required parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description explicitly states 'Retrieve a single carrier by ID', using a specific verb and resource. It distinguishes from the sibling tool `tiendanube_list_shipping_carriers` by specifying retrieval of a single item.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not guidance is provided. The intended usage is implied by the mention of 'by ID', but alternatives like listing carriers are not mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full behavioral burden. It states 'modify' but does not disclose whether updates are partial or full, any side effects, or required permissions. Important behavioral details 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences long, which is acceptable. However, it includes some repetitive and marketing-like phrasing ('Essential for dynamic marketing strategies and campaign optimization') that could be trimmed without losing substance.
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 11 parameters and no output schema or annotations, the description should clarify that only coupon_id is required, and describe the return value or confirmation. It omits error conditions, prerequisites, and partial update behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with adequate descriptions for each parameter. The description's mention of 'discount value, validity period, usage limits, and restrictions' adds minimal grouping context but does not significantly augment the schema details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it modifies existing discount coupon settings and lists specific modifiable aspects (discount value, validity, usage limits, restrictions). The verb 'modify' and resource are clear, but it does not explicitly differentiate from sibling tools like tiendanube_create_coupon or tiendanube_delete_coupon.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides use cases like adjusting campaigns, extending validity, and changing amounts, which imply when to use. However, it does not give explicit guidance on when not to use or suggest alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description does not disclose side effects (e.g., irreversible changes, permissions needed) or any behavioral traits beyond the basic action. More transparency is needed for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with two short sentences. It is front-loaded and uses no unnecessary words, though it could benefit from additional structure (e.g., bullet points).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema and annotations, the description does not explain the effect of the action (e.g., confirmation, result) or how it differs from similar tools like tiendanube_apply_cart_coupon. Missing important context for a two-parameter mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the description adds no extra meaning beyond what the schema already provides. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'ADD' and the resource 'COUPON TO ABANDONED CHECKOUT', making the action specific and distinguishable from sibling tools like tiendanube_apply_cart_coupon or tiendanube_create_coupon.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives (e.g., when to apply coupon to checkout vs cart). No prerequisites or exclusion criteria mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only states what it does without explaining side effects (e.g., whether it overrides existing coupons), validation, or any potential destructive actions. The mutation aspect is implied but not elaborated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a single sentence that directly states the tool's purpose. It is front-loaded with the tool name in uppercase, making it immediately scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has three parameters and no output schema, the description is incomplete. It does not explain what happens upon success or failure, whether it returns a value, or any error conditions. More context is needed for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 100% with descriptions, the tool description adds no additional meaning beyond the parameter names and types. It fails to clarify the relationship between cart_id and cart_token (e.g., when to use each) and does not explain any constraints beyond what's in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: apply a discount coupon code to the cart. It uses a specific verb and resource, and effectively distinguishes from sibling tools like 'add_coupon_to_abandoned_checkout' and 'create_coupon'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as when the cart exists or when to use coupon creation tools. There is no mention of prerequisites or contexts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description bears the full burden of behavioral disclosure. It only states what the tool does, with no mention of side effects, permissions, idempotency, rate limits, or return value. This insufficient transparency fails to inform the agent about safe or expected usage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no redundancy. It is front-loaded with the core action and scope. While more structure could be beneficial for a tool with six parameters, the current conciseness is adequate and not wasteful.
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 (6 parameters, nested conditions and actions, no output schema, no annotations), the description is too minimal. It does not explain what happens after creation (e.g., rule activation, applied context), potential impacts on store operations, or how to interpret the result. The agent lacks sufficient context for informed 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%, so the baseline is 3. The description adds no additional meaning beyond the schema's parameter descriptions, which are already clear. It neither enhances nor detracts from the schema's guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and the resource ('business rule'), and specifies the scope ('for filtering products, customers, or orders'), which distinguishes it from sibling tools like update, delete, or list. The verb-resource combination is precise and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as tiendanube_update_business_rule or tiendanube_delete_business_rule. The description lacks context about prerequisites or when creation is appropriate, leaving the agent to infer 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, and the description fails to disclose behavioral traits such as whether the image replaces existing ones, authentication requirements, or idempotency. The description carries the full burden but offers minimal transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, concise sentence that is immediately informative. No redundant or unnecessary words. Efficient structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema and annotations, the description is minimally adequate. It communicates the primary purpose but lacks details on return values, prerequisites, or side effects. For a simple creation tool, it is barely sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The tool description adds no extra meaning beyond what the schema already provides, but it does not detract. Hence, score remains at baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('create/add') and resource ('image to a product'), which distinguishes it from sibling tools like list or update. However, it could be more explicit about being for an existing 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?
No guidance is given on when to use this tool versus alternatives like update_product_image or list. The agent receives no decision support for selecting between sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description does not disclose behaviors like error handling for missing invoices or return format, failing to compensate for the lack of annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no redundancy, but it could be expanded without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite low complexity, the description omits return format (e.g., PDF) and does not account for the absence of an output schema or annotations, leaving the agent guessing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single parameter 'order_id' described as 'Order ID'. Description adds no additional meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool retrieves an invoice for an order, distinguishing it from siblings like tiendanube_get_order (order details) and tiendanube_create_invoice (creation).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like tiendanube_create_invoice, nor prerequisites like the existence of an invoice.
Agents often have multiple tools that could apply. Explicit usage guidance like "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 provides a high-level action. It does not disclose what the history contains (e.g., timestamps, amounts), whether it's read-only, or any side effects. Minimal disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence is efficient and front-loaded with the tool's purpose. It earns its place, though it could be slightly expanded without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema is provided, so the description should explain return value structure or examples. It fails to do so, leaving the agent guessing about the format of 'value changes history'. Incomplete for a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% but the parameter description 'Order ID' is basic. The description adds no additional context, but the schema already documents the required parameter adequately. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get a history of an order's total value changes.' with a specific verb and resource. It distinguishes from sibling tools like tiendanube_get_order_edit_history by focusing on value changes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps 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 similar tools (e.g., get_order_edit_history) or any context for appropriate usage. Sibling tools are not mentioned, leaving the agent without decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries the burden. It discloses read operation, pagination, and date filtering, but lacks details on default sort, rate limits, permissions, or response structure. Adequate but not comprehensive.
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?
Two efficient sentences. Front-loaded with purpose, second sentence adds filter detail. Minimal waste, though the first four words repeat the tool name. Good 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?
Missing crucial details about pagination behavior (default page size, max, response structure for pagination). No output schema to compensate. For a list tool with 8 parameters and no output schema, description should explain return format and pagination mechanics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions, so baseline is 3. Description adds only 'optional date filters' which maps to date parameters; no additional meaning beyond schema. No improvement over 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?
Clearly states verb (retrieve) and resource (draft orders/quotes). Includes pagination and date filters, distinguishing it from single-resource tools like get_draft_order, but does not explicitly contrast with other list tools such as list_orders.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs. alternatives like list_orders or get_draft_order. Only mentions optional date filters, providing implicit usage context but no exclusions or conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. Only mentions pagination, but lacks details on rate limits, destructive behavior, or response format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with 7 words; efficient but could be structured better by separating purpose from feature details. Not verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema or annotations; description lacks details on response format, pagination mechanics, and authentication. Incomplete for a list tool with no structured documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear parameter descriptions. The description adds no extra meaning beyond stating 'pagination support', which is already implied by schema parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'List', the resource 'product custom fields', and includes 'pagination support', making it distinct from sibling tools like 'tiendanube_get_product_custom_field'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps 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 over others, such as when listing vs retrieving a single custom field. No alternatives or exclusions mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must carry the burden. Only states 'reopen' without disclosing side effects, permissions, or consequences (e.g., impact on inventory, payments, or whether it reverses closure).
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?
Extremely concise with two short phrases. Front-loaded capital 'REOPEN ORDER' signals purpose quickly. Minor redundancy ('REOPEN ORDER' and 'Reopen...') but no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description is too sparse. Does not explain reopening behavior, error conditions, or what the agent should expect after invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Parameter 'order_id' is fully described in schema (100% coverage). Description adds no additional meaning beyond the schema's 'Order ID'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'Reopen' and resource 'order', with explicit scope 'previously closed'. Distinguishes from sibling tools like 'close_order' and 'cancel_order'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use vs. alternatives (e.g., when an order is cancelled vs. closed). Does not mention prerequisites like order must be in closed state.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Missing annotations; description only mentions triggering an email and graceful fallback. Does not disclose side effects (e.g., state changes, idempotency, permissions required, rate limits, or error behavior beyond fallback).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with useful emoji prefix; front-loaded and clear. However, could be structured to include parameter hints or more details without increasing length significantly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema and no annotations; description should explain return value, idempotency, error behavior, and prerequisites. Only mentions graceful fallback, which is insufficient for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description does not add any meaning or context to the parameters (checkout_id, language) beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action ('Trigger recovery email') and resource ('abandoned checkout'), with additional context about API support and graceful fallback. No sibling tool sends a recovery email, so it is well-distinguished.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., adding a coupon to abandoned checkout or getting checkout info). Only mentions API support dependency but no explicit when-to-use or when-not-to-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 provided, so full burden falls on description. Description only says 'update' but doesn't disclose partial update behavior, idempotency, or side effects. Minimal transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One succinct sentence, no waste. However, it is overly minimal and could benefit from adding value without verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description should provide more context about usage, behavior, and differences from similar tools. Fails to do so, leaving the agent underinformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for each parameter. Description adds no extra context but is not needed given high coverage. Baseline 4.
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?
Clearly states it updates a business rule (verb+resource). However, it does not differentiate from tiendanube_create_business_rule or list what fields are updatable, missing opportunity to distinguish.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like create_business_rule. No mentions of prerequisites, required fields beyond the ID, or limitations.
Agents often have multiple tools that could apply. Explicit usage guidance like "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. The phrase 'Replace or set' is ambiguous—it does not clarify whether it overwrites all custom fields or merges with existing ones. The behavior regarding existing fields is not disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that is front-loaded with the purpose. It is appropriate in length, though could be slightly more informative without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, and the description does not explain the return value or error scenarios. The nested 'custom_fields' object is not explained beyond 'key-value pairs'. The behavior (replace vs merge) is unclear, leaving the agent under-informed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters documented. The description adds no additional meaning beyond the schema itself, so baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (UPDATE/Replace or set) and the resource (category custom fields). It distinguishes itself from sibling tools like tiendanube_create_category which creates a category, and tiendanube_get_category_custom_fields which retrieves existing fields.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor does it specify prerequisites or when not to use it. It simply describes the action without 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 provided, so description carries full burden. It mentions 'update' implying mutation but does not disclose idempotency, side effects, permission requirements, or behavior on invalid status transitions. Minimal transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words. However, it could be more informative without losing conciseness. Length is appropriate but content is sparse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema; description doesn't hint at return value or confirmation. Misses context about evidence structure (schema covers it) and typical user actions. For a mutation tool with optional nested parameters, 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 coverage is 100%, so baseline is 3. The description does not add extra meaning beyond the schema; it merely restates 'status' and 'evidence'. No format or constraint details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update a dispute status and provide response with evidence', specifying the verb (update), resource (dispute), and scope (status, response, evidence). It distinguishes from read-based siblings like tiendanube_get_dispute and tiendanube_list_disputes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives, prerequisites (e.g., need a dispute ID from get/list), or conditions for different statuses. The description lacks explicit use instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits, but it only says 'Replace or set,' which is ambiguous. It does not state whether the operation merges or overwrites existing custom fields, whether the input object is treated as a complete replacement, or if there are side effects (e.g., causing data loss). Important details like required permissions or rate limits are omitted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence. It is efficient and front-loaded with the purpose. However, it could be more structured by using a list or additional sentences, but it is not overly verbose. The missing title is a minor issue but not penalized heavily.
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 of order data with a nested object parameter), the description is insufficient. It does not mention the return value, error scenarios, or whether the operation is idempotent. No output schema is provided, so the description should fill that gap but does not.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents both parameters. The description adds no extra meaning to the parameters—for example, it does not clarify how the custom_fields object interacts with existing fields. Baseline 3 is appropriate since the schema carries the semantic load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'UPDATE ORDER CUSTOM FIELDS - Replace or set custom fields for an order.' It specifies the verb (update), the resource (order custom fields), and the operation (replace or set). This distinguishes it from siblings like update_order which modifies other order details, and get_order_custom_fields which is read-only.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as update_order or create_metafield. It does not mention prerequisites, typical use cases, or when not to use it. 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. It only states 'Update the URL or event' without disclosing behavioral traits like side effects, permissions requirements, or idempotency. The description is too minimal for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise with one sentence. It is front-loaded, but could benefit from a brief example or additional context without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks context about the response, prerequisites (e.g., script tag ID must exist), or what happens on success/failure. For a mutation tool among many siblings, more completeness 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 coverage is 100%, so baseline is 3. The description adds no extra meaning beyond the schema parameter descriptions; it merely restates 'URL or event' which matches src and event. It does not explain values or usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (Update) and resource (script tag), and specifies the fields that can be modified (URL or event). This distinguishes it from sibling tools like create, get, delete, and 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. It does not mention prerequisites, such as the script tag must exist, nor does it explain why an agent would choose update over create or delete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must cover behavioral traits. It only states 'cancels the fulfillment' but does not disclose side effects, reversibility, or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is efficient, but lacks structure. Could include a note on return value or preconditions without adding bulk.
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?
Simple delete operation; no output schema. Description omits return value or error conditions, but given the tool's simplicity, it is marginally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds no additional meaning beyond the parameter names and types; order_id and fulfillment_order_id are self-explanatory but lack context on how to obtain them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a fulfillment order (cancels the fulfillment)', using a specific verb and resource. It distinguishes itself from sibling tools like create_fulfillment_order and update_fulfillment_order.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, nor any prerequisites or conditions (e.g., fulfillment order state). The description lacks context for proper 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 provided, and the description only states 'Remove a script tag.' It does not disclose permanence, side effects, dependencies, or permissions required for deletion.
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 at one sentence, front-loading the action. It earns its place but could benefit from a bit more context without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with one parameter and no output schema, the description is minimally adequate. It lacks details about effects or reversibility but covers the basic function.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one parameter clearly described as 'Script tag ID'. The description adds no additional meaning beyond the schema, so baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the verb 'DELETE' and the resource 'SCRIPT TAG', and clarifies with 'Remove a script tag.' It clearly distinguishes from sibling tools like create, get, list, and update script tags.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives, no prerequisites or conditions mentioned. The description gives no context for appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits. It only states the output (template) but does not mention side effects, authorization requirements, rate limits, or any state changes. The tool likely generates an artifact without mutating resources, but this is not explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that is concise and front-loaded with the core action and deliverables. No extraneous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description should clarify what the generated template contains and how it is returned (e.g., as a string, URL, or file). It lacks this context, leaving the agent uncertain about the output format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 5 parameters have descriptions in the schema (100% coverage), so the description adds little beyond summarizing the output. The mention of 'script tag + skeleton code and guidance' loosely corresponds to the 'features' parameter but does not clarify parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: generating a Checkout SDK integration template including script tag, skeleton code, and guidance. This verb+resource combination is specific and distinguishes it from sibling tools, none of which focus on template generation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidelines are provided. The description does not indicate when to use this tool versus alternatives (e.g., tiendanube_create_script_tag for only script tag creation) or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as read-only nature, authentication requirements, or whether the response is paginated. The description only states the basic operation without additional context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently conveys the tool's purpose with no extraneous words. 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?
Given the simplicity of the tool (one parameter, no nested objects) and no output schema, the description is minimally adequate. However, it lacks information about the return format or what 'custom fields' entail, which would be helpful for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% description coverage for the single parameter 'category_id', but the tool description does not add any extra meaning beyond what the schema provides. It does not explain the nature of custom fields or any constraints on the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves all custom fields for a category, using the verb 'Retrieve' and specifying the resource 'category custom fields'. This distinguishes it from sibling tools like 'tiendanube_get_product_custom_field' which operate on different 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?
No guidance is provided on when to use this tool versus alternatives such as 'tiendanube_get_product_custom_fields' or 'tiendanube_get_order_custom_fields'. There is no mention of prerequisites or context for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Only states 'GET' and 'Retrieve', implying read-only, but does not disclose error handling, idempotency, or authentication requirements. Minimal behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise single sentence. Front-loaded with the HTTP method and purpose. No wasted words or unnecessary details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description should explain return values or at least note what data is retrieved. For a simple get-by-ID tool, some basic context (e.g., 'returns full draft order details') would improve usability. Current description is too sparse.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description adds no extra meaning beyond what's in the schema. It mentions 'by ID' but that's already specified in the required parameter. The optional 'fields' parameter is not explained further.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states action (retrieve) and resource (single draft order by ID). Distinguishes from sibling tools like tiendanube_list_draft_orders by specifying 'single' and 'by ID'. No 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 on when to use this tool versus alternatives. Does not specify when not to use or mention any prerequisites. With many related tools (list, create, delete), agents need context to choose correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only states 'Get details' but does not disclose whether the operation is read-only, any authentication requirements, rate limits, or error handling (e.g., when the fulfillment order does not exist).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that directly states the tool's purpose without unnecessary words. However, it lacks additional useful details that could be included without sacrificing 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?
For a simple get operation with full schema coverage and no output schema, the description is minimally adequate. However, given the large number of sibling tools, more context about the specific fulfillment order type or related entities would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with both parameters described as 'Order ID' and 'Fulfillment order ID'. The description adds no further meaning beyond the schema, meeting the baseline expectation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'details of a specific fulfillment order', distinguishing it from sibling tools like list_fulfillment_orders, update_fulfillment_order, and delete_fulfillment_order.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as tiendanube_get_order_fulfillment or tiendanube_get_fulfillment_event, and does not mention any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, and the description only states 'Retrieve' without disclosing behavioral traits such as read-only nature, authentication needs, rate limits, or error handling. The description provides minimal behavioral context for a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise at one sentence, with no redundant words. The 'GET METAFIELD' prefix front-loads the action. It could be slightly improved by adding brief context, but overall it is appropriately sized for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of output schema and annotations, the description lacks details about the return value, including structure or example. It also does not specify potential errors (e.g., not found). The tool is simple but the description is incomplete for an agent to fully understand the behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'metafield_id' is only defined in the input schema with type and required flag; the description does not add any additional meaning or context about the parameter, such as format or source, beyond what is obvious from the tool name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Retrieve' and the resource 'metafield', and specifies the retrieval by ID. It effectively differentiates from list_metafields and other metafield operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or alternative guidance is provided, though the context of sibling tools like create_metafield and list_metafields implies when this tool is appropriate. The description lacks direct exclusions or conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It only states 'retrieve all custom fields' without disclosing behavioral traits like authorization needs, rate limits, or return format. It's a read operation but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear line ('GET ORDER CUSTOM FIELDS - Retrieve all custom fields for a specific order.'). It is concise and well-structured, though brief.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with no output schema, the description is adequate but lacks context about what custom fields are or how they differ from metafields. It does not mention any related tools or prerequisites.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with the order_id parameter described as 'Order ID'. The description does not add any meaning beyond the schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'retrieve' and the resource 'custom fields for a specific order', distinguishing it from siblings like tiendanube_get_product_custom_field (product-specific) and tiendanube_list_product_custom_fields (list 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 vs. alternatives (e.g., getting the full order or other custom field tools). No exclusion or context given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description lacks behavioral details beyond basic read operation. No annotations are provided, so the description carries full burden, but it does not mention any constraints, permissions, or what the log entails (e.g., fields included, pagination).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with a clear front-loaded title. Every word is necessary and contributes to 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?
Without an output schema, the description should clarify the response structure but does not. 'Log of all changes' is vague; it omits details like timestamps, user, or field-level changes. The tool is simple (1 param) but incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter order_id described as 'Order ID'. The description adds no additional meaning beyond the schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a log of all changes to an order, with a specific verb 'retrieve' and resource 'log of all changes'. It distinguishes from sibling get-order tools like get_order, get_order_fulfillment, and get_order_value_history.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like get_order or get_order_transaction. There is no explicit context for 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 present, so the description carries full burden. It only states a basic retrieval action without disclosing behavior on ID not found, rate limits, or response format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and to the point. It front-loads the purpose with 'GET SCRIPT TAG' and uses a single sentence, which is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given only two parameters and no output schema, the description is minimally adequate. It misses context like the expected return object (a script tag) and any error handling 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 coverage is 100%, but the description adds no extra meaning beyond the field names and brief schema descriptions. It does not elaborate on the 'fields' parameter's usage or accepted values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Retrieve') and the resource ('a single script tag by ID'). It distinguishes from sibling tools like 'tiendanube_list_script_tags' and 'tiendanube_create_script_tag'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as 'tiendanube_list_script_tags' (for retrieving multiple tags). No context about prerequisites 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 the full burden. It only states the tool gets information without disclosing behavioral traits like authentication requirements, rate limits, or whether it's read-only. The implication of 'authenticated store' 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?
Single sentence, front-loaded with verb and resource, followed by examples. No wasted words; every part 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?
Given no output schema and no parameters, the description provides a basic idea of the return content but lacks detail on exact structure or field types. It is adequate for a simple retrieval but not fully complete for an agent to predict response format.
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?
There are zero parameters, so schema coverage is 100% trivially. The description adds value by listing example fields (name, plan, configuration, features) beyond what the empty schema conveys. Per guidelines, 0 params yields a baseline of 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves basic store info including name, plan, configuration, and features. It uses a specific verb 'Get' and resource, but doesn't explicitly distinguish from the similar sibling 'tiendanube_get_store_settings', though the focus on 'basic information' provides some 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 on when to use this tool versus alternatives. It does not specify prerequisites, context, or when not to use it, leaving the agent without clear direction for selection among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "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 discloses only basic functionality (retrieving transactions) without mentioning pagination behavior, limits, or what happens when no transactions exist. This is insufficient 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two lines) and front-loaded with purpose, but it borders on under-specification. It is concise but could include more critical details without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list operation with no output schema, the description does not explain the response format, pagination, or any ordering. An agent needs more context to interpret results correctly, especially given the lack of annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All parameters are fully described in the input schema (100% coverage), so the baseline is 3. The description adds no extra meaning beyond what the schema provides, only restating the purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Retrieve transactions for a given order' with the action verb 'retrieve' and resource 'transactions for a given order', making the purpose clear. It distinguishes from sibling list tools like 'tiendanube_list_orders' by specifying focusing on order transactions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use or avoid this tool, nor any mention of alternatives. The implied usage is clear from the name and description, but the agent is left to infer context from sibling tools without direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry behavioral disclosure. It only states the removal action, omitting side effects like whether the cart is permanently modified, any constraints (e.g., cart must not be checked out), or what happens if both IDs are provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that is front-loaded with the action and includes key detail about identifier resolution. It is concise with no unnecessary words, though it could be slightly more informative without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple removal tool with 4 parameters and no output schema, the description provides the core functionality. However, it omits return value, error conditions, and prerequisites (e.g., cart must exist). It is adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds that variant_id can be used and the system will resolve item_id when needed, providing some extra context beyond the schema. However, it lacks detail on the relationship between item_id and variant_id.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool removes an item from a cart, specifying the resource (cart item) and action (remove). It distinguishes from sibling tools like tiendanube_clear_cart (clear entire cart) and tiendanube_add_cart_item.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. It mentions removal by item_id or variant_id but does not explain when one is preferred over the other, nor does it provide context about prerequisites or when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is minimal, stating only 'Update' without disclosing behavioral traits like partial vs full update, side effects, or required permissions. No annotations are provided to compensate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded with the key action and resource. It avoids unnecessary detail but is appropriately brief.
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 or output schema, the description is adequate for a simple update but lacks details on response format or success criteria. Could be more 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%, so baseline is 3. The description adds no extra meaning beyond the schema; it simply reiterates the tool's purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Update' and the resource 'existing variant for a product', which distinguishes it from sibling tools like create, get, or list variants.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps 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 (e.g., create or get variant). No prerequisites or exclusions are mentioned, leaving the agent without context for appropriate invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "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 says 'remove all items'. It does not disclose whether applied coupons or shipping are affected, if the cart is deleted or just emptied, or any required permissions. This leaves significant behavioral uncertainty.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, using a single line that packs the purpose clearly. However, it sacrifices completeness for brevity, which prevents a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool and the lack of output schema, the description is insufficient. It does not clarify which parameter is required (both are optional in schema), nor does it explain the outcome beyond 'remove all items'. More context on idempotency or side effects would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (both parameters have descriptions in the schema). The description adds no additional meaning beyond what the schema already provides, meeting the baseline for moderate coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Remove all items from the cart', using a specific verb and resource that clearly distinguishes it from siblings like 'tiendanube_remove_cart_item' (single item removal) and 'tiendanube_add_cart_item'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for emptying the entire cart, but does not provide explicit guidance on when to use it versus alternatives like 'tiendanube_remove_cart_item' for selective removal. No exclusions or prerequisites 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 does not disclose side effects (e.g., whether creating an event updates the transaction's status), required permissions, or any irreversible actions. As a mutation tool, more behavioral disclosure is needed.
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?
A single, clear sentence with key examples. No wasted words, but could incorporate more useful information without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (7 parameters, no annotations, no output schema), the description lacks pre-conditions (e.g., transaction must exist), post-conditions, and relation to sibling tools. Examples partially compensate, but the agent may miss critical usage constraints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description adds minimal value beyond the schema. The examples in parentheses (capture, refund, void) map to the 'type' enum, which is helpful, but no additional semantic guidance is given for optional fields like 'amount' or 'info'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Create a new event for an existing transaction' with examples of event types (capture, refund, void). This distinguishes it from sibling tools like create_transaction (which creates a new transaction) and get_order_transaction (which retrieves transactions).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage requires an existing transaction by saying 'for an existing transaction', but does not explicitly state when NOT to use it or mention alternative tools like create_transaction or cancel_order. The list of event types provides some context, but guidance on appropriate selection among siblings is minimal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies a read operation but does not disclose details such as pagination behavior (though parameters exist), return format, or whether the response includes full product objects or just identifiers. Since no annotations are provided, more behavioral clarity would be beneficial.
Agents need to know what a tool does to the world before calling it. Descriptions 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 conveys the tool's purpose. Every word is necessary and the structure is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (three parameters, no nested objects, no output schema), the description minimally covers the purpose. However, it lacks information about return values, ordering, or any constraints beyond what the schema provides. For a complete understanding, more context would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all three parameters with clear descriptions, achieving 100% coverage. The description adds no additional meaning beyond what the schema provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool lists products associated with a specific custom field. However, it does not distinguish itself from sibling tools like 'tiendanube_get_product_custom_field' or 'tiendanube_get_variant_custom_field_owners', 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?
No usage guidelines are provided. The description does not indicate when to use this tool versus alternatives, nor does it specify any prerequisites or contexts where this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral transparency. It only states 'Get' (implying read-only) and 'by ID' (reflecting schema), but does not disclose any error behavior, authentication requirements, or side effects. This adds no value beyond what the schema already implies.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the action and resource. Every word is necessary and there is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with two parameters and no output schema, the description is minimally complete but lacks context about expected return format or how it differs from similar get tools like tiendanube_get_product. It does not mention any prerequisites or common usage patterns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (both parameters have descriptions in the schema). The description adds no additional meaning beyond the schema's 'Product ID' and 'Variant ID' definitions, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Get' and the resource 'specific variant of a product by ID.' It distinguishes itself from sibling tools like tiendanube_get_product or tiendanube_get_product_variant_custom_field by specifying 'variant' and 'by ID.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as tiendanube_list_product_variants for listing all variants, or when to avoid using it (e.g., if variant not found). No context or exclusion criteria are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only says 'get details', implying a read operation, but does not mention idempotency, rate limits, or any side effects. Minimal disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no unnecessary words. It is front-loaded and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool, the description is adequate. However, it does not explain what 'details' are returned (e.g., custom field value, metadata). Given no output schema, this leaves ambiguity about the response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one parameter described as 'Custom field UUID'. The description adds no additional meaning beyond 'by ID', which is already implied by the schema. Baseline 3 as schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get details'), the resource ('product variant custom field'), and the identifier ('by ID'). It effectively distinguishes from related siblings like 'tiendanube_get_product_custom_field'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps 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 listing variant custom fields or getting a product-level custom field. The description lacks context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must convey behavioral traits. It mentions supported features (multi-language, variants, etc.) but lacks details on side effects, idempotency, response format, or permissions. It does not contradict any annotations since none exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise with two sentences. The first sentence states the action and minimum requirements, and the second lists capabilities. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (26 parameters, no output schema, many siblings), the description is incomplete. It does not mention the response (likely the created product), synchronous vs asynchronous behavior, error handling, or how this relates to variant and image creation tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents each parameter's meaning. The description adds minimal extra context by grouping capabilities and restating required fields. It does not significantly enhance 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 it creates a product and mentions minimum requirements. However, it does not explicitly distinguish from sibling tools like tiendanube_create_product_variant, which could cause confusion when the agent needs to create a variant instead.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by specifying required fields (name and price) but provides no guidance on when to use this tool versus alternatives (e.g., create_product_variant for variations), nor does it mention prerequisites like category existence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description adds the behavioral detail that only provided fields are updated (partial update). However, it lacks information on side effects, permissions, rate limits, or destructive potential, which is expected for an update tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no redundant information. The description is front-loaded with the core action and includes the essential behavioral note about optional fields, making it highly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite 26 parameters and no output schema, the description is minimal. It does not explain what the tool returns, validation rules, or how to use complex fields like tags or categories. The lack of output schema description further reduces completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed parameter descriptions. The description does not add additional meaning beyond the schema, maintaining the baseline score. The statement 'All fields are optional except product_id' is already implied by the required field.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update an existing product,' which is a specific verb and resource. It distinguishes from sibling tools like create, get, or update for other entities. It also clarifies that only provided fields are updated, adding specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like tiendanube_update_product_variant or tiendanube_update_category. The description does not provide context for choosing this tool over siblings, leaving the agent without comparative information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It only states 'Update' but does not clarify if the update is partial or full replacement, whether authentication is needed, or if there are side effects. The tool's behavioral characteristics are largely undisclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. It efficiently conveys the core action and key parameters. Every part is meaningful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description is insufficient. It does not specify whether the update is partial or full, what the return value is, or any prerequisites. The tool has 5 parameters, but the description only mentions 3 and omits behavioral context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description lists the mutable properties (src, position, alt) which adds some context beyond the schema, but does not explain their meaning or usage. It does not mention the required product_id and image_id parameters, though they are in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Update' and the resource 'product image properties', listing the specific properties (src, position, alt). This distinguishes it from sibling tools like tiendanube_create_product_image (create) and tiendanube_list_product_images (list).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives. It does not mention that this tool is for modifying existing images while tiendanube_create_product_image is for adding new ones. 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It notes required fields and optional parameters but does not explain side effects, success/failure behavior, or return values. The mention of password and invitation is helpful but incomplete.
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?
Two sentences with a clear heading emoji. Information is front-loaded and focused. Could be slightly more structured but remains efficient and readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 14 parameters and no output schema or annotations, the description should cover return value, uniqueness, error conditions, and behavior more thoroughly. It omits important context like what the response contains or potential failures, leaving the agent with 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 coverage is 100%, so baseline is 3. The description adds minimal extra value, grouping parameters by type (phone, identification, addresses, etc.) and clarifying the password/invitation interaction. It does not provide new semantic details beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'CREATE NEW CUSTOMER' and details use cases like registration, manual creation, bulk imports, and system integration. It clearly distinguishes from sibling tools (update, search, get, list) by focusing on creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lists appropriate use cases but does not specify when not to use it or mention alternatives like update or search. It lacks explicit exclusions or decision heuristics.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only notes the HTTPS constraint but fails to disclose behavioral aspects such as idempotency, uniqueness, auth requirements, or side effects. For a create tool, more transparency is needed.
Agents need to know what a tool does to the world before calling it. Descriptions 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: one sentence that is front-loaded with the action 'CREATE SCRIPT TAG' and includes essential constraint. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with full schema coverage, the description is minimally adequate. However, without annotations or output schema, the agent lacks context about response format or behavior, making it slightly incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description reinforces the HTTPS constraint on 'src' but adds no new meaning beyond what the schema already provides. No additional parameter details are given.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Register a new script tag' which precisely indicates the tool's action (creation) and resource (script tag). It also adds a constraint 'HTTPS URL only', differentiating from other script tag operations like update or delete.
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 creation but does not explicitly guide when to use this tool versus siblings like update_script_tag or delete_script_tag. No when-to-use or when-not-to-use instructions 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 provided, so description carries full burden. It states the operation (retrieve) and indicates it's a GET, but does not disclose safety, idempotency, error behavior (e.g., missing checkout), or any side effects. Minimal behavioral context beyond 'retrieve'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no wasted words. Action is front-loaded. Title-like structure (GET CHECKOUT) clearly indicates HTTP method. Efficient and scannable.
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 retrieval tool with no output schema and no annotations, the description lists key return components. However, it omits details like pagination (if any), error handling, or field format. Adequate for basic use but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, both parameters have descriptions. The description adds context by listing example fields ('items, customer, totals and status') that the 'fields' parameter can include, but does not provide additional semantics or format details beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Retrieve' and resource 'checkout by ID', and lists included data (items, customer, totals, status). It distinguishes from sibling tools like tiendanube_get_abandoned_checkout by specifying it's a general checkout retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied as a basic retrieval tool, but no explicit guidance on when to use or avoid, nor mention of alternatives or prerequisites. The description does not differentiate from related tools like get_cart or get_order.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It only indicates a read operation ('Retrieve'), but fails to mention specific behavioral traits such as permissions, rate limits, or response structure. For a safe read tool, more explicit transparency is needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, using a single paragraph with a clear leading statement. It includes an emoji and bold for quick scanning. Slightly better front-loading could be achieved, but overall very efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the single parameter and no output schema, the description lists expected return fields (tracking numbers, carrier info, etc.) and use cases. It adequately covers the tool's purpose and typical data, though it could mention behavior for orders without fulfillment.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with 'order_id' having a description. The description adds no additional parameter meaning beyond the schema, so baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Retrieve' and specific resource 'detailed fulfillment and shipping information for a specific order', listing concrete data points. It distinctly separates from siblings like 'get_fulfillment_order' by focusing on order-level fulfillment.
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 'logistics management, customer support, and shipping status updates', but does not explicitly state when not to use or compare to alternatives like 'get_fulfillment_order' or 'list_fulfillment_orders'. Usage guidance is present but incomplete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It states 'Get details' which implies read-only, but lacks information about permissions, rate limits, or response structure. With no output schema, more context on what 'details' entails is necessary.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no fluff. It is concise and front-loaded, clearly communicating the core functionality.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (one parameter, no nested objects) and the lack of output schema and annotations, the description is adequate but minimal. It could be more complete by hinting at the return fields or any special behaviors.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with the parameter already described as 'Custom field UUID'. The description adds no additional meaning, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get details'), the resource ('product custom field'), and the method ('by ID'). It is specific and distinguishes from sibling tools like tiendanube_list_product_custom_fields which retrieves all custom fields.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives like tiendanube_get_product_custom_field (although there is identical behavior) or tiendanube_list_product_custom_fields. Usage is implied by the purpose but no when-not-to-use or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It mentions output fields (price, stock, SKU) but fails to disclose important behaviors such as pagination, ordering, safety (read-only nature), permissions, or any rate limits. This omits critical information for an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the action. It is concise and contains no filler, earning its place by efficiently conveying purpose and key output fields.
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 (1 parameter, no nested objects, no output schema), the description is mostly adequate but missing essential context like pagination behavior, sort order, and a comprehensive list of returned fields. For a listing tool, this incomplete information could lead to incorrect usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has a single parameter 'product_id' with a generic description 'Product ID'. The tool description does not add additional meaning beyond this; it only says 'for a given product'. Since schema description coverage is 100%, the baseline is 3, and no extra value is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all variants for a given product', specifying the verb 'list' and the resource 'variants'. It distinguishes itself from sibling tools like 'get_product_variant' (single variant retrieval) and 'list_products' (product listing). The addition of 'including price, stock and SKU' adds specific detail about the output.
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 (list all variants for a product) but provides no explicit guidance on when to use this tool versus alternatives like 'get_product_variant' or 'search_products'. There are no when-to-use or when-not-to-use statements, nor any comparative context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses key behaviors: sets status to 'cancelled' and may trigger automatic refunds based on payment status. It doesn't mention irreversibility or authorization requirements, but provides useful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with an icon and action phrase. It is clear and efficient, though it could be slightly more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with 2 parameters and no output schema, the description covers purpose, usage scenarios, and behavioral effects. However, it omits details like potential side effects (e.g., whether it can be undone) and authorization needs, leaving minor 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 coverage is 100%, so the baseline is 3. The description mentions the optional reason parameter but adds no additional meaning beyond the schema's description ('Reason for cancellation').
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 cancels an existing order, with an optional reason. It distinguishes from sibling tools like close_order and reopen_order by explicitly using 'cancel' and listing cancellation reasons, though it doesn't directly compare with similar tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides when to use the tool (e.g., customer requests, fraud, inventory issues) but lacks explicit guidance on when not to use it or mention of alternatives like close_order or update_order.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It only states the basic purpose and does not cover side effects, error handling, idempotency, or what happens if prerequisites like order existence are not met.
Agents need to know what a tool does to the world before calling it. Descriptions 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 two sentences, front-loads the action, and contains no redundant information. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 parameters, nested objects, no output schema, and no annotations, the description is too brief. It lacks context on how to properly use the nested parameters, the relationship to create_transaction_event, and what the tool returns or implies upon success.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all parameters. The description adds no additional meaning beyond what is in the schema, thus meeting the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('create'), resource ('transaction for an order'), and context ('used by payment providers to register payment attempts'), distinguishing it from read-only or other transaction-related tools like tiendanube_create_transaction_event.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies that it is used by payment providers to register payment attempts, providing clear context. However, it does not explicitly exclude other users or compare to closely related siblings such as tiendanube_create_transaction_event, leaving room for ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the ownership restriction but fails to mention success responses, error handling, or irreversibility. The single behavioral note is helpful but incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one sentence, directly stating the action and the key constraint. No unnecessary words; 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?
Given the simple one-parameter tool with no output schema or annotations, the description should cover success behavior, error cases, and ownership verification. It misses these elements, leaving the agent without sufficient context for robust invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The parameter 'custom_field_id' is described as 'Custom field UUID' in the schema. The description adds no additional meaning beyond that. Since schema coverage is 100%, the baseline is 3, and no extra context is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a product custom field' with a specific action and resource. It also adds the constraint 'only custom fields created by current app', which distinguishes it from any potential general delete and aligns with sibling tools that handle custom field CRUD operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for deleting app-created custom fields but does not explicitly state when to use it versus alternatives like getting or updating. It lacks guidance on prerequisites or error scenarios, leaving the agent to infer from sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It states the tool lists fulfillment orders but does not mention that it is a read operation, does not describe pagination behavior, or any side effects. This is insufficient for a tool with no annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence of 9 words with no waste. Every word contributes to the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 8 parameters and no output schema, the description is too brief. It does not mention that the tool returns a list, that pagination is available, or any constraints beyond the schema. It is incomplete for 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?
Schema coverage is 100%, so parameters are already documented. The description adds value by clarifying that the order_id parameter refers to 'a specific order', providing context beyond the schema's description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('fulfillment orders for a specific order'), clearly distinguishing it from sibling tools like tiendanube_get_fulfillment_order (single fulfillment order) and tiendanube_list_orders (all orders).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have an order_id, but does not explicitly state when to use this tool versus alternatives like get_fulfillment_order for a single fulfillment order. No when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, and the description does not disclose behavioral traits beyond the basic operation. It does not mention whether the operation is read-only, idempotent, or any side effects. For a list operation, this is adequate but not enriched.
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 two sentences, effectively conveying the core purpose and key features. It is concise without fluff, though it could be slightly more structured to highlight use cases or response format.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description does not explain the response format (e.g., paginated list with metadata). Given the parameter richness (22 params), the description covers the input aspect well but misses output context, leaving the agent partially uninformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all 22 parameters have descriptions. The description adds a high-level summary of filter categories but does not provide additional semantics beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all products with optional filtering, pagination, and sorting. It distinguishes from sibling tools like tiendanube_get_product (single product) and tiendanube_search_products (search-based).
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 listing products with filters but does not explicitly state when to use this tool over alternatives like tiendanube_search_products or tiendanube_get_product. No when-not or alternative tool guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden. It mentions the HTTPS requirement for security, which adds value. However, it does not disclose potential side effects (e.g., duplicate creation), auth needs, or rate limits. The behavioral transparency is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with a visual header. It is relatively concise, though the second sentence lists generalities (e.g., 'establish automated workflows') that could be tightened. Overall, it uses space efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 2 required parameters, no output schema, and no annotations, the description provides sufficient context: purpose, supported events, and a security constraint. It could mention how to manage the webhook afterward, but for a simple creation tool it is complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters have descriptions in the schema (100% coverage). The description adds a bit of context by summarizing the event types as 'major store events including orders, customers, products, and categories', but this does not significantly enhance what the schema already provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'CREATE NEW WEBHOOK' and explains it sets up real-time event notifications. It lists specific use cases (automated workflows, sync, trigger processes) and supported events (orders, customers, products, categories). This distinguishes it clearly from siblings like get_webhook or list_webhooks.
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 gives context for using the tool (real-time integrations, workflows) but does not explicitly say when not to use it or mention alternatives like update_webhook. It implies usage for initial setup but lacks exclusions or comparisons.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must stand alone. 'List' implies a read-only operation, which is assumed but not explicitly stated. No additional behavioral traits (e.g., permission needs, pagination, caching) are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. It efficiently conveys the core purpose and data source.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple parameterless list tool, the description is largely sufficient. However, without an output schema, the agent may need to infer the response structure (e.g., list of provider objects). Slightly more detail on output would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema coverage is 100%, so the description need not add parameter details. Baseline score of 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (list) and resource (payment providers configured in the store). It also mentions the data source (/store), but does not differentiate from sibling tool tiendanube_list_payment_providers_dedicated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The usage is implied by the simple listing action, but without distinguishing from the dedicated variant, context is limited.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It mentions pagination and filtering but does not disclose behavioral traits like rate limits, authentication, or response structure. It adds minimal context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words, effectively conveying the core functionality.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description does not mention the return format or any additional behavioral details like sorting or defaults. Given no output schema, this is a gap. However, it covers the basic parameter usage adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds little new meaning beyond the schema descriptions; it aligns 'text query' with query, 'pagination' with page/per_page, and 'filtering by category and publication status' with category_id and published. Language parameter is not mentioned.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches for products using a text query, with pagination and filtering by category and publication status. This distinguishes it from sibling tools like list_products (which likely lists all products) and get_product (single product).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool vs alternatives. It implies usage from the name and parameters, but does not mention exclusions or suggest alternative tools for different scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses the tool's functionality (creates coupons with various features) but omits details about side effects, error handling, or authorization requirements. Adequate but not comprehensive.
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 four sentences long and front-loaded with an emoji and imperative 'CREATE'. It is mostly concise, though the use of emoji and capitalization may be extraneous. Every sentence adds value, but minor redundancy exists.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 10 parameters and no output schema, the description covers use cases and supported features well. However, it lacks information about expected return value (e.g., created coupon object) and error scenarios. Adequate for a creation tool but could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so each parameter has a description in the schema. The tool description adds context about overall capabilities but does not enhance understanding of individual parameters beyond what the schema provides. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'CREATE' and the resource 'NEW COUPON', explicitly listing use cases like launching sales and customer retention. It distinguishes itself from sibling tools by focusing solely on coupon creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance on when to use the tool ('launching sales, customer retention, first-time buyer discounts, and seasonal promotions'), but does not explicitly mention when not to use it or alternatives. The context is sufficient for selecting this tool over non-related siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses the key constraint about app-ownership, but does not mention other behaviors such as irreversibility, required permissions, or effects on associated data. With no annotations, more detail would be helpful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no unnecessary words. Information is front-loaded and direct.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation with one parameter, the description covers the essential purpose and constraint. Missing explicit return value info, but acceptable for a deletion tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes the parameter as 'Custom field UUID' with 100% coverage. The description adds no additional meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action (delete), the resource (product variant custom field), and the scope constraint (only custom fields created by current app). Distinguishes from sibling tools like delete_product_custom_field.
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?
Implies usage for deleting custom fields owned by the app, but does not explicitly state when to use this tool versus alternatives like delete_product_custom_field. No when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only states that the tool returns 'items, totals and metadata' without discussing side effects, permissions, rate limits, or behavior when both cart_id and cart_token are provided. The nature may be inferred as read-only, but explicit 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 is a single sentence with a prominent 'GET CART' label followed by concise details. Every word is informative with no redundancy, and it front-loads the core action efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema and annotations, the description adequately covers the tool's purpose, identification methods, and return summary. It lacks specifics on required fields (none set as required) and error scenarios, but for a simple retrieval tool, it provides sufficient baseline completeness.
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?
Although schema coverage is 100%, the description adds valuable context by stating that the cart can be retrieved 'by numeric id or token', clarifying the alternative identification role of cart_id and cart_token. This goes beyond the individual parameter descriptions in the schema, aiding parameter selection.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the action ('GET CART - Retrieve') and the resource ('shopping cart') with specific identification methods ('by numeric id or token'). It differentiates from sibling tools like tiendanube_add_cart_item or tiendanube_clear_cart, clearly defining its scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving a cart, but does not explicitly contrast with alternatives like tiendanube_get_checkout or tiendanube_get_abandoned_checkout. No guidance is provided on prerequisites, error handling, or when to use this tool over others, leaving the agent to infer context from the name and siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is minimal for a tool with no annotations. It discloses that the operation is a retrieval (read-only), but does not mention error handling (e.g., if order or transaction not found), authorization requirements, or any side effects. For a simple get, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, free of fluff, and directly conveys the tool's purpose. It is appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's straightforward nature (2 parameters, no output schema, no nested objects), the description covers the essential action and inputs. However, it could be more complete by mentioning the return type (e.g., 'returns the transaction object') or error cases, but overall it is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both parameters described ('Order ID', 'Transaction ID'). The description adds no additional meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Retrieve') and the resource ('a single transaction'), and specifies the unique identification method ('by order and transaction IDs'). This distinguishes it from sibling tools like tiendanube_list_order_transactions, which retrieves multiple transactions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a specific transaction is needed, but does not explicitly state when to use this tool over alternatives (e.g., when to use tiendanube_list_order_transactions instead) or any conditions or prerequisites. No exclusion criteria 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 provided. The description does not disclose any behavioral traits beyond being a read operation. It lacks details on authorization, rate limits, or potential side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with key information, no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description mentions what is included in the response (variants, images, categories, metadata). With no output schema, this provides useful context. It lacks details on pagination, errors, or response structure but is sufficient for a simple retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all three parameters with descriptions. The description adds that the response includes variants, images, categories, and metadata, but does not add specific meaning to parameters beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves detailed product information by ID, including variants, images, categories, and metadata. It distinguishes from list and search sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage is clear from the name and description: use this when you have a product ID and need full details. However, no explicit guidance on when to use alternatives like list_products or search_products.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies reading settings but does not explicitly state it is read-only or disclose any potential side effects. Without annotations, the burden is on the description, and it falls short of 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?
Single sentence of 14 words with front-loaded purpose. Every word is informative with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the returned data categories, which is adequate for a parameterless tool. However, it lacks details on permissions, rate limits, or differentiation from similar tools, but overall reasonable.
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 no parameters, so the description cannot add parameter meaning beyond schema. However, it provides useful context about what the tool returns (languages, design, features, domains), adding value beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets extended store settings and lists specific categories (languages, design, features, domains). It includes the endpoint (/store) and implicitly differentiates from sibling 'tiendanube_get_store_info' by noting 'extended'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. With numerous sibling tools, particularly 'tiendanube_get_store_info', a usage hint or comparison would help the agent choose correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description mentions paginated and filters but omits behavioral traits like rate limits, data freshness, or read-only nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two efficient sentences: a bold title with key features and a brief use-case sentence. No wasted words, front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers main purpose and filters, but lacks explanation of pagination behavior and output format; however, given 10 params and no output schema, it is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so description adds only minor context (e.g., 'export leads') beyond the parameter descriptions already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists abandoned checkouts with pagination and filters, distinguishing it from single-get and email-send siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly mentions use cases like analyzing recovery opportunities and filtering by dates/email, but lacks when-not-to-use guidance relative to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the full burden. It states it retrieves a list with filtering but does not disclose any behavioral traits like pagination behavior, auth requirements, rate limits, or side effects (though it's a read operation). Adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise, starting with purpose in bold and emoji, followed by use cases. Every sentence adds value; no filler. Could be slightly shorter but efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 11 parameters and no output schema, the description lacks details on return format or pagination behavior. It mentions filtering and use cases but does not cover what the list response looks like or any limits. Adequate but incomplete for a comprehensive list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description mentions 'advanced filtering options' but adds no specific parameter information beyond what the schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'LIST ALL COUPONS' and specifies the resource (discount coupons) and action (retrieve comprehensive list). It lists use cases, distinguishing it from other list tools by resource type. The verb is specific and the resource is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit use cases like promotional campaign management, coupon analytics, expired coupon cleanup. It implies when to use this tool for comprehensive retrieval but does not exclude alternatives like get_coupon for single coupon retrieval. No explicit when-not or comparison to siblings, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full responsibility. It discloses pagination, filtering by dates and text search, and return content (contact info, spending totals, order history). However, it does not mention rate limits, performance expectations, or that it is a read-only operation. Adequate but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: a header with emoji and two clear sentences. It front-loads the purpose and uses simple, direct language. No redundancy or unnecessary details. Every sentence contributes essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 9 parameters and no output schema, the description adequately covers the tool's capabilities (pagination, filtering, search) and expected output fields. It provides enough context for an agent to understand how to use the tool effectively, though it could mention default pagination limits or iteration patterns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed parameter descriptions. The description adds slight value by summarizing filtering capabilities and mentioning 'identification' in search (not in schema's 'name or email') and specifying return fields. However, it mostly reiterates schema information, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Retrieve a paginated list of store customers' and specifies the resource 'customers'. It distinguishes itself from siblings like tiendanube_get_customer (single customer) and tiendanube_search_customers (search functionality) by emphasizing pagination and listing. The emoji and capitalization also aid quick recognition.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides general use cases ('customer management, analytics, segmentation, and finding specific customers') but does not explicitly contrast with sibling tools like tiendanube_get_customer (for a single customer) or tiendanube_search_customers (which might have different query capabilities). Lacks guidance on when to prefer this tool over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does not mention side effects (e.g., immediate impact on active integrations), required permissions, or what happens on invalid input. The description focuses on purpose and use cases but lacks necessary 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 concise with three sentences, front-loaded with the core purpose. Every sentence adds value: first sentence defines action, second gives specific use cases, third emphasizes importance. No fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (3 scalar params, no output schema), the description covers essential context: purpose, use cases, and what fields can be updated. However, it omits behavioral details like success/failure responses or validation, which leaves minor gaps in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes all three parameters (webhook_id, url, event) with clear descriptions and an enum for event. The description only reiterates that the tool updates 'endpoint URL and event type', adding no extra meaning beyond the schema. Schema coverage is 100%, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states this tool modifies existing webhook configuration, including endpoint URL and event type. It provides specific use cases like changing integration endpoints and updating event subscriptions, effectively distinguishing it from sibling create/get/list tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly lists when to use this tool ('changing integration endpoints, updating event subscriptions, fixing broken webhook URLs, adapting to system changes'), giving clear context. However, it does not explicitly mention when not to use it or what alternatives exist, such as creating a new webhook instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the core behavior (converting draft to order) but does not mention side effects, irreversibility, preconditions, or error handling. This is adequate for a simple action but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that immediately communicates the action. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has one parameter and no output schema, the description explains the main effect but does not cover preconditions, postconditions, or return values, leaving some gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, draft_order_id, is fully described in the schema (100% coverage). The description adds no additional semantics beyond the schema, meeting the baseline expectation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Confirm' and the resource 'draft order', and specifies the outcome 'convert it to a regular order'. This distinguishes it from siblings like create_draft_order, delete_draft_order, and get_draft_order.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates when to use this tool (to confirm a draft order) and implies it is for converting a draft. It does not explicitly state when not to use it or mention alternatives like create_order, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries the burden. It mentions pagination briefly ('paginated list') and return fields ('customer info, products, totals, fulfillment data'), but does not detail default behavior (e.g., default status filter, sorting order, rate limits). It is transparent about filtering options but lacks some behavioral specifics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with 3 sentences, front-loaded with the main action ('LIST ALL ORDERS'). It uses an emoji for visual impact. Each sentence adds value, though the structure could be tighter by separating use cases from filter list.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite 20 parameters and no output schema, the description covers the main purpose, filter capabilities, and return data. It mentions pagination and comprehensive filtering, but lacks details on default behavior or parameter interactions. It is mostly complete for a list tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description summarizes filter categories ('status, payment state, shipping status, date ranges, total values, customer IDs, text search') but does not add new meaning beyond the schema's parameter descriptions. It is adequate but not enhanced.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool is for listing orders with filtering, using specific verb 'LIST ALL ORDERS' and resource 'store orders'. It distinguishes from siblings like tiendanube_get_order and other list tools by emphasizing 'comprehensive filtering capabilities' and listing use cases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use this for order management, analytics, and finding specific orders,' which gives context. However, it does not contrast with alternatives like tiendanube_get_order for single orders or tiendanube_list_draft_orders for draft orders, missing an opportunity to guide tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states support for filtering by URL, event type, and date ranges, which adds behavioral context. However, it omits details like pagination behavior, rate limits, authentication requirements, or error scenarios.
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 an emoji, followed by use cases and filtering support. It is fairly concise but includes slightly excessive phrasing like 'Essential for maintaining API integrations.'
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich schema with 10 well-described parameters and no output schema, the description covers purpose, use cases, and filtering. It lacks explicit mention of the return structure (fields), but overall it is complete enough for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with all 10 parameters documented. The description reinforces filtering capability (URL, event type, dates) but adds no new meaning beyond the schema's own descriptions. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves all configured webhook endpoints, with a specific verb and resource. It distinguishes itself from sibling tools like create_webhook, get_webhook, update_webhook, and delete_webhook by focusing on listing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit use cases such as integration management, monitoring, debugging, and auditing. However, it does not mention when to use tiendanube_get_webhook instead for a single webhook, nor does it offer exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that the tool supports custom pricing, shipping options, payment gateway selection, and inventory management, giving the agent a good sense of its behavioral capabilities. However, it does not mention rate limits, authorization needs, or idempotency, which would be needed for a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the action with an emoji and 'CREATE NEW ORDER'. It conveys the purpose, use cases, and requirements efficiently. It could be broken into shorter sentences for readability, but it remains clear and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the high parameter count (33) and no output schema, the description covers the essential required fields and supported features. However, it lacks mention of optional parameters like shipping address fields, payment status enumeration, and what the tool returns (output). This leaves some gaps for an agent to fully understand the tool's capabilities.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (all parameters described in the schema). The description adds context by summarizing required fields (customer name/email, products, billing address) and supported features (custom pricing, shipping). However, it does not provide new details beyond what is already in the schema, meeting the baseline but not exceeding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Create' and the resource 'new order', and explicitly lists use cases such as manual order creation, bulk imports, external integrations, and processing orders from other channels. This distinguishes it from sibling tools like update_order or cancel_order, as it focuses on creation of a new order.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use scenarios (manual creation, bulk imports, etc.) and lists required inputs (customer details, product variants, billing address). However, it does not explicitly mention when not to use the tool or reference alternatives, which prevents a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It correctly indicates it is a retrieval (GET) operation and notes that omitting fields returns everything. However, it does not disclose error cases (e.g., 404 if not found), authentication needs, or rate limits. Behavior is basic but adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with a supplementary clause. Every part earns its place, and there is zero waste. It is concise yet informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by listing included components (customer, items, totals). However, it does not mention error conditions or that the response is a single object. For a simple get-by-ID tool, this is mostly sufficient but could be slightly more thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters documented. The description adds value beyond the schema by explaining special values for 'fields' ('all' or '*') and the effect of omitting it. This is a useful nuance that aids correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Retrieve' and resource 'a single abandoned checkout by ID', and specifies included sub-resources (customer, items, totals). It distinguishes itself from siblings like 'tiendanube_list_abandoned_checkouts' (list vs single) and 'tiendanube_get_checkout' (non-abandoned).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides guidance on the 'fields' parameter (omit or set to all/*) but does not explicitly state when to use this tool versus siblings. Implicitly it is for retrieving a specific abandoned checkout, but no exclusions or alternative recommendations are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description implies a read operation via 'retrieve' and lists return content, but does not explicitly state read-only nature, authorization needs, or potential limitations. Adequate for a simple get tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, effectively front-loaded with an emoji-highlighted action. Every sentence adds value: first states the action and resource, second lists use cases. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description lists returned information types (localized names, SEO, etc.), which is helpful. It covers tool purpose and parameters. Missing aspects like error handling or response format, but sufficient for this tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions. The tool description slightly enriches by referencing 'by its unique ID' for category_id and 'localized content' for language, but adds no significant new meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (retrieve) and resource (single product category by ID), and lists comprehensive details returned. It is distinct from siblings like list_categories by focusing on a single category retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies when to use the tool (comprehensive category info needed) and lists use cases (category management, SEO optimization, catalog organization). It does not explicitly mention alternatives or when not to use, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It implies read-only (GET operation) and lists the data returned, but does not mention side effects, authentication, rate limits, or other behavioral traits. The description is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a bolded action and emoji, followed by a concise purpose statement. The subsequent sentence listing use cases is slightly verbose but still efficient. Nearly excellent, with minor room for tightening.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature of the tool (get by ID, optional fields) and no output schema, the description comprehensively covers what the tool returns (discount value, type, usage stats, etc.). Usage context is well-addressed, making it fully complete for an agent's selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters have descriptions. The description adds context by listing examples of fields (e.g., discount value, type) but does not significantly enhance understanding beyond the schema. At high coverage, baseline is 3; slight added context keeps it at 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (get/retrieve) and resource (specific coupon by ID), distinguishing it from list_coupons and other siblings. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies when to use the tool (e.g., for comprehensive coupon info, management, support) but does not explicitly state when not to use it or contrast with alternatives like list_coupons. The guidance is clear but lacks exclusionary detail.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so description carries full burden. Mentions hierarchical list and return structure (tree with names, descriptions, product counts) but omits pagination, read-only nature, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise with one front-loaded sentence, an emoji, and bold formatting. Every part adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description explains return structure (tree with names, descriptions, product counts). Could mention pagination or response format but covers key 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?
Schema coverage is 100%, so baseline 3. Description adds no parameter-specific meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'LIST ALL CATEGORIES' with a specific verb and resource. Distinguishes from siblings like get_category (single) and other list tools by specifying 'categories' and 'hierarchical'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit use cases ('catalog management, navigation setup, category analytics, and organizing products'). While it lacks explicit 'when not to use' or alternatives, the context implies it's for listing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden. It indicates a read-only operation ('list') and the data source, but does not disclose any additional behavioral traits such as authorization needs, rate limits, or what happens if no providers are configured.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that conveys the purpose directly with no unnecessary words. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters, no output schema, and no annotations, the description is adequate for a simple list operation. It could be improved by clarifying the return format (e.g., provider names/details) but is sufficient for selection and invocation.
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 no parameters and schema coverage is 100% trivially. The description adds no parameter information, but none is needed. Baseline for 0 parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists available shipping providers configured in the store, specifying the source (extracted from /store). It distinguishes itself from sibling tools like tiendanube_get_shipping_carrier and tiendanube_list_shipping_carriers.
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 configured shipping providers, but provides no explicit guidance on when to use this tool versus related tools (e.g., tiendanube_get_shipping_carrier, tiendanube_list_shipping_carriers). No exclusions or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/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 discloses multi-language support, hierarchical organization, and Google Shopping integration but lacks details on permissions, reversibility, or side effects. For a creation tool, more behavioral context (e.g., whether creation is immediate or requires activation) would be beneficial.
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 mostly concise, with one main sentence plus a use-case enumeration. It is front-loaded with the emoji and bold action. While the phrases 'expanding catalog structure, organizing products, improving navigation, and setting up category-based promotions' are slightly wordy, they are functional and not excessive.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description does not need to explain return values. It covers key features: multi-language, hierarchy, Google Shopping, and use cases. However, it omits any mention of error conditions or limitations (e.g., required fields beyond name_es). Overall, it provides sufficient context for an agent to decide to use the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. The description adds value by connecting parameters to use cases: multi-language support ties to name_es/name_pt/name_en, hierarchical organization to parent_id, and Google Shopping integration to google_shopping_category. This helps the agent understand parameter relationships beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a new category with multi-language support and hierarchical organization. It uses a specific verb ('Create') and resource ('category'), and distinguishes from sibling tools like update, delete, or list categories. The mention of expanding catalog structure, organizing products, and setting up promotions adds clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool: for expanding catalog structure, organizing products, improving navigation, and setting up promotions. It implies alternatives (such as update or delete categories) but does not explicitly state when not to use it or provide direct contrasts with siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses key behaviors: permanent deletion, automatic reassignment of products to parent category or uncategorized. It does not mention authentication or rate limits, but for a deletion tool, the side effects are well-covered.
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 front-loaded with the action and a warning. It consists of three clear sentences, each adding value. The emojis aid visual scanning but may be slightly verbose. Overall it is concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (single parameter, no output schema), the description adequately covers the purpose, side effects, and usage guidance. It could mention error cases like non-existent category or subcategories, but overall it is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers all parameters (category_id with 100% description coverage). The description adds no additional meaning beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'DELETE CATEGORY - Permanently remove a product category from the store catalog.' It uses specific verbs and resource, and it is distinct from sibling tools like create_category, update_category, and list_categories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage context: 'Use this for catalog cleanup, removing obsolete categories, or restructuring product organization.' It also warns about impact on navigation and product findability, implying when to avoid using it. However, it does not explicitly mention alternative tools for non-permanent changes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool retrieves (read-only) data and lists the types of information returned. Since no annotations are provided, the description carries the burden well, though it could note that it does not modify 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 a single sentence, front-loaded with an emoji and verb. It is clear and well-structured, though slightly verbose with the list of included details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a retrieval tool with no output schema, the description adequately describes the return content (customer data, line items, etc.). It could mention pagination or response format, but it is sufficient for agent understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with each parameter described. The description does not add meaning beyond the schema; it repeats 'unique ID' for order_id and implies fields but adds no details. Baseline 3 fits.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves complete details for a single order by its unique ID. It lists specific data included, distinguishing it from sibling tools like tiendanube_list_orders (multiple orders) and tiendanube_get_order_custom_fields (specific sub-part).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (for comprehensive order info, order processing, customer service). It does not explicitly mention when not to use it or name alternatives, but the context is clear enough for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Being a GET operation, it's inherently read-only. Description lists returned info (endpoint, event type, auth, delivery status, error logs), which adds transparency beyond the absence of annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with front-loaded purpose. Second sentence is slightly verbose but packs useful details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description lists key returned fields. Covers the essential context for a retrieval tool, though lacks error handling or pagination notes.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 has 100% description coverage, so baseline is 3. Description does not add extra meaning beyond what schema already says about webhook_id and fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly specifies retrieving a single webhook by ID, and distinguishes from listing webhooks by mentioning 'specific webhook' and 'unique ID'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides guidance on when to use (for comprehensive info, troubleshooting), but does not explicitly mention when not to use or point to siblings like list_webhooks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the fallback remove+add behavior when using variant_id, but does not clarify required cart identification (cart_id or cart_token) or describe the response.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that front-load the purpose and avoid extraneous information. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core logic but omits details like how to identify the cart (though schema parameters are present) and what the tool returns, which would help an agent assess completeness given no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description adds context beyond the schema by explaining that variant_id is an alternative to item_id and that using variant_id triggers a fallback remove+add operation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (UPDATE CART ITEM QTY) and specifies the resource (line item quantity). It distinguishes from siblings like add and remove by mentioning the update mechanism and fallback behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context for use (updating quantity) and mentions the fallback behavior, but does not explicitly exclude when not to use it or suggest alternatives among sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that only provided fields are updated, preserving existing data (partial update semantics). It does not mention permissions, side effects, or return values, but the partial update detail is valuable.
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 relatively concise and front-loaded with the key action and resource. The emoji and all-caps are unnecessary but not harmful. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description covers purpose, usage context, partial update behavior. It is fairly complete for a simple update tool, though missing expected return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for each parameter. The tool description adds context about multi-language and hierarchy changes, but does not provide additional meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it modifies existing category information, including names, descriptions, and hierarchy relationships. It distinguishes itself from create_category and delete_category by explicitly mentioning 'update' and 'modify existing'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides usage context: category management, localization updates, SEO improvements, and reorganizing catalog structure. However, it does not explicitly state when not to use or mention alternatives, though siblings imply create/delete are separate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description details what the tool returns (personal details, contact info, addresses, etc.) and notes it retrieves a single customer. As annotations are absent, the description carries the burden; it implies a read-only operation but does not explicitly state that. It lacks info on error conditions or permissions, but for a simple GET this is mostly sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, using a clear header and bullet-style list of fields. It front-loads the purpose and usage, with no extraneous information. Every sentence adds value, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lists the types of data returned but does not explain the response structure or format, especially since there is no output schema. For a single-customer retrieval tool, this is largely complete, but a brief note on the response shape would enhance completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers both parameters (customer_id and fields) with 100% description coverage. The tool description does not add additional meaning or examples beyond what the schema already provides. Since schema coverage is high, a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Retrieve complete details for a single customer by their unique ID', specifying the verb and resource. Its title 'GET SPECIFIC CUSTOMER' and the mention of listing fields (personal details, contact info, addresses, etc.) distinguish it from sibling tools like tiendanube_list_customers and tiendanube_search_customers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context: 'Use this when you need comprehensive customer information... Essential for customer service, account management, and personalized marketing.' It implies when to use but does not explicitly exclude scenarios or name alternative tools for listing or searching. The context is clear but could be more directive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that updates are limited to certain fields after order creation to maintain data integrity. Lists the allowed statuses, which aligns with the enum. No annotations exist, so description carries the transparency burden well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each serving a distinct purpose: action summary, specific use cases, and limitation note. No unnecessary words, direct and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (3 parameters, no nested objects, no output schema), the description covers the main use cases and limitations. Missing mention of prerequisites like order existence, but that is implied by 'existing order'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already describes each parameter. The description adds value by grouping fields (status, owner notes) but does not provide details beyond what the schema offers (e.g., format of owner notes). Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action (modify specific fields) and resource (existing order). Enumerates the modifiable fields (status, owner notes) and differentiates from order-specific tools like cancel_order or close_order by describing the general update capability.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: updating status to open/closed/cancelled or adding owner notes. Implies limitations ('Limited to certain fields') but does not explicitly mention alternative tools like cancel_order or close_order for more specific actions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description explains that only provided fields are updated and existing data is preserved. This is good disclosure of update behavior. Does not mention permissions or side effects, but sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, followed by usage and behavior. No fluff, every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 14 parameters and no output schema, the description is sufficient for an update operation. Lacks mention of return value or error conditions, but overall adequate given the context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with descriptions. The description adds that all fields except customer_id are optional and that only provided fields will be updated, which supplements the schema. Baseline 3 raised to 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it modifies existing customer information, lists categories of updatable fields (personal details, contact, notes), and uses the verb 'Modify' with resource 'customer'. It distinguishes from create_customer and other update tools for different entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states use cases: customer profile updates, data corrections, preference changes, maintaining records. Mentions partial update behavior. Could be improved by contrasting with create_customer, but still clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description implies read-only search. It could explicitly state non-destructive nature, but the context is sufficient for an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with emoji prefix, no redundancy. Every sentence adds value: purpose, use cases, pagination, comparison to alternative.
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?
Covers purpose, usage, and pagination, but lacks details on output structure or return fields. Adequate for a search tool, but could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage, so baseline 3. Description adds value by specifying search fields (names, emails, identification numbers) and supporting pagination, enhancing schema info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool searches customers via text across names, emails, and IDs. Distinguishes from sibling tool 'tiendanube_list_customers' by highlighting fuzzy matching flexibility.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly lists use cases (quick lookup, support queries, order assignment) and contrasts with listing filters. Mentions pagination for large results, giving clear when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description fully discloses irreversibility, immediate invalidation, and impact on customers who have saved the coupon, providing essential behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with front-loaded purpose and warnings, but includes some redundancy (e.g., emojis) that could be trimmed without loss of clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation with one parameter and no output schema, the description covers purpose, irreversibility, use cases, and alternatives, making it fully actionable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already describes the parameter adequately. The description adds no extra semantics beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool permanently removes a discount coupon, using strong verbs and distinguishing it from create/update/list siblings via explicit action and warning.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (clean up expired, remove unused, terminate problematic) and advises against deletion if usage tracking is important, suggesting deactivation instead.
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:

[![nuvem-shop-mcp-server MCP server](https://glama.ai/mcp/servers/PedroHSGuimaraes/nuvem-shop-mcp-server/badges/card.svg)](https://glama.ai/mcp/servers/PedroHSGuimaraes/nuvem-shop-mcp-server)

Score Badge

Copy to your README.md:

[![nuvem-shop-mcp-server MCP server](https://glama.ai/mcp/servers/PedroHSGuimaraes/nuvem-shop-mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/PedroHSGuimaraes/nuvem-shop-mcp-server)

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/PedroHSGuimaraes/nuvem-shop-mcp-server'

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