Upmind MCP Server

Server Quality Checklist

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

Latest release: v3.0.0
Disambiguation4/5
Most tools have clear, distinct purposes with detailed descriptions, and each targets a unique resource+action. However, the large number of similar product/contract/update tools (e.g., update_contract_product_dates vs update_contract_product_price) creates some risk of misselection, though descriptions mitigate this.
Naming Consistency5/5
All tools follow a consistent snake_case verb_noun pattern (list_, get_, create_, update_, delete_, etc.). Minor verb variations like change, sync, and apply do not break the overall predictable naming convention.
Tool Count1/5
With 97 tools, this is an extreme mismatch for an MCP server. The sheer number overwhelms an agent's ability to efficiently select the right tool, far exceeding the recommended 3-15 range and even the 25+ threshold.
Completeness4/5
The tool set covers comprehensive CRUD and lifecycle operations for clients, products, contracts, orders, invoices, payments, and tickets. Minor gaps exist (e.g., no delete_product, no create_department, no update_invoice), but agents can typically work around these omissions.
Average 4/5 across 97 of 97 tools scored. Lowest: 2.9/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 4 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
Add a LICENSE file by following GitHub's guide. Once GitHub recognizes the license, the system will automatically detect it within a few hours.
If the license does not appear after some time, you can manually trigger a new scan using the MCP server admin interface.
MCP servers without a LICENSE cannot be installed.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations mark this as a non-read-only, non-destructive operation, and the description does not contradict these hints. However, it adds minimal behavioral context: it does not disclose side effects on the lead (e.g., status change), what 'real client record' implies, or whether the operation is reversible, which is insufficient for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the action and object. Every word contributes to meaning, with no fluff or redundancy, making it appropriately sized for a simple operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should clarify return values or post-conditions, but it only states the conversion. It does not explain what the tool returns (e.g., client ID) or how the lead is affected, leaving the agent with incomplete context for a significant business operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage for the lead_id parameter with a description of 'Lead UUID'. The tool description adds no additional meaning beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (convert) and the objects (lead to client record), distinguishing it from simple create/update operations. However, it does not explicitly contrast with sibling tools like create_client, so it lacks explicit differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as creating a client manually or updating a lead. There is no mention of prerequisites, qualification criteria, or preferred scenarios, leaving the agent without decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-read-only and non-destructive, so the description adds little beyond that. It doesn't disclose whether the copy includes all product data, whether a new product ID is generated, if permissions are needed, or any side effects. The parenthetical adds domain context but not behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one sentence, front-loaded with the action and target, and contains no redundant information. Every word contributes to understanding the tool's purpose, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description should explain expected return values or side effects, but it doesn't. It also omits details about optional parameters (like category_id) and whether the copy is deep or shallow. The tool's complexity is moderate, and the description leaves too many questions unanswered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so the schema documents all parameters. The description does not add any extra meaning about parameter relationships or usage, so it meets the baseline but provides no additional value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb (copy) and resource (product to another brand), and the parenthetical (multi-brand catalogue management) gives context. However, it does not distinguish from the sibling tool 'duplicate_product', which may perform a similar operation within the same brand or with different semantics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool vs. alternatives such as 'duplicate_product' or 'create_product'. No exclusions or prerequisites are mentioned, leaving the agent without direction for selection among similar tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds no behavioral context beyond the title—no mention of pagination, default limits, return format, or any special behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that is easy to parse. However, it is largely redundant with the tool title and could be more informative without adding significant length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with two optional pagination params and read-only annotations, so the minimal description plus schema is adequate. However, without an output schema, the description could have mentioned what promotions are returned or any applicable filters or ordering, leaving gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: both limit and offset have detailed descriptions in the input schema (e.g., 'Results per page (default 20)'). The description itself adds no parameter details, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and the resource ('promotions/coupon codes'), making the purpose evident. However, it does not explicitly differentiate from sibling tools like get_promotion, though the plural form implies a list operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives such as get_promotion, create_promotion, or disable_promotion. There is no mention of context, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description says 'Remove' which implies a destructive action, but the annotations declare destructiveHint=false. This is a direct contradiction, and the description does not disclose any additional behavioral traits such as reversibility or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that conveys the core action without any filler. It is appropriately sized and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although the tool is simple with full schema coverage, the contradiction with destructiveHint leaves the behavior unclear. The description also lacks any mention of return values or consequences, making it incomplete for an agent to fully understand the operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters, so the schema fully explains product_id and migration_product_id. The tool description adds no extra parameter meaning beyond what is already in the schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Remove') and the resource ('upgrade path from a product'), distinguishing it from sibling tools like get_upgrade_paths and set_upgrade_paths. It is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor does it mention excludes or prerequisites. It simply states what it does without context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations indicating readOnlyHint=false and destructiveHint=false, the safety profile is known, but the description adds no behavioral context. It does not explain whether the update is partial or replaces the entire object, what happens to omitted fields, whether validation occurs, or what the response contains.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loading the key information ('Update fields of an existing promotion'). No wasted words; it earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (2 params, one nested object) and the presence of reasonable schema annotations, the description is minimally sufficient for basic invocation. However, it lacks information on return values, error behavior, or when this tool is appropriate, leaving clear gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with promotion_id described as a UUID and fields described with examples. The description itself adds no parameter detail, but the schema handles the burden. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Update') on a specific resource ('existing promotion'), which clearly distinguishes it from sibling tools like create_promotion, get_promotion, and disable_promotion. However, it is slightly generic in not listing what fields can be updated, though the schema partially compensates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. For instance, it does not clarify when to use update_promotion instead of disable_promotion or create_promotion, nor does it mention prerequisites like whether the promotion must already exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, but the description adds minimal behavioral context. It does not disclose whether updates are partial or full, what happens to omitted fields, or any permission requirements. This lacks transparency for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, with the verb and resource front-loaded. No word is wasted, and the advice about 'extra' is immediately actionable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update tool, the description covers the core purpose but lacks details such as response format, partial update behavior, or required permissions. With no output schema and minimal parameter documentation, the description could be more complete, but it is adequate for straightforward use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema describes client_id only, leaving five parameters undocumented. The description adds meaning to 'extra' by explaining it as a catch-all for any other Upmind client field, which is helpful. However, notes, lastname, firstname, and public_name remain undefined without any elaboration 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 tool's function: 'Update client profile fields.' This is specific to the client resource and distinguishes it from sibling tools like create_client or list_clients. The mention of 'extra' for any other Upmind client field further clarifies the scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives, nor does it mention conditions, prerequisites, or exclusions. The only guidance, 'Use "extra" for any other Upmind client field,' is about parameter handling rather than tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate this is a write operation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds no further context, such as whether the update is partial or full, whether fields are validated, or what the response looks like. Essentially it restates the tool's name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and front-loaded: 'Update fields on a lead.' Every word carries meaning and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter update tool with full schema descriptions and annotations, this is minimally adequate. However, it omits important behavioral context like whether the operation is a merge or replacement, and what constitutes valid fields for the 'fields' object. Given the lack of an output schema, a bit more detail would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: both lead_id and fields have descriptions. The tool description itself provides no additional parameter semantics beyond what the schema already states, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Update' and identifies the resource 'lead' and the scope 'fields'. This clearly differentiates from sibling tools like list_leads, create_lead, and convert_lead_to_client.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It doesn't mention that it's for modifying an existing lead, nor does it reference any related tools like create_lead or list_leads. The intended usage is only implied by the verb 'Update'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only provide readOnlyHint=false and destructiveHint=false, offering little behavioral context. The description does not disclose potential side effects (e.g., sending verification emails), required permissions, behavior when a client already exists, or what happens when has_login is true vs false. This is a significant gap for a write operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with three short sentences that each contribute meaningful information. It front-loads the primary purpose and efficiently covers required inputs, optional login credentials, and the use of the 'extra' field.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 8 parameters and no output schema, the description provides basic usage but lacks critical context. It does not mention what the API response contains, edge cases like duplicate emails or invalid brand IDs, or any prerequisites. While the description is adequate for a simple invocation, it is incomplete for a complex mutation tool of this size.
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 75%, so the schema already documents most parameters. The description adds guidance about using 'extra' for additional fields, but misleadingly includes currency_code as an example when it is already a direct schema property, causing confusion about where to pass it. It also says 'Provide email + name' while only email is required by the schema, implying name is required when it isn't.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 ('Create a new client under a brand') and distinguishes it from sibling creation tools like create_lead or update_client by identifying the resource (client) and context (under a brand). It also specifies key inputs, making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives implied usage by explaining that email and name are required and login credentials are optional, but it does not explicitly contrast this tool with alternatives like create_lead or convert_lead_to_client. No when-to-not-use or exclusion criteria are provided, leaving the user to infer when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, so the description's 'Create' aligns with expected mutation. The description adds context about the lead being a prospect from an inbound enquiry but does not disclose additional behaviors such as required brand validation, potential side effects, or return values.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently conveys the tool's purpose and an example scenario. Every word contributes, and there is no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimally adequate for a create tool, clarifying the target object (sales lead) and an example use case. However, with 7 parameters, no output schema, and minimal parameter guidance, it leaves gaps about required inputs and expected results, though annotations provide some context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 29% (only name and brand_id have descriptions), and the description adds no parameter information. It does not help clarify the seven parameters or indicate which are essential, failing to compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a sales lead (prospect), using a specific verb and resource. It distinguishes from sibling lead tools like list_leads, update_lead, and convert_lead_to_client by focusing on creation, with an example of an inbound enquiry.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used when a new sales lead/prospect needs to be created, with an example source. However, it does not explicitly state when not to use it or mention alternatives like update_lead, leaving the usage guidance implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description's 'DESTRUCTIVE' note merely echoes the existing destructiveHint=true annotation, adding no new behavioral context such as irreversibility, side effects, or authorization requirements. It repeats rather than extends what annotations already 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 extremely concise, front-loading the action 'Delete a webhook endpoint' followed by the explicit warning 'DESTRUCTIVE.' Every word serves a purpose, with 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 one-parameter delete tool with destructiveHint=true and full schema coverage, the description is adequate. It names the resource and action, and the annotation covers the destructive nature, making it 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 schema fully documents webhook_id as 'Webhook endpoint UUID' with 100% coverage, so the description adds no extra meaning beyond the parameter name and type. Baseline score of 3 is appropriate since schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a webhook endpoint,' using a specific verb and resource. It distinguishes from siblings like create_webhook, update_webhook, and list_webhooks by naming the delete action directly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool vs. alternatives, such as when to delete versus update or when it should not be used. The description only states the action without context or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate this is not read-only and not destructive, and the description does not add behavioral details such as rate limits, whether it can be sent only to unverified clients, or side effects on email history. It simply restates the action without enriching the agent's understanding of side effects or constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that immediately conveys the action and target without superfluous words. It is well-structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, single-parameter side-effect tool with no output schema, the description provides adequate context. It could mention expected behavior or error conditions, but the current level is sufficient for an agent to understand the core function.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description ('Client UUID') for the sole parameter. The tool description adds no extra meaning beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Resend' with a clear resource ('the account verification email') and target ('to a client'). It clearly distinguishes from the sibling tool 'resend_email' by narrowing to the verification email type, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'resend_email', nor any prerequisites or exclusions. The usage context is only implicit from the tool name and description, and there is no mention of conditions such as 'only for unverified clients'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare a non-read-only, non-destructive operation, but the description adds no behavioral context. It does not clarify whether updates are partial or full, if the secret field is write-only, or any side effects. It simply restates the update action without enrichment.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that is front-loaded with the verb and resource. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no output schema and minimal annotations, the description lacks information about return values, partial-update behavior, validation, or potential side effects. It is adequate only as a minimal statement of intent.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 repeats the schema's field list (url, enabled, name, secret) without adding new meaning. Schema coverage is 100%, so the baseline is 3; the description does not elevate it with details like parameter formats or validation rules.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (update) and resource (webhook endpoint), and lists specific fields (URL, enabled state, name, secret). It distinguishes from sibling tools like create_webhook and delete_webhook.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for modifying an existing webhook but does not explicitly state when to use it versus alternatives, nor any prerequisites or exclusions. The sibling names provide context but the description lacks explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare destructiveHint=true, and the description repeats this with 'DESTRUCTIVE' without adding more context. The 'pending' qualifier adds a constraint on order state, which is useful, but the description does not disclose consequences like irreversibility, side effects, or what happens to associated data. Since the safety profile is covered by annotations, this is a minimal but acceptable addition.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of two short sentences that front-load the action ('Cancel') and include a one-word emphasis on destructiveness. There is no wasted text, and it is easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with annotations and no output schema, the description is minimally viable but leaves gaps. It states the action and the pending-order constraint, but it does not explain when cancellation is allowed (e.g., order status prerequisites) or what the outcome is beyond cancellation. The annotations and schema cover the basics, so the description alone is not fully complete for an agent that needs to make nuanced decisions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents order_id as a required string (UUID) with 100% coverage, so the baseline is 3. The description adds no additional parameter semantics—it simply mentions canceling a pending order, which does not clarify the exact format or how to obtain the order_id beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Cancel') and the resource ('a pending order'), making the tool's purpose immediately obvious. The qualifier 'pending' distinguishes it from possibly canceling orders in other statuses, and the sibling tools include cancel_contract and cancel_contract_product, so specifying 'order' prevents confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided beyond the raw operation. The description does not mention when to use this tool versus alternatives like convert_order_to_invoice or cancel_contract, nor does it state exclusions (e.g., 'do not use for non-pending orders'). The word 'pending' implies a condition, but that is not explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare this as a safe read operation (readOnlyHint=true, destructiveHint=false). The description adds minimal behavioral context beyond that—it only hints at the data relationships that can be loaded. It does not address potential side effects, pagination, error responses, or rate limits, but these are less critical given the read-only annotation. 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—one sentence plus a short phrase. It front-loads the core purpose and then provides a supplementary tip for parameter usage. Every word is useful, and there is no redundant or repetitive content.
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-only tool with a well-documented schema and safety annotations, the description is nearly complete. It covers the key parameter nuance via the 'with' values. Minor lacking aspects: it doesn't explicitly state that the response is a single client object, but this is implied by the tool name and the required client_id parameter. Overall, 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 schema covers 100% of parameter descriptions, giving the baseline of 3. The description adds significant value by listing common 'with' values (emails, phones, addresses, etc.), which helps the agent construct valid and relevant requests. This goes beyond the schema's generic 'Relations to load (comma-separated)' and gives concrete, actionable examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: "Get client details." This is a specific verb and resource, and the tool name reinforces the single-record intent. However, it does not explicitly differentiate from list_clients or other client-related tools, leaving some ambiguity about the tool's scope (e.g., fetching one vs. many clients).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives. While it lists common values for the 'with' parameter, it does not mention when to prefer get_client over list_clients or other client tools. This leaves the agent to infer usage context from the tool name and schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the active status filter and product scoping, which is useful context beyond the annotations. However, it does not explain what 'active' means or what the return type is. Since readOnlyHint=true and destructiveHint=false already disclose the safety profile, a score of 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no filler or redundancy. It front-loads the verb and clearly states the object and scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter count tool with read-only annotations, the description is largely sufficient. It clearly describes what is counted. The lack of an output schema is mitigated by the fact that 'Count' implies a numeric result, but a brief note on return format would make it more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully covers product_id with a description 'Product UUID' (100% schema description coverage). The tool description adds no additional parameter semantics, so it does not exceed the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Count active contract products for a product' clearly states a specific action (count), a distinct resource (active contract products), and a scope (for a product). This distinguishes it from sibling tools like list_contracts and get_contract, which list/retrieve rather than count.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives. The description does not mention exclusions, prerequisites, or contrast with list_contracts or get_contract. The agent must infer usage from the name and description alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds context about the output content (products, restrictions, usage) but does not disclose any additional behavioral traits such as auth requirements or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the action and key output categories without filler. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-get tool with read-only annotations and one fully documented parameter, the description sufficiently covers the purpose and expected return categories. No output schema exists, but the mention of products, restrictions, and usage gives a reasonable picture of the return payload.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 sole parameter promotion_id is fully documented in the schema with a clear description ('Promotion UUID'), and the tool description adds no additional parameter-level semantics. Schema coverage is 100%, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action (get) on a specific resource (one promotion) and lists the detail categories (products, restrictions, usage), making it easy to distinguish from list/create/update operations. However, it does not explicitly name an alternative or contrast with sibling tools like list_promotions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for retrieving detailed information on a single promotion, but it does not explicitly state when to prefer it over list_promotions or provide exclusions. There is no guidance on alternative tools for bulk listing or mutations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds 'affects future invoices', which is useful context beyond the annotation readOnlyHint=false. However, it does not disclose other behavioral traits such as whether the change is reversible, permissions required, or impact on existing pricing history. The bar is lower due to annotations, but this is a minimal addition.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the action and includes a parenthetical note on the effect. Every word earns its place, and there is no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters including two boolean flags (total_price, quantity_based) that alter price calculation semantics, the description is too terse. It explains neither how these flags interact nor the full behavior of the pricing update. The schema covers individual parameter descriptions, but the overall operation context is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond the schema; it only reiterates 'recurring' and 'selling price', both of which are already in the schema descriptions for selling_price.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 ('Change') and resource ('recurring selling price of a contract product'), and adds a distinguishing behavioral effect ('affects future invoices'). This clearly separates it from sibling tools like set_contract_product_renewal or update_contract_product_dates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for price changes affecting future invoices, but does not explicitly state when to use this tool versus alternatives or provide exclusions. No comparison with sibling tools like change_contract_product or set_contract_product_renewal is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, so the description needs only to add behavioral nuance. It adds that the payment can be partial ('part of') and uses wallet balance, but provides no details on side effects, failure conditions, or reversibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no redundant wording. It states the action and funding source efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (2 params, no output schema) and the presence of annotations and complete schema coverage, the description provides sufficient context for the core operation. It could mention response behavior, but that is not critical for this simple payment action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema descriptions fully cover both parameters: invoice_number clarifies it expects a number not UUID, and credit_amount explains that omitting it applies the maximum. The description's 'part of' aligns with credit_amount but adds no further semantic detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the verb 'Pay' and specifies the resource 'invoice' and funding source 'client's wallet/credit balance', clearly distinguishing it from other invoice-related sibling tools like credit_invoice or refund_invoice.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. It implies usage when a client wants to pay an invoice from wallet credit, but does not mention exclusions or compare against add_payment or refund_from_wallet.
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=false and destructiveHint=false, indicating a non-read-only, non-destructive operation. The description adds the constraint 'draft order/basket', which clarifies the scope. However, it does not disclose what happens to the original order after conversion, whether the operation is reversible, or any side effects on the order's state, so transparency is limited.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the core action and resource. Every word earns its place, with no redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and a single parameter, a fuller description should explain the post-conditions, such as whether the original order is marked as converted or remains in draft state, and what the tool returns (e.g., the new invoice). The current description only covers the basic transformation, leaving significant gaps for an AI agent to safely use the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema already describes order_id as 'Order UUID' with complete coverage, the description adds important semantic context by specifying that the order must be a 'draft order/basket'. This tells the agent which orders are valid inputs, adding value beyond the schema's basic type 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 action: 'Convert a draft order/basket into a real invoice.' The verb 'convert' and the resource 'draft order/basket' to 'invoice' are specific, and the tool is clearly distinguished from sibling tools like list_orders, get_order, and create_renewal_invoice.
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 by specifying it applies to 'draft order/basket' only, which hints that it should be used when an order is in draft state. However, it does not explicitly mention when not to use it or provide alternatives, leaving the agent to infer the correct scenario from the wording alone.
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=false and destructiveHint=false, so the agent knows this is a mutation but not deletion. The description adds the behavioral consequence that the promotion 'can no longer be used,' which is useful. However, it does not disclose reversibility, permissions, or effects on existing uses.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 9 words, front-loaded with the action ('Disable a promotion') and followed by a brief consequence. No filler or redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with annotations and no output schema, the description is adequate: it states the purpose and effect. It doesn't mention how to re-enable a promotion or contrast with update_promotion, but these are not essential for basic usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: promotion_id is described as 'Promotion UUID.' The tool description adds no parameter-specific information beyond what the schema already provides, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Disable' with the resource 'promotion' and states the outcome 'so it can no longer be used.' This clearly distinguishes it from siblings like update_promotion, which handles other changes, and get_promotion/list_promotions, which are 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage is implied: use this when you want to disable a promotion. However, there is no explicit guidance on when not to use it or how it differs from update_promotion, which might also alter promotion status. No alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds that it lists 'every' endpoint, indicating no filtering beyond the group, but does not mention pagination, error behavior, or return format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, succinct sentence that front-loads the verb 'List' and includes illustrative examples without any filler. Every word contributes to understanding the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, clear annotations, and fully documented schema, the description is mostly complete. It could specify what an endpoint entry looks like or how includeDetails affects output, but the basic usage is well understood from the description and schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both group and includeDetails fully described. The tool description adds no additional parameter semantics beyond what the schema already provides, so it meets the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists every endpoint in one API group/category, with specific verb and resource. Examples ('Contracts', 'Admin_Products') help distinguish it from group-level or individual-endpoint tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by noting the scope (one API group/category) but does not explicitly compare with alternatives like search_endpoints or get_endpoint_details. It lacks clear 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds useful scoping ('all prices... across all pricelists, currencies, and billing cycles'). However, it does not disclose response format, pagination, or any additional behavioral constraints beyond what annotations and scope imply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundant words. Every piece ('all prices', 'one product', 'across all pricelists, currencies, and billing cycles') earns its place and directly clarifies the tool's scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only, single-parameter tool, the description adequately covers the scope and outcome. It lacks an explicit return-value description, but the absence of an output schema and the tool's simplicity keep the gap minor. The description would benefit from noting the response is a collection of prices.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully documents product_id as 'Product UUID' (100% coverage). The description adds no new parameter-level detail beyond reinforcing that the tool targets one product. The baseline of 3 applies since the schema already handles parameter 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 retrieves all prices for a single product across multiple dimensions (pricelists, currencies, billing cycles). The verb 'Get' and specific resource 'product prices' distinguish it from siblings like get_product or list_pricelists.
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 comprehensive price data for a specific product, but it does not explicitly mention alternatives or exclusions. There are no siblings that directly compete, so the context is clear but not explicitly guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that the values are 'current' and scoped to a product, but does not disclose return format, permissions, or other behavioral traits. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise, front-loaded sentence that directly states the action and object with no extraneous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only getter with one parameter and no output schema, the description adequately conveys the purpose. It could explicitly state the return format, but 'get the current ... values' reasonably implies the return. It is sufficiently complete given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents the sole parameter product_id with a description 'Product UUID' (100% coverage). The description adds no additional parameter-specific information beyond mentioning 'a product', so it provides marginal value over the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' with a clear resource ('provision field values') scoped to 'a product', which clearly distinguishes it from sibling tools like list_provision_fields (likely listing available fields) and update_provision_field_values (which modifies).
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 current configured values for a product are needed, but it does not explicitly compare to sibling tools or mention when not to use it. No exclusions or alternatives are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds the detail that the tool returns products the user is 'allowed to upgrade/migrate to,' which implies a permission-based filter and a list result. However, it does not explain the exact return shape, potential empty results, or any edge cases. This is moderate additional 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, focused sentence that immediately conveys the tool's purpose. It is concise, front-loaded with the verb, and contains no superfluous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one required parameter, no output schema), the description adequately explains what the tool does and what it returns conceptually. It is sufficiently complete for an AI agent to select and invoke the tool correctly, though it could have mentioned that the result is a list or array of products.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for the single parameter product_id, with a clear description ('Product UUID'). The tool description does not add further parameter semantics, but the baseline of 3 applies because the schema already fully documents the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
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: 'Get the products a given product is allowed to upgrade/migrate to.' It uses a specific verb ('Get'), identifies the resource ('products'), and clarifies the context ('a given product'). This distinguishes it from sibling tools like set_upgrade_paths and remove_upgrade_path, which are mutation operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage context is implied by the description: you would use this tool to retrieve upgrade/migration options for a product. However, it does not explicitly mention when to use it versus alternatives, nor does it provide any exclusions or comparisons to sibling tools like get_product or set_upgrade_paths. 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the filtering capability but does not disclose pagination behavior, return format, or any other operational details that would go beyond the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler or redundant information. It efficiently communicates the core purpose and filtering capability.
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?
Simple list tool with no output schema, but the description plus annotations and fully documented parameters are sufficient for an agent to understand the tool's basic behavior. It lacks explicit mention of default pagination or return format, but those are inferable from the schema and typical list patterns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters with clear descriptions, so the baseline is 3. The description's mention of 'filterable by client or invoice' adds marginal emphasis on the filter parameters but does not provide additional semantic meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List') and resource ('payment transactions') with an added filter capability ('filterable by client or invoice'). This clearly distinguishes it from sibling tools like list_invoices or list_wallet_transactions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives context that the tool lists payments and can be filtered by client or invoice, implying when it might be useful. However, it does not explicitly contrast with alternatives or state when not to use it, which is a clear gap given the large sibling list.
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 destructiveHint=false, covering the safety profile. The description adds the scoping detail that it lists 'all' pricelists organisation-wide, which is useful context, but it does not disclose any other behavioral traits such as pagination or ordering.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence that is front-loaded with the action and resource. There is no unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no parameters and no output schema, the description is mostly complete. It could optionally mention what a pricelist contains or the format returned, but that is not critical for a basic 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 0 parameters, so the schema is fully covered. Baseline is 4 for no parameters, and the description does not need to explain any parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'pricelists' with scope 'in the organisation', making it unambiguous. It is distinct from sibling tools like list_products or list_categories because it specifically targets pricelists.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps 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 does not provide any when-to-use guidance or mention alternatives. It simply states the function, leaving the agent to infer when to invoke it. No exclusions or prerequisites are noted.
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 destructiveHint=false, so safety is covered. The description adds no additional behavioral context such as pagination, rate limits, or output details. 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 a single, clear sentence with no superfluous words. It is front-loaded with the action 'List' and the object 'event types.'
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-only list tool with two straightforward parameters and no output schema, the description sufficiently conveys the tool's purpose. It does not explain return format, but 'List' implies a list of event types, and the simple nature of the tool makes this adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for both parameters, so the schema already provides necessary semantics. The description adds no further parameter 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 lists 'event types that webhook endpoints can subscribe to,' using a specific verb and resource. It distinguishes itself from sibling tools like list_webhooks, which lists webhook subscriptions rather than event 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 implies the tool is for discovering available event types before setting up webhooks, but it does not explicitly state when to use it versus alternatives like list_webhooks. No exclusions or alternative tool references are provided.
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 a significant behavioral detail beyond the annotations: 'PRODUCTION: changes are live.' This warns the agent that changes take effect immediately on live data, which is important context for a write operation. However, it does not mention whether existing paths are overwritten or appended, nor any permission or rollback implications, so it is not a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences that communicate the core purpose and a critical production caveat. Every word earns its place, with 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?
Given the tool's simplicity (2 parameters, no output schema, no nested objects), the description covers the essential functionality and a key operational warning. It could be more complete by explaining whether the call replaces all existing upgrade paths or adds to them, but the current content is adequate for most use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides full descriptions for both parameters ('Source product UUID' and 'Target product UUIDs'), so the schema coverage is 100%. The description adds no extra parameter-level semantics beyond restating the general purpose, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a clear action verb 'Set' and explicitly names the resource ('upgrade paths'), specifying what is configured: 'which products a product can be upgraded to.' This distinguishes it cleanly from siblings like get_upgrade_paths (read) and remove_upgrade_path (delete).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as get_upgrade_paths or remove_upgrade_path. The description only states what it does, leaving the agent to infer appropriate use cases from the name and schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations showing readOnlyHint=true and destructiveHint=false, the safety profile is already disclosed. The description adds 'full details' as a scope, but provides no additional behavioral context such as error handling, auth requirements, or return format. It meets the lower bar for annotation-backed tools but adds only minimal extra transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one short sentence ('Get full details for one brand.') that is front-loaded and contains no fluff. It earns its place with clear, specific 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?
For a simple read-by-ID tool with one parameter, high schema coverage, and read-only annotations, the description is complete. It states the purpose and scope sufficiently; no output schema exists, but this is a simple operation where the full details are expected to align with similar get_* tools. The context of sibling tools (e.g., list_brands) provides additional disambiguation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (brand_id is documented as 'Brand UUID'), so the schema fully explains the single parameter. The description does not add any semantic meaning beyond what the schema provides, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get full details for one brand' uses a specific verb and resource, clearly distinguishing it from list_brands (which would handle multiple brands) and other get_* tools. It is concise and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving a single brand's details, but does not explicitly state when to use this tool versus alternatives like list_brands. There is no explicit exclusion or alternative named, relying on the sibling tool name for differentiation.
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 destructiveHint=false, indicating a safe read operation. The description adds valuable behavioral context by explaining the default return format ('compact summaries') and how to obtain raw records ('full=true'), which goes beyond the annotation information. This helps the agent understand expected output.
Agents need to know what a tool does to the world before calling it. Descriptions 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, consisting of two sentences with no wasted words. It is front-loaded with the primary action and then adds essential detail about filters and return formats. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with read-only annotations and no output schema, the description is fairly complete. It explains the filters and the difference between compact and full records. However, it does not mention pagination (limit/offset) or default page size, which are covered in the schema but not in the description. Given the moderate complexity, this is adequate but not exhaustive.
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 high (83%), so the schema already documents most parameters. The description adds meaning by mapping user-facing filter names (client, status, brand) to the relevant parameters and providing status examples ('unpaid', 'paid', 'overdue') and clarifying the full flag's effect. It also helps interpret status values that accept short forms as noted in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'List invoices' with filters for client, status, and brand. This identifies the resource (invoices) and the specific verb (list), and the mention of filters adds scope. It is distinct from sibling tools like get_invoice (individual retrieval) and list_contracts (different resource), though it does not explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when listing or filtering invoices, and the context of the tool name makes this evident. However, it does not provide explicit when-to-use vs. alternative tools, nor does it mention exclusions (e.g., 'for a single invoice, use get_invoice'). 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds minimal behavioral context beyond the schema—it mentions filters but does not describe pagination or return format. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded, no redundant words. It efficiently states the purpose and key filters.
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 5 optional parameters fully described in the schema, the description is sufficient. 'List products' clearly implies returning a product collection, and pagination is documented in the schema. No output schema exists, but return type is self-evident.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover 100% of parameters with clear meanings (name, limit, offset, brand_id, category_id). The description restates the filter options (brand, category, exact name) but adds no additional semantics beyond the schema. Baseline 3 due to high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' and resource 'products', clearly distinguishing from sibling tools like get_product or create_product. It also notes key filter dimensions (brand, category, exact name), which helps clarify the scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not mention when to use this tool over alternatives such as get_product for a single product, nor does it state any exclusions. The usage context is implied by the name and description, but no explicit guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that the tool returns names, types, and labels, but no further behavioral details such as pagination or error scenarios are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundancy or filler. It efficiently conveys the action, scope, and return 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?
For a simple 1-parameter list tool with read-only annotations, the description covers the action, scope, and return content (names, types, labels). Without an output schema, this is sufficient for an agent to understand what to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the single parameter product_id is fully documented as a Product UUID. The description only reinforces that fields are scoped by product, adding no additional meaning or constraints beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action (list) and resource (provision blueprint fields), and specifies the output content (names, types, labels). This distinguishes it from sibling tools like list_provision_configs and get_provision_field_values, which address different aspects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when you need field definitions for a product, but it does not explicitly contrast with alternatives like get_provision_field_values (which retrieves values) or update_provision_field_values. No when-not or alternative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While annotations already mark destructiveHint=true, the description adds valuable context by warning 'may lock out whoever uses that address.' This goes beyond the annotation and discloses a concrete consequence.
Agents need to know what a tool does to the world before calling it. Descriptions 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 two short sentences that front-load the action and add the important destructive warning. 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 simple removal tool with full schema coverage and no output schema, the description completely covers the core action and the key risk. No additional behavioral info is necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides full descriptions for both parameters (whitelisted_ip_id and user_id), so the description adds no parameter-specific value. Schema coverage is 100%, meeting the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Remove' and clearly identifies the resource as 'whitelisted IP entry'. It distinguishes the tool from sibling tools like add_whitelisted_ip and list_whitelisted_ips.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool, such as needing to first list whitelisted IPs to obtain the ID or not using it if the IP is critical. There are no explicit alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds that this is a trigger action (sending an email) beyond the annotations (readOnlyHint=false, destructiveHint=false), which already indicate it is a non-read, non-destructive operation. It does not disclose potential side effects or required permissions, but with annotations present, the added context is reasonable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The single-sentence description is highly concise and front-loaded with the core action, containing only essential information. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple two-parameter tool and existing annotations/schema, the description is adequate but does not mention return behavior or failure conditions, which could be important since there is no output schema. Still, it is sufficient for basic invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides descriptions for both client_id and email, with 100% coverage. The description adds no additional parameter semantics, so it relies on the schema for this information, 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 explicitly states the action ('Trigger'), the resource ('password-reset email'), and the target ('client'), clearly distinguishing it from sibling tools like resend_client_verification or update_client. It also notes 'admin-initiated' to clarify the context, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'admin-initiated' provides clear context that this is for administrator-triggered password resets, not self-service. However, it does not explicitly mention alternatives or when not to use it, though the clear purpose implicitly differentiates it from similar email-sending 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?
The description adds meaningful behavioral insight beyond the annotations by warning 'PRODUCTION: changes are live.' This signals immediate impact, which is not captured by readOnlyHint=false or destructiveHint=false. It also hints at pass-through behavior via 'extra'. However, it does not detail side effects on unspecified fields or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise — two sentences with a clear format. It front-loads the core purpose, lists key field groups, and adds the crucial production-live warning, all without wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having 9 parameters and no output schema, the description covers the primary purpose and a key caution, but leaves gaps: it does not specify whether partial updates preserve unspecified fields, nor what a successful update returns. It is adequate for a simple update operation but could be more complete given the parameter 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?
With schema description coverage at only 33%, the description partially compensates by grouping parameters into 'name, descriptions, category, visibility flags', giving context to otherwise undocumented booleans. It also clarifies the 'extra' parameter as a catch-all for other Upmind fields, but does not explain individual parameter nuances or behavior of omitted 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 clearly states the verb ('Update') and the resource ('product fields'), and enumerates specific field categories (name, descriptions, category, visibility flags). It distinguishes itself from sibling tools like create_product or duplicate_product by focusing on updating existing product fields.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for updating existing products, but does not explicitly state when to use it over create_product or other alternatives. It does give a guidance on using 'extra' for any other Upmind product field, which is a partial usage instruction, but lacks explicit when-not-to-use scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the operation is not read-only and not destructive, and the description adds the behavioral effect of 'marks the service active.' While consistent, the description does not disclose additional traits such as idempotency, required permissions, or downstream effects, which would be valuable 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, clear sentence that conveys the purpose and scope without unnecessary words. It is appropriately front-loaded and 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 the low complexity, presence of annotations, and full parameter schema, the description is nearly complete. It explains the core action and the target state, but could briefly mention reversibility or downstream provisioning to be fully comprehensive for a state-changing 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 fully describes both parameters ('Contract UUID' and 'Contract product UUID') with 100% coverage. The description adds no extra parameter-level meaning, so it does not go beyond the baseline established by the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Activate') and resource ('contract product'), and clarifies the scope by stating it applies to 'pending/inactive' items and 'marks the service active.' This clearly distinguishes it from sibling tools like cancel_contract_product or set_contract_product_renewal.
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 the tool is for activating pending/inactive contract products, providing clear context for when to use it. However, it does not explicitly mention alternatives or situations where this tool should not be used, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are neutral (readOnlyHint=false, destructiveHint=false). The description adds useful context about the discount scope ('Applies to all products unless restricted via extra') and the type/currency relationship, but it does not disclose potential side effects or validation 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?
Two sentences, no redundant words. Front-loads the action and provides key parameter semantics efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 14-parameter tool, the description highlights the two most complex attributes (type and extra) while relying on the schema for defaults and constraints. It could mention return values, but the lack of an output schema makes this a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (93%), so the baseline is 3. The description adds meaning beyond the schema by explaining that type=1 requires currency_id and that 'extra' can restrict products, pricelists, and billing_cycles, which the schema merely labels as 'Additional raw 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 opens with the verb 'Create' and the object 'a promotion code', making the tool's function immediately clear. It distinguishes itself from siblings like update_promotion and disable_promotion by focusing on creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives. It implies via 'Create' but does not name or exclude alternatives like update_promotion or disable_promotion.
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 the operation is mutating but not destructive, so the description does not need to restate that. It adds the useful detail that the new product is named '{name} Copy', but does not disclose other behaviors like which fields are copied or whether the operation is synchronous. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the action and scope, followed by the naming detail. Every word earns its place with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the single parameter, no output schema, and straightforward operation, the description covers the essential context. It lacks details about what fields are copied or what the response contains, but for a simple clone tool with one parameter, the provided information is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with product_id described as 'Source product UUID'. The description adds 'existing product' and 'within the same brand', slightly reinforcing the parameter's meaning, but the schema already does the heavy lifting, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Clone' with a clear resource 'existing product' and a scope constraint 'within the same brand'. It also discloses the naming convention of the copy, which helps distinguish it from sibling tools like copy_product_to_brand.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'within the same brand' clearly indicates when this tool is appropriate, contrasting with cross-brand duplication. However, it does not explicitly name an alternative tool or state when not to use it, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds that it returns products and totals, which is useful context beyond the annotations, but it does not disclose any other behavioral traits such as error handling or the effect of the 'with' parameter on the response. With annotations covering the main safety aspects, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that is clear and free of unnecessary words. Every word contributes value, making it highly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple read tool with good annotations and full schema coverage. The description succinctly explains the core function and output contents. Since there is no output schema, it helps that the description mentions 'products and totals'. It lacks guidance on when to use it versus list_orders, but for a basic get tool, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (both order_id and with are described). The description does not add any additional parameter semantics; it merely implies the 'with' parameter can include products, which is already in the schema. Baseline 3 applies because the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses a specific verb 'Get' with a clear resource 'one order' and explicitly mentions the included data 'products and totals'. This distinguishes it from list_orders (which fetches many orders) and other order-related tools like create_order or cancel_order.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'one order' implies this is the tool to use when a single specific order is needed, contrasting with list_orders for multiple orders. However, it does not explicitly name alternative tools or state when not to use it, so it stops short of full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and destructiveHint=false, so the description's 'Get details' adds no additional behavioral context. The description does not mention permissions, response format, or any side effects, but the annotations cover the safety profile adequately.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that states exactly what the tool does. No redundant or extraneous information is present, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple lookup by ID, the description is adequate, and the annotations cover the safety profile. However, with no output schema, the description does not specify what 'details' are returned, which is a minor gap for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has full coverage (100%) for the single user_id parameter, including a description 'User UUID.' The description adds no further meaning beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'details for one staff user,' making it specific and action-oriented. The phrase 'one staff user' distinguishes it from sibling list_users, which presumably retrieves multiple users.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies this is for retrieving a single user by ID, giving clear context. However, it does not explicitly name list_users as the alternative for multiple users, so there is no direct comparison or exclusion.
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 destructiveHint=false, covering the safety profile. The description adds that account IDs are needed for wallet operations and that most clients have one, which is useful context. However, it does not disclose potential edge cases (e.g., client with no accounts) or return format details, leaving some behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the action and resource, with a parenthetical adding relevant context. No wasted words, and it is easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter list tool with read-only annotations and no output schema, the description adequately covers what it does and why it matters. It does not spell out the exact return shape, but the emphasis on account IDs implies the essential output. Given the low complexity, the description is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameter descriptions with client_id as 'Client UUID'. The description does not add new parameter-level details beyond noting the client context, so it provides no additional value beyond the schema baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists billing accounts of a client, which is a specific resource distinct from sibling tools like list_clients or list_contracts. The parenthetical adds purpose (needed for wallet operations) and cardinality (most clients have one), making the tool's intent 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 when to use this tool: before wallet operations, since account IDs are needed. It does not explicitly name alternatives or exclusions, but the context is clear and helpful for an agent deciding between this and get_wallet_balance or list_clients.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations (readOnlyHint=true, destructiveHint=false) already declare the safe, non-destructive nature of the operation. The description adds minimal behavioral context beyond the schema, such as the ability to search and filter, but does not disclose response format or pagination behavior. With annotations covering the safety profile, a 3 is fair.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, with no redundant words. It front-loads the main action ('List or search clients') and immediately specifies scope. Every word earns its place, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list/search tool with no output schema, the description and annotations cover the essential context: what it does, what parameters it accepts, and that it is read-only. It does not specify the return format, but the tool name and description imply a list of clients. This is adequate for a low-complexity tool, though a note on pagination would push it to 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% description coverage for all parameters, including the meaning of 'search' and 'brand_id'. The description essentially repeats the schema's parameter descriptions ('by name, email, or company', 'filter by brand') without adding new semantic value. The baseline of 3 applies since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
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 ('List or search clients') and the resource being acted upon (clients). It further specifies searchable fields (name, email, company) and a filter (brand), making the tool's purpose distinct from sibling tools like list_client_accounts or get_client.
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: to list or search clients with specific criteria. It does not explicitly mention alternatives or exclusions, but the stated search and filter capabilities make the intended usage obvious. A 4 is appropriate because the context is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the agent knows this is a safe read. The description adds some behavioral context (confirming sent emails, filterability) but doesn't disclose anything beyond that, such as pagination behavior, default ordering, or whether unfiltered calls return all history. 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 two sentences, front-loaded with the action and resource. The first sentence states what it does and its filters; the second provides a practical use case. No redundant or filler content.
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 strong annotations, the description covers the main purpose and use case. However, since all parameters are optional, it would be more complete to explicitly state that unfiltered calls return the full email history. Still, the description is largely adequate 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 coverage is 100% with descriptions for all four parameters (limit, offset, brand_id, client_id). The description adds that filtering by client or brand is possible, which is a slight semantic enhancement, but not enough to exceed the baseline of 3 when the schema already documents each 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 ('List') and the resource ('emails the platform has sent'), and adds filtering dimensions ('client or brand'). This distinguishes it from related sibling tools like get_email and resend_email, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides a concrete use case—'confirm whether an invoice reminder, verification, or notification actually went out'—which tells the agent when to use it. However, it doesn't explicitly mention alternatives to exclude, such as get_email for reading a single email, so it lacks explicit exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds 'optionally searching by text', which is a behavioral feature, but it largely restates the purpose and does not disclose additional traits like pagination behavior or response format. The bar is lower given annotations, yet the description contributes minimal extra context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the action and resource, and contains no filler. It efficiently communicates the core function without redundancy, leaving the schema to handle parameter 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?
Despite the lack of an output schema, the tool is a simple list operation with well-documented parameters. The description, combined with the schema, gives the agent enough to invoke the tool correctly. It doesn't explain the return structure, but for a list tool with pagination parameters, the schema and name imply an array of leads. This is acceptable given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% parameter description coverage, including limit, offset, search, and brand_id. The description's phrase 'optionally searching by text' echoes the search parameter but adds no new meaning. A baseline of 3 is appropriate since the schema does the heavy lifting and the description provides no further semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List sales leads/prospects', combining a specific verb ('List') with a defined resource ('sales leads/prospects'). It distinguishes itself from sibling tools like create_lead or update_lead by focusing on listing, and clarifies the resource type, avoiding ambiguity with other list tools such as list_clients or list_contracts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: this tool is for listing sales leads, optionally filtered by text. It implies use when the agent needs to retrieve leads, not create or modify them. However, it does not explicitly mention when not to use it or reference alternatives, so it stops short of full exclusion 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 destructiveHint=false, so the safety profile is covered. The description adds context about loading relations via 'with', which is useful, but does not mention pagination behavior, ordering, or response format. This is minimal additional behavioral disclosure 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 two short sentences, front-loaded with the core purpose. Every word serves a purpose; no redundancy 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?
The tool is a simple list operation with optional relations and pagination. The schema fully documents parameters, and the description explains the 'with' parameter. No output schema exists, but for a list tool the return type is likely Order objects. The description lacks details on filtering (e.g., by client or status), but since the schema only accepts with/limit/offset, the absence is acceptable. Overall, the description is sufficient given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% description coverage for all three parameters (with, limit, offset). The description adds value by providing examples for 'with' (client, products), clarifying what relations can be loaded. This goes beyond the schema's generic 'Relations to load (comma-separated)' description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists orders/baskets, using a specific verb and resource. It is distinguished from sibling tools like get_order (single Order), create_order, and cancel_order by being the 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 usage guidance for the 'with' parameter ('Use "with" for relations like client, products') but does not explicitly state when to use this tool vs alternatives such as get_order or list_invoices. It is implied by the name and context, but no exclusions or alternative suggestions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds context about the contents of the history (credits, debits, top-ups), which is useful, but it does not disclose behaviors like ordering, default pagination, or the impact of missing identifiers. With annotations covering the core safety aspects, this level of additional detail earns a 3.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is concise, front-loaded with the action and resource, and includes a parenthetical clarification of what counts as 'transactions'. No unnecessary 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?
The tool has a simple listing purpose with well-documented parameters and read-only annotations. The description covers the transaction categories but does not mention default pagination or output format, though the schema already provides pagination parameter details. It is arguably complete enough for a knowledgeable agent, but a hint about default sorting or result structure would make it fully self-sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all 4 parameters, so the description does not need to repeat those details. It adds the context that this is a client-specific transaction history, but does not provide additional parameter-level semantics beyond what the schema already explains. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the verb 'List', the resource 'wallet transaction history', and the scope 'client's', with concrete examples of transaction types (credits, debits, top-ups). It is easily distinguished from sibling tools like get_wallet_balance or refund_from_wallet, which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage 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: to retrieve a client's wallet transaction history. However, it does not explicitly mention when not to use it or point to alternative tools for related but different needs, such as checking current balance.
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=false and destructiveHint=false, so the safety profile is known. The description adds that it's a regeneration (implies overwrite) but doesn't disclose permissions, reversibility, or side effects. Some added context, 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?
A single sentence, front-loaded with the action 'Regenerate', and includes an illustrative example. No wasted words, ideal conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with annotations and no output schema, the description covers purpose, usage context, and effect. Minor omissions like prerequisites are not critical given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers invoice_id with description 'Invoice UUID' giving 100% coverage, so the description doesn't need to elaborate. It adds no parameter-specific meaning beyond what the schema provides, matching the baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses a specific verb 'regenerate' and identifies the resource 'invoice data and its PDF', clearly distinguishing it from sibling tools like list_invoices/get_invoice and other mutation operations such as credit_invoice or refund_invoice.
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 an explicit use case ('after changing brand details or a template') giving clear context for when to invoke. It doesn't explicitly state alternatives or exclusions, but the example effectively communicates the intended scenario.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-destructive mutation. Description adds that it applies to previously sent emails, but does not disclose potential consequences like duplicate sends or error behavior if email_id is invalid.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no redundancy, front-loaded with the action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with full schema coverage, the description provides purpose, usage context, and an example. Minor gaps like error handling are not critical for selection/invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters with descriptions (100%), so baseline 3. Description clarifies email_id refers to a previously sent email, adding slight value, but adds nothing about dispatch_now beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states a specific action ('Resend') and resource ('previously sent email'), with examples (invoice/verification) that clearly distinguish it from sibling tools like resend_client_verification and get_email.
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 usage context ('a previously sent email... that never arrived') indicating when to use, but does not explicitly exclude alternatives or mention 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=true and destructiveHint=false, the safety profile is already conveyed by annotations. The description adds that parameters are optional and vary per report, but it does not explain return format, latency, or required permissions. This is adequate but not rich beyond what annotations already tell us.
Agents need to know what a tool does to the world before calling it. Descriptions 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 concise sentences, front-loaded with the action and resource. Every sentence earns its place, with no redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only tool with good annotations and schema, the description covers key prerequisites (check list_reports first) and parameter variability. The only gap is the lack of explanation about the return value, which is not covered by an output schema, but the overall context is sufficient 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 coverage is 100%, so the schema already documents 'report' as a string code/name and 'parameters' as a per-report object. The description's mention of 'date ranges etc.' and 'parameters vary per report' adds no substantive meaning beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Run'), the target resource ('built-in Upmind report'), and the method ('by its code/name'). It also differentiates from the sibling tool list_reports by instructing the user to check it first, establishing the report-running scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides a clear prerequisite ('Check list_reports first') and notes that parameters vary, implying the need to consult the report's expected parameters. However, it does not explicitly state when not to use this tool in favor of an alternative, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only provide readOnlyHint=false and destructiveHint=false. The description adds that changes are live immediately, which is a meaningful behavioral disclosure beyond the annotations. However, it does not specify whether existing prices are overwritten or merged for the given product/pricelist.
Agents need to know what a tool does to the world before calling it. Descriptions 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: first states the purpose concisely, second lists required fields and the production warning. Every sentence earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/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, required parameter structure, and production impact. It lacks details on return values or whether the call replaces existing prices, but given the relatively simple schema and no output schema, it is largely complete for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for all three parameters. The description restates the required fields per entry (currency_id, billing_cycle_months, price) but adds no new meaning beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Set/update') and resource ('prices for a product on a specific pricelist'), making the tool's function immediately clear and distinguishing it from sibling read tools like get_product_prices or general product updates like update_product.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context (setting prices on a pricelist) and includes a production warning ('changes are live immediately'), but it does not explicitly mention when to use this tool versus alternatives or provide exclusion criteria. The guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this is not read-only and not destructive, and the description's 'Create' aligns with that. The description adds a behavioral detail about immediately subscribing via event codes, but does not disclose other traits like default enabled state or response behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It states the core action and the optional subscription capability concisely.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and five parameters, the description could be more complete regarding expected response or side effects. However, the schema describes most parameters, and the tool's CRUD context is evident from sibling names. The description provides a viable baseline for invocation but lacks deeper behavioral details.
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 80% with most parameters described. The description adds value by clarifying that 'subscriptions' can be event codes for immediate subscription, which is not fully specified in the schema. It does not cover the 'name' parameter, but the schema's high coverage compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 'Create a webhook endpoint' with a specific verb and resource, clearly distinguishing this from sibling tools like update_webhook, delete_webhook, and list_webhooks. It also adds a useful option about subscription event codes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a clear use case (creating a new webhook) and mentions optional subscriptions, giving context for when to pass subscription codes. It does not explicitly compare with alternatives, but the tool name and sibling list make the usage obvious.
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 destructiveHint=false, so safety is covered. The description adds the return contents (parameters, response schema, headers, permissions) but no additional behavioral context such as rate limits, authentication needs, or side effects. This is acceptable given 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 two sentences, front-loaded with the core purpose, and includes a concrete example. Every word earns its place with no filler 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?
For a simple read-only tool with one parameter and no output schema, the description fully covers purpose, input format, and what details are returned. The annotations cover safety, so nothing is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the tool description essentially repeats the schema's parameter description (name or URL pattern). It adds no new meaning beyond the schema, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('full details for one API endpoint'), lists the returned content (parameters, response schema, headers, permissions), and specifies the input format (endpoint name or URL pattern). This clearly distinguishes it from sibling tools like search_endpoints or list_contracts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use this tool: when you have a specific endpoint name or URL pattern and need full details. It does not explicitly name alternatives or exclusions, but the context is unambiguous for a single-endpoint lookup tool.
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 destructiveHint=false, establishing this as a safe read operation. The description adds scope ('all') and context ('in the Upmind API reference'), indicating it returns a complete catalog of groups, which is useful behavioral information 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 with no redundancy. Every word adds meaning.
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 listing tool with one optional, well-described parameter and strong annotations, the description provides the necessary purpose and scope. Although no output schema exists, the nature of the return (a list of groups) is clear from the description and title.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 sole parameter includeCount is fully described in the JSON schema with default behavior (default true). The tool description adds no additional parameter semantics, so the schema carries the full burden. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' and identifies the resource as 'endpoint groups/categories in the Upmind API reference.' This clearly distinguishes it from sibling tools like get_group_endpoints, which focus on endpoints within groups.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context that this lists all groups, but does not explicitly state when to prefer this over alternatives such as search_endpoints or get_group_endpoints. The 'all' qualifier implies a top-level overview, but no explicit exclusion or alternative is mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds value by disclosing the return content (subcategories and product counts) and the optional brand scoping, but does not describe deeper behavior like pagination or ordering. This matches the baseline for annotation-covered simple tools.
Agents need to know what a tool does to the world before calling it. Descriptions 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 core purpose, the included details (subcategories, counts), and the optional brand scoping. No unnecessary words 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 simple list tool with one optional parameter and good annotations, the description is complete. It explains what the tool returns (categories with subcategories and product counts) and the optional brand filter, which sufficiently covers the agent's needs. No output schema exists, but the description covers return value basics adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single optional parameter (brand_id). The description's 'optionally scoped to a brand' paraphrases the schema without adding new syntax or format details. Baseline 3 is appropriate because the schema handles the parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') with a specific resource ('product categories') and adds differentiating details: it includes subcategories and product counts, and can be scoped to a brand. This clearly distinguishes it from siblings like list_brands (lists brands) or create_category (creates categories).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: it lists product categories, optionally filtered by brand. It implies the primary use case (listing categories with subcategory/count info) without explicitly naming alternatives or exclusions, which is acceptable for a simple list tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description doesn't need to restate safety. It adds the scope constraint (staff/admin only), which is useful but not rich behavioral detail. No return format or pagination behavior is mentioned beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no filler. The main action is front-loaded, and the parenthetical adds essential cross-tool context without 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's simplicity (3 optional params, no output schema) and existing annotations, the description is sufficiently complete. It states the resource scope and a key use case, leaving schema to handle parameter details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters (limit, offset, search). The description adds no parameter-specific meaning, staying at the baseline for well-covered schemas.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and identifies the resource ('staff/admin users'), clearly distinguishing from sibling tools like list_clients (clients) and get_user (single user). The parenthetical about IDs for assign_ticket further defines the tool's role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear context for when to use: to obtain user IDs needed for assign_ticket. It doesn't explicitly state when not to use or name alternatives, but this context is specific enough to guide the agent.
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 destructiveHint=false, covering the safety profile. The description adds 'configured' and 'and their subscriptions,' providing minor behavioral context but no mention of pagination, ordering, or other response traits. 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 a single sentence that leads with the verb 'List,' immediately clarifying the operation. It contains no filler words and is appropriately sized for a simple list tool.
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 (zero parameters, read-only, no output schema), the description is complete. It clearly states what is listed ('webhook endpoints and their subscriptions') and is sufficient for an agent to invoke correctly without needing 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 schema coverage is 100% (no properties). Baseline for zero parameters is 4, and the description does not need to elaborate on parameter syntax since none 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 the specific verb 'List' with a clear resource: 'configured webhook endpoints and their subscriptions.' This distinguishes it from sibling tools like list_webhook_events, create_webhook, update_webhook, and delete_webhook by clarifying it covers endpoints and subscriptions, not events or mutations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the action: use this tool to view webhook endpoints and their subscriptions. However, it does not explicitly state when to prefer this over alternatives like list_webhook_events or get_endpoint_details, nor does it mention any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-readOnly and non-destructive, so the bar is lower. The description adds context about the two modes (intervals after next_due_date vs. explicit hold-off dates) and that dates must be today or future. However, it does not disclose behavior if both modes are supplied, whether existing scheduling is overwritten, or other side effects, leaving some transparency gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action, and no redundant information. The second sentence adds a practical use case, making every word earn 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 main functionality and use case but leaves gaps: it doesn't specify whether at least one optional parameter is required, how conflicting inputs are handled, or the effect on existing settings. Given 8 parameters and no output schema, a bit more detail on expected input constraints would make it more complete, but it is adequate for a straightforward update tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75%, so baseline is near 3. The description enriches the parameter semantics by explaining that intervals are 'days after next_due_date' and listing the explicit hold-off parameters, which the schema only minimally describes (e.g., YYYY-MM-DD). It does not fully elaborate on every parameter but adds meaningful value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool changes suspend/cancel/close scheduling for a contract product, using specific terms for the fields and distinguishing it from sibling tools like cancel_contract_product or update_contract_product_price. The verb "Change" plus the resource "contract product" and the explicit scheduling aspects make the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear use case ('Useful to give clients extra time before suspension') and implies when to use it, but it does not explicitly name alternatives or state when not to use it. Since the scheduling focus is distinct from sibling tools, the context is sufficient for selection, though it lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds context by explicitly warning 'DESTRUCTIVE: this cancels live services', which clarifies the real-world impact. It also notes the requirement to provide a cancellation_reason, adding behavioral nuance beyond the schema. This is consistent with annotations, no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the primary purpose. The two sentences are efficient, with the destructive warning placed prominently and the key requirements stated without extraneous 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?
The description covers the main aspects: what is cancelled, destructiveness, required reason, and optional product restriction. It lacks details about return values or post-cancellation status, but no output schema exists and annotations handle the safety profile. Adequate for a destructive mutation tool, though slightly more could be said about side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% description coverage for all three parameters, including 'omit = all main products' for product_ids. The description's mention of 'specific contract product UUIDs' reinforces but does not add beyond the schema. With full schema coverage, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool cancels either an entire contract or specific products on it, using the specific verb 'cancel' and naming the resource. This distinguishes it from sibling tools like cancel_contract_product, which likely cancel only a single product, and cancel_order, which targets orders.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool: for whole-contract cancellation or partial product cancellation, with the option to limit to specific products via UUIDs. However, it does not explicitly mention alternatives such as cancel_contract_product for single-product-only scenarios, so guidance is clear but not fully explicit about 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 indicate destructiveHint=true and readOnlyHint=false. The description adds context by explicitly stating 'DESTRUCTIVE: cancels a live service' and detailing refund modes, reinforcing the destructive nature and elaborating on behavior beyond the annotation. 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 well-structured: the first sentence states the core action, and the second explains refund modes and adds a destructive warning. Every sentence carries meaningful information with no waste.
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 destructive tool with annotations and schema, the description covers the essential purpose, refund control, and the destructive nature. It does not mention refund_source or cancellation_reason (though the schema covers them), nor post-cancellation effects, but overall it is sufficiently complete for an agent to understand the tool's role.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 80%, so baseline is 3. The description explains refund_mode values (0/1/2) which the schema already covers, and does not add new meaning for contract_id, contract_product_id, refund_source, or cancellation_reason. It provides no additional parameter semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it cancels a single service on a contract, with refund control. The phrase 'single service' distinguishes it from the sibling `cancel_contract`, which cancels the whole contract, so the purpose is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it: canceling a single service on a contract, and the refund mode details provide options. However, it does not explicitly mention alternatives or when not to use it (e.g., for full contract cancellation), so it lacks clear exclusions but provides enough contextual 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 discloses that the tool has side effects (changing the product) and that by default it will change something unless dry_run=true is set. It also mentions the pro-rata billing impact, which is beyond what annotations provide. Annotations indicate readOnlyHint=false and destructiveHint=false, and the description aligns without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first states the primary purpose, the second gives a critical usage tip. It is front-loaded and zero-waste, with no unnecessary details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 9 parameters and no output schema, the description covers the core behavior and the most important safety workflow (dry_run). It mentions billing implications (pro-rata) and changing products. It does not explain return values, but no output schema exists to require that. It is reasonably complete for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers most parameters with descriptions (78% coverage). The description highlights the critical 'dry_run' parameter and explains its purpose ('preview the billing impact without changing anything'), adding value. It does not explain other parameters like refund_source or billing_cycle_months, but the schema already provides that context. Thus baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Upgrade or downgrade a contract product to a different product'. It also distinguishes itself from sibling tools like 'update_contract_product_price' by focusing on product change rather than price or other attributes. The mention of pro-rata invoice/credit note adds specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear recommended workflow: 'Set dry_run=true first to preview the billing impact without changing anything.' This gives the agent a concrete usage directive. However, it does not explicitly mention alternatives or when not to use the tool, though sibling tool names like 'cancel_contract_product' and 'activate_contract_product' inherently differentiate usage.
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 non-read-only, non-destructive operation. The description adds the behavioral nuance that subcategories are created when parent_id is supplied, which adds 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 a single concise sentence that front-loads the core purpose and includes the key subcategory clarification. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create tool with three parameters and no output schema, the description adequately covers the action and the subcategory nuance. It does not describe the return value, but this is not essential for correct invocation and is not expected from a simple create tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for all three parameters. The description adds no new parameter details beyond what the schema provides; the mention of 'subcategory via parent_id' only restates the schema's own description of parent_id.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'create' and the specific resource 'product category', with an explicit note about subcategories via parent_id. This distinguishes it from sibling tools like list_categories and create_product.
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: creating a category for a brand, and optionally a subcategory via parent_id. It does not explicitly mention alternatives or exclusions, but given there is no other category-creation tool among siblings, the guidance is adequate.
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 indicate readOnlyHint=false and destructiveHint=false, so the description adds value by explaining that the tool triggers generation 'now' (manual vs scheduler) and optionally limits to one contract product. This goes beyond the basic read/write hint, though it doesn't disclose potential side effects like idempotency or financial impact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, well-structured sentence that front-loads the primary action and includes the key option. Every word earns its place, no redundancy or filler. Excellent conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params, no output schema, clear annotations), the description covers the essential behavior and the optional scoping. It does not mention return values or edge cases (e.g., if an invoice already exists), but these are not critical for the core operation. Slightly more detail on expected outcome would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters (contract_id and contract_product_id) have clear descriptions. The description's mention of 'Optionally scope to one contract product' reinforces the contract_product_id parameter but does not add additional meaning beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: generate the next recurring/renewal invoice for a contract immediately, rather than waiting for the scheduler. It also indicates an optional scope (contract product), making the tool's purpose specific and distinct from sibling tools like list_invoices or get_invoice.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'instead of waiting for the scheduler' clearly conveys when to use this tool: to trigger an invoice generation manually. It also hints at the alternative (regular scheduled generation) and describes the optional scoping behavior. No explicit exclusions or named alternative tools, but the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal a non-read-only, non-destructive operation. The description adds useful context about acting on behalf of a client and gives example scenarios, going beyond the structured annotations. It does not disclose possible side effects like notifications, but this is not expected for a basic create action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the action, includes a parenthetical with examples, and contains no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a creation tool with 7 parameters and no output schema, the description gives a clear purpose and context. Combined with the well-documented schema and annotations, it provides enough for an agent to invoke correctly. It doesn't mention the response format, but that is not critical for selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is high (86%), and the schema already contains descriptions for most parameters. The description's phrase 'on behalf of a client' implicitly references client_id, but it adds no parameter-specific details beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Open a new support ticket' and the resource (support ticket), and adds the 'on behalf of a client' scope. It distinguishes this from sibling tools like reply_ticket and list_tickets.
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 contextual use cases ('document a phone call or start an outbound conversation') and clarifies the actor ('on behalf of a client'). It doesn't explicitly mention when not to use it, but the examples imply the appropriate scenarios.
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 mark destructiveHint=true; description adds context by stating it 'moves money / changes billing records', providing specific impact beyond the annotation. 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?
Three concise sentences, each carrying meaningful information: purpose, full-credit usage guidance, and a destructive warning. No wasted words, front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 5 parameters, no output schema, and annotations available, the description covers key decision points (full credit, refund source, destructive side effects). It does not mention return values, but for a mutation tool with schema descriptions, this is acceptable and the description is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover 100% of parameters and already explain 'amount' as 'omit = remaining' and 'refund_source' as '0 original source, 1 wallet only'. The description only repeats this information, adding no new semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Issue a credit note against an invoice', a specific verb and resource. It distinguishes from sibling tools like refund_invoice by specifying 'credit note' rather than refund, and clarifies full-credit behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear context on usage: 'Omit amount to credit the full remaining amount, or set full_credit=true' and explains refund_source options. However, it does not explicitly mention when not to use it or mention alternatives like refund_invoice, so it lacks 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 destructiveHint=false. The description adds behavioral value by explaining that the tool loads related data via the 'with' parameter and providing common relation values, which clarifies the response composition 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 two sentences with no waste. It front-loads the core purpose and then provides immediately useful examples for the 'with' parameter. Every sentence 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?
Despite lacking an output schema, the description is sufficiently complete for a read-only getter. It names the key relations and implies the return structure. The annotations cover safety, and the schema covers parameters. Some might expect more detail on response format, but the core needs are met.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds extra meaning by listing common 'with' values (products, client, products.product, products.status), which go beyond the schema's generic 'Relations to load' and help the agent understand valid options.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a single contract with its products and related data. The verb 'get' and resource 'contract' are specific, and the mention of 'products and related data' distinguishes it from list_contracts and cancel_contract.
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: the tool fetches a single contract by ID. It provides guidance on the 'with' parameter listing common relation values, but does not explicitly state when to use this over list_contracts or other getters, nor any 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 destructiveHint=false, so the safety profile is clear. The description adds behavioral context by indicating that related data is not included by default and must be explicitly requested via 'with', which is a useful trait 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 two concise sentences, front-loaded with the primary purpose. Every word adds value: the first sentence states the tool's function, and the second explains the optional 'with' parameter with concrete examples. No wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only tool with only two parameters, strong annotations, and no output schema, the description is adequately complete. It covers the core function and the key parameter behavior, though it doesn't elaborate on the exact composition of 'full product details' or any potential response variations.
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 already covers both parameters with descriptions (100% coverage), so the baseline is 3. The description enriches meaning by enumerating valid relation names for 'with', going beyond the schema's example and providing a more complete reference for parameter values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get full product details' with a specific verb and resource. It distinguishes from sibling tools like list_products by focusing on a single product's details, and from get_product_prices by mentioning inclusion of multiple related data sets via the 'with' parameter.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage context is implied (retrieve a product by ID), but there is no explicit guidance on when to use this tool versus alternatives like list_products or get_product_prices. The only direct guidance is how to use the 'with' parameter, not when to choose this tool over others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows it's a read-only operation. The description adds the 'built-in' scope and the relationship to run_report, but does not disclose return format or other behavioral details, which would add further 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 a single, front-loaded sentence (13 words) that immediately conveys the action and target, with no unnecessary words. Excellent structure.
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-only, zero-parameter list tool, the description is mostly complete: it tells the agent what to expect (built-in reports) and how they might be used (with run_report). However, it does not explicitly state the return content (e.g., report names, IDs), leaving a small gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so the baseline is 4. The description adds no parameter-related detail, but none is needed. The mention of report categories gives context but is not parameter-specific.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 and specifically states the tool's function: listing Upmind's built-in reports, with concrete examples (revenue, churn, tax, transactions) and a pointer to run_report. This distinguishes it from sibling tools like run_report and other list_* resources.
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: use this to discover available reports, then run them with run_report. It names the alternative tool (run_report) and gives context, but does not explicitly state exclusions or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, and the description reinforces this with 'DESTRUCTIVE: reduces the client's credit balance', adding the specific consequence. It also notes the operation is 'Manually' performed, providing extra 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 two sentences: the first states the action and example, the second warns about destructiveness. It is front-loaded and concise, with no redundant or vague wording.
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 (6 params, 3 required) and absence of an output schema, the description covers the core action and destructive consequence. However, it does not explicitly distinguish this from refund_invoice/refund_payment or describe the response format, leaving minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 83%, so the baseline is 3. The description adds no additional parameter-level details; it only mentions 'client's wallet balance', which maps to client_id but doesn't explain parameters like amount or currency_code beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action with a specific verb and resource: 'refund an amount from a client's wallet balance', and gives an example use case ('paying out unused credit outside the system'). This distinguishes it from sibling tools like refund_invoice and refund_payment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a concrete context for when to use the tool ('paying out unused credit outside the system') and implies wallet-specific refunds, which differentiates it from invoice/payment refunds. However, it does not explicitly mention alternative tools or say 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 destructiveHint=true, so the description adds value by specifying 'records money movement,' which clarifies the financial impact beyond the boolean flag. It also states the gateway prerequisite, providing additional behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and includes the essential warning at the end. Every word earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, prerequisite, and destructiveness. With no output schema, it could mention return values, but for a mutation tool this is acceptable. Minor gap: it does not explicitly contrast with sibling tools like credit_invoice or refund_payment, but that is not critical for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%; all three parameters have descriptions. The description adds no new parameter-level details beyond the schema, so it meets the baseline but does not exceed it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Record') and resource ('manual refund against an invoice or pay out a credit note'), clearly distinguishing it from automatic refunds (refund_payment) and other credit-related tools. It also clarifies the manual/offline nature upfront.
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: this is for manual (offline) refunds or paying out a credit note, and it requires the gateway. It does not explicitly name alternatives or when-not-to-use conditions, but the 'manual/offline' phrasing implies the distinction from gateway-integrated refunds.
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 destructive=true, but the description adds context by specifying 'DESTRUCTIVE: moves real money' and confining the operation to 'captured payment' through a gateway. This goes beyond the boolean hint, though it does not cover auth requirements or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, with the core verb and resource front-loaded. No redundant filler; every phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with no output schema, the description covers the action, scope, and amount behavior. It lacks explicit return value details or error conditions, but these are not required given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers both parameters at 100%, so the description adds minimal extra meaning. The 'omit amount' instruction mirrors the schema note 'omit = full,' providing little additional value beyond what is already structured.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 ('Refund') and the resource ('captured payment through its gateway, by transaction reference'). It distinguishes itself from sibling tools like refund_invoice and refund_from_wallet by specifying the payment context.
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 usage context by limiting the operation to captured payments and explaining amount omission behavior. It does not explicitly name alternatives or exclusions, but the context is sufficient for most use cases.
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 annotations (readOnlyHint=false, destructiveHint=false), the description adds the behavioral consequence of disabling renewal—scheduling expiration at the end of the paid period. This clarifies the non-destructive yet mutating nature, providing useful context 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 two sentences, front-loaded with the primary action and complemented by a succinct explanation of the off state. No redundant detail exists.
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 mutation tool with four parameters, no output schema, and good annotations, the description covers the essential behavior and effect. It lacks details on return values or prerequisites, but these are not critical given the schema coverage and simplicity of the operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides descriptive parameter definitions with 100% coverage. The description adds no new parameter-specific meaning beyond restating the renew semantics in prose, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: turning auto-renewal on or off for a contract product. It specifies the resource (contract product) and the effect of turning renewal off (service expires at end of paid period), distinguishing it from sibling tools like cancel_contract_product or activate_contract_product.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context of when to use this tool is clear: when you need to change the auto-renewal setting for a contract product. It does not explicitly mention alternatives or exclusions, but the purpose is distinct enough that no ambiguity arises.
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 mutation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds the significant behavioral detail that changes affect how new services provision, which is valuable for deployment decisions. It does not, however, disclose details like whether changes are applied immediately or whether they impact existing services.
Agents need to know what a tool does to the world before calling it. 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 sentences that are directly informative. The purpose statement is front-loaded, and the production warning is concise and prominent. Every element serves a purpose without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a simple two-parameter update tool and no output schema, the description provides essential information: what it updates, an example, and a production impact warning. It could further clarify whether the update is a merge or replace operation, but overall it is sufficiently complete for an AI agent to 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 schema provides basic descriptions for both parameters (product_id and field_values). The description adds a concrete example of a field_values map, which clarifies the expected format beyond the schema's generic 'field_name → value map'. Since both params are fully covered by the schema, the example serves as an enhancement, earning a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Update' and identifies the resource as 'provision field values on a product', with a concrete example. This clearly distinguishes it from sibling tools like get_provision_field_values and list_provision_fields.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for modifying provision fields and warns that it affects production provisioning, but it does not explicitly contrast with alternatives such as get_provision_field_values for reading or list_provision_fields for viewing available fields. The production note provides context for caution rather than clear usage guidelines.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, so the agent knows it's a mutating but non-destructive operation. The description adds that it updates specific properties, implying partial updates, but does not disclose additional behavioral details such as response format, side effects, or permission requirements. It provides some value beyond annotations but not rich context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the action and resource, then enumerates the updatable properties. Every word earns its place, with no redundant or vague phrasing.
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 straightforward nature of the tool, the description covers the essential information: what it changes and which properties. The schema and annotations provide additional context (e.g., required ticket_id, non-destructive behavior). It does not mention return values or error behavior, but this is not critical for a simple update tool and is likely handled by the schema or standard expectations.
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 83%, so the schema already documents most parameters. The description adds semantic clarity by mapping 'status' to status_code (with example 'closed'), 'department' to department_id, and 'linked service' to contract_product_id. This helps the agent understand the purpose of these parameters beyond the schema's short descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'update' and the resource 'ticket', and specifies the exact properties that can be updated (status, subject, department, priority, linked service). This distinguishes it from sibling tools like reply_ticket and assign_ticket, which handle different aspects of ticket management.
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: when you need to change ticket properties such as status, subject, etc. It does not explicitly mention alternatives or exclusions, but the context of sibling tools (reply_ticket, assign_ticket) makes the intended use clear. No explicit 'use X instead' guidance is given, but the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations by disclosing a critical behavioral side effect: 'once a whitelist is active, access from other IPs is blocked — add your current IP first.' This warns about potential lockout, which is not captured by readOnlyHint=false or destructiveHint=false. The description also clarifies the scope (organisation vs. staff user).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one sentence stating the action and scope, followed by a critical warning. It is front-loaded with the purpose and contains no filler. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the schema fully documents the parameters and there is no output schema requiring return-value explanation, the description covers the essential context: the action, the scope, and the high-risk side effect. This is complete for a simple add operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage for all three parameters (ip, user_id, description) with clear descriptions. The tool description does not add additional parameter-specific meaning beyond what the schema offers, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Whitelist an IP for the organisation (or one staff user).' This uses a specific verb ('whitelist') and resource ('IP'), and it distinguishes the action from sibling tools like 'remove_whitelisted_ip' and 'list_whitelisted_ips'.
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's usage context (whitelisting an IP for org or user) but does not explicitly contrast it with alternatives or state when not to use it. The caution about adding your current IP first is a safety guideline rather than a tool-selection guideline, so the usage guidance remains 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?
Beyond the annotations, the description reveals the default convert=true behavior, the need for product_id and billing_cycle_months, and the PRODUCTION warning that real billing documents are created. This adds valuable operational context not present in 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?
Four concise, front-loaded sentences that each add distinct value: purpose, default behavior, product requirements, and production impact. No redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, defaults, and production cautions, but does not mention return values or output shape, which is significant for a create tool lacking an output schema. Some parameter behavior is also ambiguous.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning to selling_price ('overrides list pricing') and indicates billing_cycle_months is needed per product, but the schema only lists product_id as required, so this guidance is somewhat misleading. It adds some value beyond the 88% schema coverage but introduces potential confusion.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create an order') via the admin quick-order flow, and clarifies its default conversion to invoice, distinguishing it from sibling tools like cancel_order or convert_order_to_invoice.
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 (admin quick-order flow, default conversion behavior) but does not explicitly state when to use this tool versus alternatives such as convert_order_to_invoice, nor does it list 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 destructiveHint=false, covering the safety profile. The description adds value by disclosing that the rendered body is not exposed via the API, which is a meaningful behavioral limitation not captured by annotations. It also lists the returned data fields.
Agents need to know what a tool does to the world before calling it. Descriptions 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, information-dense sentence with a parenthetical clarification. Every word earns its place, with no repetition or filler. It is front-loaded with the action and resource.
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 1-parameter read-only tool with no output schema, the description is complete: it lists the returned fields, states the tool is for one sent email, and discloses the body limitation. No additional context is needed for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides a full description of the only parameter (email_id: Email UUID) at 100% coverage. The tool description does not add additional meaning beyond what the schema already specifies, so a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb and resource: 'Get delivery details for one sent email.' It enumerates the exact fields returned (recipient, subject, sent/bounced state, error/bounce data), distinguishing it from sibling names like list_email_history and resend_email.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies it is for a single sent email, providing clear context for when to use it (when you need details for one email). It does not explicitly mention alternatives or exclude them, but the singular focus and explicit use case give adequate 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 destructiveHint=false, covering the safety profile. The description adds useful context about loading related resources via 'with' values but does not detail return format or error handling, acceptable given the annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences front-load the purpose and include only actionable examples. No filler 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?
For a simple read operation with robust annotations and full schema documentation, the description is complete. It clearly explains the tool's singular scope and provides key parameter guidance. No output schema means return structure need not be documented.
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 descriptions cover 100% of parameters, but the description adds value by listing common 'with' values (products, payments, client, credit_notes) that are not in the schema. This enhances understanding of the parameter's use.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' and clearly states 'one invoice', distinguishing it from sibling list_invoices. The mention of common 'with' values further clarifies it fetches a single invoice with optional related 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?
Provides clear context: retrieve a single invoice, which implies list_invoices for multiple. The common 'with' values offer practical usage guidance. However, it does not explicitly name alternatives or exclusion criteria.
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 destructiveHint=false, so the agent knows this is a safe read operation. The description adds the specific metadata fields returned (status, client, assignees) but does not disclose any additional behavioral details such as permissions, performance, or pagination. This is adequate for a simple read tool, 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 exactly two sentences with no filler. It front-loads the core purpose and then provides a single, relevant pointer to a sibling tool. 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 simple read-only single-resource tool with strong annotations, a fully described schema, and no output schema, the description covers all necessary context. It tells what the tool returns, points to a sibling for related content, and is complete 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides full descriptions for both parameters: ticket_id as 'Ticket UUID' and with as 'Relations to load, e.g. "messages,client,users"'. The description does not add parameter-specific context, but schema coverage is 100%, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource: 'Get one ticket with its metadata (status, client, assignees)'. It also explicitly differentiates from a sibling tool by pointing to get_ticket_messages for the conversation, so the agent knows exactly what this tool does and what it doesn't.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an explicit alternative: 'Use get_ticket_messages for the conversation.' This tells the agent when not to use this tool and directs to the appropriate sibling for a different need, which is clear and actionable.
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 destructiveHint=false, so the safety profile is clear. The description adds that it lists 'configured' gateways and that IDs are used elsewhere, but does not disclose response format or any filtering behavior. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the action and resource, and the parenthetical adds useful context without any waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple, read-only list tool with no parameters and strong annotations. The description fully covers its purpose and practical use case; the return format is implied by the tool's name and the mention of needing IDs.
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 zero parameters, so the baseline is 4. The description does not need to add parameter details, and it provides no unnecessary 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's function with a specific verb 'list' and resource 'configured payment gateways'. The parenthetical about IDs needed for refunds and manual payments adds context and distinguishes it from other list_* tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool: whenever gateway IDs are needed for refunds or manual payments. It does not explicitly name alternatives, but no closely-related sibling tool exists, so the guidance 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 destructiveHint=false, covering safety. The description adds the behavioral nuance that omitting category_code changes the result set from configurations to categories, which is not captured by annotations. No contradictions exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, each earning its place. The first states the primary function and example; the second explains the optionality. No wasted words, and the key action is 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 simple read-only list tool with no output schema and good annotations, the description fully covers the tool's behavior, parameter semantics (category_code omission), and relationship to categories. It is complete for the complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 descriptions for brand_id and category_code, but not for limit. The description adds meaningful semantics to category_code by explaining the omission behavior, but does not clarify limit or brand_id beyond the schema. With 67% schema coverage, the description partially compensates but leaves limit under-explained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists provision configurations (e.g., servers) for a given category code, and also explains the special behavior of omitting category_code to list categories themselves. This distinguishes it from sibling tools like list_categories and list_provision_functions by specifying the exact resource and optional behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: use with category_code to list configurations for that category, or omit it to list categories. It does not explicitly name alternatives or exclusions, but the 'omit category_code' instruction effectively guides when to use this tool versus other listing 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 provide readOnlyHint=true and destructiveHint=false, covering safety. The description adds behavioral context by naming example function types and clarifying that the output is intended for use with trigger_provision, which goes 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 two sentences: the first states the core action with examples, the second gives the next-step guidance. It is concise, front-loaded, and contains 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 simple list tool with two well-specified parameters and read-only annotations, the description provides sufficient context: what is listed, examples of functions, and how to use the result. No output schema exists, so return-value details are not required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters have descriptive schema entries (Contract UUID, Contract product UUID), achieving 100% schema coverage. The description does not add explicit parameter syntax or details beyond the schema, but it implies the identifiers needed for the operation, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists provision functions on a contract product, with specific examples (setup, suspend, terminate, getUsage). It distinguishes from sibling tools like list_provision_fields by specifying that the returned function id is used with trigger_provision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use the returned function id with trigger_provision, indicating the primary workflow and when this tool is useful. It does not mention alternatives or when not to use it, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds that the output contains IDs needed for ticket creation/movement, which is helpful context but does not reveal additional behavioral traits like pagination or ordering.
Agents need to know what a tool does to the world before calling it. Descriptions 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 front-loads the action and immediately states the purpose. There is no wasted wording.
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 operation with read-only annotations, the description is adequately complete: it states the action, the resource, and the purpose. No output schema is needed for such a trivial 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?
With zero parameters, the schema fully covers parameter semantics (100% coverage). The description is not required to explain parameters, and it adds nothing about them, but the baseline for 0-param tools is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'list' and specifies the resource 'ticket departments'. The parenthetical '(IDs needed for creating/moving tickets)' clarifies the purpose and differentiates it from related ticket tools like list_tickets.
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 clearly implies the use case: retrieving department IDs for creating or moving tickets. However, it does not explicitly state alternatives or exclusion criteria, so it stops short of fully distinguishing when to use this over other 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 destructiveHint=false, covering the safety profile. The description adds meaningful behavioral context beyond annotations: it searches fields like names, titles, descriptions, groups, and URLs, and supports multi-word queries. No contradictions exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long. The first sentence states the action and scope, while the second covers capabilities and intended use. Every phrase 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 simple search tool, the description, combined with detailed schema and safety annotations, is complete. It specifies what is searched, why to use it, and the fact that it is read-only. The lack of an output schema is acceptable since the purpose is discovery rather than detailed retrieval.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: 'query' is described as 'Search query (supports multiple words)' and 'limit' as 'Max results (default 10)'. The description does not add any parameter details beyond the schema, so it receives the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Search') and a specific resource ('the Upmind API reference') with scale ('1,270+ endpoints'), distinguishing it from sibling tools like get_endpoint_details or list_api_groups. It also details the search scope (names, titles, descriptions, groups, URLs), making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear use case: 'Use this to discover the right endpoint before calling live tools or building integrations.' This explicitly tells when to use the tool. However, it does not explicitly mention when not to use it or name alternative tools, though the discovery-vs-direct-access distinction is implied.
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 include destructiveHint=true, but the description adds valuable context by stating 'DESTRUCTIVE: records money movement,' clarifying what the destructive action entails. It also notes currency constraints, going beyond the schema. 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 compact and front-loaded with the core purpose. It delivers the key usage modes, a cross-reference, and a warning in just two sentences, with no filler or repetition of schema property names.
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 mutation tool with no output schema, the description effectively covers the primary use cases, currency requirement, and destructive nature. It does omit details like idempotency or response behavior, but given the annotations and rich schema, it is sufficiently complete for selection and invocation decisions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds relational meaning by explaining the two payment modes: gateway_id for offline/manual and payment_details_id for stored methods. It also reinforces the amount currency requirement already in the schema. This extra guidance justifies a 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 tool records a payment against an invoice, with a specific verb ('Record a payment') and resource ('invoice'). It distinguishes two distinct modes (offline gateway or stored payment method), separating it from sibling tools like refund_invoice or apply_client_credit.
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 when-to-use guidance: 'typically an offline/manual payment through an offline gateway (see list_gateways), or charge a stored payment method.' It references the relevant gateway-listing tool, but does not explicitly state when not to use alternatives (e.g., apply_client_credit), so it falls short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate a non-read-only, non-destructive operation. The description adds the behavioral nuance of unassignment by omitting user_id, which is not fully captured by annotations alone. It also implies the assignee must be a staff user, adding useful context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundant words. Every part contributes meaning, and the parenthetical reference to list_users 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?
For a simple two-parameter tool with no output schema, the description covers the purpose, the main behavioral variant, and a pointer to related tooling. It slightly lacks explicit error handling or permission context, but these are not critical for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds value by specifying that the user must be a staff user and referencing list_users for obtaining valid IDs, which enriches the meaning of user_id beyond the schema's 'Omit to unassign'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 ('assign') and identifies the resource ('ticket') and target ('staff user'), clearly distinguishing it from generic update tools. It also explicitly states the unassign behavior, which differentiates it from other ticket operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: use to assign a ticket to a staff user, with a pointer to list_users for finding valid users. It does not explicitly mention when not to use it, such as choosing update_ticket for other ticket changes, but the context is adequate for a simple tool.
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 annotations (readOnlyHint=false, destructiveHint=false), the description discloses that this creates a live production product hidden from clients unless clients_can_order is true. It also explains default behaviors (single product, single-option order type, monthly billing), adding significant 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?
Three sentences with no filler: the main action, defaults, extra parameter guidance, and production warning. Each sentence earns its place and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description doesn't specify return values, but it does cover core behavior, defaults, and production implications. It's reasonably complete for an agent to invoke the tool, though it omits error scenarios or prerequisites beyond the schema's parameter descriptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 75% schema coverage, the description goes further by clarifying that 'extra' can pass through any Upmind product fields, and it explains the practical effect of clients_can_order. It also contextualizes billing defaults, adding value beyond the schema's individual parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Create a new product in a category,' a specific verb-object-resource pairing. It clearly distinguishes from sibling operations like update_product and duplicate_product by stating a creation action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage 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 initial product creation, and the mention of 'sensible defaults' and 'PRODUCTION' helps set expectations. However, it does not explicitly mention alternatives or when not to use the tool, so it doesn't fully reach the 'explicit when/when-not' 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?
The description adds significant behavioral detail beyond the readOnlyHint/destructiveHint annotations. It explicitly states that HTML is stripped, making the conversation 'readable', and that private staff notes are included. This informs the agent about content and format, which is not implied by the annotations alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the core purpose and key behavioral traits without any filler. Every phrase adds value (message thread, HTML stripped, readable, private staff notes).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only tool with a straightforward purpose, the description covers the essential information: what is fetched, the transformation applied, and the inclusion of private notes. It does not explicitly mention pagination behavior or response format, but the schema handles pagination parameters, and the absence of an output schema is acceptable given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all three parameters with descriptions for each (ticket_id, limit, offset), giving 100% coverage. The description adds no parameter-specific meaning beyond what the schema already provides, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Get the message thread of a ticket' with a specific verb and resource. It also distinguishes from siblings like get_ticket by noting HTML is stripped and that it includes private staff notes, making it unique among ticket-related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage 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 reading a ticket's conversation thread, including non-public staff notes. It does not explicitly name alternatives or state when NOT to use it, but the naming and description make the use case obvious relative to siblings like reply_ticket or update_ticket.
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 destructiveHint=false, indicating a safe read. The description adds the behavioral nuance that passing client_id triggers automatic resolution of the default account, whereas passing account_id targets a specific account. This is useful beyond the structured annotations, though it does not describe return values or error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the main purpose and followed by a compact parameter explanation. No redundant words or filler.
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-only balance check, the description covers the essential behavior and parameter selection, and annotations confirm safety. It lacks any mention of the response format or what happens if neither identifier is provided, but given the tool's simplicity and sibling context, this is a minor gap. The absence of an output schema slightly increases the need for return-value disclosure, but the description remains adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with basic UUID descriptions. The description adds meaning by explaining the relationship between client_id and account_id: they are alternatives, and client_id uses a default account. This helps the agent choose the correct parameter for the context, exceeding the schema's bare definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a client's wallet/credit balance, using the specific verb 'Get' and identifying the resource. It distinguishes from siblings like list_wallet_transactions by focusing on the current balance, not transaction history. The additional parameter guidance reinforces the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description instructs to pass either client_id or account_id, explaining that client_id resolves to the default account automatically. This provides clear context for parameter selection, but it does not explicitly contrast with alternative tools such as list_wallet_transactions or refund_from_wallet. Since the tool's purpose is obvious from context, the guidance is adequate 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by explaining the default compact summary output and the full=true flag for raw records, which is not apparent from the schema alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long and front-loaded with the primary action and filter list. It wastes no words and directly states the key distinction between summary and raw output.
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 there are 8 parameters and no output schema, the description adequately covers the output format (summary vs raw) and key filters. However, it omits mention of pagination (limit/offset) and does not reference sibling tools like count_active_services, which could be useful for comparative use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by giving example status codes (contract_active, contract_suspended, contract_cancelled) and naming the main filters (product, client, status, brand), which helps the agent understand parameter intent beyond the schema's basic descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists contract products/services with specific filters (product, client, status, brand) and distinguishes from sibling tools like get_contract which retrieves a single contract. The verb 'list' and resource 'contract products' 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 gives clear context for using this tool as a list operation with filters, and mentions the full=true option for raw records. However, it does not explicitly mention alternatives like count_active_services or get_contract for specific use cases, nor any 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 destructiveHint=false, so the safety profile is known. The description adds useful behavioral context: full-text search covers subjects and message bodies, and status codes accept both full forms and short forms. This goes beyond annotations and helps correct invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences. The first front-loads the action and filter options; the second provides essential status code syntax. No filler or redundant content.
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 list tool with annotations and full schema coverage, the description covers the main purpose, filtering, and search behavior. Pagination is not described but is documented in the schema via limit/offset. No output schema exists, so return format is unspecified, but the essential usage is adequately covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description enhances parameter understanding by naming the filter dimensions (client, status code, department, brand) and explaining the accepted status code values, including short-form matching. This adds practical meaning beyond the schema's individual property descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states it lists support tickets with specific filters (client, status, department, brand) and full-text search, clearly distinguishing it from sibling tools like get_ticket (single ticket) and list_contracts (different resource). The verb 'list' plus resource 'support tickets' is specific and actionable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates when to use this tool: to list tickets with various filters or search. It doesn't explicitly mention alternatives (e.g., 'use get_ticket for a single ticket'), but the context is sufficient for an agent to infer the primary use case. No exclusionary guidance is provided.
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 set destructiveHint=true and readOnlyHint=false. The description adds that execution happens 'immediately on the hosting server', emphasizing real-time impact, which aligns with and enriches the annotation. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise, purposeful sentences. The first defines the operation, the second provides a lookup pointer, and the third warns about immediate execution. No filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter tool with no output schema, the description covers the core action, parameter discovery, and execution risk. It lacks return value details, but given the tool's nature as a trigger, this is acceptable. The warning about production impact compensates for the missing output spec.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds meaningful context by explaining how to obtain function_id (via list_provision_functions), which helps the agent correctly populate that parameter. It also lists example function types, clarifying the semantic range of function_id.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Run' and the resource 'provisioning function on a contract product', with concrete examples (setup, suspend, unsuspend, terminate, getUsage). This distinguishes it from sibling tools like list_provision_functions and cancel_contract_product by focusing on executing a generic provisioning 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?
It explicitly directs the agent to 'Find function IDs with list_provision_functions', providing a clear alternative for discovery. It also warns 'PRODUCTION: executes immediately', implying caution and real-world impact, but it does not explicitly contrast with related tools like cancel_contract_product.
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 destructiveHint=false, covering the safety profile. The description adds value by enumerating the specific metrics returned and the optional brand scoping behavior, which goes beyond the annotations. It does not discuss pagination or performance, but for a read-only stats tool, the additional behavioral context is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that directly communicates purpose, contents, and optional scoping. Every element is necessary, and there is no redundant or filler text.
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 stats tool with one optional parameter and no output schema, the description fully covers what the tool does, what metrics it returns, and how scoping works. It is complete for the tool's low complexity and aligns with the quality of high-scoring examples like get_calls.
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 100% schema coverage, the schema documents brand_id as a 'Brand UUID'. The description adds the semantic meaning that the parameter 'optionally scoped to a brand', clarifying that it filters the stats. This goes slightly beyond the schema, earning a score above the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: providing a quick operational overview with specific metrics (active services, total clients, open tickets, unpaid invoices, pending orders). It distinguishes itself from the many list/detail sibling tools by focusing on aggregated dashboard stats rather than individual records.
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 indicates when to use the tool ('Quick operational overview') and the optional brand scoping, giving clear context. It does not explicitly name alternatives or exclusions, but the 'quick overview' framing implies it is a summary alternative to the more detailed list tools, such as list_contracts or count_active_services.
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 destructiveHint=false. The description adds value by specifying the output fields (IDs, domains, currencies) and the scope ('all brands'), which is beyond the annotations. No contradictions found.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no filler. It front-loads the action and immediately provides scope and return fields, earning every word.
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 simplicity of the tool (no params, no output schema) and solid annotations, the description is complete. It states what is returned and the scope, which is sufficient for an agent to 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?
There are zero parameters, so the baseline is 4 per the rubric. The description does not need to explain parameters, and the schema is trivially fully defined with no properties.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List all brands'), the target resource ('in the Upmind organisation'), and the returned fields ('IDs, domains, and currencies'). This distinguishes it from sibling tools like get_brand (single brand) and list_currencies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clear—use this tool when you need to list all brands—but it does not explicitly mention alternatives or when not to use it, such as 'use get_brand for a single brand.' Lacks explicit exclusions, so not a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and non-destructive behavior. The description goes beyond by disclosing the return payload (UUIDs, codes, symbols). For a parameterless list operation, this is sufficient behavioral context; no additional quirks like pagination are mentioned, but none are implied by the simple nature of the tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that fully communicates the function and output. 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 simplicity of the tool (no params, no output schema), the description is complete: it explains what is returned and the scope ('available currencies'). The annotations cover safety, so no further context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so no parameter explanation is needed. The baseline for 0 params is 4, and the description adds no unnecessary parameter-related text, keeping the focus on 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 lists available currencies, with a specific verb ('List') and resource ('currencies'). It also specifies the returned fields (UUIDs, codes, symbols), distinguishing it from other list tools like 'list_contracts' or 'list_brands'.
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: an agent should use this when needing available currencies. There are no direct alternatives or exclusions, but the context is clear enough for a simple tool like this. A more explicit 'when to use' is not strictly necessary but could be added.
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 destructiveHint=false, so the safety profile is covered. The description adds useful context: user_id filtering behavior and the security policy that admin access is only allowed from whitelisted addresses, which goes beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two clear, front-loaded sentences with no redundant information. It conveys the core function, the optional parameter, and the security implication efficiently.
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 operation with one optional parameter and good annotations, the description is fully adequate. It explains the scope, the access restriction context, and there is no need for return format details given the simple resource type.
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 already describes user_id as 'Omit for the organisation-level list', giving 100% coverage. The description adds that user_id refers to a staff user, providing slightly more specificity. Overall, the description complements the schema effectively.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's function ('List whitelisted IPs') and distinguishes between organisation-level and staff-user-level scope. The added context about admin access restrictions further clarifies the tool's purpose, distinguishing it from generic list tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when needing to view whitelisted IP addresses for either the organisation or a specific staff user. It does not explicitly name alternatives like add_whitelisted_ip or remove_whitelisted_ip, but the context of admin access restriction provides clear when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only indicate not read-only and not destructive, which is consistent. The description adds behavioral context by specifying that the entire list of product UUIDs must be provided, implying the tool replaces the full display order. This goes beyond schema and 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, with the action stated first and the key usage detail second. No redundant or filler 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?
The tool has a single parameter and no output schema, so return values are not critical. The description covers the essential operational detail (full list requirement) and is fully adequate 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?
Schema coverage is 100% with a clear description of 'Product UUIDs in desired display order.' The description enriches this by adding the requirement that it must be ALL product UUIDs of the category, which is not stated in the schema properties.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb-resource pair ('Reorder products') and defines the scope ('within a category'). It clearly distinguishes from sibling tools like update_product or create_product by indicating a display-order operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description sets clear context for when to use the tool (reordering products in a category) and provides a crucial usage instruction: pass ALL product UUIDs, not just a subset. However, it does not explicitly mention alternative tools or when not to use it, but no obvious alternative exists.
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 key behavioral side effects: public replies email the client, and private notes are hidden from the client. This context is valuable and not available in 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 extremely concise, consisting of two sentences. The main action is front-loaded, and every sentence adds value—no redundant or filler 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's simplicity (3 parameters, no output schema, no nested objects), the description is complete. It covers the core action, the private/public distinction, and the email side effect, providing an agent with all necessary knowledge to 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 schema already covers all parameters with descriptions (100% coverage). The description adds meaningful context for the is_private parameter, clarifying its behavioral impact (internal staff note versus public email), which goes beyond the schema's simple boolean description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's primary action: 'Post a reply on a ticket.' It also distinguishes between public replies and private internal notes, making it distinct from sibling tools like create_ticket or update_ticket.
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 the tool (replying to tickets) and explains the private vs. public reply distinction. It also includes a production caution about emails, but it does not explicitly mention alternatives or when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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:

[![upmind-mcp-server MCP server](https://glama.ai/mcp/servers/spidyhost-crm/upmind-mcp-server/badges/card.svg)](https://glama.ai/mcp/servers/spidyhost-crm/upmind-mcp-server)

Score Badge

Copy to your README.md:

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

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