clover-mcp

Server Quality Checklist

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

Latest release: v0.7.0
Disambiguation5/5
Each tool targets a distinct resource or action, with clear boundaries even among the many list_* tools (orders, payments, refunds, items, categories, etc.). The only potential overlap, list_open_orders versus list_orders with a state filter, is explicitly documented as a convenience wrapper.
Naming Consistency4/5
Most tools follow a consistent verb_noun pattern (list_, get_, create_, set_, update_). Minor deviations include 'whoami' (single word), 'inventory_reorder_suggestions' (noun phrase instead of verb-first), and the mix of set_item_* vs. update_item_name.
Tool Count1/5
With 56 tools, the server far exceeds the threshold for an appropriate count. Even for a broad POS integration, 50+ tools is an extreme mismatch and will overwhelm agents with too many options.
Completeness2/5
The server provides extensive read-only reporting and some inventory/customer writes, but it lacks critical lifecycle operations: no payment capture/refund/void, no update/delete for orders or inventory items, and no order closing. Creates exist for orders and items but no way to complete or remove them, leaving obvious dead ends.
Average 4.4/5 across 56 of 56 tools scored. Lowest: 3.6/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 93 commits in the last 12 weeks
- Last stable release on July 2, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
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

Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the description adds value by disclosing additional behavioral traits: it needs a sampling-capable client with a graceful fallback, and it requires specific permissions (INVENTORY_R and ORDERS_R). It also notes the 'AI' nature, implying non-deterministic output. These go beyond what annotations alone provide.
Agents need to know what a tool does to the world before calling it. Descriptions 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—three short lines—each conveying distinct information: the core purpose, read-only nature, client requirement, and permissions. No filler or redundancy; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core purpose, key requirements, and a behavioral quirk, and the presence of an output schema addresses return values. However, it lacks parameter semantics and explicit usage guidance, which is a notable gap for a tool with optional parameters and no schema descriptions. It is adequate for selection but not fully complete for invocation.
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?
The input schema has three parameters (date_to, date_from, threshold) with zero description coverage, and the description does not explain any of them. It mentions 'low-stock items crossed with sales velocity' but does not relate this to the threshold or date range parameters, leaving the agent without sufficient information to set them correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 produces a 'prioritized reorder list' combining low-stock items with sales velocity, which is specific and distinguishes it from siblings like list_low_stock_items. The 'Read-only suggestion' wording reinforces its function as an advisory tool rather than a direct action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context (reorder suggestions) and provides important constraints such as 'Needs a sampling-capable client' and 'Requires INVENTORY_R and ORDERS_R', but it does not explicitly state when to use this tool versus alternatives or when to avoid it. No exclusions or alternative tools are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the bar is lower. The description adds meaningful behavioral context: default to today UTC, 90-day chunking, each line item counting as one unit, and the ORDERS_R permission requirement. This goes beyond the annotations and helps the agent understand side effects and constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, front-loaded with the primary purpose, and every subsequent sentence adds value (defaults, chunking, unit definition, permission). There is no fluff or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and read-only annotations, the description adequately covers the main behavioral aspects: what the tool returns, default date window, chunking behavior, unit semantics, and required permission. The only minor gap is the ambiguous meaning of '90-day chunked' and lack of date format details, but these are not critical given the 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 description coverage is 0%, so the description must compensate for the three undocumented parameters. It only vaguely mentions 'date window' and default today, and does not explain the date format, inclusivity, or the meaning/constraints of top_n beyond its name. This is insufficient for an agent to confidently construct valid arguments.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 ('Return') with a clear resource ('best-selling items') and unique scope ('in a date window, ranked by units sold'). It clearly differentiates from sibling tools like get_sales_summary or list_orders by focusing on best-seller ranking.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool should be used when best-selling items in a date window are needed, and it provides context like defaulting to today and requiring ORDERS_R. However, it does not explicitly state when not to use it or name alternative tools for similar analytics needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the description's additional note that PINs are never returned adds meaningful privacy behavior beyond structured metadata. This is a useful disclosure not present in annotations, earning a score above baseline.
Agents need to know what a tool does to the world before calling it. Descriptions 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 (two sentences, ~11 words), front-loaded with the core action, and every phrase earns its place. No redundant information or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (2 optional params, no nested objects), the output schema exists to define return values, and annotations cover safety, the description provides the additional needed context (permission requirement, PIN redaction). It is sufficient for a simple listing tool, though it could mention pagination behavior more explicitly.
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%, and the description does not explain the 'limit' and 'offset' parameters beyond the word 'page'. While parameter names and defaults are somewhat self-explanatory, the description fails to compensate for the lack of schema-level documentation, leaving semantics only partially inferable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Return a page of employees') and resource ('employees'), with a unique constraint ('PINs never returned') that distinguishes it from other employee-related tools like get_employee. This fully satisfies the purpose clarity requirement.
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 paginated employee listing and provides a permission prerequisite ('Requires EMPLOYEES_R'), but it does not explicitly state when to use this tool versus alternatives such as get_employee for single records or list_shifts for related data. Usage context is implied rather than explicitly specified.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey read-only and open-world behavior. The description adds the permission requirement (Requires INVENTORY_R), which is useful context beyond annotations. However, it does not describe any additional behavioral traits such as return format or potential side effects, making it 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 extremely concise, consisting of exactly two sentences with no redundant or filler content. The primary purpose is front-loaded, and the permission note is a necessary addition. Every word earns its place.
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 zero-parameter, read-only list tool with an output schema and readOnlyHint/openWorldHint annotations, the description is sufficiently complete. It states what it returns, explains what the tags are, and notes the required permission. No further details are necessary for an agent to use this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema is entirely empty. Per the rules, a zero-parameter tool warrants a baseline of 4 because the description does not need to explain parameter semantics. The description adds no param details, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Return the merchant's tags/labels used to group items.' It uses a specific verb ('Return') and resource ('tags/labels'), and the qualifier 'used to group items' distinguishes it from other list tools like list_categories or list_item_groups.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps 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 a permission requirement (Requires INVENTORY_R) but does not explicitly state when to use this tool or mention alternatives. With numerous sibling list tools, the lack of usage guidance or exclusions makes it unclear when to choose this over others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and openWorldHint. The description adds the EMPLOYEES_R permission requirement and the critical behavior that omitting employee_id aggregates shifts across all employees, going beyond the annotation baseline.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with information front-loaded. Each sentence adds value: the core action, optional filters, permission requirement, and aggregation behavior. There is 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?
For a simple list tool with three optional parameters and an output schema, the description covers essential behavior and a key aggregation caveat. It lacks date format details and sibling differentiation, but is sufficient for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It maps 'by employee and/or date window' to employee_id, date_from, and date_to, but does not define date formats or inclusivity, leaving some ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'List shifts,' providing a specific verb and resource. It further specifies optional filtering by employee and date window, and the sibling tool list_active_shifts makes it clear this covers all shifts, not just active ones.
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 contexts with 'Requires EMPLOYEES_R' and the aggregation note, but it does not explicitly compare with alternatives like list_active_shifts. The when-to-use is inferred rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond the readOnlyHint annotation, such as the need for a sampling-capable client with graceful fallback and specific permission requirements. It does not contradict 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 concise and well-structured: the first sentence states the purpose, and the second sentence covers prerequisites and constraints. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists and annotations provide read-only safety, the description covers the essential context: purpose, prerequisites, and fallback behavior. Minor gaps like date format are not critical with an output schema present.
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 description mentions a 'window' with 'default: today' but does not explain the meaning or format of 'date_from' and 'date_to'. With 0% schema description coverage, the description should compensate, but it leaves parameter semantics ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 function: to flag unusual refund/discount/sales patterns within a time window. It uses a specific verb 'flag' and resource 'patterns', differentiating it from sibling tools that list or summarize data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it is a read-only analysis tool requiring specific permissions (PAYMENTS_R and ORDERS_R) and a sampling-capable client. This helps an agent understand when to invoke it, though it doesn't explicitly name alternative tools for similar tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and openWorldHint, so the description only adds the MERCHANT_R permission requirement. It does not disclose other behavioral traits such as side effects, rate limits, or data scope beyond what annotations cover.
Agents need to know what a tool does to the world before calling it. Descriptions 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 ('Return') and includes essential permission information. Every word earns its place.
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?
The tool is simple with no parameters and has an output schema (which should document return structure). The description adequately covers purpose and permission, making it complete for this low-complexity tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline of 4 applies. There is no parameter information needed in the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Return' and the specific resource 'merchant's default service charge configuration' with the fields (name, enabled, percentage). This distinguishes it from siblings, as no other service charge tool exists.
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 includes a prerequisite (Requires MERCHANT_R) but does not explicitly state when to use this tool versus alternatives. There are no exclusions or alternative tool references, so usage is only implied by the purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, but the description adds value by disclosing that PINs are never returned and that a specific permission (EMPLOYEES_R) is required. This goes beyond the annotations and is consistent with them.
Agents need to know what a tool does to the world before 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, each carrying essential information: the core purpose and two key constraints (PINs and permission). No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with one parameter, an output schema, and read-only/open-world annotations, the description covers the essentials: what it does, the input, a data privacy guarantee, and access requirements. It does not describe error behavior, but that is not critical given the tool's simplicity and the presence of an 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 description coverage is 0%, so the description must compensate for the undocumented employee_id parameter. It does not: the description merely says 'by ID', which adds nothing over the schema's property name and type. The parameter name is somewhat self-explanatory, but the description fails to provide format, source, or examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the specific action (return), the resource (a single employee), and the method (by ID). It clearly distinguishes from list_employees (which returns multiple employees) and get_sales_by_employee/get_tips_by_employee (which return related data rather than the employee record itself).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when you have an employee_id and need a single employee, and it explicitly states the required permission (EMPLOYEES_R). However, it does not name alternatives or explicitly say 'instead of list_employees', though the singular context makes the intended usage 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?
Annotations already declare readOnlyHint=true, and the description adds valuable behavioral context: required permissions (PAYMENTS_R, EMPLOYEES_R) and the degradation to IDs-only with a note. This goes beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before 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: the first states the core function, the second covers permission requirements. Perfectly front-loaded with no filler.
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 tool with two optional parameters and an output schema, the description covers the essential aspects: purpose, default behavior, and permission needs. It is complete enough for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds meaning with 'date window' and 'default: today', clarifying that nulls mean today. However, it does not specify date format or inclusive/exclusive boundaries, leaving some ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 ('Return'), names the resource ('gross sales'), specifies the grouping ('by employee'), and defines a date window. It is clearly distinct from sibling tools like get_sales_summary and get_sales_by_hour.
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 purpose implies when to use this tool, but there is no explicit comparison to alternatives such as get_sales_summary or get_tips_by_employee. The default 'today' provides contextual guidance for parameter omission, but no exclusions or when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds the permission requirement 'INVENTORY_R' and the 'all' scope, which provides some context beyond annotations. However, it does not disclose details like pagination, ordering, or handling of empty results, which could be relevant.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, each adding value: what the tool does and what permission is needed. There is no fluff or repetition. It is front-loaded with the core purpose and highly efficient.
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 tool's simplicity (no parameters), the presence of a readOnlyHint and openWorldHint, and an output schema, the description is complete. The permission requirement is a crucial operational detail. No additional behavioral explanation is necessary for this straightforward list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the description need not explain parameter semantics. The schema covers everything with 100% coverage (vacuously). Baseline for 0 params is 4, and the description adds no unnecessary parameter information, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Return all inventory categories.' The verb 'return' and resource 'inventory categories' are specific and unambiguous. The permission requirement 'Requires INVENTORY_R' further clarifies the scope. This distinguishes it from sibling list tools like list_tags or list_attributes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: when you need inventory categories, use this tool. However, it provides no explicit guidance on when to use this versus alternatives, nor does it mention any exclusion scenarios. The permission requirement is a prerequisite, not usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description reinforces this with 'Suggestion only'. It adds useful behavioral context beyond the annotations, including the sampling-capable client requirement and graceful fallback behavior, plus the INVENTORY_R permission. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the core purpose. Each subsequent line adds valuable information: the suggestion-only nature, client requirements, and permissions. No wasted words 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 moderate complexity, the description covers the essential aspects: purpose, distinction from writes, client capability, and permission. The output schema is present, so return values don't need elaboration. The only minor gap is a slightly vague explanation of the graceful fallback, but overall it's sufficiently complete.
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 0% description coverage, and the description does not mention the 'limit' parameter at all. While the parameter is simple (optional integer with default 100), the description fails to compensate for the lack of schema-level explanation, leaving the effect of 'limit' ambiguous (e.g., number of suggestions, sample size).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 function: suggest categories for uncategorized items using the merchant's own taxonomy. It uses a specific verb and resource, and distinguishes itself from siblings like list_categories and create_category by emphasizing that it only suggests and does not apply.
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 clear context: it's for suggesting categories, not applying them (which is a separate write). It also notes requirements like needing a sampling-capable client and INVENTORY_R permission. However, it doesn't explicitly name alternative tools to use when the client lacks sampling capability or when applying categories, so it's not a full exclusionary guide.
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?
The description goes well beyond annotations, disclosing duplicate guard (case-insensitive), dry_run preview behavior, confirmation via MCP elicitation or confirm=True, and required permission. This gives the agent a solid sense of side effects and prerequisites.
Agents need to know what a tool does to the world before 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 concise sentences: the first states purpose, the second and third cover behavioral safeguards and permissions. No redundant wording or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description, combined with the input schema and annotations, is fully adequate for a simple tool. It covers purpose, parameters, side effects, and prerequisites, and the output schema handles return values.
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?
With 0% schema description coverage, the description compensates well: it explains name (tag name with duplicate check), dry_run (preview), and confirm (confirmation). It doesn't explicitly name the parameters, but the semantics are clear from context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create a new tag/label') and its purpose ('used to group items'), distinguishing it from sibling tools like list_tags and create_category. The opening 'Modifies merchant data' is somewhat generic but quickly clarified.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: use to create a tag. It mentions the required permission (INVENTORY_W) and behavior like dry_run and confirm, but does not explicitly contrast with alternatives or state 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate a read-only operation, and the description adds value by disclosing timezone fallback behavior (merchant's local timezone, falling back to UTC with a note) and the permission requirement (PAYMENTS_R). This goes beyond the annotations and helps the agent understand operational nuances.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded, using exactly two sentences to cover the core purpose, default behavior, timezone handling, and permission. There is no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, an output schema exists, and annotations cover safety, the description is largely complete. It covers the default date, timezone behavior, and required permission. Minor gaps remain regarding date format and what exactly constitutes 'gross sales', but these are not blockers for invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero description coverage for the single 'date' parameter. The description implies it is a date and defaults to today, but does not specify the expected format (e.g., YYYY-MM-DD). It provides partial semantics but leaves ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 returns gross sales bucketed by local hour-of-day for a single day, with a default of today. This distinguishes it from siblings like get_sales_summary or get_sales_by_employee by focusing on hourly granularity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it is for a single day, defaults to today, and uses the merchant's local timezone. However, it does not explicitly mention alternatives or when-not-to-use this tool, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and openWorldHint=true. The description adds valuable behavior beyond annotations: it discloses permission requirements (PAYMENTS_R for basic, EMPLOYEES_R for name enrichment), degradation behavior to IDs-only with a note, and the default date scope. This is more than the annotations alone provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary purpose, and includes permission notes in a compact manner. Every sentence earns its place, and the structure is 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 tool's simplicity (2 optional params, no nested objects) and presence of output schema, the description covers the key context: purpose, default behavior, permission requirements, and degradation mode. It does not describe return format, but the output schema likely handles that. Slight gap: no explicit statement about what the emp-name note looks like, but overall 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 0%, so the description must compensate. It explains the date range concept ('default: today') but does not detail the date_from/date_to parameters format or semantics beyond the schema's names and types. The schema itself is minimal (two nullable strings), so the description adds some value but not enough to fully clarify parameter behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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: returning a tip-out sheet with tips grouped by employee, defaulting to today. It uses a specific verb ('return') and names the resource ('tip-out sheet', 'grouped by employee'), which distinguishes it from sibling tools like get_sales_by_employee or list_tip_suggestions.
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 indicates when to use (default today, optional date range) and implies a read-only reporting context. It does not explicitly mention alternatives or exclusions, but the clarity of the resource and the presence of sibling tools like get_sales_by_employee provide context. Lacks explicit 'use when... vs. otherwise' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint. The description adds valuable context: the INVENTORY_R permission requirement and the constraint that the 'fields' parameter can only narrow (not widen) the response. This goes beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact at four sentences, front-loads the primary action, and avoids filler or repetition. Every sentence contributes meaning.
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?
As a read-only list endpoint with an output schema, the description adequately covers permission and filtering behavior. It could mention sorting or default ordering, but those are likely evident from the schema/output, making this sufficient.
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?
With no schema descriptions (0% coverage), the description explains the non-obvious parameters: query, category_id, and fields (including the narrowing behavior). Limit and offset are left to standard pagination semantics, which is acceptable given their self-explanatory 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 tool returns a page of inventory items and supports filtering by name or category. This specific verb+resource combination distinguishes it from sibling list tools like list_low_stock_items or get_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 the tool is for paginated, filtered listing of inventory items but does not explicitly explain when to use it over alternatives such as list_low_stock_items or get_item. It provides no exclusions or alternative tool names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and openWorldHint annotations, the description adds substantial context: it specifies that cards are never returned, requires the CUSTOMERS_R permission, and clarifies the fields parameter's narrowing behavior. These are valuable behavioral details not captured by the annotations or 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 three sentences, front-loaded with the core purpose, and includes essential behavioral notes without any fluff. Every sentence adds value, and the structure is easy to scan.
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 search tool with an output schema and good annotations, the description covers the key aspects: search keys, a permission requirement, a critical exclusion (cards), and field projection. It lacks explicit details on limit behavior and how criteria combine, but overall is sufficiently comprehensive for an agent to invoke it effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains the semantics of query (full name), phone, email, and fields (including the allowlist constraint), which is meaningful given zero schema description coverage. However, the limit parameter is not described, and the relationship between multiple search criteria (AND vs OR) is ambiguous, keeping it from a perfect score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 customers by full name, phone, or email, which is a specific verb and resource. It also differentiates from siblings like get_customer by emphasizing it is a search operation rather than a single-record fetch.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is provided on when to use this tool versus alternatives such as get_customer, which might be used when a customer ID is already known. The description explains the search criteria but does not offer contextual recommendations or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and openWorldHint, and the description reinforces read-only. It goes beyond annotations by specifying which fields are expanded (lineItems and payments) and that customer card data is never expanded, plus the 404 error behavior if the order ID is missing. These are valuable behavioral details not captured in structured metadata.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, front-loaded with the core purpose, and every sentence adds value: purpose, expansion behavior, and error handling. No fluff or redundancy beyond the read-only statement that echoes the annotation.
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?
The tool is simple (1 parameter, no nested objects) and has an output schema, so the description does not need to explain return values. It covers the key aspects: what is returned, what is excluded, and error behavior. Combined with annotations, this is fully sufficient for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema lists order_id as a required string but has 0% description coverage. The description mentions 'order_id' in the 404 sentence, implying it is the unique identifier, but it does not provide a dedicated parameter explanation. Since the parameter name is self-explanatory and the description references it, it provides mild compensation but not exhaustive clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches a single order by ID, with specific detail on expanded fields (line items and payment summary). This distinctively separates it from sibling tools like list_orders and list_open_orders, which list multiple orders.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys clear context: use this for fetching a single order's details. It explicitly notes that customer card data is never expanded, providing a limitation that guides when not to use it. However, it does not name alternative tools for retrieving card data or modifying orders, so it stops short of explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation is consistent with the 'Return' wording, and the description adds the INVENTORY_R authorization requirement, which is not visible in the annotations. It also clarifies that the result includes 'options' (the attribute's possible values), adding 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?
Two sentences with no filler; the purpose is front-loaded in the first sentence, and the permission note is a compact second sentence.
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 read-only, parameterless tool with output schema and annotations, the description covers purpose, permission, and return content sufficiently. No additional details are needed for correct 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, so the description does not need to explain parameter syntax. The baseline for a zero-parameter tool is 4, and the description adds relevant context about the return content.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Return' and names the resource 'item attributes', with concrete examples (variant axes like Size/Color). This clearly distinguishes it from sibling list tools like list_items or list_categories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear permission requirement (INVENTORY_R) but does not specify when to choose this tool over alternatives, nor does it mention any exclusions. Usage is implied (when needing attribute axes), but there is no explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral details beyond the readOnlyHint and openWorldHint annotations by specifying the result cap (`limit`, default 50, max 500) and the permission requirement (MERCHANT_R). It also qualifies the result as 'recent', setting expectations about the time scope. These are meaningful additions that help the agent 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 two sentences with no filler. The first sentence fronts the purpose and the second adds constraints and permission. Every word earns its place, making it appropriately concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists and the tool has a single simple parameter, the description covers the essential elements: what it returns, the parameter behavior, the permission, and the read-only nature. The only minor gaps are the lack of a precise definition for 'recent' (time window) and no mention of ordering, but for this simple list tool it is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has only one parameter, `limit`, with no description (0% coverage). The description explains the parameter clearly by stating 'Capped at `limit` (default 50, max 500)', fully compensating for the schema's lack of detail. Since `limit` is the only parameter, the description provides complete 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 states 'Return recent cash-drawer events' with a specific verb and resource, and enumerates event types (paid in/out, no-sale, deposits). This clearly distinguishes it from sibling list tools like list_payments or list_refunds, which focus on different transaction types.
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 clear context for when to use this tool (when querying cash-drawer events), but it does not explicitly mention alternatives or state when not to use it. The 'Requires MERCHANT_R' line is a permission note, not a usage guideline. Thus, usage is implied rather than explicitly differentiated from siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only and open-world hints. The description adds the specific permission requirement (INVENTORY_R) and the content types, providing useful context beyond the 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 one concise sentence that front-loads the purpose and adds the permission requirement. No wasted words.
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 tool's simplicity (no parameters), existing output schema, and annotations covering safety, the description adequately covers the needed information: return type, permission, and discount types.
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, so the baseline is 4. The description does not need to elaborate on parameters, and it adds no conflicting information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the merchant's discount catalogue, specifying the resource and action. It also clarifies the types (fixed-amount or percentage), distinguishing it from other list_* siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly compare with alternatives, but it does state a required permission (INVENTORY_R), which is a precondition. Usage timing is implied: when the discount catalogue is needed.
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?
Beyond the readOnlyHint and openWorldHint annotations, the description discloses that untracked-stock items are excluded and that INVENTORY_R permission is required. This adds useful behavioral context without contradicting the 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?
Two concise sentences deliver the core purpose, exclusion rule, and permission requirement without redundancy. The information is front-loaded and every sentence adds value.
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 read-only list tool with one optional parameter and an output schema, the description covers scope, inclusion threshold, untracked-item exclusion, and required permission. It is complete for the tool's complexity.
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 schema has a single threshold parameter with zero description coverage, but the description defines its meaning: items whose stock is 'at or below threshold' are returned. This gives the agent sufficient understanding to set or omit 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 action: 'Return all items whose stock quantity is at or below threshold.' It also adds a scope qualifier ('Items with no stock tracking are excluded') that distinguishes it from general list_items or inventory 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 intended use is implied by the low-stock semantics, but there is no explicit when-to-use guidance or mention of alternatives such as inventory_reorder_suggestions. It does not explain when this tool should be preferred over other inventory-related 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?
Beyond the readOnlyHint and openWorldHint annotations, the description adds an auth requirement (MERCHANT_R) and hints at non-exhaustive results with an ellipsis. This supplements the annotations without contradicting them, though it does not provide additional behavioral details like rate limits or 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, front-loaded sentence that efficiently conveys the action, resource, examples, and permission requirement. There is no waste or repetition, making it highly concise.
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 tool with no parameters, a clear output schema, and a simple read operation, the description is fully sufficient. It covers what is returned, gives examples, and notes the required permission, leaving no critical gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description does not need to elaborate on parameter semantics, and the schema confirms an empty object with 100% coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific action ('Return the merchant's order types') and provides concrete examples (Dine In, Take Out), leaving no ambiguity. It is easily distinguished from sibling tools like list_orders or list_open_orders, as it targets a distinct resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a permission prerequisite (Requires MERCHANT_R) but does not explicitly state when to use this tool over alternatives, such as list_orders or list_categories. Usage can be inferred from the clear purpose, but no explicit guidance or exclusions are provided.
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?
Even though readOnlyHint=true exists, the description reinforces read-only behavior and adds unique context: 'Customer card data is never included' and the field narrowing constraint 'cannot widen past the allowlist'. This goes beyond the annotation and informs the agent of privacy and response-shaping 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 three sentences, front-loaded with the primary purpose, and each sentence adds necessary detail. No filler 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?
The description covers main behavior, defaults, safety, and field selection. An output schema exists, so return values need no explanation. Minor gaps include date format and a more explicit mention of how limit behaves, but overall the tool is well described for its complexity.
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?
With 0% schema description coverage, the description compensates by explaining the state parameter with its enum values, the fields parameter's narrowing behavior, and the concept of a date window. It partially explains limit via 'limit 50' and mentions date_from/date_to generically, but does not specify formats or full limit 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 opens with a specific verb and resource: 'List orders' and clarifies the scope with 'optional date window and/or state filter'. It distinguishes itself from sibling tools like list_open_orders by covering all states ('omit for all states') and from get_order by being a list operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context on defaults (today, limit 50) and filters, but it does not explicitly state when to use this tool over siblings like list_open_orders or when not to use it. The usage is implied rather than stated with exclusions.
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?
Annotations already mark readOnlyHint; the description reinforces this with 'Read-only suggestion' and adds substantial context: the internal process (gathers data, then calls model), fallback to raw data with a note, and required permissions ORDERS_R/PAYMENTS_R. These details go well beyond the 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?
Two short, front-loaded paragraphs. The first sentence clearly states the tool's core purpose, and each subsequent sentence adds unique value: process, fallback, and permissions. 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?
An output schema exists and annotations cover safety, so the description need not explain returns. It covers process, fallback behavior, permissions, and date default. The only notable omission is date format, but overall it is complete for a moderately complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has two optional date parameters with 0% description coverage. The description says 'date window (default: today)', which maps to date_from/date_to, but it does not specify the expected format or whether the range is inclusive. It provides basic meaning but leaves gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool produces a 'plain-language sales briefing' and explains it gathers 'sales summary + top items' then asks the client's model to write a narrative. This clearly distinguishes it from raw-data siblings like get_sales_summary and get_top_items.
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 first line implies use when a plain-language briefing is needed, and the fallback note explains behavior if the client can't sample. However, it does not explicitly name alternative tools or state 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds significant detail beyond annotations: explains the optimistic lock mechanism, dry_run previews the POST body and never writes, and lists required permissions (INVENTORY_R and INVENTORY_W). No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with three focused sentences, no fluff, and front-loads the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 parameters, it covers most aspects well (lock, bounds, dry_run, permissions) and output schema exists, so return values need not be explained. But the missing 'confirm' parameter leaves a small completeness 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 0%, so description must compensate. It explains expected_current_name, new_name bounds, and dry_run behavior, and implies item_id. However, it does not mention the 'confirm' parameter, which is a notable gap for a 5-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 'rename' and the resource 'inventory item', with an explicit note that other fields are preserved. This distinguishes it from sibling tools like set_item_price_cents or set_item_stock_quantity.
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 clear context including optimistic locking, bounds, dry_run behavior, and required permissions, but does not explicitly name alternatives or state when not to use this tool. The guidance is implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses important behavior beyond annotations: it requires confirmation before writing (dry_run previews, confirm=True or MCP elicitation needed), it modifies merchant data, and it requires ORDERS_W permission. This adds significant context on side effects and authorization.
Agents need to know what a tool does to the world before calling it. Descriptions 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 each sentence contributing essential info: purpose, scope, safety behavior, follow-up tool, and permission. It's front-loaded with the primary purpose and uses clear formatting.
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?
Despite having only 3 parameters and no required ones, the description covers the tool's purpose, creation scope, dry-run/confirm behavior, related tool, and permission requirement. The output schema exists, so return values don't need to be explained. This is complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains dry_run and confirm parameters (preview vs. write with confirmation), but the 'note' parameter is not described at all. Given the schema has 0% coverage, the description partially compensates but leaves one parameter ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 'Create a new open order' with the specific scope of no line items and no payment, distinguishing it from siblings like add_line_item. The verb+resource is explicit and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear guidance on how to use the tool: dry_run for preview, confirm via MCP elicitation or confirm=True, and explicitly directs users to add_line_item for adding items. It doesn't explicitly state when not to use it, but the context strongly implies this is only for creating bare orders.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description explicitly explains key behaviors: it never sends anything, requires a sampling-capable client with graceful fallback, and needs the CUSTOMERS_R permission. This adds substantial context that annotations alone do not convey, including permission and runtime requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only three sentences, front-loaded with the primary action, followed by essential caveats. Every sentence adds value with no repetition or fluff, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple two-parameter schema and existing output schema, the description covers all major aspects: purpose, side-effect safety, technical requirements, and permissions. It is complete enough for an agent to correctly select and invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides only names and types with zero descriptions. The description partially compensates by explaining that 'intent' refers to the type of message (promo/win-back/thank-you), but it does not explicitly clarify 'customer_id' or confirm the allowed values for intent. Since schema coverage is 0%, the description should do more, but it does add some meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb ('draft') and resource ('customer message'), and lists the intents (promo, win-back, thank-you). It is unambiguous and distinguishes itself from all sibling tools, none of which deal with message drafting.
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 the tool: when a draft for a specific customer intent is needed. It also clarifies that it only returns a draft and never sends, setting expectations. However, it does not explicitly mention alternative tools or exclusions, though no alternative exists among 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?
Annotations already declare readOnlyHint and openWorldHint, which signal a safe read operation. The description adds valuable behavioral context beyond annotations: 'Cards are never returned' and 'Requires CUSTOMERS_R', which inform the agent about data exclusion and permission requirements. This is a meaningful addition beyond the structured metadata.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences of minimal length, front-loaded with the primary purpose, and every sentence adds specific information: purpose, parameter usage, and constraints. No wasted words.
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 two-parameter get-by-ID tool with an output schema present, the description covers the purpose, parameter usage, data exclusions, and authorization requirement. It is sufficiently complete for an agent to correctly select and invoke the tool without needing additional clarification.
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 descriptions for either parameter (0% coverage), so the description must compensate. It clarifies customer_id's purpose implicitly via the tool's purpose, and explicitly explains include with concrete examples ('include=["addresses"] or include=["orders"]') and the concept of opting into optional fields. This adds useful meaning beyond the raw 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 opens with 'Return a single customer by ID,' a specific verb+resource+scope statement that clearly distinguishes this from list/search tools. It unambiguously identifies the operation and the key identifier.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use the tool: when you have a customer ID and want a single customer. It also gives usage details like the include parameter for optional fields and the required CUSTOMERS_R permission, but it does not explicitly name alternative tools or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is clear. The description adds valuable behavioral context by disclosing the cache-priming side effect, which is a non-obvious consequence of calling this tool. It does not go into potential errors or response details, but the cache note goes beyond mere annotation reiteration.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary purpose, and every word adds value: the first sentence states the action and scope, the second lists returned fields, and the third (part of the same sentence) explains the cache-priming behavior. No fluff or repetition.
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 zero-parameter read-only tool with an output schema present, the description covers everything needed: what the tool does, what information is included, and an important behavioral note (cache priming). The output schema handles return-value details, so the description is appropriately scoped and 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?
The tool has zero parameters, so the schema leaves nothing to explain. Per the rubric, a baseline of 4 is appropriate when no parameters exist; the description correctly avoids inventing parameter-like details and instead focuses on what data is returned.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb ('Return') and a clear resource ('key information about this Clover merchant'), then enumerates the exact fields (name, address, currency, timezone, country, business type). This clearly distinguishes it from sibling tools like get_merchant_properties and whoami by focusing on a compact set of key merchant details.
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 conveys when to use the tool by noting it 'primes the internal currency and timezone cache used by all other tools,' implying it should be called early in a session to enable correct formatting in subsequent operations. It does not explicitly mention alternatives or exclusions, but for a zero-parameter getter that is sufficient context.
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?
Annotations already declare readOnlyHint=true and openWorldHint=true, and the description adds meaningful behavioral context: it discloses the required permission (MERCHANT_R) and guarantees that banking/account fields are never returned. This goes beyond the structured annotations and clarifies the tool's data access boundaries.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences, front-loaded with the main purpose, followed by a key exclusion and a requirement. No wasted words.
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 tool has no parameters, an output schema exists, and annotations are present, the description sufficiently covers scope, exclusions, and auth requirements. It is complete for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema is trivially complete. The baseline for 0 params is 4, and the description adds no parameter-specific meaning (none needed).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Return the merchant's POS configuration' and enumerates specific fields (currency, tips, stock tracking, closeout, locale, support contacts). It also distinguishes itself by explicitly excluding banking/account fields, which differentiates it from potentially similar tools like get_merchant_info.
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 useful context (returns POS configuration, never banking fields, requires MERCHANT_R) but does not explicitly state when to use this tool over alternatives or when not to use it. The usage is implied rather than directly guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses detailed behavioral rules: it counts only SUCCESS payments, reports voids/refunds separately, breaks out tips/taxes, flags offline payments, uses merchant currency, defaults to today UTC, and chunks 90-day windows with progress logs. This is rich, non-obvious behavior that annotations alone wouldn't convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and information-dense: a one-sentence purpose, a sentence on defaults and chunking, and a sentence of rules/exclusions. Every sentence adds value with no redundancy or marketing language.
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 tool with two optional parameters, rich annotations, and an output schema, the description covers the essential behaviors: what is counted, how breakdowns work, long-range handling, and what it cannot do. The output schema handles return types, and the description adds operational context like progress logs and timezone defaults, making it complete enough for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description partially compensates by explaining the date window concept and the default of today when no dates are supplied. However, it does not specify the date format, inclusivity, or handling when only one date is provided, leaving some ambiguity for the two optional date parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Return' with the resource 'aggregated sales summary' and a date window scope, clearly distinguishing it from sibling tools like list_payments (raw list) and summarize_sales (likely a different summary). It also states exclusions, removing ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context on when to use it: to get aggregated sales data for a date window, with default behavior and long-range handling. It explicitly states what it does not support (payment capture, refunds, voids), which clarifies boundaries. However, it doesn't name specific alternative tools for those actions, so it's not a fully explicit 'use X instead' guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already convey read-only and open-world hints. The description adds valuable behavioral context by specifying the permission requirement ('Requires EMPLOYEES_R') and the broad scope ('across all employees'), which goes beyond the annotations. It does not contradict the annotations and clarifies authorization needs for the call.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: two sentences, with the primary purpose front-loaded in the first sentence and the permission prerequisite in the second. Every word contributes meaning, with no redundancy or filler.
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?
The tool is simple (no parameters) and has an output schema, so the description does not need to explain return values. It covers the key aspects: what it returns (currently open shifts), the scope (all employees), and the required permission. This is sufficient for an agent to select and invoke the tool correctly, especially with the supporting annotations and siblings 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?
The input schema is empty, so there are no parameters to describe. The baseline for zero parameters is 4. The description adds no parameter details because none exist, which is appropriate. The 'across all employees' phrasing confirms the tool's implicit no-filter behavior, but this is not a parameter semantic.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 function: 'Return currently open shifts (clocked in, not out) across all employees.' The verb 'Return' specifies a list operation, the resource 'open shifts' is defined precisely, and the scope 'across all employees' distinguishes it from sibling tools like list_shifts, which likely lists all shifts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for use: it targets currently open shifts, which implies it is for real-time monitoring rather than historical review. It also mentions the permission requirement 'EMPLOYEES_R', giving a practical prerequisite. However, it does not explicitly name an alternative like list_shifts for non-active shifts, so it misses the explicit 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description adds the permission requirement (MERCHANT_R) and restricts scope to the 'merchant's' devices, giving useful behavioral context. It does not contradict annotations and does not over-explain since the output schema is available.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that conveys purpose and a key requirement with no redundancy. It is highly concise and front-loaded.
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 no-parameter, read-only listing tool with an output schema, the description is fully adequate. It covers the core action, scope, and permissions, while annotations and output schema handle the rest.
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 no parameters, so schema coverage is trivially 100%. The description adds no parameter details, which is appropriate and aligns with the baseline for zero-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb ('Return') and resource ('Clover devices/terminals'). This distinguishes it from sibling list tools like list_items or list_orders, which target other 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?
Provides clear context by indicating it returns the merchant's devices, making it obvious when to use it. It also mentions a prerequisite permission (MERCHANT_R). However, it does not explicitly address alternatives or when not to use this tool, but that is less critical given the unique resource.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, lowering the bar. The description adds the permission requirement (INVENTORY_R), which is a behavioral constraint not present in annotations. It does not contradict any annotations, and the short scope is acceptable given the annotations and output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys purpose and a usage requirement with an illustrative example. Every word is valuable and nothing is redundant.
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?
With an output schema and strong annotations, the description provides all necessary context: what the tool returns, an example, and a permission requirement. No additional behavioral or return-value details are needed for this simple, parameterless tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema is already 100% covered and no parameter documentation is needed. The description's explanation of what item groups are adds context about the return data, which is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Returns item groups' and provides a concrete example ('sets of item variants, e.g. size/color'), making the purpose unambiguous. It distinguishes itself from sibling tools like list_items and list_attributes by specifying 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool through the example 'size/color' variants, and the explicit permission requirement 'Requires INVENTORY_R' gives a clear prerequisite. It does not explicitly name alternatives, but the context is sufficient for an agent to differentiate from similar list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the description doesn't need to restate safety. It adds valuable permission context (INVENTORY_R) and specifies that the result includes modifier groups and their modifiers. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two short sentences front-loaded with the action and resource, followed by a single permission requirement. Every word earns its place.
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 tool's low complexity (0 params), rich annotations, and presence of an output schema, the description is complete. It covers the primary behavior, permission requirement, and is sufficient for an agent to invoke correctly without additional 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?
The tool has zero parameters, and the empty input schema fully documents this. With 0 parameters, the baseline is 4, and the description correctly adds no parameter information since none exists.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 'Return' and clearly identifies the resource 'modifier groups' with detail 'with their modifiers', making it unambiguous and distinct from sibling list tools like list_tags or list_categories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly tells the agent when to use this tool (when modifier groups are needed) and includes a prerequisite (INVENTORY_R). It does not explicitly name alternatives or exclusions, but for a simple parameterless list tool 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, and the description adds a critical auth requirement (MERCHANT_R) beyond the structured data. It also specifies the structure of the return data (per-day time ranges), which helps the agent understand the response format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that packs purpose, structure, and permission requirement without fluff. It is front-loaded with the verb.
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 read-only, zero-parameter tool, this description is sufficient: it states the purpose, permission, and basic return structure. The output schema exists to fill in details, so the description need not elaborate further.
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 the schema is fully covered. The description doesn't need to explain parameters, and the per-day time range detail adds context to the output.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 function with a specific verb ('Return') and resource ('opening-hours sets'), and details the output ('per-day time ranges'). This distinguishes it from other list_* sibling tools, as none specifically target opening hours.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: it should be used when the merchant's opening hours are needed. It doesn't explicitly name alternatives, but the scope is so specific that no alternative is obvious; there are no 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?
Annotations already declare readOnlyHint=true and openWorldHint=true, meaning the tool is safe and may return dynamic data. The description adds value beyond annotations by stating the required permission (EMPLOYEES_R) and specifying the returned fields, which is useful for the agent. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: the first sentence clearly states what it does, and the second sentence adds the permission requirement. No wasted words or redundant information, making it highly efficient.
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 that the tool has no parameters, is a simple list operation, and has an output schema, the description is complete. It states the purpose, the permission needed, and the output format sufficiently for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description does not need to explain parameters, and there are none to elaborate on. The schema coverage is trivially 100%, and the description adds no param info because no params exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Return') and resource ('the merchant's employee roles'), and even specifies the output fields ('name + system role category'). This clearly distinguishes it from sibling tools like list_employees or get_employee, which focus on employee data rather than roles.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (whenever you need employee roles), and it provides the authorization prerequisite (EMPLOYEES_R). However, it does not explicitly name alternatives or when-not-to-use conditions, but since there is no other role-listing sibling, the use case is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, and the description adds value by disclosing the 'INVENTORY_R' permission requirement and the exact output composition (raw rate + computed percent). This goes beyond the annotations, satisfying the lower bar for behavioral disclosure given the presence 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the core action ('Return the merchant's tax rates') and immediately adds valuable detail ('raw rate + computed percent') and the permission requirement. Every word earns its place with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless read-only list tool with a good output schema and annotations, the description is fully adequate. It states what data is returned, the permission needed, and the purpose. No missing information would hinder an agent's ability to select and invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema is empty, so the 100% schema coverage makes parameter documentation moot. The baseline for 0-parameter tools is 4, and the description doesn't need to add anything about parameters since there are none.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 returns the merchant's tax rates, specifying they include both raw rate and computed percent. This specific verb+resource combination (Return + tax rates) makes the purpose unambiguous and distinguishes it from all sibling tools, none of which deal with taxes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context that this is a read-only list operation for tax rates, appropriate whenever that data is needed. The INVENTORY_R permission requirement gives a practical prerequisite. Since no alternative tax tool exists among siblings, explicit exclusions are unnecessary, though the description doesn't explicitly 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a read-only operation, but the description adds the auth requirement (MERCHANT_R) and the nature of the returned data (percentage or flat amount presets), providing useful behavioral context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence that states the action, resource, and permission without any superfluous words.
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 list tool with no parameters and an existing output schema, the description provides the essential context: what is returned, the format, and the required permission. It is complete for its complexity.
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, so the schema fully covers everything. The description adds no parameter-specific details, but per the rubric, a zero-parameter tool receives a baseline of 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 the verb 'Return' and the resource 'merchant's tip-suggestion presets' with the additional detail of 'percentage or flat amount', making it specific and distinguishable from sibling tools. It also includes the required permission, enhancing 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 provides clear context by stating exactly what the tool returns and the required permission (MERCHANT_R), allowing the agent to infer when to use it. However, it does not explicitly mention alternatives or exclusions, so it falls short of the highest bar.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses the dry-run preview behavior, the confirmation mechanism via MCP elicitation or confirm=True, and the INVENTORY_W permission requirement. This provides a clear safety and authorization profile, with no contradiction to 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 consists of two concise sentences plus a permission note, with no filler. The core purpose is front-loaded in the first meaningful clause, and subsequent sentences add behavioral context. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential aspects: purpose, required permission, and the dry-run/confirm flow. An output schema exists, so return values are not necessary to describe. It lacks explicit guidance on when to use this tool vs. alternatives, but for a straightforward create operation, the context is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameter descriptions (0% coverage), so the description compensates by explaining dry_run ('Previews on dry_run') and confirm ('confirms...before writing'). The name parameter is implicitly clear from 'Create a new inventory category.' While not exhaustive, it covers the essential semantics for all three 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 'Create a new inventory category,' which is a specific verb-object pair. This distinguishes it from sibling create tools like create_item or create_modifier. The initial phrase 'Modifies merchant data' is generic, but the core 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 provides clear context by specifying 'Requires INVENTORY_W' permission and explaining the dry-run/confirm workflow. It implies when to use the tool (to create a category) but does not explicitly compare it to alternatives like list_categories, which would have elevated it to a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses crucial behavioral traits beyond annotations: existence check with error handling, numeric bounds, dry-run behavior, confirmation workflow, and permission requirement. This significantly exceeds the annotation hints.
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 compact and organized into three short segments (generic purpose, specific operation, critical execution details). No wasted words, though 'Modifies merchant data' could be removed without loss.
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 an output schema exists, return-value documentation is not needed. The description covers preconditions, error cases, constraints, preview/confirm flow, and permissions, making it complete for a mutation tool with moderate complexity.
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?
With 0% schema coverage, the description compensates by explaining price_cents bounds, dry_run/confirm semantics, and referencing modifier_group_id in the pre-check. 'name' is not explicitly described but is self-explanatory. Missing detail on some parameters but overall helpful.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new modifier within a modifier group' which is a specific verb+resource, and distinguishes from the sibling 'create_modifier_group'. The opening 'Modifies merchant data' is generic but immediately clarified.
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 actionable guidance: pre-check for modifier group existence (404 error), bounds on price_cents, dry_run preview, confirmation via elicitation or confirm=True, and required permission INVENTORY_W. Does not explicitly name alternatives but clearly scopes when to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond readOnlyHint=false, it discloses a write requiring ORDERS_W permission, explains that name/price are copied from catalog item, states no payment, and details the dry-run/confirmation behavior before writing. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with a single-sentence purpose, followed by compact behavioral notes. Every sentence adds distinct info (copy semantics, dry_run/confirm, permission, payment exclusion). No redundancy.
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 4-parameter write tool, the description covers permission, confirmation flow, side effects, and non-payment. With an output schema present and annotations provided, no critical context is missing.
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 0%, but the description adds meaning by identifying item_id as a catalog item and order_id as the target order, and by explaining dry_run and confirm. However, parameter names/IDs are not explicitly declared, so it's strong but not maximal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource: 'Add a catalog item as a line item to an order' and clarifies the source (catalog item) and target (order). This distinguishes it from sibling tools like create_order and apply_order_discount.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use it (adding a line item to an existing order) and provides workflow guidance: use dry_run to preview, confirm via elicitation or confirm=True. It does not explicitly contrast with alternatives or list when-not-to-use, so not a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations, the description discloses the idempotency guard, duplicate-check refusal behavior, dry_run functionality, and required permissions (CUSTOMERS_R and CUSTOMERS_W). This adds significant behavioral context beyond the basic readOnly/destructive hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and structured: a clear action statement, followed by idempotency behavior, dry_run, and permission requirements. Every sentence adds value without unnecessary repetition.
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 7 parameters and zero schema descriptions, the description covers the essential non-obvious behaviors (duplicate handling, dry_run, permissions) and relies on the output schema for return format. It is sufficiently complete for effective tool 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?
With 0% schema description coverage, the description compensates by explaining dry_run, confirm_duplicate, and the role of email/phone in the duplicate check. It does not explicitly describe marketing_allowed, but most parameter meanings are clear from their names and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 'Create a new customer record in Clover', using a specific verb and resource. It distinguishes itself from sibling tools like update_customer by focusing on creation rather than modification.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context that this tool is for creating new customer records, including idempotency guard behavior. However, it does not explicitly mention when to use an alternative like update_customer or list when not to use the tool.
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?
The description discloses the write behavior, the required permission (INVENTORY_W), price bounds (0–100,000,000 cents), and the dry_run/confirmation flow. This goes well beyond the annotations, which only indicate readOnlyHint=false. It adds critical context about side effects and prerequisites.
Agents need to know what a tool does to the world before 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 total: the first states the core purpose, the second adds constraints, and the third explains the execution flow and permission. Every sentence earns its place, with no redundancy or filler. The information is front-loaded and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create tool, the description covers the creation flow, validation bounds, permission, and confirmation mechanism. The existence of an output schema means return values need not be described. The description is complete enough for an AI agent to invoke the tool correctly without requiring external documentation.
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?
With 0% schema coverage, the description compensates by explaining the required fields (name, price in cents) and adding bounds to price_cents. It also clarifies the roles of dry_run and confirm. It does not individually describe the confirm and dry_run parameters, but the schema provides their types and defaults, so the added context is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new inventory item (name + price in cents)' with a specific verb and resource. This distinguishes it from sibling tools like set_item_price_cents and update_item_name, which modify existing items. The opening 'Modifies merchant data' is generic but quickly narrowed to a precise action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for creating new items rather than updating existing ones, which is clear from the verb 'Create' and the mention of 'new inventory item'. It provides guidance on dry_run and confirmation flows, but does not explicitly name alternative tools for exclusion. This is slightly below the highest level because explicit 'use this instead of X' guidance is absent.
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?
Goes well beyond annotations by disclosing duplicate guard (case-insensitive name check), dry-run preview via dry_run, confirmation via MCP elicitation or confirm=True, and the required INVENTORY_W permission. These are non-obvious behavioral details that inform agent decisions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four tight sentences: one intro/purpose, one example, two covering guards and permissions. No fluff, all information is operationally valuable and easy to scan.
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 output schema exists, return values need not be explained. The description covers the key operational aspects: preconditions (permission), safety (dry-run, confirmation), and failure mode (duplicate guard). This is sufficient for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It explicitly explains dry_run and confirm behavior, and uses 'Milk options' as an example for name. This adds meaning beyond the bare schema, though name's format isn't fully detailed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious 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's action: 'Create a new modifier group' with an example ('Milk options'). Distinguishes from sibling create_modifier by explicitly using 'group', making the resource type 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?
Provides clear context: creating a modifier group, not a modifier. However, it doesn't explicitly mention when not to use this tool or name alternatives like create_modifier. The example and naming imply the boundary, so it's clear but lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description adds the INVENTORY_R permission requirement and explains the opt-in behavior for associations, giving the agent critical context about defaults and access control.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and includes only necessary details about permissions and optional includes. Every sentence earns its place.
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 output schema exists, the description sufficiently covers what the tool returns and how to invoke it, including the required permission. It is complete for a simple read operation.
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?
With 0% schema description coverage, the description compensates by explaining the include parameter values and their purpose. The item_id parameter is described implicitly via 'by ID', and the schema marks it as required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 returns a single inventory item by ID, distinguishing it from list tools like list_items. The verb 'Return' and resource 'single inventory item' are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a single item ID is available, but does not explicitly contrast with list_items or other alternatives. It does provide clear guidance on the optional include parameter, which helps the agent decide how to call the tool.
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?
The description goes beyond the readOnlyHint and openWorldHint annotations by revealing that the element shape is unverified due to an empty sandbox and that the shape is conservatively defined. It also discloses the required permission.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first states purpose and the limit, the second captures a caveat and permission. Every phrase adds value with no redundancy.
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 zero-parameter list tool with an output schema and annotations, the description adequately covers purpose, limit, permission, and data-quality caveat. No critical information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema coverage is 100%, so there is no parameter detail needed. The description does not need to compensate for any schema gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 returns the merchant's credits, defined as store/account-credit adjustments, with a 1000-item cap. This distinguishes it from sibling tools like list_payments and list_refunds by naming the specific 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides a clear context: requires PAYMENTS_R permission and mentions the 1000-item limit. It does not explicitly compare to alternatives or state when not to use it, so it falls short of full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds important behavioral details beyond the readOnlyHint annotation: a 200-order limit, exclusion of customer card data, and the fixed open-state filter. These are significant for an agent to understand the tool's constraints and privacy implications, going well beyond the structured 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 highly concise, with just two sentences. The first sentence front-loads the core behavior, and the second provides critical caveats (no date filter, card data exclusion, read-only). Every word contributes value, with no fluff or redundancy.
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 tool has no parameters and an output schema is present, the description sufficiently covers the essential context: what is returned, the 200-limit, and the privacy guarantee. It is complete and unambiguous, allowing an agent to select and invoke the tool correctly without further information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the description effectively explains the empty schema by stating 'no date filter, state=open only.' This clarifies why no parameters are needed, meeting the baseline for no-parameter tools with a small added explanation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: returning all currently open orders for the merchant, limited to 200. It also distinguishes itself from sibling tools by explicitly noting it is a convenience wrapper with no date filter and state=open only, which differentiates it from the more general list_orders.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: it is for fetching open orders without date filters, and the 'state=open only' note implies using this when you need only open orders. However, it does not explicitly name an alternative tool for different states or filters, so it stops short of full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses important behaviors: only SUCCESS payments are returned, card transaction details are never included, and the 'fields' parameter narrows the response (cannot widen past the allowlist). It also mentions default limit and date window behavior, adding significant value beyond the 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 concise and well-structured, with the main action in the first sentence, followed by essential constraints and a clear exclusion note. Every sentence adds substantive information with no redundancy or fluff.
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 that an output schema exists, the description does not need to explain return values. It covers all key operational aspects: default date window and limit, successful-payment filter, card-detail exclusion, field filtering behavior, and unsupported actions. This is a complete and self-sufficient description for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameter descriptions (0% coverage), so the description must compensate. It explains the 'fields' parameter semantics in detail and mentions the 'limit' default, and 'date window' covers date_from/date_to. While it doesn't explain date parameter formats or exact names, it provides enough context for an agent to infer 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 tool's function: 'List payments within an optional date window', with a specific verb and resource. It further distinguishes itself from siblings by specifying 'Only result=SUCCESS payments' and 'Card transaction details never included', making the scope 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 clear context on when to use the tool: for listing successful payments in a date range. It also explicitly states exclusions: 'This tool does NOT support payment capture, refund, or void actions.' However, it does not name alternative tools (e.g., list_refunds) that should be used for those actions, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only and open-world hints, but the description adds meaningful behavioral context: refunds are separate objects with positive amounts, card/transaction detail is never included, requires PAYMENTS_R, and does not issue refunds. This goes beyond the annotations and sets correct expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences, front-loaded with the primary function. Every sentence earns its place: purpose, domain nuance, permission, and non-action. No unnecessary words.
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 list tool with 3 optional params and an output schema, the description covers purpose, defaults, domain specifics, permissions, and exclusions. The output schema handles return-value details, so the description is fully sufficient.
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 0% and there are no per-parameter descriptions, but the description clarifies the 'optional date window (default: today, limit 50)', giving meaning to the date_from/date_to and limit parameters. It does not specify date format, but that is a minor gap for a simple list tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious 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 refunds within an optional date window' with a specific verb and resource. Distinguishes itself from sibling tools by explaining Clover refunds are separate positive-amount objects, not negative payments, and noting card/transaction detail is never included.
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 clear context: optional date window, default behavior, and explicitly states 'This tool does NOT issue refunds'—a key exclusion. Also notes the required PAYMENTS_R permission. However, it does not explicitly name alternative tools for related operations (e.g., list_payments), so some guidance is implicit.
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?
The description adds the authorization requirement (MERCHANT_R) that is not present in the annotations, providing important context for safe invocation. It also confirms read-only behavior consistent with readOnlyHint=true, and the examples clarify the scope of the returned data, which goes beyond the bare annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It conveys the resource, examples, and a permission requirement in a compact form, every clause earning its place.
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 parameter-less, read-only list tool with an output schema, the description is complete: it states the resource, enumerates sample contents, and specifies auth. No additional return-format or pagination details are necessary given the schema and simple nature of the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema requires no explanation. The description adds value by explaining the semantic content of the result set (tender types with examples), which supports understanding of the output without needing parameter details. Baseline for 0 params is 4, and this description is adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 ('Return') and clearly identifies the resource ('the merchant's tender types') while giving concrete examples (payment methods: cash, credit, custom). This distinguishes it from sibling tools like list_payments, which deal with transaction records, and list_credits/list_refunds, which are different financial objects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use this tool (when you need to view tender types) and notes a prerequisite (Requires MERCHANT_R). However, it does not explicitly mention alternatives or contrast with sibling list tools, so it stops short of the 'explicit when/when-not' level.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnly=false, destructive=true), the description discloses partial-field updates ('Only the fields you pass change'), the dry-run preview behavior, the confirmation mechanism (MCP elicitation or confirm=True), and the required permission. These are not visible in the schema or annotations, providing excellent behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences: the first states purpose, the second explains partial-update behavior, the third covers dry_run, confirmation, and permissions. Every sentence adds value; no filler or redundant details.
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?
Covers purpose, permissions, update granularity, and safety (confirmation). With an output schema present and annotations providing safety hints, the description is complete for an agent to decide when and how to use it.
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 0%, so the description carries the burden. It maps fields to 'name' (first_name, last_name) and 'marketing opt-in' (marketing_allowed), and explains the semantics of dry_run and confirm. However, it doesn't clarify the difference between omitted vs null parameters (e.g., whether null clears a field), leaving some ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Starts with 'Update a customer's name and/or marketing opt-in' which names the verb (update), resource (customer), and specific fields. This clearly distinguishes it from create_customer (new records) and get_customer (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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
While it doesn't explicitly name alternatives, it provides clear context: this tool updates an existing customer's name and marketing opt-in, implying it is for modifications after creation. It also mentions the permission requirement (CUSTOMERS_W) and the dry_run/confirmation flow, adding practical usage 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?
The description goes well beyond the annotations by explaining the Clover-specific negative amount negotiation, dry_run behavior with client-computed subtotal, confirmation flow (elicitation or confirm=True), and required ORDERS_W permission. It aligns with annotations (destructive, read-only false) and adds enriching details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded, starting with the purpose. Every sentence provides necessary detail without redundancy. It packs substantial information into a compact paragraph, making it easy to scan.
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 complex write operation with 7 parameters, the description covers all critical aspects: parameter selection, dry_run behavior, confirmation, permissions, and side effects. Since an output schema exists, return values are not required. The description is fully complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description compensates thoroughly by explaining the exactly-one constraint among percentage, amount_cents, and catalogue_discount_id, including ranges and the Clover negation for amount_cents. It also describes how catalogue discounts are resolved client-side. The 'name' parameter is not explicitly explained, but the overall semantic coverage is excellent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 action ('Apply an order-level discount') and modifies merchant data. It distinguishes from siblings by specifying order-level, unlike item-level tools like set_item_price_cents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool (applying discounts to orders) and discusses parameter constraints, but it does not explicitly contrast with alternatives or mention when not to use it. The reference to list_discounts for catalogue discounts shows dependency rather than alternative selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (which already mark it as destructive and idempotent), the description discloses the optimistic lock mechanism, the absolute price bounds, the dry_run semantics (still performs a read but never writes), and permission requirements. This provides substantial behavioral detail that annotations alone do not convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is succinct yet information-dense. It opens with the core purpose, then uses bullet-like lines for the lock, bounds, dry_run, and permissions. Every sentence contributes necessary behavioral or semantic detail with no fluff.
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 mutation tool with optimistic locking, the description covers all critical aspects: the write semantics, the stale-context protection, the range constraints, the dry_run option, and required scopes. An output schema exists, so return values need not be described. The description is fully sufficient for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description fully compensates by explaining the meaning of each parameter: item_id (implicit), new_price_cents (bounds defined), expected_current_price_cents (used for optimistic lock), and dry_run (preview mode). This goes far beyond the bare schema, making parameter usage clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 'Set an item's price (in cents, absolute value)', identifying the exact verb, resource, and unit. It distinguishes from sibling tools like set_item_stock_quantity or update_item_name by focusing on price modification, making the tool's purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for use: it specifies the optimistic locking requirement, the valid price bounds, the dry_run preview behavior, and required permissions (INVENTORY_R and INVENTORY_W). It does not explicitly name alternatives or exclude other tools, but the guidance is strong enough for an agent to know when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=true), the description discloses the optimistic lock mechanism, the absolute vs delta distinction, the 0–1,000,000 quantity bounds, the dry_run side-effect (still performs a read), and the required INVENTORY_R/W permissions. This is rich behavioral context that the annotations alone do not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: a one-line summary followed by three bullet-like sentences covering lock, bounds, dry_run, and permissions. No filler; every sentence adds essential information.
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?
Despite having an output schema (presumably describing the response), the description covers all critical practical aspects: mutation semantics, safety lock, validation bounds, dry_run behavior, and required scopes. It is complete enough for an agent to invoke the tool correctly without external docs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/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 carry full parameter meaning. It explains that new_quantity must be within bounds, expected_current_quantity is used for the optimistic lock, and dry_run previews the PUT body without writing. These semantics go far beyond the bare schema 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?
The description names a specific verb ('Set') and resource ('item's stock'), and specifies the absolute quantity semantics, clearly distinguishing it from sibling tools like set_item_price_cents or update_item_name. The phrase 'ABSOLUTE quantity (not a delta)' removes ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides strong usage context, including the optimistic lock condition, valid bounds, and the dry_run preview behavior. It implicitly contrasts with delta-based stock updates ('not a delta'), but it does not explicitly name alternative tools for incremental adjustments or other inventory operations. Overall, it clearly indicates when and how to use the tool.
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?
Annotations provide readOnlyHint=true, and the description adds critical behavioral context: no Clover data returned, no secrets, and only the names of token claims (never values). This goes beyond the annotation's safety hint and clarifies exactly what the tool does and does not expose.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with a clear diagnostic question, then precise details on returns and use case. Every sentence earns its place with no redundant content.
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 tool has no inputs, no parameters to document, and an output schema exists, the description still provides purpose, behavioral scope, and a concrete usage scenario. It fully covers what an agent needs to decide when to invoke this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema coverage is 100% (empty schema). The baseline for zero params is 4; the description adds value by explaining the tool's return information, which indirectly clarifies why no parameters are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose as a diagnostic for identifying the authenticated identity and Clover tenant mapping. It specifies exactly what it returns (identity, token claim names, scopes, tenant provisioned) and distinguishes itself from sibling tools which are business operations like list_orders or create_customer.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use it when setting up multi-tenant' and gives a concrete use case: discovering which identity claim the platform provides to key CLOVER_TENANTS_JSON correctly. This provides clear when-to-use guidance without needing alternatives.
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:

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

Score Badge

Copy to your README.md:

[![clover-mcp-server MCP server](https://glama.ai/mcp/servers/SBolivarLoL/clover-mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/SBolivarLoL/clover-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/SBolivarLoL/clover-mcp-server'

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