Gorgias MCP Server

Server Quality Checklist

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

Latest release: v2.0.0
Disambiguation3/5
Multiple tools serve overlapping purposes: raw vs smart variants for ticket retrieval, search, and reporting. Though descriptions help differentiate them, an agent could easily select the wrong one (e.g., gorgias_get_ticket vs gorgias_smart_get_ticket).
Naming Consistency4/5
Most tools follow the gorgias_verb_noun pattern, but there are deviations like gorgias_smart_search and use of synonyms (retrieve vs get). Overall the naming is consistent and predictable enough.
Tool Count1/5
112 tools is far beyond any reasonable scope for an MCP server; it reflects the entire REST API surface rather than a curated set, with many redundant smart variants and overlapping endpoints.
Completeness4/5
The tool set covers CRUD for customers, tickets, messages, tags, teams, users, views, macros, integrations, and more, plus search and reporting. Minor gaps exist (e.g., no delete satisfaction survey, non-functional upload), but the surface is remarkably complete.
Average 4.2/5 across 112 of 112 tools scored. Lowest: 3.2/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 0 commits in the last 12 weeks
- Last stable release on April 14, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

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

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

How is the quality score calculated?

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

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

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

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

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds 'All fields are optional,' but this information is already evident from the schema (0 required parameters). With annotations already indicating a write operation (readOnlyHint=false), the description offers no additional behavioral context such as return value, side effects, or authentication needs. The openWorldHint=true annotation hints at external implications, but the description does not elaborate.
Agents need to know what a tool does to the world before calling it. Descriptions should go 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 includes the HTTP method and path. It is front-loaded with the core action and contains no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create operation with 11 parameters, nested objects, and no output schema, the description is too sparse. It does not indicate what a successful response returns, possible error conditions, or any constraints or side effects. The openWorldHint annotation suggests broader implications, yet the description stays silent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions for all 11 parameters, so the description need not repeat them. The statement that all fields are optional aligns with the schema's lack of required fields, but does not add new meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new customer' with the explicit endpoint 'POST /api/customers', identifying the verb and resource distinctly. This naturally differentiates it from siblings like gorgias_update_customer and gorgias_delete_customer.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not clarify prerequisites, such as whether an external_id is required for integration, or when updating an existing customer would be preferable. The only usage clue is the obvious 'create' action.
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 openWorldHint=true, and the description does not contradict them. It adds constraints about required message fields but does not disclose side effects, default behaviors, or error conditions. Given the annotation coverage, the description adds a modest amount of behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Opens with a crisp one-sentence summary, but then devotes a long bullet list to message fields that largely mirrors the input schema's messages item description. While structured, it is verbose and not front-loaded with broader context; the schema already documents most of this.
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 22-parameter creation tool with no output schema, the description thoroughly documents message subfields but omits workflow aspects like how the ticket is routed, how to assign via IDs, or when to use alternative tools. It is serviceable but not comprehensive for an agent making real-world 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 coverage is 100%, so baseline is 3. The description goes beyond the schema by clarifying defaults (e.g., 'public (optional, default true): false = internal note'), explaining the meaning of from_agent, and detailing the structure of sender/receiver/source. This adds value for a complex nested parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new support ticket' and includes the API endpoint, making the action and resource unambiguous. However, it doesn't directly differentiate from sibling tools like gorgias_create_message or gorgias_update_ticket, so it misses the 'distinguishes from siblings' criterion for a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions required fields ('Requires via and at least one message') but provides no guidance on when to choose this tool over alternatives like create_message (for adding a message to an existing ticket) or update_ticket. No 'use this when' or 'instead of' context is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond the annotations. It does not disclose side effects, permissions required, irreversibility, or what is returned. While annotations indicate a non-read-only operation, the description offers no additional transparency about consequences or prerequisites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the HTTP method and action. It includes a concise definition of a macro without any redundant wording. Every sentence 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.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (5 parameters, create operation) and absence of an output schema, the description is minimally adequate. It explains the macro entity but does not mention what the API returns (e.g., created macro object), authentication requirements, or potential side effects. The annotations partially cover the safety profile, but completeness is limited.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers all 5 parameters with descriptions (100% coverage), so the baseline is 3. The description adds minimal semantic value by defining a macro as 'a list of actions', which loosely relates to the 'actions' parameter, but it does not explain individual parameters 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 'Create a new macro' with the specific HTTP method POST and resource '/api/macros'. It partially distinguishes from siblings by defining a macro as a canned response and list of actions, which differentiates from update/delete/list operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives. It does not mention that update_macro should be used for modifying existing macros or list_macros for viewing. The description only states the action itself, leaving the agent without contextual usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, meaning a write operation, but the description adds almost no behavioral context beyond that. It does not disclose potential side effects, permissions required, error behavior, or what happens on success. The only added detail is the user types, which is already partly in 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 the HTTP method and resource clearly identified. 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.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The schema covers all parameter details, and the description gives the core purpose. However, with no output schema, the return value or response format is not described, and there is no context about error scenarios or special behaviors. This is adequate but not rich.
Complex tools with many parameters or behaviors need more documentation. Simple tools need 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 thoroughly. The description adds no extra meaning beyond pointing out agent/administrator roles, which is a subset of the full role enum. 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 a specific verb ('Create') and resource ('a new user') in the Gorgias helpdesk, and even specifies the user types (agent or administrator). This distinguishes it from sibling tools like gorgias_create_team or gorgias_create_customer.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not explain when to use this tool versus alternatives, nor does it mention prerequisites or exclusions. The intended use is only implicitly obvious from it being a create operation.
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, so the mutation flag is covered. The description adds the HTTP method 'POST' and a summary of the resource configuration. It does not disclose potential side effects, permissions needed, or return behavior, but with annotations present this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go 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: 'POST /api/views — Create a new view with filters, sorting, and visibility settings.' Every word contributes; no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 12 optional parameters and nested objects, but no output schema. The description is terse and does not explain what the response will be or typical usage combinations. However, the schema is very detailed, partially compensating for the lack of contextual guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter explained in detail (e.g., visibility enum, filter expression example). The description minimally summarizes these as 'filters, sorting, and visibility settings', adding no new meaning beyond the schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: 'Create a new view'. It also lists key features—filters, sorting, visibility settings—which distinguish it from siblings like gorgias_update_view or gorgias_list_views.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives (e.g., updating an existing view), no prerequisites, and no context about views in the Gorgias system. The agent must infer usage solely from the tool name and generic 'create' semantics.
Agents often have multiple tools that could apply. Explicit usage guidance like "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 adds no behavioral context beyond what annotations already provide. Annotations indicate readOnlyHint=false, openWorldHint=true, and idempotentHint=true, but the description does not elaborate on side effects, permissions, or error scenarios.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the HTTP method and core purpose. It contains no filler and is easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, and the description does not mention return values or partial update semantics. However, the tool is simple and annotations cover safety and idempotency, making the description minimally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with clear descriptions for each parameter. The tool description adds no additional meaning beyond the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb 'Update' and resource 'tag', and includes the HTTP method PUT, making the purpose unambiguous. It clearly distinguishes from sibling tools like create_tag and delete_tag.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the description ('Update an existing tag by ID'), but there is no explicit guidance on when to use it versus creating/deleting tags or using other update tools. No alternatives or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, so the mutating nature is known. The description adds the context that settings are helpdesk-wide, which is useful. However, it does not disclose side effects, authentication needs, idempotency, or failure behavior. Given the annotations, the description provides adequate but not 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 two concise sentences. The first sentence leads with the HTTP method and the core action; the second adds valuable context with examples. There is no redundancy or filler, and it is appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple create tool with three well-documented parameters, no output schema, and reasonable annotations. The description plus schema fully covers how to invoke it. Missing details like return value and error cases are not critical here, but for full completeness they would be nice to have.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and each parameter has a meaningful description (type, name, data with an example for business-hours). The description's mention of business hours and satisfaction surveys reinforces the 'type' meaning but does not add new parameter semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create a setting') and the resource ('the current account'), with a specific endpoint. It gives useful examples of what account settings are, but it does not explicitly distinguish this tool from sibling create tools such as create_satisfaction_survey, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/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 by defining account settings as helpdesk-wide configuration objects and giving examples, but it does not provide explicit guidance on when NOT to use it or which sibling tools to prefer (e.g., update_account_setting for modifications, create_satisfaction_survey for surveys). This is implied usage, not explicit direction.
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 write operation (readOnlyHint=false), so the description doesn't need to restate that. It adds the behavioral trait that tag names are case-sensitive, which is useful context not captured by annotations. However, it does not disclose potential side effects, idempotency, or auth requirements, which would be valuable for a create operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, informative sentence that leads with the action and endpoint, followed by a key behavioral note. It is concise, well-structured, and avoids 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 simple create operation with a fully described schema and annotations, the description is mostly complete. It lacks explicit mention of the response format (e.g., created tag object) and does not clarify the openWorldHint annotation, but these are not critical for basic usage. Overall, it provides enough context for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description repeats the 'case-sensitive' note already present in the schema's name parameter description, adding no new parameter meaning. It provides no extra context beyond what the schema already offers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Create a new tag' with the HTTP endpoint, using a specific verb and resource. It distinguishes from sibling tag operations like list, update, delete, and merge. The additional detail about case-sensitivity further clarifies the tool's behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use versus alternatives, such as create vs update vs delete tag, or when not to use (e.g., if tag already exists). The description only states the basic action, leaving usage inference to 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 indicate readOnlyHint=false and openWorldHint=true, which align with the 'Create' action. The description adds the context that the widget displays integration data in the sidebar, which is useful, but it does not disclose any other behavioral traits such as auth requirements or side effects beyond creation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the HTTP method and resource, followed by the purpose. It is concise with no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
As a create operation with no output schema, the description does not mention the return value or any error conditions. It also does not explain how the template structure translates to the rendered widget, though the schema covers parameters. This leaves the agent without sufficient information about expected outcomes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with all 7 parameters documented. The tool description does not add any parameter-specific information, so it adds no value beyond the schema. 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 with a specific verb ('Create') and resource ('new widget'), and specifies the context ('ticket or customer sidebar'), distinguishing it from sibling tools like get_widget or update_widget.
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 over alternatives or any exclusions. It simply says 'Create a new widget,' which implies the usage scenario but provides no guidance on alternatives or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is known. The description adds no further behavioral context (e.g., error handling, permissions, rate limits), merely echoing the GET method which is already covered by 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?
The description is a single sentence that front-loads the HTTP method and endpoint, with zero wasted words. It efficiently conveys the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only getter with one parameter and no output schema, the description is adequate. It tells the agent exactly what the tool does and what input it needs. There is no mention of return values or errors, but those are not required when no output schema exists and the tool is straightforward.
Complex tools with many parameters or behaviors need more documentation. Simple tools need 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 for the 'id' parameter. The description's 'by its unique ID' restates rather than adds meaning, so it does not enhance the schema's existing explanation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Retrieve a single voice call by its unique ID' with a specific verb and resource, and the endpoint GET /api/phone/voice-calls/{id} reinforces this. It is distinct from sibling tools like list_voice_calls and get_voice_call_event.
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 makes the primary usage clear (retrieve one voice call by ID) but does not explicitly mention when to use this over list_voice_calls or provide exclusions. The context is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations readOnlyHint=true and openWorldHint=true already convey the read-only nature. The description adds the REST endpoint path, but no additional behavioral details such as error handling, response format, or side effects. It does not contradict annotations but adds minimal value beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with the endpoint and a clear purpose. There is no redundancy or wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 parameter, no output schema), the description is adequate for an agent to understand the operation. It identifies the resource and the identifying parameter, though it does not specify return structure or potential error conditions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% description coverage for the id parameter, and the description repeats the notion of a unique identifier without adding further constraints, format, or examples. The baseline of 3 applies because the schema is fully documented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves a single voice call event by its unique identifier, using a specific verb ('retrieve') and naming the resource ('voice call event'). It distinguishes from siblings like list_voice_call_events and get_voice_call by specifying 'single' and 'event'.
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 have a unique identifier for a voice call event, but it does not explicitly state when to use this versus list_voice_call_events or get_voice_call. No alternatives or exclusions are mentioned; the context is clear but not 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 and openWorldHint, so the description adds cursor pagination and default ordering context. However, it does not mention response format, rate limits, or behavior beyond what annotations already 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 concise, containing only two sentences that immediately state the endpoint, purpose, and key behaviors. Every phrase adds value, with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich schema and annotations, the description covers the essential behavior for a list tool. It could explicitly mention response shape (e.g., next_cursor), but the cursor parameter description compensates, making it 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?
The schema provides 100% coverage with detailed descriptions for all 8 parameters. The description simply summarizes the filterable fields without adding new meaning or relationships 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 lists events, with the exact endpoint, pagination behavior, and supported filters. This distinctly sets it apart from gorgias_get_event, which retrieves a single event.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps 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 gorgias_get_event or other list tools. It only describes what it does, without stating scenarios, prerequisites, 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?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the description has a lower burden. It adds the behavioral detail of cursor-based pagination, which is useful, but does not disclose response shape, default limits, error behavior, or any additional constraints. Thus, it makes a moderate contribution beyond 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, front-loaded with the HTTP method and endpoint, followed by a concise summary of the action and pagination. Every word earns its place with 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?
For a simple, read-only list tool with optional parameters and no output schema, the description adequately covers the action, scope, and pagination mechanism. It lacks an explicit description of the response structure, but given the low complexity and strong annotations, this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with clear descriptions for all three parameters (limit, cursor, order_by). The description adds no parameter-specific meaning beyond what the schema already provides, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' with the resource 'satisfaction surveys' and explicitly states scope ('all'), clearly distinguishing it from singular get or mutating create/update siblings. It also mentions cursor-based pagination, adding a specific and useful behavioral detail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps 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 such as gorgias_get_satisfaction_survey for a single survey or gorgias_create_satisfaction_survey for creation. No context or exclusions are given; the usage is only implied by the verb '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 openWorldHint=true, covering the safety profile. The description adds that pagination is cursor-based, which provides some behavioral context, though it's also reiterated in the parameter schema. No additional side effects or limitations are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, efficiently conveying the HTTP method and core functionality. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with full schema coverage and read-only annotations, the description is adequate but lacks detail on the response structure (e.g., returned fields, pagination metadata). It also doesn't mention any usage exclusions. Slightly incomplete for a tool with no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description's mention of 'optional filtering' is generic and doesn't add specifics beyond the schema's 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 clearly states the tool lists all tags, includes optional filtering and pagination, and provides the HTTP method. The verb 'list' and resource 'tags' distinguish it from sibling tools like gorgias_get_tag (singular).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies its usage as a listing endpoint but does not explicitly state when to use it versus alternatives like gorgias_get_tag or gorgias_create_tag. There is no exclusion or alternative 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=false, so the mutating nature is known. The description adds domain context (teams used with auto-assign tickets) but does not disclose additional behavioral traits such as required permissions, duplicate handling, or side effects. With annotations present, the bar is lower, but no extra behavioral detail is added beyond the obvious 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 two sentences and directly states the endpoint and purpose. The second sentence about auto-assign tickets is valuable context without unnecessary fluff. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a straightforward create operation with a rich input schema that documents all parameters. The description provides the core purpose and domain context. It lacks explicit return-value information or authentication requirements, but for a simple create tool with well-documented params, it is largely 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 each parameter (name, members, decoration, description) documented in the schema. The description does not add any additional meaning or syntax details for parameters, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'POST /api/teams — Create a new team' uses a specific verb and resource, clearly identifying the action. It is distinct from sibling tools like gorgias_list_teams, gorgias_update_team, and gorgias_delete_team, and adds useful context about the auto-assign tickets feature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used for creating teams, and the note about auto-assign tickets gives context, but it does not explicitly state when to use this tool versus alternatives like updating or listing teams. No exclusions or 'when not to use' guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, so the description's emphasis on 'permanently' and 'irreversible' adds some nuance but does not disclose additional behavior like error handling, required permissions, or side effects. 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 a single, front-loaded sentence that states the HTTP method, endpoint, and key behavioral trait ('irreversible'). No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with one well-described parameter and robust annotations, the description covers the essential purpose and permanence. It could mention response codes or prerequisites, but these 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 input schema fully describes the only parameter (id) with a clear description. The tool description adds no extra parameter semantics, so the schema carries the burden. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (DELETE), the resource (rule by ID), and its permanent nature, distinguishing it from other delete tools like gorgias_delete_customer or gorgias_delete_tag. The verb 'delete' is explicit and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (use when you need to permanently delete a rule) but provides no explicit when-not-to-use or alternatives. For example, it doesn't mention that update_rule could be used for reversible changes, which would help an agent choose between tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so safety and mutability are covered. The description adds that this is a GET request listing tickets with cursor-based pagination, but it does not explain the open-world behavior or describe the response structure. 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 a single sentence that front-loads the endpoint and clearly states the action and the pagination trait. It is appropriately sized with 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?
For a read-only list tool with a well-described schema and good annotations, this description is mostly sufficient. It clearly identifies the resource (tickets in a view) and pagination style, though it could be more complete by mentioning the return shape and explicitly differentiating from similar list/search tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All parameters have descriptions in the schema (100% coverage), so the description does not need to explain each parameter. The phrase 'cursor-based pagination' adds slight context for cursor/direction/limit, but it does not add meaningful semantics beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the specific verb 'List' and the specific resource 'tickets belonging to a view', which clearly distinguishes it from sibling tools like gorgias_list_tickets (all tickets) or gorgias_search_view_items (search across views). The endpoint path reinforces the action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used when you have a view_id and want to list its tickets, and it mentions cursor-based pagination. However, it does not explicitly compare against alternatives such as gorgias_search_view_items or gorgias_list_tickets, nor does it state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a write (readOnlyHint false) and idempotent operation (idempotentHint true). The description adds key behavioral context by stating that the operation 'replaces the stored customer data entirely' and supports optimistic concurrency, which goes beyond what the annotations alone convey. 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?
The description is three short sentences that are front-loaded with the HTTP method and purpose. Each sentence delivers distinct information: the action, the replacement behavior, and concurrency support. No redundant or 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?
Given the simple PUT operation, the description combined with the detailed schema and annotations provides a solid understanding of the tool's behavior and parameters. The main gap is the lack of response/return value information, which would be helpful since there is no output schema, but overall it is sufficiently complete for a straightforward set operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all three parameters. The description adds no extra meaning beyond highlighting the version parameter's role, so it does not enhance the schema's already complete parameter information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool sets a customer's data field via HTTP PUT and specifies that it replaces the stored data entirely. This provides a specific verb, resource, and behavioral scope, though it doesn't explicitly contrast with sibling tools like gorgias_update_customer.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool should be used when you want to replace an entire customer data field, and mentions optimistic concurrency for version control. However, it does not explicitly state when to prefer this over alternatives or when not to use it, leaving usage guidance mostly implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that jobs are asynchronous and run in the background, which is not conveyed by the annotations (readOnlyHint=false, openWorldHint=true). This adds behavioral context beyond the structured fields, but it stops short of explaining the job lifecycle (e.g., polling via gorgias_get_job, response format, or failure handling).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence (with dash), front-loading the endpoint and action, followed by a brief rationale for background jobs. No fluff; every clause adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the schema thoroughly documents all 4 parameters, the description lacks information about return values (no output schema) and the need to monitor job progress via sibling tools. Given the tool's complexity and async nature, a brief mention of 'poll job status via get_job' would improve completeness. Still, the description covers the main 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?
Schema description coverage is 100% with detailed parameter descriptions, including dependencies (e.g., applyMacro needs macro_id + ticket_ids, importMacro needs url). The description itself adds no parameter semantics beyond what's in the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Create a new asynchronous job' with the HTTP endpoint, clarifying it creates jobs rather than executing operations synchronously. It lists concrete examples of long-running tasks (bulk updates, macros, exports, imports), distinguishing it from siblings like gorgias_get_job, gorgias_list_jobs, gorgias_update_job, and gorgias_cancel_job.
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 for long-running background tasks, giving examples that map to job types (bulk ticket updates, macro application, exports, imports). It does not explicitly state when not to use it or name alternative synchronous endpoints (e.g., gorgias_update_ticket for single updates), but the context is reasonably 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?
The description adds some behavioral context beyond the annotations by indicating that rules contain 'JavaScript logic and event triggers,' which explains how the rule operates. However, it does not mention side effects, execution behavior, or requirements like valid code. Annotations already signal a write operation (readOnlyHint: false), so the description is consistent but not highly informative.
Agents need to know what a tool does to the world before calling it. Descriptions should go 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 includes the HTTP method and endpoint, making it immediately actionable. Every word contributes to clarity, with no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for a create operation with a well-documented schema, but it lacks details about post-creation behavior (e.g., whether the rule activates immediately, what the response contains, or any side effects). Given the lack of an output schema and the openWorldHint annotation, a bit more context would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage of parameter descriptions, so the baseline is 3. The description's mention of 'JavaScript logic and event triggers' loosely maps to the 'code' and 'event_types' parameters but does not add new meaning beyond what the schema already provides. No additional parameter semantics are introduced.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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: 'Create a new automation rule with JavaScript logic and event triggers.' It uses a specific verb ('Create') and resource ('automation rule'), and distinguishes itself from sibling tools like gorgias_get_rule, gorgias_update_rule, and gorgias_delete_rule by focusing on the creation action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context: it is for creating rules, as opposed to retrieving, updating, or deleting them, which are covered by sibling tools. However, it does not explicitly mention when not to use it or name alternatives, so it falls short of a 5. The context is clear enough for an agent to select it for rule creation.
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, openWorldHint, and idempotentHint, covering safety. The description adds the HTTP method (PUT) and the dynamic view_id=0 behavior, but no further behavioral details like pagination defaults, auth requirements, or response shape.
Agents need to know what a tool does to the world before calling it. Descriptions 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 endpoint and core action. 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.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The schema is highly detailed and annotations cover safety, but there is no output schema and the description does not mention response format or pagination behavior. For a search tool with nested parameters, a bit more context would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so every parameter is already documented in detail. The description adds minimal extra semantic value beyond referencing 'inline view configuration' and explaining view_id=0, which the schema also mentions. 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 ('Search tickets') and the mechanism ('inline view configuration'), with a notable differentiator: passing view_id=0 enables dynamic querying without a saved view. This distinguishes it from gorgias_list_view_items and other search 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?
It provides clear context by explaining the inline configuration approach and the special view_id=0 behavior for dynamic searches. However, it does not explicitly mention alternatives like gorgias_list_view_items or gorgias_search, leaving the agent to infer when to prefer this 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 indicate this is a write operation (readOnlyHint=false), and the description confirms it by saying 'Create'. The description adds only the data type discriminator note, which is more of a parameter relationship than a behavioral disclosure. It does not reveal side effects, auth needs, or response behavior, but the annotations cover the mutation aspect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the action and resource, then adds the key discriminator detail. No wasted words, and it conveys the essential information clearly.
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 complex tool with 9 params and nested objects, the schema provides thorough parameter documentation, and the description adds the entity type scope and discriminator hint. However, there is no mention of the return value or expected response, which would be helpful given no output schema exists. Still, the overall context is sufficient for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with detailed descriptions for every parameter including the input_settings variants. The description's mention of the data_type discriminator is useful but redundant, since the schema already specifies the input_settings structure. Thus the description adds limited value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create a new custom field') and the resource ('Ticket or Customer entities'), making the tool's purpose immediately obvious. It distinguishes itself from sibling tools like gorgias_update_custom_field by using the verb 'create' and specifying the two target entity types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage 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 creating custom fields, not updating or deleting them. It does not explicitly mention alternatives like gorgias_update_custom_field, but the scope is self-evident, making the usage context clear without 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 a write operation (readOnlyHint=false), and the description's 'Create' is consistent. The description adds the one-survey-per-ticket rule, which is beyond annotation scope, but it does not disclose error behavior or permissions, so it's 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?
Two brief sentences capture purpose and constraint with zero waste. The description is front-loaded with the HTTP method and immediately states 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?
The definition is adequate for a creation tool with well-described parameters; the uniqueness constraint is important context. However, without an output schema, it could mention the response or conflict handling, keeping it at a 4.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 9 parameters have descriptions in the schema, so baseline is 3. The description's uniqueness rule duplicates the ticket_id schema description, adding no new parameter semantics beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the verb (Create) and resource (satisfaction survey), and the uniqueness constraint 'Only one survey is allowed per ticket' distinguishes it from sibling tools like get/list/update. The HTTP method adds precision.
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 states the action and the key constraint 'Only one survey is allowed per ticket,' giving clear context for when to use it. However, it does not explicitly mention alternatives or exclusions beyond the uniqueness rule, so it's a 4.
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, so the description adds value by disclosing specific side effects: deactivating views and blocking deletion for tags used in macros/rules. This goes beyond the annotation flags and helps the agent anticipate consequences.
Agents need to know what a tool does to the world before calling it. Descriptions 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. The first sentence front-loads the HTTP method and core purpose, and the subsequent sentences add essential caveats without any 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 single-parameter delete tool with annotations and no output schema, the description covers purpose, permanence, side effects, and failure conditions. It misses nothing critical for an agent to decide invocation, though it could mention the absence of a confirmation or rollback, but 'permanently' already implies that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% coverage for the single parameter 'id' with a clear description ('The unique ID of the tag to delete'). The tool description does not add additional parameter-level meaning, which is acceptable given the high schema coverage. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (DELETE) and the resource (a single tag), and includes 'Permanently delete' to emphasize the effect. It distinguishes from siblings like gorgias_delete_tags by specifying 'single tag' and from merge/update operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides important constraints on when deletion is allowed ('Tags used in macros/rules cannot be deleted') and consequences ('Views using this tag will be deactivated'), but it does not explicitly mention alternative tools like gorgias_delete_tags for bulk deletion or gorgias_merge_tags. Usage context is implied but not contrasted with siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safe-read behavior is covered. The description adds what the response includes (channels, integration data, optionally custom fields), which is useful, but does not disclose error handling, 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?
Single sentence, starts with the API endpoint, and every word adds value. 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?
For a simple get-by-id tool with good annotations and full schema coverage, the description adequately conveys the return content. It does not need to explain return values in detail beyond the optional relationships, and no output schema exists to require more.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for both parameters. The description's mention of 'optionally custom fields' echoes the schema's description of the 'relationships' parameter, adding little beyond what is already documented. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Retrieve' and resource 'a single customer by ID', distinguishing it from the sibling 'list_customers' tool. It also specifies the included data (channels, integration data, optionally custom fields), making the tool's 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context: retrieve a specific customer by ID, as opposed to listing customers. It does not explicitly name alternatives or provide exclusions, but the 'single by ID' wording gives clear context for when 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safety profile is clear. The description adds value by specifying the HTTP GET method and the return structure (full CustomField object with definition, metadata, and configuration), which aids the agent in anticipating the response. 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?
One concise sentence front-loads the endpoint and action, with no wasted words. It is appropriately sized and immediately conveys the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter read tool, the description covers purpose, HTTP method, and return content. The absence of an output schema is mitigated by the mention of the full CustomField object. Annotations handle safety transparency, making this sufficiently complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents the single 'id' parameter with 100% coverage, including type and description. The description merely restates that it's the unique ID, adding no additional semantic information beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (retrieve), the resource (custom field), and the scope (single by unique ID). It distinguishes from sibling tools like gorgias_list_custom_fields by emphasizing 'single' versus a list operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have a specific custom field ID and need its details, but it does not explicitly state when to use this tool versus alternatives like list_custom_fields or create/update. No exclusions or alternative tool names are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds context that events are 'read-only records generated automatically by the Gorgias system,' which reinforces the safety profile. However, it does not disclose additional behavioral traits such as response format, error handling, or any rate limits, so it adds only modest 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?
Two sentences, zero wasted words. The first sentence front-loads the HTTP method and purpose; the second adds essential context about event record semantics. Perfectly sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read-only tool, the description is adequately complete. It explains the tool's purpose and the nature of the resource (system-generated events). The absence of an output schema means return format isn't documented, but for such a simple retrieval operation, this is not a critical gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage for the single 'id' parameter with a clear description ('The unique ID of the event to retrieve'). The description's mention of 'unique ID' is redundant and does not add syntax, format, or additional meaning beyond the schema, so it earns the baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states a specific verb ('Retrieve') and resource ('single event by its unique ID'), clearly distinguishing it from siblings like gorgias_list_events and other get_* tools. The HTTP method and endpoint prefix further clarify the exact 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 clearly implies when to use this tool: when you have a specific event ID and need that single event. It does not explicitly mention alternatives or exclusions (e.g., 'use list_events for multiple events'), but the singular scope and ID requirement provide clear context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint and openWorldHint annotations already cover the safety profile. The description adds minimal behavioral context beyond the HTTP method and ID-based lookup, with no discussion of errors, auth, or rate limits. 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 concise sentence that front-loads the HTTP method and purpose. Every word contributes value with 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 simple single-parameter read operation, the description provides sufficient context to use the tool correctly. It could mention return value details, but the absence of an output schema and the tool's simplicity keep it acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with the 'id' property already described as 'The unique ID of the rule to retrieve'. The description's phrase 'by its unique ID' adds no significant meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Retrieve' and the resource 'a single rule' with a specific identifier. It distinguishes from sibling tools like gorgias_list_rules by emphasizing 'single rule by its unique ID'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for fetching one specific rule, contrasting with list tools. However, it does not explicitly mention alternatives or when-not-to-use conditions, so it lacks explicit 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 openWorldHint=true, so the read-only nature is fully covered. The description adds no extra behavioral context beyond the endpoint path and 'retrieve' wording, which doesn't contradict annotations. For a simple GET-by-ID, this is adequate but not additive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with zero wasted words. It includes the HTTP method, endpoint, and a clear action. Perfectly concise 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 one-parameter read operation with readOnly annotation, the description is sufficient. It doesn't mention the response shape, but without an output schema and given the simplicity, this is a minor gap. The description is complete enough for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the id parameter's description already explains its meaning. The tool description's 'unique ID' adds no additional semantics beyond 'the ID of the survey to retrieve.' Baseline 3 is appropriate when the schema carries 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 clearly states a specific action: 'Retrieve a single satisfaction survey by its unique ID.' It uses a specific verb (retrieve), resource (satisfaction survey), and scope (single by ID), which distinguishes it from sibling tools like list_satisfaction_surveys or create_satisfaction_survey.
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 have a specific ID and need a single survey. While it doesn't explicitly mention alternatives or exclusions, the context is clear and the sibling list tool is obviously different in purpose. A slightly more explicit note about using list_satisfaction_surveys for retrieving multiple surveys would earn 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 indicate readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds little beyond the schema's parameter info, but it doesn't contradict annotations or hide any surprising behavior. It lacks extra context like error handling or return format, but for a simple GET this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with zero waste, front-loaded with the HTTP method and resource path. It communicates the essential action immediately and efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter GET endpoint with read-only annotations, the description is sufficiently complete. It states the action, resource, and parameter. It doesn't describe the response shape, but no output schema exists and the operation is standard, so this is a minor gap. Overall, the description provides enough context for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage for the single 'id' parameter, including a description. The tool description's phrase 'by its unique ID' slightly reinforces the parameter's purpose, but it doesn't add meaningful 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?
The description uses a specific verb ('Retrieve') with a clear resource ('a single view') and scope ('by its unique ID'). It clearly distinguishes from sibling tools like gorgias_list_views (list all) and gorgias_update_view (modify).
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 when you have the specific view ID and need that single view. It doesn't explicitly mention alternatives, but the distinction from similar view tools is fairly obvious from the restful pattern and sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds the endpoint and clarifies that the resource includes voicemails, but does not disclose response format or error behavior. 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?
One concise sentence with the endpoint and a clear action. No wasted words 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 simple GET with one param and no output schema, the description adequately covers what the tool does and its endpoint. It could mention the return type, but the low complexity makes this sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single 'id' parameter, which already includes a description. The tool description adds no new parameter information beyond restating 'by its unique identifier', so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb (Retrieve) and resource (voice call recording or voicemail) with a unique identifier, clearly distinguishing it from list or delete operations on the same resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: use this when you have an identifier for a single voice call recording. It does not explicitly mention alternatives, but the context is clear for a simple GET operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the agent knows it is a safe read operation. The description adds behavioral context by mentioning pagination and default ordering (created_datetime:desc), which goes beyond the annotations. It doesn't contradict any annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently conveys the endpoint, purpose, and key filter capabilities. Every word serves a purpose, and there is no redundancy or unnecessary detail.
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, pagination, and default ordering. While there is no output schema to clarify return values, the tool name and description imply a list of customers. The schema handles parameter details, and the description sufficiently orients the agent for a read-only list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the input schema already describes all 11 parameters clearly (e.g., filters, limit, cursor, order_by). The description's list of filters adds no new semantics beyond what the schema provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
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 ('List customers') with the API endpoint, and the name reinforces this. It explicitly distinguishes from single-customer retrieval (gorgias_get_customer) and mutation tools by focusing on listing with pagination and filtering.
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 multiple customers and mentions supported filters, but it does not explicitly state when to use this tool versus alternatives (e.g., for a single customer use gorgias_get_customer) or provide any exclusion criteria. The context is sufficient but not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds useful behavioral context: cursor-paginated results, the need for object_type, and support for name/archived filtering. This goes beyond the static annotation without contradicting it.
Agents need to know what a tool does to the world before calling it. Descriptions 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 endpoint and action in the first sentence, then adding pagination/requirement and filtering details in two more sentences. There is 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 schema coverage (100%) and read-only annotation, the description adequately covers purpose, pagination, entity requirement, and filtering. It does not describe return shape or explicit alternative exclusions, but these are partially addressed by the schema and sibling context, making it complete enough for selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with detailed descriptions for all six parameters, including enums, defaults, and constraints. The description merely echoes the object_type requirement and filter capabilities, adding no new semantic detail 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 'Returns a cursor-paginated list of custom fields' with an explicit HTTP method and the required object_type scoping. It distinguishes the tool from sibling create/update/get custom field operations by specifying the listing behavior and entity scoping.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: list custom fields for a specific entity with optional filters. However, it does not explicitly mention when to prefer this over alternatives like gorgias_list_ticket_fields or gorgias_get_custom_field, nor does it state 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 openWorldHint=true, so the safety profile is known. The description adds value by disclosing that results are cursor-based paginated and scoped to the account, which goes beyond the annotations. It doesn't discuss rate limits or error behavior, but the annotation coverage lowers the burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go 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 HTTP method and resource, then adds key details about filtering and pagination. Every word earns its place with no redundancy or verbosity.
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 combination of description and schema is fairly complete: it explains the return type (Integration objects), pagination mechanism (cursor-based), and account scope. With no output schema, the description's mention of the return type is helpful. It could have noted that only 'http' can be filtered, but the schema covers that. Minor gaps remain around fully explaining pagination navigation, but overall it's solid.
Complex tools with many parameters or behaviors need more documentation. Simple tools need 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 detailed descriptions for type, limit, cursor, and order_by. The description's phrase 'matching the given parameters' is generic and adds no new parameter-specific meaning beyond what the schema already provides. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (List), resource (integrations), and scope (for the account), and mentions the pagination behavior. It distinguishes itself from siblings like gorgias_get_integration (single fetch) and create/update/delete operations by specifying it returns a paginated list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is used to list integrations with optional filters and pagination, but it does not explicitly state when to use this over gorgias_get_integration or other integration-related tools. No exclusions or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the read-only nature is known. The description adds valuable behavioral context beyond annotations: cursor-based pagination, default ordering by created_datetime descending, and the optional ticket filter. This goes beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the HTTP method and endpoint, and concisely covers scope, pagination, filtering, and ordering. 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?
For a list tool with no output schema, the description covers all key aspects: what is listed, pagination mechanism, ordering, and filtering. It lacks mention of response structure, but that is often implied for list endpoints and the schema provides parameter details. The description is complete enough for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters with detailed descriptions, so the baseline is 3. The description adds minimal extra semantic value—it repeats the ticket_id filter and default ordering, but does not introduce any new meaning beyond the schema's existing 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 messages across all tickets, with specific features like cursor-based pagination, optional ticket_id filtering, and default ordering. It distinguishes from siblings like gorgias_list_ticket_messages and gorgias_get_message by explicitly scoping to 'across all tickets'.
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 for when to use the tool (listing messages globally, optionally filtered by ticket). However, it does not explicitly mention alternatives or when not to use it, especially given the existence of sibling gorgias_list_ticket_messages which likely serves per-ticket listing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safe/read-only nature is covered. The description adds actionable behavioral detail: template variables in filters are resolved to the authenticated user's values, which is not captured in annotations or schema. This is a meaningful addition beyond what structured fields already communicate.
Agents need to know what a tool does to the world before calling it. Descriptions 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 endpoint and action. It contains no filler or redundancy, every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list operation with no required parameters, good annotations, and a clear endpoint, the description covers pagination and a non-obvious behavior (template variable resolution). No output schema exists, so the response structure is not explained, but this is a minor gap for a simple list tool. Overall, it 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 covers 100% of parameter descriptions, including limit, cursor, and order_by with clear explanations. The description's mention of cursor-based pagination aligns with the cursor parameter but does not add new details beyond the schema. Hence, 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 ('List all views') and resource ('views'), with a specific endpoint. It distinguishes from sibling tools like gorgias_get_view (single view) and gorgias_list_view_items (items within a view) by indicating this is a list operation for views.
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 listing views, and mentions cursor-based pagination, but does not explicitly state when to use this versus alternatives (e.g., gorgias_get_view for a single view). The context is clear enough, but no exclusions or alternative recommendations are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnlyHint=true, and the description adds cursor-paginated behavior and the strict parameter allowance ('only cursor, limit, and call_id'), which are not in annotations. It does not describe rate limits or ordering but adds meaningful constraints beyond the structured data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise, front-loaded clauses: endpoint and action first, then definition and constraint. No filler and every sentence contributes useful 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 read-only cursor-paginated list with complete schema, the description adequately defines the resource, pagination, and parameter restriction. It does not detail the return shape, but no output schema exists and sibling get_voice_call_event likely covers event 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?
Input schema covers all three parameters with descriptions, so baseline is 3. The description adds only the 'only' restriction and cursor-paginated framing; it does not elaborate on parameter semantics beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States 'List voice call events' with the endpoint path, defines events as 'discrete occurrences during the lifecycle of voice calls,' and cursor-paginated scope differentiates it from single-event retrieval and call listing 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?
Implies usage for listing events and filtering by call_id, but does not explicitly state when to prefer this over alternatives or mention tools like get_voice_call_event or list_voice_calls. The 'accepts only cursor, limit, and call_id' constraint provides some selection guidance but no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds the HTTP method and that results are ordered, but it does not mention pagination behavior, response format, or any potential operational details beyond the annotations and schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that includes the HTTP method, resource path, action, scope, and ordering behavior. There is no redundant or filler content, making it appropriately 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?
Given the tool's simplicity, the well-documented schema, and the helpful annotations, the description is mostly sufficient. It lacks explicit information about return value shape or pagination semantics, but the 'list all' phrasing combined with the schema's limit/cursor parameters provides adequate context for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all five parameters documented in the input schema. The description adds no distinct parameter semantics; it only hints at ordering, which is already represented by the order_by parameter. A baseline of 3 is appropriate since the schema carries the parameter documentation burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'GET /api/widgets — List all widgets for the account, ordered.' It uses a specific verb ('List'), identifies the resource ('widgets'), and clarifies account scope, distinguishing it from sibling tools like get_widget, create_widget, update_widget, and delete_widget.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: use this tool to list all widgets for the account. It does not explicitly name alternatives or state when not to use it, but the resource name and 'list' verb make the usage context obvious relative to sibling get/create/update/delete widget 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 indicate destructiveHint=true, and the description adds valuable context: 'Source tags are deleted after merge.' This goes beyond the annotation by specifying exactly what is destroyed. 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 a single sentence that is front-loaded with the endpoint and action. No wasted words; every part contributes to understanding.
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 merge tool with two fully described parameters and strong annotations, the description covers the essential behavior including the destructive aspect. No output schema exists, but the description does not explain the response; however, this is not critical for a merge 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 provides 100% coverage for both parameters, so the description does not need to add much. The description mentions destination and source but does not add meaning beyond the schema's property descriptions. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the operation: merging source tags into a destination tag. The specific verb 'merge' and the resource 'tags' distinguish it from siblings like delete_tag or delete_tags. The endpoint is also provided for precision.
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 defining the action, but it does not explicitly state when to use this tool versus alternatives like gorgias_delete_tag or gorgias_merge_customers. There is no exclusion or alternative mention, so 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the key behavioral trait that the operation is a full replacement, not a partial update, which goes beyond the annotation metadata. It also scopes to 'current account', providing additional context beyond the readOnlyHint/idempotentHint 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 HTTP method and endpoint, and includes the essential replacement semantics without any filler. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward update operation with well-documented parameters and annotations, the description covers the core behavior (full replacement) and scope. It does not mention response format, but with no output schema and simple update semantics, this is a minor gap given the strong schema and annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all parameters. The description itself does not add parameter-level meaning, but the schema already provides adequate detail (e.g., data replaces existing, type must match). 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 updates a specific AccountSetting by ID via PUT, distinguishing it from create/list operations. It names the resource and the action with precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for updating an existing setting by referencing 'replaces the existing configuration,' but it does not explicitly contrast with creating a new setting using gorgias_create_account_setting. Usage context is implied rather than explicitly directed.
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 cover idempotency (idempotentHint=true) and non-read-only (readOnlyHint=false). The description adds that it returns the updated Integration object, which is useful given no output schema, but it does not disclose behavior like partial vs. full replacement of fields, which is a significant ambiguity for an update tool with many optional 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 two sentences, front-loaded with the HTTP method and endpoint, and contains no fluff. It efficiently conveys the core purpose, the minimum requirement, and the return value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderately complex schema with nested objects and no output schema, the description provides the essential return type ('returns the updated Integration object') and the core update intent. The field-level details are well-covered by the schema, and annotations fill the safety profile. However, it lacks guidance on how optional fields behave during updates, which 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 provides 100% coverage with descriptions for all parameters, so the baseline is 3. The description adds no additional parameter meaning beyond restating that 'name' is required and mentioning the HTTP endpoint, which is already reflected in the schema's required list.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 an existing integration by its ID' with the HTTP method PUT specified. This distinctly differentiates it from sibling tools like create_integration, delete_integration, and get_integration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context that this is for updating existing integrations and requires at least a name. It implies the need for an existing integration ID, though it doesn't explicitly mention alternatives like create or delete. No when-not-to-use guidance is given beyond the implied existing-entity requirement.
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 disclose readOnlyHint=false and idempotentHint=true, and the description adds little beyond noting it's a POST batch operation. It lacks details on failure semantics or auth, but the endpoint and 'single request' provide some context. 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 one sentence, front-loaded with the HTTP method and action, and contains zero filler. It efficiently conveys the 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?
For a simple one-parameter batch operation with a comprehensive schema and no output schema, the description is nearly complete. It could add a note about atomicity or partial failure behavior, but given the minimal complexity, it is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with meaningful descriptions for 'id' and 'priority' (including the higher-values-first behavior). The description's mention of 'execution priority' adds no new parameter information beyond what the schema already provides, so it defaults to 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 action ('Batch update') and target ('execution priority of multiple rules'), distinguishing it from siblings like gorgias_update_rule (single rule) and gorgias_list_rules (listing). It is specific and directly tied to the endpoint's 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 wording 'in a single request' conveys the batch use case, strongly implying this tool is for updating multiple rule priorities at once. It does not explicitly name alternatives or state when not to use it, but the context is clear enough to guide selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint=false) and idempotent. The description adds the PUT method, explains how to resolve the field ID, requires that the value type match the field's data_type, and mentions that null clears the value. It does not cover error behavior or permissions, but the annotation coverage lowers the bar somewhat.
Agents need to know what a tool does to the world before calling it. Descriptions 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 front-loads the endpoint and purpose, the second packs ID resolution, type requirements, and null-clearing behavior. It is efficient and contains no 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 4-parameter mutation tool with no output schema, the description covers essential invocation details: endpoint, field ID source, value types, and clearing. The schema fills parameter descriptions. The only clear gap is the ambiguous dual-ID situation (id vs definition_id), which could confuse an agent, but overall the description is sufficient for correct use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with descriptions for all parameters. The description essentially repeats the schema's explanations for 'id' and 'value' and does not add new meaning. It also fails to clarify why both 'id' and 'definition_id' are required and how they relate, which is a notable gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Update') and resource ('the value of a single custom field on a ticket'), and includes the exact endpoint. The phrase 'a single custom field' distinguishes it from the sibling tool gorgias_update_ticket_fields, which implies bulk updates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for updating one custom field value on a ticket, and provides field type matching guidelines. However, it does not explicitly say when to use this tool instead of related tools like gorgias_update_ticket_fields or gorgias_update_customer_field_value, and it gives no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already communicate readOnlyHint=false and idempotentHint=true. The description adds useful behavior (PUT method, partial update, id=0 special case) but does not disclose other potential side effects or prerequisites such as password confirmation requirements, which remain only in 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 that conveys the endpoint, action, and key usage tip without any fluff. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of 17 parameters and no output schema, the description is concise but still provides the essential context for selecting the tool: it updates an existing user, supports partial updates, and has a special id=0 case. The rich schema and annotations cover the remaining invocation 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 coverage is 100%, with each parameter having a detailed description. The tool description itself adds no additional parameter semantics beyond what the schema provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('Update an existing user by ID'), includes the HTTP method and resource, and adds a distinctive special case (id=0 for current user). This distinguishes it from sibling update tools like gorgias_update_customer or gorgias_update_tag.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear usage guideline: 'Only include fields to modify' indicates partial update semantics. It does not explicitly mention alternatives like gorgias_create_user, but the guidance is sufficient for typical 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?
Annotations already provide readOnlyHint=true, and the description aligns with that by using 'Retrieve'. The description adds value by listing the returned fields (status, type, params, info/progress, timestamps), which is useful behavioral context about the response beyond what annotations convey. 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?
The description is two sentences, front-loaded with the HTTP endpoint, and includes all essential information without fluff. Every sentence contributes meaning: the purpose and the return value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-resource getter with one parameter and no output schema, the description fully covers the endpoint, purpose, parameter, and expected return content. It is complete enough for an agent to invoke the tool correctly and understand the response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the parameter description 'The unique ID of the job to retrieve' is clear and self-sufficient. The description does not add extra semantics beyond what the schema provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Retrieve a single job by its unique ID' with a specific verb, resource, and scope. It distinguishes itself from sibling tools like list_jobs (plural), create_job, update_job, and cancel_job by explicitly targeting a single job retrieval by ID.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage is implied by the description—use this when you have a job ID and need full details—but there is no explicit guidance about alternatives or when not to use it. It does not mention list_jobs for discovering jobs or create/update/cancel for mutations, so the guidance remains implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safe read nature is established. The description adds the expected return fields (name, description, decoration, usage count, timestamps) but does not discuss error behavior, auth, or other edge cases. This is some added value 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 compact two-part sentence: the HTTP endpoint and a clear verb-driven purpose, followed by the return fields. Every word earns its place, and it is front-loaded with the main action.
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 one-parameter read operation with readOnlyHint annotation, the description provides sufficient information: it identifies the tag, what it returns, and implies a single result. No output schema exists, but the listed return fields cover the essentials.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage for the only parameter 'id', with a clear description. The tool description merely repeats the concept of a unique ID and does not add additional semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Retrieve a single tag by its unique ID'), specifies the resource and scope, and differentiates from siblings like gorgias_list_tags by indicating a single-tag fetch by ID. The HTTP method and path also add 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 implies the use case (when you have a specific tag ID), which distinguishes it from listing or mutation tools. However, it does not explicitly name alternatives or state when not to use it, though the singular scope makes the guidance fairly 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 the description's 'Retrieve' and GET method align with that. No additional behavioral context is provided (e.g., error behavior, authorization), but given the strong annotation coverage, the description doesn't need to over-explain.
Agents need to know what a tool does to the world before 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 with the endpoint and action, no fluff. Ideal length and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-resource retrieval with strong annotations and a fully documented parameter, the description covers the essential usage. No output schema is present, but the tool's purpose is unambiguous.
Complex tools with many parameters or behaviors need more documentation. Simple tools need 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 'id' is fully documented in the schema with a description and constraints, and the description's 'by its unique ID' adds no new semantic information. Schema coverage is 100%, so the description doesn't need to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Retrieve a single widget by its unique ID' with a specific verb (Retrieve) and resource (widget), and the path GET /api/widgets/{id} clearly distinguishes it from sibling list/create/update/delete 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?
It clearly implies usage when an ID is available for a single widget, distinguishing from gorgias_list_widgets. However, it doesn't explicitly state exclusions or name alternatives, so it misses the '5' bar.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the description adds value by mentioning the return format ('array of field definitions with their current values') and the exact endpoint. 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-loads the endpoint and purpose, and contains no superfluous text. Every word contributes 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 one-parameter list operation with good annotations, the description sufficiently explains purpose and response shape. The absence of an output schema is compensated by the explicit mention of what is returned.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides full coverage of the single parameter customer_id with a clear description. The tool description adds no additional parameter nuance, so a baseline score is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all custom field values set for a customer' with the specific endpoint, distinguishing it from related tools like gorgias_list_custom_fields which would list field definitions globally rather than per-customer values.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use the tool (when you need a specific customer's custom field values) but does not explicitly mention alternatives or when not to use it, leaving the agent to infer from the name and sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the description's addition of 'cursor-paginated' and the explicit accepted-parameter list provides useful behavioral context (pagination and filtering constraints) without contradicting 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, front-loaded with the HTTP method and direct action, and includes only necessary clarifications about the resource and accepted parameters. 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, read-only listing endpoint with no output schema, the description sufficiently covers the resource type, pagination behavior, and the only supported parameters. It is complete enough for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes all three parameters with types and meanings, so the description's mention of 'only cursor, limit, and call_id' adds no new semantic value. It merely reiterates schema information, warranting the baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' with the resource 'voice call recordings,' clarifies 'voicemails and call recordings,' and notes cursor pagination. This distinguishes it from single-resource siblings like gorgias_get_voice_call_recording and from delete operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage 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 is a listing operation but does not explicitly contrast it with alternatives or specify when to use it versus getting or deleting a single recording. The note about accepting only cursor, limit, and call_id implies a narrow scope, but no direct 'when to use' guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so safety and partial results are known. The description adds valuable context beyond annotations: order number search uses 'Gorgias server-side full-text search across ticket subjects, messages, and metadata,' and it discloses auto-detection limitations for ambiguous numeric queries. It does not mention pagination or result format, but the annotation coverage lowers the burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, but every sentence adds critical value: the purpose, usage guidance, and a follow-up tool reference. It is front-loaded and free of filler or redundant restatement of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 parameters, 2 enums, no output schema), the description addresses the main ambiguities an agent might face, such as when to use search_type and what the order number search covers. It lacks explicit details about return structure or pagination, but the schema's limit parameter and the mention of 'tickets, customers, and views' provide sufficient context for initial invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and each parameter already has a meaningful description. The tool description enhances the semantics of the query and search_type by explaining when to set search_type explicitly and how auto-detection handles different input types. It also clarifies the underlying search behavior for order numbers, going beyond the schema's enum descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs an 'Intelligent search across tickets, customers, and views,' giving a specific verb and resource. It does not explicitly contrast with the sibling gorgias_search, but the phrase 'smart search' and the detailed discussion of auto-detection differentiate it enough. It could be clearer about how it differs from gorgias_search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use the search_type parameter: 'Use the search_type parameter when intent is clear from context' and especially for ambiguous numeric queries. It also explains the strengths of auto-detection for emails, keywords, view names, and customer names. It names gorgias_smart_get_ticket as the alternative for viewing full conversations, but does not discuss when to prefer other search-related siblings like gorgias_search.
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 write operation (readOnlyHint: false), and the description adds context about how the created integration behaves ('calls an external URL when specific ticket events occur'). This goes beyond the annotation by explaining the purpose of an HTTP integration. However, it doesn't disclose permission requirements or response format, so it's not a perfect score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the HTTP method and resource, and contains no filler. Every word adds value, 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 tool with a nested 'http' object and multiple parameters, the description provides a solid high-level overview, and the schema fills in the details. It lacks information about the return value, but the absence of an output schema lowers the need. It's adequate 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?
Schema coverage is 100%, so the baseline is 3. The description adds a minor note about HTTP being the primary type, which reinforces the 'type' parameter's constraint, but it doesn't provide additional semantics beyond what the schema already documents in 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 clearly states the action ('Creates a new integration'), specifies the resource ('within the Gorgias helpdesk system'), and distinguishes the tool by noting the primary supported type is HTTP integration. This differentiates it from sibling tools like get/update/delete integration.
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 (to create a new integration) and notes that the REST API only supports HTTP integrations, which guides the agent toward the 'type' parameter. It doesn't explicitly name alternatives like update_integration, but the create action is inherently distinct from list/get/update/delete siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true, but the description adds the critical nuance of irreversibility: 'Deletion is irreversible.' This goes beyond the simple destructive flag and informs the agent that the action cannot be undone.
Agents need to know what a tool does to the world before calling it. Descriptions should go 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 HTTP method and endpoint, immediately stating what it does and adding the irreversible caveat. There is 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 simple one-parameter delete tool with strong annotations, the description is sufficient. It states the action, target, and consequence. It does not mention side effects on associated data, but this is not essential 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 provides a full description for the 'id' parameter (100% coverage). The tool description adds no additional parameter-level details beyond confirming the user is identified by ID, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Permanently delete a single user by ID' uses a specific verb (delete), resource (user), and scope (single by ID). It clearly distinguishes from sibling delete tools like delete_customer and delete_team by naming the user resource.
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 identifies when to use this tool: when a user needs to be permanently deleted by their ID. It does not explicitly mention alternatives or exclusions, but given the resource-specific siblings, the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds that deletion is irreversible (beyond just destructive) and states the success response code '204 No Content', which is not present in 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 composed of two sentences with no extraneous content. It front-loads the HTTP method and endpoint, making it immediately actionable and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter delete operation with no output schema, the description covers purpose, irreversibility, and success response. The openWorldHint suggests potential external side effects that are not elaborated, but overall the description is sufficiently complete for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully documents the single 'id' parameter with a description and validation constraints, achieving 100% schema description coverage. The description adds no additional parameter semantics beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the HTTP method and endpoint ('DELETE /api/widgets/{id}') with the verb 'delete' and resource 'widget'. This makes the tool's purpose unmistakable and distinguishes it from sibling deletion tools for other entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly warns that the operation is 'Permanently delete' and 'irreversible', providing a clear when-not-to-use condition (if reversibility is needed). It does not explicitly name alternative tools, but the context is sufficient for simple deletion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=true and openWorldHint=true annotations, the safety profile is already known. The description adds value by stating that the return is the full Integration object and highlights HTTP configuration details for HTTP-type integrations, which informs the caller about possible response complexity. This goes beyond the bare annotation and enriches behavioral expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that starts with the HTTP method and resource. It contains no filler or redundant phrasing, every clause adds meaningful information about scope and return content, 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 GET-by-ID tool with a fully documented schema and read-only annotations, the description adequately covers the primary context: what is retrieved and what is returned. It does not explicitly address error behavior or when to prefer list_integrations, but given the low complexity and existing annotations, this is not a significant gap. It falls just short of fully complete because it omits any mention of not-found responses or relationship to sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage for the single 'id' parameter, including a clear description. The description only repeats 'by its ID' without adding extra syntax, format, or edge-case context. Per calibration, when schema coverage is high, a baseline of 3 is appropriate unless the description offers supplementary meaning, which it does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 and resource: 'Retrieve a single integration by its ID.' It specifies the action (GET) and distinguishes from siblings like list_integrations or create_integration by focusing on a single record retrieval. It also adds specific return details (full Integration object with HTTP configuration), 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: use this tool when you need a specific integration by ID. It does not explicitly mention synonyms like 'use list_integrations to see all' but the ID-based lookup is unambiguous. No exclusions or alternative tool references are given, but the simple nature of the operation makes the usage context 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 indicate readOnlyHint and openWorldHint, so the safety profile is known. The description adds value by specifying the return payload: 'full TicketMessage object including content, sender/receiver details, attachments, timestamps, and metadata.' This goes beyond the annotations and helps the agent understand what to expect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that starts with the HTTP endpoint and immediately states the purpose and return type. It is concise, front-loaded, and free of any 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 simple read-only retrieval tool with complete schema coverage and strong annotations, the description provides sufficient context: it explains the resource, required IDs, and return structure. It does not elaborate on potential errors or authentication, but these are less critical for a GET endpoint and the annotations already signal safety.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage with clear descriptions for both required parameters (ticket_id and id). The description adds no additional semantic detail beyond what the schema offers, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Retrieve a single message by its ID within a specific ticket.' It uses a specific verb ('Retrieve') and resource ('message by ID within a ticket'), and it distinguishes from sibling tools like list_messages or get_ticket by emphasizing the single-message scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context: you need both a ticket_id and a message ID to fetch a specific message. It clearly identifies when to use this tool (to get one message) but does not explicitly mention alternatives or when not to use it, which is acceptable given the tool's straightforward nature.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds valuable behavioral details: it returns an array of AccountSetting objects, does not support pagination, and supports filtering by type. This goes beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the endpoint and purpose. Every phrase carries information: the response type, pagination behavior, and filter capability. No redundant words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description clearly covers the core behavior: listing all settings, the optional filter, and the return type. Without an output schema, it does not detail the AccountSetting object structure, but for a simple list tool with one optional parameter, the information is sufficient for an agent to call 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 already provides a detailed description of the 'type' parameter, and the description's statement 'Supports filtering by type' adds no new meaning. With 100% schema coverage, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the HTTP method and resource path ('GET /api/account/settings') and the action ('List account settings'). It distinguishes this read-only listing tool from sibling tools like create/update account setting by its verb and scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It specifies the scope ('for the current account') and explicitly notes the lack of pagination, telling the agent that a single call returns all settings. It also mentions filtering by type, which provides usage context. It does not explicitly contrast with create/update alternatives, but the purpose is self-evident.
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, so the safe-read nature is known. The description adds useful behavioral details: the REST endpoint, cursor-based pagination, and ordering by created_datetime descending. It does not contradict 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, compact sentence that front-loads the endpoint and resource. It includes the most important information without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with good annotations and full schema coverage, the description covers the essential behavior: endpoint, filtering, pagination, and ordering. It does not describe the return format, but this is inferable for a list operation and no output schema exists. The gap is minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters are already documented in the schema. The description mentions status/type filtering and pagination, but these are also covered by the schema descriptions. No additional parameter meaning is added 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 'GET /api/jobs — List all jobs', identifying the resource and operation with a specific verb. It also mentions optional filtering and pagination, which distinguishes it from sibling tools like gorgias_get_job (single job) and gorgias_create_job.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys that this tool is for listing jobs, with filtering by status/type, which implies its use case. It does not explicitly exclude alternatives, but the list semantics are clear enough to guide selection. No explicit 'use when' or 'use instead' is given, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this as a read-only operation. The description adds behavioral context by specifying that it supports cursor-based pagination and that it lists all macros, not just a single one. It does not contradict annotations and provides additional detail about the operation's scope.
Agents need to know what a tool does to the world before calling it. Descriptions 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 HTTP method and core purpose. It lists filter types and pagination without wasted words, making it highly scannable.
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 10 optional parameters and no output schema, the description gives a good overview of capabilities: listing all macros, filtering options, and pagination. It doesn't detail response structure, but the absence of an output schema means the tool's purpose as a list operation is clear enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so each parameter is already well-documented with descriptions. The description only summarizes the filter categories, which aligns with the schema but doesn't add new semantics beyond what's already present.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all macros' which identifies the action and resource. It also lists optional filters and pagination, distinguishing it from singular get_macro and mutation macros.
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 list all macros with optional filtering. It doesn't explicitly name alternative tools, but the context is sufficient for an agent to distinguish this from create/update/delete/get macro operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds cursor-based pagination behavior, which is valuable beyond annotations. It does not contradict annotations and gives a hint about the response pattern.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that packs the endpoint, action, resource scope, and pagination type. Every word contributes value, with no redundancy or irrelevant details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with optional pagination parameters and no output schema, the description covers the essential purpose and behavior. It could mention return format, but the annotations and sibling context make the tool's usage clear enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with detailed descriptions for limit, cursor, and order_by (including default and max). The description adds no additional parameter semantics, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all rules' with the HTTP endpoint, specifying the verb (GET) and resource (rules). This distinguishes it from sibling tools like get_rule (single rule) or mutation 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 listing all rules with pagination. It does not explicitly name alternatives, but the sibling tool list makes it obvious that get_rule is for individual rules. There are no explicit exclusions, but the use case is unmistakable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds valuable context: it returns a cursor-based paginated response with a data array and meta.next_cursor, and confirms ordering. This goes beyond the structured annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that efficiently conveys the REST method, path, purpose, and response format. No redundant content or unnecessary 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 list with 3 optional parameters and no output schema, the description adequately covers purpose, filtering, ordering, and pagination format. It does not mention error cases or defaults, but those are not critical given the schema and 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 100% of parameters with detailed descriptions. The description only says 'matching the given parameters' and 'ordered', which does not add meaning beyond the schema. Baseline 3 applies as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List teams matching the given parameters, ordered' with the endpoint 'GET /api/teams'. It distinctly identifies a batch-list operation, differentiated from siblings like gorgias_get_team (single team) and gorgias_create_team.
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 that this tool lists teams, implying use when retrieving multiple teams or applying filters. It does not explicitly mention alternatives, but the verb and resource make the use case obvious, and there are no exclusions or misleading statements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare this a read-only operation, and the description adds valuable detail beyond that: the response envelope ({data: [...]}), the exact structure of each item (field, prediction, value), and the behavioral note that field.id serves as the identifier for subsequent mutation operations. This is meaningful 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?
The description is two sentences, front-loaded with the endpoint and action, followed by the response shape and a usage hint. Every clause earns its place: endpoint, purpose, return format, item structure, and actionable guidance. No wasted words or repetition of schema 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 read-only list operation with a single parameter and no output schema, the description is unusually thorough: it gives the endpoint, the response structure, the item attribute names, and how to use the returned IDs for mutations. It lacks only details like pagination or error handling, which are not critical for this simple endpoint. The presence of sibling tools is handled by the clear scoping to ticket custom field values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes ticket_id with a clear description, and the schema coverage is 100%. The tool description does not add any extra parameter-level semantics beyond what the schema already provides. It does explain the return structure in the context of the item, but not the parameter itself, 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 lists all custom field values for a specific ticket using the GET endpoint. It distinguishes itself from siblings like gorgias_list_custom_fields (which lists field definitions) and gorgias_list_customer_field_values (which handles customer, not ticket, fields). The verb 'list' plus the resource 'ticket custom field values' makes 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 clear context: use when you need custom field values assigned to a specific ticket. It also gives follow-up guidance, noting that field.id is used for update/delete operations. However, it does not explicitly compare with alternative sibling tools or state when not to use it, 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 already declare readOnlyHint and openWorldHint, and the description adds valuable behavioral traits such as cursor-based pagination and the supported filter fields. It does not contradict annotations and provides useful context beyond the safety hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence, front-loaded with the HTTP method and resource, and lists key capabilities without any filler. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given full schema coverage and annotations, the description provides a solid overview of the tool's purpose, pagination, and filters. However, with no output schema, it does not explicitly describe the response shape (e.g., paginated list with cursors), which is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description summarizes several filter parameters (email, external ID, role, search, ordering) but does not add syntax or semantics beyond the schema. Other params (limit, cursor, available_first) are only covered by the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'GET /api/users — List users' with a specific verb and resource, and enumerates filtering and pagination capabilities, distinguishing it from user mutation tools and 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 implicitly conveys when to use the tool (whenever listing users with filters/pagination) but does not explicitly compare with alternatives like get_user for single-user retrieval. It provides clear context without exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the description is not burdened with stating safety. It adds valuable behavioral context by specifying cursor-paginated behavior and the constraint that only cursor, limit, and ticket_id are accepted. This goes beyond the annotations and schema, providing insight into how the endpoint behaves.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the HTTP method and endpoint, and every phrase contributes information. It avoids fluff and is appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/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 no output schema, the description covers the essential behavior: what it does, how it paginates, and which parameters are allowed. It does not describe the response format, but the annotations (readOnlyHint) and parameter schema provide sufficient context. The pagination mention is valuable, and the tool is not complex enough to require more.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter (limit, cursor, ticket_id) having a clear description. The description adds the note that the endpoint accepts 'only' these parameters, which is a slight constraint but largely redundant with the schema since only these are defined. It adds little 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 verb 'List' and the resource 'voice calls', with the explicit endpoint path 'GET /api/phone/voice-calls'. It distinguishes from sibling tools like gorgias_get_voice_call by indicating the plural, list-oriented nature, and the cursor-paginated behavior is a specific characteristic.
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 listing voice calls with cursor-based pagination, and it notes the accepted query parameters. However, it does not explicitly mention when to prefer this over alternatives (e.g., gorgias_get_voice_call) or when not to use it, so it stops short of full explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint false, idempotentHint true), the description adds the crucial partial-update behavior—omitted fields remain unchanged. This is exactly the kind of context that helps an agent avoid overwriting data unintentionally, though it doesn't cover error handling 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?
Two sentences, front-loaded with the HTTP method and resource, and every word earns its place. The partial-update note is the single most important semantic and is included without any fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich schema and annotations, the description provides the essential behavioral context (partial update) in a concise way. It doesn't enumerate all parameters, but the schema already handles that, and the tool's core purpose is fully covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with rich descriptions for all 12 parameters, so the description is not required to repeat them. It adds the general partial-update concept but no per-parameter details beyond what the schema already provides, justifying the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Update an existing customer by ID' with the HTTP method, clearly identifying the action and resource. It distinguishes itself from sibling tools like create_customer and delete_customer, and the mention of 'partial update semantics' further clarifies the tool's specific 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 gives clear context: use this to update an existing customer, and only send the fields you want to modify. It doesn't explicitly mention when not to use it or point to alternative update tools, but the guidance is unambiguous and sufficient for most 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?
The description adds critical behavioral detail: 'if you include `actions`, the entire actions array is replaced — you cannot append individual actions.' This goes beyond the annotations' idempotency and open-world hints, alerting the agent to a common pitfall. It also clarifies the partial-update semantics.
Agents need to know what a tool does to the world before calling it. Descriptions 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 HTTP method and purpose. The caution about `actions` is necessary and positioned prominently. 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 partial update with 6 params and no output schema, the description covers the key behavior, including the actions replacement. It could mention error handling or prerequisites, but the annotations and schema cover the safety profile sufficiently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides descriptions for all 6 parameters (100% coverage). The description adds a general statement that all body fields are optional, which applies across parameters, and restates the actions replacement nuance already present in the schema. This is useful but incremental.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 'Partial update of a macro by ID' along with the HTTP endpoint, making the verb and resource explicit. It distinguishes this from sibling tools that create, get, or delete macros.
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 specifies that all body fields are optional and only supplied fields are modified, providing clear context for when to use this partial update. It does not explicitly mention alternatives or exclusions, which prevents a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=true), the description discloses the key partial-update behavior—only supplied fields are modified—and illustrates with practical examples. This adds informational value without contradicting the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the HTTP method and action. Every clause contributes: the action, the partial-update rule, and practical examples, with no superfluous 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?
For a moderately complex tool with 8 parameters and no output schema, the description captures the essential behavioral nuance of partial updates and provides enough context for correct use. It does not mention return values or error handling, but the schema and annotations cover the remaining details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides thorough descriptions for all 8 parameters (100% coverage), so the baseline is 3. The description adds slight value by suggesting common parameter manipulations (bump priority, edit description) but does not deeply elaborate on individual parameter semantics beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update a rule by ID' with the HTTP method, making the action unambiguous. It distinguishes from sibling tools by focusing on a single rule with partial updates, rather than bulk operations like update_rules_priorities.
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, emphasizing partial updates: 'All body fields are optional; only the fields you supply will be modified' and giving common examples like toggling deactivated_datetime or editing description. However, it does not explicitly mention alternatives such as create_rule or update_rules_priorities, so the guidance is contextual rather than explicitly exclusive.
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 readOnlyHint=false and idempotentHint=true, so the agent knows this is a write operation. The description adds the key behavioral nuance that only provided fields are updated (partial update semantics despite PUT), which is not expressed in the annotations. It does not discuss error conditions or permissions, but the essential mutation behavior is disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the endpoint and purpose, followed by a concise usage note. Every phrase earns its place, with no redundant or vague words. It is an excellent example of minimal yet informative description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 13 parameters and no output schema, the description is adequate because the schema thoroughly documents each parameter and annotations provide safety cues. It does not mention response format or error scenarios, but for an update operation with a known endpoint, this is sufficient. The description could be slightly richer, but it is not incomplete enough to warrant a lower score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 13 parameters have detailed descriptions in the schema (100% coverage), so the description does not need to restate them. The only parameter-related addition is 'Only include fields to modify,' which is a general note rather than per-parameter meaning. This meets the baseline for comprehensive schema coverage but adds little beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Update an existing view by ID' and includes the HTTP method PUT, clearly indicating this tool modifies an existing view. This distinguishes it from sibling tools like gorgias_create_view, gorgias_get_view, and gorgias_delete_view. The phrase 'Only include fields to modify' further clarifies its partial-update 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 provides clear context: use this tool when you need to update an existing view, identified by ID. It also advises to include only the fields to modify, which is a practical usage guideline. It does not explicitly mention alternatives or exclusions, so it falls short of a 5, but 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false (write), idempotentHint=true, and openWorldHint=true. The description adds crucial context about the PUT method and full-replacement semantics, warning that omitted fields may be lost. This goes beyond the basic annotations, though it does not detail auth requirements or error responses.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the HTTP method and resource path. Each sentence adds value: the first states what it does, the second explains the critical full-replacement behavior and usage hint. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 parameters, nested template object) and lack of output schema, the description provides the essential semantic of full-replacement. However, it does not mention what the response contains or any special considerations for nested fields. Still, with strong annotations and schema, this is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all 8 parameters with descriptions, achieving 100% coverage. The description itself does not add any parameter-specific meaning, but the schema already provides sufficient semantics. This aligns with the baseline of 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the operation as 'PUT /api/widgets/{id} — Update an existing widget by ID', which is a specific verb and resource. It distinguishes from sibling tools like create or delete by focusing on updating an existing widget.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by noting this is a 'full-replacement operation' and instructs to 'Include all fields you want to retain.' This implies it should be used when replacing the entire widget, and cautions against partial updates. However, it does not explicitly name alternative tools for partial updates, though none exist among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructive behavior and idempotence. The description adds valuable context by explicitly stating the scope of deletion (value assignment only) and the success status code (204 No Content), which goes beyond the annotations and clarifies the tool's actual effect.
Agents need to know what a tool does to the world before calling it. Descriptions 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, starting with the HTTP method and endpoint, followed by a clear explanation of the operation, a key distinction from related operations, and the expected response. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter delete tool with no output schema, the description covers the essential behavioral details: the exact effect, the non-effect, and the success response. Combined with the annotations, it provides a complete picture for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are fully documented in the schema. The description reinforces the meaning of 'id' but doesn't add new information beyond the schema, making it a baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the verb 'Remove' and the resource 'custom field value from a customer', clearly distinguishing it from deleting the custom field definition. The HTTP method and path are also given, making the tool's purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear 'when-not' by stating 'it does NOT delete the custom field definition', which helps prevent a common misuse. It also clarifies the id parameter references the definition ID, but it doesn't explicitly name alternative tools or broader usage context, earning a 4 rather than 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 destructiveHint=true and readOnlyHint=false, but the description adds the critical context that deletion is 'permanent,' which is not explicitly in the annotations. It also specifies the HTTP endpoint 'DELETE /api/customers', providing additional behavioral clarity beyond the structured hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the HTTP method and purpose, and contains no filler. Every word earns its place by conveying the endpoint, bulk nature, and permanent outcome.
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 only one parameter, clear annotations, and no output schema. The description covers the essential aspects: what it does, how it operates (bulk delete via DELETE), and the permanent impact. For a straightforward bulk delete operation, this is complete and sufficient for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the only parameter 'ids', and its description 'A list of customer IDs to delete' fully explains the property. The tool description simply restates this without adding extra meaning, so it meets the baseline for high schema coverage but adds no additional value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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: 'Bulk delete multiple customer records' and 'permanently deletes all specified customers.' It uses a specific verb and resource, and the 'Bulk' qualifier distinguishes it from the sibling singular 'gorgias_delete_customer'.
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 bulk deletion when multiple customer IDs need to be removed. It doesn't explicitly mention alternatives like 'gorgias_delete_customer' for single deletions, but the title and context provide clear guidance. However, missing explicit exclusions or alternative references keeps it from 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 declare destructiveHint=true and readOnlyHint=false. The description adds valuable context beyond annotations: deactivating dependent views and blocking deletion when used in rules or other integrations. This is meaningful behavioral disclosure for a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the endpoint, and every sentence contributes essential information: purpose, side effects, and deletion constraints. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter delete tool with strong annotations, the description is complete. It covers the operation, consequences (views deactivated), and constraints (rules/integrations usage), which is sufficient for the agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides full documentation for the id parameter (type integer, min/max, description). The tool description does not add any additional parameter semantics; hence score is at baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Delete an integration' with the endpoint. This specific verb+resource distinguishes it from sibling delete tools (e.g., gorgias_delete_customer) and other integration 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 provides clear context that this tool deletes an integration and includes important constraints (views deactivated, cannot delete if used in rules/integrations). It does not explicitly mention alternatives like update or list, 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?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the agent knows this is a destructive operation. The description adds valuable context with 'Permanently delete' (irreversibility) and the restriction on system views, which goes beyond the annotation flags.
Agents need to know what a tool does to the world before calling it. Descriptions 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 core action, and includes no wasted words. Every sentence provides useful 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 delete-by-ID tool, the description covers all essential aspects: the action, permanence, and a critical constraint. Combined with comprehensive schema and annotations, no additional context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the 'id' parameter, which includes a description. The description only says 'by ID', adding no extra meaning beyond the schema. Baseline 3 applies because the schema already documents the parameter adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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: 'Permanently delete a view by ID.' It also includes the HTTP method and a distinguishing constraint (system views cannot be deleted), which separates it from sibling create/update/get/list view 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 a clear when-to-use (deleting a view by ID) and an explicit when-not (system views like Trash and Spam cannot be deleted). However, it does not mention alternative tools or operations (e.g., updating a view instead), so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructive and non-read-only behavior. The description adds value by emphasizing 'Permanently delete' and specifying the success response (204 No Content). It also broadens scope to include voicemail, which is beyond what the tool name alone suggests.
Agents need to know what a tool does to the world before calling it. Descriptions 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 a single sentence that covers the operation, the endpoint, the permanence, and the expected response. No filler words; every element contributes to understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation with one parameter, no output schema, and robust annotations, the description provides sufficient context. It states the HTTP method, the permanent nature, the success response, and the resource affected. No critical information 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?
The input schema provides 100% coverage with a clear description for the single parameter 'id'. The tool description does not add additional parameter semantics, but this is unnecessary because the schema fully explains the parameter's meaning and constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Permanently delete a voice call recording or voicemail.' It uses a specific verb (delete), identifies the resource (voice call recording/voicemail), and distinguishes from sibling retrieval tools like get_voice_call_recording. The HTTP method is also specified.
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 permanently delete a voice call recording or voicemail. There are no explicit exclusions or alternative recommendations, but the purpose is unambiguous enough that an agent can infer when to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so safety is known. The description adds value by specifying the response contents 'full Macro object including all actions, metadata, and timestamps,' which is 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?
Single sentence, front-loaded with the endpoint and action, 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 single-ID retrieval with readOnlyHint and no output schema, the description sufficiently covers what it does and returns. No more is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%; the schema already describes the id parameter thoroughly. The description's mention of 'unique ID' adds no new semantic information, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Retrieve a single macro by its unique ID,' specifying the verb and resource. It distinguishes from sibling tools like list_macros, create_macro, update_macro, delete_macro by focusing on a single retrieval by ID.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies correct usage (when you have a specific macro ID), providing clear context. It does not explicitly name alternatives like list_macros, but the 'single macro' phrase signals when to use this tool over list operations.
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 useful context beyond the readOnlyHint annotation by explicitly listing the returned fields (name, description, decoration, members, timestamps) and specifying the GET method. This tells the agent what to expect from the response without an output schema, though it doesn't disclose other behaviors like rate limits or auth (which may be irrelevant for a simple read).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that starts with the endpoint and follows with the action and return fields. Every word earns its place; there is no fluff, 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.
Completeness5/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's enumeration of return fields is essential and sufficiently complete for a single-resource read tool. The one-parameter input is fully covered by the schema, and the description provides all necessary context: endpoint, action, field, and expected response content.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents the 'id' parameter comprehensively (type, range, required, description). The description merely repeats that it retrieves by ID, adding no new parameter-level semantics. With 100% schema coverage, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Retrieve') and clearly specifies the resource ('a single team by its unique ID'), which distinguishes it from siblings like list_teams, update_team, and delete_team. It also identifies the HTTP method and endpoint, leaving no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies usage: call this when you have a team ID and need a single team's details. However, it does not explicitly mention when not to use it or name alternatives (e.g., gorgias_list_teams for listing all teams), so it falls short of full explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the agent knows this is safe. The description adds the useful detail that id=0 returns the authenticated user and exposes the HTTP GET method. 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?
Two concise sentences that front-load the endpoint and purpose, with 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 single-parameter read tool, the description covers purpose, the special id=0 behavior, and is consistent with annotations. No output schema is needed for such a standard resource 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?
The schema already fully documents the id parameter, including the special 0 value, so description adds no new semantic information. Baseline 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Retrieve') and resource ('a single user by ID'), and adds the special case of id=0 for the authenticated user. This clearly distinguishes it from list-oriented siblings like gorgias_list_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 conveys the intended use case—retrieving a specific user by ID—and the id=0 special case. However, it does not explicitly contrast with gorgias_list_users or gorgias_update_user, so 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, establishing safety. The description adds valuable behavioral context by stating the response is 'not cursor-paginated' and specifying the return shape ({data: [...]} with tag array and fields), which is beyond what annotations provide. This helps the agent understand pagination and output expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the endpoint and purpose, followed by essential response details. Every sentence earns its place with no redundant 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-only list tool, the description covers the purpose, response format, pagination behavior, and field contents. Combined with strong annotations and full schema coverage, the agent has all needed context to select and invoke the tool correctly. No output schema exists, but the description compensates by detailing return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single parameter, with ticket_id described as 'The unique ID of the ticket whose tags to list'. The description does not add additional semantic meaning beyond the schema, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'List all tags currently associated with a specific ticket' using a specific verb and resource. It distinguishes itself from sibling tools like gorgias_list_tags (global tag list) and gorgias_add_ticket_tags/remove_ticket_tags (mutations) by focusing on a specific ticket's tags.
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 when you need tags for a specific ticket. It does not explicitly mention alternatives or exclusion cases, but the specificity of 'associated with a specific ticket' provides strong contextual guidance. A slightly higher score would require explicit sibling differentiation.
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 critical behavior beyond annotations: the source customer is deleted after the merge, and the operation fails with 409 if both customers share data for the same integration. This complements the destructiveHint and readOnlyHint annotations 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 a concise two-sentence summary that front-loads the endpoint and core action, then adds a key failure condition. No wasted words or redundant restatements.
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 detailed schema and annotations, the description is sufficiently complete: it explains the purpose, the destructive side effect, and a significant error case. No output schema exists, so return value explanation is 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?
Schema coverage is 100%, so the schema already fully documents all parameters. The description adds context about merge behavior but does not elaborate on individual parameter formats or special values beyond what is in the schema. Baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific verb 'merge' with the resource 'two customers' and explains the source-to-target data flow plus deletion of the source. This distinguishes it from sibling tools like delete_customer or update_customer.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage is implied by the operation itself (merge two customers), but there is no explicit guidance on when to use this vs alternatives such as combining delete+create or updating fields individually. No exclusions or alternative tools are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds useful operational details beyond the annotations: it states the restoration effect, the bulk limit of 30 IDs, and the per-ID results format. With no output schema, this return format is particularly valuable. It is consistent with the idempotentHint and readOnlyHint=false.
Agents need to know what a tool does to the world before calling it. Descriptions 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, starting with the endpoint and primary action, followed by three short sentences each containing a distinct fact: restoration effect, 30-ID limit, and per-ID results. 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 one-parameter bulk mutation, the description captures all essential details: endpoint, action, effect, constraint, and response format. It does not need to explain return values further because the per-ID results statement covers it. This is complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully documents the 'ids' parameter with type, min/max items, and a description, providing 100% coverage. The tool description adds no extra parameter semantics beyond the redundant 'by ID' phrasing, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Bulk unarchive multiple previously archived macros'), the resource (macros), and the effect ('Restores macros to active status'). It distinguishes from siblings by specifying 'previously archived' and the bulk nature, making it distinct from archive/delete operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it by targeting 'previously archived macros' and specifying the bulk operation (max 30 IDs per request). It doesn't explicitly name alternatives or exclusions, but the context is clear enough for an agent to select it over archive or delete macros 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 indicate a write operation (readOnlyHint: false) and idempotent PUT (idempotentHint: true). The description adds useful behavioral nuances beyond annotations, specifically the mandatory inclusion of required fields even for unchanged values and the deactivation rule via deactivated_datetime, which clarifies PUT semantics.
Agents need to know what a tool does to the world before calling it. Descriptions 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 front-load the HTTP method and resource. Every sentence provides a specific, actionable detail with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 10 parameters, nested objects, and no output schema, the description provides some critical guidance but omits an explicit statement about full-replace semantics (e.g., what happens to omitted optional fields) or return values. The required-field warning hints at PUT semantics, but it could be more explicit for a complex 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 coverage is 100% with detailed descriptions for all 10 parameters, so the baseline is 3. The description adds extra meaning by emphasizing that the three required fields must always be included even if unchanged, and by explaining the deactivation behavior of deactivated_datetime, which goes slightly beyond the schema's per-property descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates a single custom field by ID using PUT, identifying the specific resource and action. It distinguishes from siblings like bulk_update_custom_fields or create_custom_field by focusing on a single-object update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit context: the three required fields must always be included even if unchanged, and deactivation is achieved by setting deactivated_datetime to a past timestamp. It does not explicitly mention alternatives, but the single vs. bulk usage is implied by the tool name and sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a mutation (readOnlyHint=false), so the description does not need to state that. It adds useful context beyond the annotations: the operation is additive, existing tags are preserved, and on success it returns 201 with an empty body. This gives the agent expectations about side effects and response format, which are not available from the structured fields 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 and front-loaded with the HTTP method and endpoint. Every sentence adds value: the first states the action and endpoint, the second explains the additive nature, accepted input formats, the required constraint, and the success response. There is no 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 add-tags operation, the description covers the essential aspects: endpoint, additive behavior, parameter requirements, and success response. It does not elaborate on error cases, idempotency for duplicate tags, or permission requirements, but given the straightforward nature and the presence of sibling tools, it is reasonably complete. The openWorldHint suggests potential side effects, but the description does not need to over-explain for this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides full descriptions for all three parameters, so the baseline is 3. The description goes beyond the schema by stating that at least one of 'ids' or 'names' must be provided and that they can be combined, which is a critical constraint not encoded in the JSON schema (no anyOf). This adds meaningful value to parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Add one or more tags to a ticket' and identifies the HTTP endpoint, making the verb and resource specific. It also distinguishes itself from sibling tools by highlighting that the operation is additive and preserves existing tags, which is a clear differentiator from set_ticket_tags or remove_ticket_tags.
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 operational guidance: tags can be specified by IDs or names, and at least one of those fields must be provided. It also implies when to use this tool (for adding without removing) via the additive note, but it does not explicitly name alternative tools like set_ticket_tags or remove_ticket_tags, so it misses a direct exclusion.
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=false and idempotentHint=true, indicating a safe-to-retry write operation. The description adds valuable partial-update semantics ('Only id is required per item; all other fields are optional'), which clarifies which fields will be changed. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long and immediately front-loads the HTTP method, endpoint, and core action. Every sentence adds value—there is no filler or redundant restatement of the title. It is appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich input schema that documents all nested properties, the description provides the essential framing for how to construct the 'fields' array. It does not elaborate on return values or error behavior, but with annotations covering safety and idempotency, the tool is reasonably complete 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.
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 a concise summary of the array structure and the requirement that each item must contain an id, while reinforcing that other fields are optional. This goes beyond the schema's property-level descriptions by explaining the top-level usage pattern.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Bulk update') and resource ('custom fields') with explicit scoping ('multiple custom fields in a single request'). It distinguishes itself from the sibling gorgias_update_custom_field by emphasizing the bulk nature, leaving no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys the intended use case for batch updates ('Bulk update multiple custom fields') vs single-field updates, but it does not explicitly name alternative tools or provide when-not-to-use guidance. The context is clear enough for an agent 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as destructive and not read-only, but the description adds 'Permanently' and 'irreversible', which clarifies that the deletion cannot be undone. This goes beyond the structured annotations and is valuable behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loaded with the HTTP DELETE endpoint. It includes all essential information without wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with strong annotations, the description is nearly complete. It covers what is deleted, that it is permanent, and that it is by ID. However, it does not mention what happens upon success (e.g., response format) or explicitly reference the bulk-delete alternative, which would tighten 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 schema has 100% coverage with the id parameter described as 'The ID of the customer to delete.' The description only says 'by ID', adding no extra meaning beyond what the schema already provides. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool permanently deletes a single customer by ID, using a specific verb and resource. The phrase 'single customer' distinguishes it from bulk-delete siblings like gorgias_delete_customers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates this is for deleting one customer by ID, which implies the use case. However, it does not explicitly mention when not to use it (e.g., for bulk deletion use gorgias_delete_customers) or provide an alternative, so it lacks a full exclusion.
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 annotations declare destructiveHint=true, but the description goes further by disclosing that views using deleted tags will be deactivated and that tags used in macros/rules cannot be deleted. This provides critical side-effect and constraint information beyond the 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?
The description is three short sentences. The first states the core action, the second and third add essential behavioral caveats without wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one parameter and no output schema. The description covers the action, side effects, and constraints, but doesn't mention error handling or response format. Given the simplicity, it is adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with the 'ids' parameter described as 'Array of tag IDs to delete'. The tool description only says 'by ID' and does not add additional parameter semantics, 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 states 'Bulk delete multiple tags by ID' with a specific verb, resource, and scope. It clearly distinguishes from the sibling gorgias_delete_tag by emphasizing 'bulk' and 'multiple'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for deleting multiple tags at once, but does not explicitly name alternatives like gorgias_delete_tag for single deletion. The bulk context is clear, but no exclusions or comparison to singular delete tool 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 declare readOnlyHint=true, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: the precise URL-to-parameter mapping and that the file is private, which helps the agent correctly construct requests.
Agents need to know what a tool does to the world before calling it. Descriptions 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 endpoint and purpose. The second sentence provides an explicit example for parameter derivation, with no wasted words 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?
No output schema exists, but the tool's purpose as a download implies the response is the file content. The description covers the essential operational steps (URL mapping) and is sufficient given the simplicity of the tool and strong annotations.
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 descriptions for each parameter, so baseline is 3. The description adds meaning beyond the schema by explaining how all parameters derive from the attachment URL and providing a concrete example ('https://gorgias.io/attachments/abc123/file.png' maps to file_type='attachments', etc.).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 downloads a private file from Gorgias's servers, with a specific verb ('Download') and resource. It also explains the URL path structure, distinguishing it from related tools like upload_file.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool: when you have an attachment URL and need to download its file. It doesn't explicitly state alternatives or exclusions, but the context is clear and the URL mapping guidance is strong.
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, so the safety profile is covered. The description adds valuable context about the response contents (customer, messages, tags, custom fields, assignees, satisfaction survey, metadata) and explicitly labels it as the 'raw API response,' which helps an agent set expectations about data granularity. It does not contradict the openWorldHint annotation, as it describes a read operation that may return varied data but no 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 two sentences long, front-loaded with the HTTP method and purpose. The first sentence states exactly what the tool does; the second sentence provides the alternative and lists response components without unnecessary elaboration. Every sentence earns its place with zero 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 single-ticket read operation, the description is quite complete: it specifies the endpoint, the raw nature of the response, the key data fields, and the alternative for a cleaner view. With readOnly annotations and no output schema, this provides enough context for an agent to select and invoke the tool correctly. Minor gaps like pagination or error handling are not critical for this type of operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters (id and relationships). The description adds no additional parameter-level detail, but it does mention 'custom fields' in the response, which loosely relates to the relationships parameter. The baseline of 3 applies because the schema carries the parameter documentation burden and the description provides marginal extra value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 ('Retrieve a single ticket's raw API response') and resource (ticket by ID), and explicitly distinguishes it from gorgias_smart_get_ticket by contrasting the raw response with the LLM-optimised view. This makes it easy for an agent to know exactly what this tool does and how it differs from a sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use the alternative tool: 'For a clean, LLM-optimised view... use gorgias_smart_get_ticket instead.' This gives a clear when-not-to-use directive and names the alternative, satisfying the highest bar for usage guidelines.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safe read-only nature is covered. The description adds behavioral context beyond annotations: raw message format, deprecation status, and lack of pagination support, which helps the agent understand expected behavior and limitations.
Agents need to know what a tool does to the world before calling it. Descriptions 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 endpoint and action, followed by two precise sentences of guidance. No word is wasted; deprecation and alternatives are efficiently conveyed.
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 read-only tool, the description covers the core purpose, deprecation, and alternatives. However, it does not explicitly state what the raw response contains or note pagination behavior of the current endpoint, though the deprecation note implies limitations. Still, completeness is strong for 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?
Schema coverage is 100% with ticket_id fully described as 'The unique ID of the ticket whose messages to list.' The description only references ticket_id in the endpoint URL without adding extra parameter semantics, matching the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List raw messages for a ticket' with the HTTP endpoint, making the action and resource explicit. It distinguishes itself from gorgias_smart_get_ticket and gorgias_list_messages by noting the alternative use cases, so the purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly directs when to use alternatives: 'use gorgias_smart_get_ticket instead' for a clean projected view, and 'prefer gorgias_list_messages with ticket_id filter for pagination support.' It also flags the endpoint as deprecated, providing clear decision guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=false, idempotentHint=true, and openWorldHint=true. The description adds valuable behavioral context: value type must match the field's data_type, passing null clears the value, and clarifies the path 'id' is the custom field definition ID. It doesn't mention auth or side effects, but the annotations cover the safety profile.
Agents need to know what a tool does to the world before 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 HTTP method and endpoint, no fluff. Every sentence contributes essential information about what the tool does and how to invoke it correctly.
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 4 required parameters and no output schema, the description covers the key operational aspects: purpose, ID semantics, value type constraints, and null behavior. It doesn't specify response behavior, but for a simple update tool and given the annotations, this is sufficient. Slight gap is the lack of explicit alternative tool guidance.
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 all 4 parameters with 100% coverage. The description adds meaning by explaining the relationship between the path 'id' and the body 'definition_id', and gives concrete type mapping (string for text, number for number, boolean for boolean) plus null semantics, going 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 specific action (update) and resource (value of a single custom field for a given customer), and the endpoint is given. It distinguishes from siblings like gorgias_update_customer_fields (plural) by emphasizing 'single' custom field.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for updating a single custom field value, and contrasts with bulk or plural updates via the word 'single'. However, it does not explicitly name alternative tools or state when not to use this tool, so it stops 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?
The annotations already signal that this is a non-read-only, idempotent operation. The description adds meaningful behavioral context by disclosing the partial-update behavior, which prevents agents from assuming omitted fields are reset. This goes beyond the structured annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—three short sentences front-loaded with the endpoint and action. Every sentence adds meaningful information (endpoint, modifiable fields, patch behavior) with 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?
Given the tool's moderate complexity (nested params, no output schema), the description covers the essential behavioral context: what can be updated and how partial updates work. The schema fully documents the parameters, and the annotations cover idempotency. A small omission is not explaining job-type-specific param variations, but that is documented in the schema itself.
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 input schema provides 100% parameter descriptions, the description adds value by stating that only fields in the request body are updated, clarifying parameter semantics for partial updates. This helps agents construct payloads without sending all fields. Beyond that, it does not duplicate schema details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update a job by ID') with the HTTP method and path. It lists the specific modifiable fields (meta, params, scheduled_datetime, status), which distinguishes it from sibling tools like create_job, cancel_job, and get_job.
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 using the tool on an existing job and explicitly notes the partial-update semantics ('Only fields included in the request body are updated'), which is important guidance. However, it does not explicitly compare against alternatives such as create_job or cancel_job, so it lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds meaningful behavioral context beyond the annotations: it specifies the return status (202 Accepted), the full updated TicketMessage object, and the role of the action param. Annotations already cover read-only/idempotent/open-world hints, and there is 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 three succinct sentences, front-loaded with the operation and resource, and each sentence provides key information without 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?
For a complex 22-parameter mutation tool with no output schema, the description covers the essential context: purpose, required fields, return value, and a notable edge case (action param). The comprehensive schema and annotations fill in the remaining 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?
The input schema has 100% parameter description coverage, so the baseline is 3. The description adds value by highlighting the action param's purpose (recovery from failed external actions) and reiterating the required fields, giving a slight boost 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 the exact operation ('Update an existing ticket message') with the HTTP method and resource path. This clearly distinguishes it from sibling tools like gorgias_create_message, gorgias_get_message, and gorgias_delete_message.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies usage for modifying an existing ticket message and adds a specific usage note for the action query param to handle recovery from failed external actions. However, it does not explicitly state when not to use the tool or name alternative 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 discloses partial-update semantics and the destructive replacement behavior for tags and custom_fields, which goes beyond the annotation hints (readOnlyHint=false, openWorldHint=true, idempotentHint=true). It does not mention return format or auth, but annotations already signal the mutation 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, front-loaded with the endpoint and purpose. Each sentence carries distinct value: method, partial-update behavior, and dangerous replacement caveats. No fluff 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 23 params and 100% schema coverage, the description covers the non-obvious partial-update and replace semantics that the agent most needs. It omits return value details, but no output schema exists and annotations provide idempotency/open-world context, so the description is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema provides descriptions for all 23 parameters, so the baseline is 3. The description adds the critical general semantic that only provided fields are updated, and reinforces the replace-all warnings for tags/custom_fields, exceeding what the schema alone conveys.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update an existing ticket' with the specific HTTP method and path, distinguishing it from create/delete operations. It also proactively points to dedicated tag endpoints, which differentiates it from sibling tag-management tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit guidance that omitted fields retain current values, and warns that tags and custom_fields are wholesale replaced. It names dedicated tag endpoints as alternatives, but does not explicitly mention field-specific update tools like update_ticket_field(s), which are also siblings.
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?
Despite annotations providing destructiveHint=true and readOnlyHint=false, the description adds crucial context: archiving is not permanent deletion, max 30 IDs per request, and returns per-ID results. This goes beyond the safety profile and gives meaningful behavioral expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently packages the HTTP method, endpoint, action, behavioral caveat, limit, and return format. 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 one-parameter mutation with annotations, the description provides essential details: endpoint, action, non-permanent nature, request limit, and per-ID results. This is sufficient for an agent to correctly select and invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides full coverage of the single 'ids' parameter with min/max constraints and description. The tool description mentions 'Max 30 IDs per request' which reinforces but does not add new meaning beyond the schema's own 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 states a specific verb and resource: 'Bulk archive multiple macros by ID' with the endpoint PUT /api/macros/archive. It clearly distinguishes from sibling tools like delete_macro and unarchive_macros by clarifying that archiving is non-permanent.
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 clarifies that archiving removes macros from the active list without permanent deletion, implying when to use archive vs delete. It also specifies the bulk nature and 30-ID limit. However, it does not explicitly name alternatives like unarchive_macros or delete_macro.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds critical context: cancellation is always allowed but does not revert already-applied changes, and a successful call returns 204 No Content. This goes beyond the structured hints and gives the agent a clear expectation of 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?
Two sentences, front-loaded with the HTTP method and action, and no filler. Every clause adds meaningful signal: the action, the cancellation timing, the non-revert warning, and the success response.
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 one-parameter cancel operation with no output schema, the description covers the essential behavioral contract: what happens on success, side effects, and the fact that cancellation is unrestricted. Combined with annotations, it provides a complete picture.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes the only parameter 'id' as 'The unique ID of the job to cancel' with 100% coverage. The description simply says 'by ID', adding no additional semantic nuance. Baseline 3 is appropriate given high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states exactly what the tool does: 'Cancel a job by ID.' It uses a specific verb (cancel) and resource (job), and clearly distinguishes it from sibling tools like get_job, create_job, or update_job. The HTTP method 'DELETE' reinforces the action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on when cancellation is appropriate ('Jobs can be canceled at any time') and a key caveat ('changes already applied will not be reverted'). It doesn't explicitly name alternative tools for similar actions, but the purpose is clear enough that an agent would know when to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint, idempotentHint, and readOnlyHint=false. The description adds important behavioral details: irreversibility, the 409 conflict condition, and the 204 No Content success response, going well beyond the structured hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences, front-loaded with the HTTP method and resource. Every word contributes: permanence, irreversibility, conflict condition, and success response. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter delete operation, the description covers the essential outcomes (204 success, 409 failure) and the irreversibility warning. No output schema exists, but the response behavior is specified, making the description complete for this tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, id, is fully documented in the schema with its own description. The phrase 'by ID' in the description adds little beyond the schema, so baseline 3 is appropriate since schema coverage is 100%.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('delete'), the resource ('macro'), and the targeting mechanism ('by ID'). It emphasizes 'permanently delete' and 'cannot be undone', which distinguishes it from archive_macros and other macro-related operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context on when deletion is allowed (not if in use by active rules) and the resulting 409 Conflict, which implies that archiving might be an alternative for in-use macros. However, it doesn't explicitly name archive_macros as the alternative, so guidance is slightly 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 (destructiveHint=true, readOnlyHint=false), the description adds crucial behavioral details: deletion is irreversible, the parent ticket remains unaffected, and a successful call returns 200 OK with an empty body. This gives the agent a complete picture of side effects and expected response.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the endpoint and action. It consists of two sentences that cover purpose, irreversibility, scope, and response behavior with 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 delete operation with two well-documented parameters and a clear annotation set, the description is complete. It covers the effect, scope (parent ticket preserved), and return value, leaving no significant gaps for an agent to misuse the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% descriptive coverage for both parameters (id and ticket_id) with clear explanations. The description adds no additional semantic meaning beyond what is in the schema, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Permanently delete a specific message from a ticket' with a clear verb and resource. It distinguishes from deleting the parent ticket by explicitly noting 'The parent ticket is not deleted', which differentiates it from sibling tools like gorgias_delete_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 about when to use this tool by specifying what it does (delete a message) and what it does not do (does not delete the parent ticket). However, it does not explicitly mention alternative tools or exclusion criteria, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, and the description adds crucial behavioral context: 'Deletion is irreversible' and 'Tickets previously assigned to the team will lose their team assignment'. This goes beyond the annotation by explaining what exactly gets destroyed, which is exactly the kind of context that helps an agent understand consequences. 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 a single, front-loaded sentence that begins with the HTTP method and resource, then provides critical caveats (irreversibility and ticket assignment loss). Every element adds value 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?
This is a simple delete operation with one parameter, no output schema, and strong annotations. The description fully covers the operational context, including side effects and irreversibility. It is complete for an agent to correctly select and invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters with a description for the id field. The tool description only says 'by ID' and adds no new semantics beyond what the schema already provides. With full schema coverage, the baseline of 3 is appropriate; the description does not need to compensate further.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb and resource: 'Permanently delete a team by ID'. It also distinguishes itself from sibling tools by focusing on deletion and mentioning the irreversible nature and effect on tickets. This leaves no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context: use when you need to permanently delete a team. It provides important context about irreversibility and the consequence for tickets, which helps the agent decide whether this is the right tool. However, it does not explicitly mention alternatives or when not to use it, though the purpose is clear enough to avoid confusion with update/get 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 mark this as destructive and idempotent. The description adds valuable context by explaining the destructive scope is limited to the value assignment, not the field definition, and by noting the 204 No Content response. This enhances understanding without contradicting 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 three sentences, each earning its place: the endpoint and action, the scope clarification, and the parameter/response detail. It is front-loaded with the HTTP verb and resource, with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation with only two well-described parameters and no output schema, this description fully covers the behavioral scope, parameter meanings, and success response. The presence of annotations covers safety expectations, and the description adds the critical distinction from definition deletion.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both 'id' and 'ticket_id' having descriptions. The main description repeats the 'id' explanation from the schema but adds no new parameter-level information, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific action ('Remove a custom field value from a ticket') and immediately disambiguates the resource by stating it does NOT delete the custom field definition. This clearly distinguishes it from other ticket-related deletion tools in the sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly clarifies when to use this tool (to remove a value assignment) and when not (not to delete the definition). The phrase 'does NOT delete the custom field definition' provides an explicit exclusion, and the parameter clarification gives useful context for correct invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the safety profile is known. The description adds behavioral context by noting the tool returns 'raw ticket data' and uses 'cursor-based pagination,' which helps the agent understand the output and pagination behavior beyond the basic read-only hint. It does not disclose rate limits or error cases, but given the annotation coverage, the added 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?
The description is three sentences with no filler. It front-loads the endpoint and core purpose, then immediately gives the alternative for intelligent search, followed by a concise list of filters and pagination. Every sentence earns its place, making it both efficient and readable.
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?
Even without an output schema, the description thoroughly conveys the tool's role, capabilities, and relationship to a sibling tool. It mentions the endpoint, pagination, filtering options, and trashed-ticket behavior, which is complete for a list-like operation. The agent can confidently decide when and how to invoke this tool based on the description alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage of all 9 parameters with descriptions, so the description does not need to add new syntax details. It does summarize the key filtering categories (customer, external ID, view, rule, ticket IDs, trashed), which helps the agent quickly grasp capabilities, but this is a recap rather than new semantic meaning. Thus, the schema remains the primary source of parameter 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 clearly states it returns a paginated list of raw ticket data via a GET request, making the purpose specific and actionable. It also distinguishes itself from the sibling tool gorgias_smart_search by explicitly naming that alternative for intelligent search, which eliminates ambiguity.
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 when-not-to-use directive: 'For intelligent search with auto-detection of emails, names, views, and keywords, use gorgias_smart_search instead.' This clearly guides the agent away from this tool for intelligent search and implies it is the right choice for raw, filterable ticket lists, covering both selection and exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations declare readOnlyHint=true and openWorldHint=true, and the description does not contradict them. The description adds useful behavioral context beyond the annotations, such as the query structure depending on the scope field, support for filtering/grouping/measures/time analysis, and cursor-based pagination. It does not mention rate limits or auth, but the read-only annotation provides a baseline.
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 long but well-structured: it front-loads the core purpose, then the alternative, then capabilities, and finally a comprehensive scope list. The sentence 'Retrieve analytics reporting statistics data' is somewhat redundant with the opening line, but the extensive scope list and procedural details justify the length for a tool of this complexity.
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 complex low-level API with no output schema, the description covers the core aspects: the low-level nature, the alternative, scope semantics, query capabilities, and pagination. It does not explicitly describe the response format, which could be a gap, but the detailed scope and measure/dimension lists give agents enough context to infer expected results.
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 significant meaning by enumerating all 27 scopes with parenthetical explanations (e.g., 'tickets-closed (closed ticket stats)'), which goes beyond the schema's bare enum list. This helps the agent select the correct scope and understand the resulting query shape.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as 'Retrieve analytics reporting statistics data' and its low-level nature ('POST /api/reporting/stats — Low-level reporting API'). It distinguishes itself from the sibling tool gorgias_smart_stats by positioning itself as the low-level alternative, which makes 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 Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to prefer the alternative: 'For easier stats with automatic scope defaults, dimension validation, agent name resolution, and date handling, use gorgias_smart_stats instead.' This provides clear when-not-to-use guidance and names the alternative, making the use case boundaries explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate a write operation with idempotency, and the description adds valuable behavioral details: partial update semantics (fields not included are left unchanged) and the return format (array of updated field value objects). This goes beyond the structured hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, front-loaded with the endpoint and action, and every sentence provides necessary detail without redundancy. It is highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with two parameters (one being an array of objects) and no output schema, the description covers the request shape, key field requirements, partial update behavior, and return type. This is complete enough 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 already provides 100% description coverage for both parameters, including the requirement for 'id' to be the custom field definition ID and the value type rules. The description reinforces this but does not add new semantic meaning beyond what the schema offers, 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 updates multiple custom field values on a customer in a single request, using a specific verb and resource. It distinguishes itself from the singular sibling tool by highlighting the batch nature and the specific endpoint.
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 update multiple fields in one request) and explains that omitted fields are left unchanged. However, it does not explicitly name alternatives or say when not to use it, though the bulk vs singular distinction is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond annotations by revealing key behaviors: the need for 'CUSTOM FIELD DEFINITION ID' from a specific endpoint, the semantics that fields not included are left unchanged, and the return format of updated field value objects. This adds valuable context beyond the readOnlyHint=false and idempotentHint=true annotations, giving the agent a clear model of 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 three sentences, front-loaded with the HTTP method and endpoint, and every sentence delivers essential information (purpose, parameter requirements, behavior, return value). No redundant or vague language is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, the description explains the return value and behavior sufficiently. It covers the API endpoint, parameter semantics, idempotent-like behavior (fields not included unchanged), and the critical distinction of definition IDs. This is a complete and self-sufficient description for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage with detailed descriptions for both ticket_id and fields, including the definition ID requirement and value type constraints. The description mostly restates this information (e.g., 'id' requires definition ID) and adds only slight behavioral context about unchanged fields, which does not substantively enhance parameter understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action: 'Update multiple custom field values on a ticket in a single request.' It clearly identifies the resource (ticket custom fields) and differentiates from siblings by emphasizing bulk ticket-specific updates and the exact API endpoint. This unambiguously distinguishes it from similar tools like gorgias_bulk_update_custom_fields.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear contextual guidance by noting this is for batch updates in a single request and that fields not included are left unchanged, implying a partial update use case. However, it does not explicitly compare itself to alternatives like gorgias_update_ticket or gorgias_bulk_update_custom_fields, which would have made usage boundaries more precise.
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?
Adds context beyond annotations: explains asynchronous sending behavior when sent_datetime is omitted, and how to create internal notes (public=false). No contradiction with readOnlyHint=false.
Agents need to know what a tool does to the world before 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 tightly written sentences, front-loaded with the action and endpoint. No 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?
Despite 29 parameters, the schema covers all semantics and the description covers the three primary scenarios. Missing output format information, but no output schema is provided, and it doesn't hinder correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% description coverage, so the baseline is 3. The description adds value by grouping parameters into three use cases, clarifying the role of sent_datetime, channel, and public. However, it doesn't explain other complex params like meta or action beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new message on an existing ticket' with the HTTP endpoint, and it differentiates from sibling tools like get_message/update_message by specifying the creation action and ticket association.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly outlines three use cases with specific parameter guidance (omit sent_datetime for send, provide it for import, set channel to internal-note and public=false for notes). This is strong when-to-use guidance, though it doesn't name alternatives.
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, so the description doesn't need to restate safety. It adds useful context beyond annotations by specifying that the account is tied to authentication credentials and that the returned data includes metadata and account-wide settings, giving the agent a clearer picture of the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, front-loaded with purpose and endpoint, followed by a key usage note. Every word earns its place with no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple read-only tool with no parameters, no output schema, and strong annotations. The description fully covers what it does, what it returns, and how the account is identified, making it complete for its complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters, the schema provides no semantics. The description explicitly states 'No parameters required' and explains that the account is determined by authentication credentials, fully clarifying the parameter situation and going beyond the baseline for param-less tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Retrieve') and identifies the exact resource ('account information including metadata and account-wide settings'). It even includes the HTTP endpoint for traceability. This clearly distinguishes it from sibling tools like list_account_settings, which focus on settings lists rather than the account object itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: no parameters are required, and the account is determined by authentication credentials. This tells the agent when to use the tool and what to expect. However, it does not explicitly mention alternatives or when not to use it, so it falls short of a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate a non-read-only, idempotent operation, but the description adds crucial behavioral detail: the PUT is a full-replacement, so customer_id and ticket_id must be re-sent to preserve linkage. This goes beyond the annotations by revealing the destructive nature of omitting 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?
Two sentences: the first states the endpoint and purpose; the second gives the critical caveat and prerequisite tool reference. No fluff, well front-loaded, and structurally clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a 10-parameter schema fully described and annotations covering idempotency and openness, the description provides the essential full-replacement warning and the read-first step. However, it doesn't mention the response format or error cases, which would be helpful but isn't strictly required given the rich 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%, so the schema already documents all parameters thoroughly. The description reinforces the importance of customer_id and ticket_id but doesn't add meaning beyond what the schema states (e.g., 'Required: PUT is a full-replacement operation').
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update an existing satisfaction survey by ID') and specifies the resource and ID parameter. It distinguishes from siblings by referencing the PUT method and full-replacement semantics, making it unambiguous against create/get/list survey tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs to 'Read the survey first via gorgias_get_satisfaction_survey to obtain the IDs,' naming the alternative tool to use beforehand. It also explains the full-replacement requirement, giving clear context for when this update should be performed.
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 annotations already indicate destructiveHint=true and readOnlyHint=false, but the description adds critical context: the deletion is irreversible and removes associated messages, tags, and custom field values. This goes beyond simple annotation flags and warns of collateral 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?
Two sentences, front-loaded with the HTTP method and action. The first sentence states the core purpose, and the second adds crucial caveats and an alternative. No wasteful 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 one-parameter delete operation with clear destructive effects, the description fully covers what an agent needs to know: the endpoint, irreversibility, associated data removal, and a safer alternative. The lack of an output schema is acceptable for delete operations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage for the single 'id' parameter, including a clear description. The tool description doesn't add parameter-specific details, which is acceptable when schema covers it fully. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource: permanently delete a ticket by ID. It also clarifies the scope of deletion (associated messages, tags, custom field values) and distinguishes from the soft-delete alternative via 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 Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises using trashed_datetime via Update Ticket for a soft-delete instead, providing clear guidance on when to use this tool vs. an alternative. This is a direct when/when-not comparison.
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 (destructive, idempotent), the description discloses the HTTP method, that tags can be specified by IDs/names/both, the partial removal behavior, and the 204 empty body response. This gives the agent a clear picture of runtime 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?
Three tightly-worded sentences front-load the endpoint and action, then provide essential detail without fluff. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description states the 204 success response, covers the parameter combination rule, and clarifies scope (only specified tags removed). Sibling tool names provide additional context, but the description is self-sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers parameter descriptions, but the description adds critical usage semantics: tags can be specified by IDs, names, or both, and at least one of them must be provided. This goes beyond the schema's optional field flags and enforces a business rule.
Input schemas describe structure but not intent. Descriptions should explain non-obvious 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 the specific action 'Remove specific tags from a ticket' with the endpoint, and clarifies that only specified tags are removed while others remain. This clearly distinguishes from sibling tools like add_ticket_tags, set_ticket_tags, and delete_tag.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context (selective removal) with 'Only the specified tags are removed; other tags remain,' and sets a precondition requiring at least one of 'ids' or 'names'. However, it does not explicitly name alternatives like set_ticket_tags when a full replacement is intended.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond annotations by explicitly stating that all existing tags not included are removed, how to clear all tags with an empty body, and that IDs/names can be combined. It also notes the success response (202). This richly complements the destructiveHint 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?
Five concise sentences cover the endpoint, destructive behavior, clearing mechanism, accepted input formats, and response. No filler or redundancy; every sentence carries meaningful 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 destructive tag-replacement tool, the description explains the core behavior, edge case (empty body), input flexibility, and success response. Combined with strong annotations, it is fully sufficient for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already provides thorough descriptions for all three parameters (100% coverage). The description adds practical guidance that IDs and names can be used independently or together, and that an empty body clears all tags, which is not obvious from the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 'Replace the complete list of tags on a ticket' with a specific HTTP verb and resource, which distinguishes it from sibling tools like add/remove/list ticket tags. The destructive-replacement behavior is explicit in the first sentence.
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 for when to use the tool (full replacement) and warns about destruction of omitted tags, but does not explicitly mention alternative tools (e.g., gorgias_add_ticket_tags) for non-destructive updates. This is clear context without direct exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations only declare readOnlyHint and openWorldHint. The description adds valuable behavioral details: automatic defaults, validation, post-processing, auto-pagination across pages, the 366-day date range constraint, cursor-driven manual pagination, and a list of broken scopes. This significantly exceeds what the annotations convey.
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 longer than average but structured with line breaks and category headers, making it scannable. The first sentence front-loads the core purpose. Some content, such as the exhaustive scope list, is necessary for correct tool selection and could not be easily trimmed without losing value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (10 parameters, many scope options) and the absence of an output schema, the description does a solid job explaining behavior, pagination, and constraints. It covers return-related concepts like rows and nextCursor, though it doesn't fully describe the response shape. Still, it provides enough context for an agent to choose and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers all 10 parameters with descriptions (100% coverage), so the baseline is 3. The description goes beyond by grouping scopes by category, calling out broken scopes, explaining when to use granularity 'none', and showing how to use the cursor with nextCursor. These additions give real semantic 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 opening sentence states a specific action: 'Retrieve Gorgias analytics with automatic defaults, validation, post-processing, and auto-pagination.' It clearly identifies the resource (Gorgias analytics) and distinguishes itself from the raw sibling tool by explicitly directing raw API needs to gorgias_retrieve_reporting_statistic. The scope categories further clarify what kinds of analytics are included.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool versus the alternative: 'For raw API access, use gorgias_retrieve_reporting_statistic.' It also gives actionable conditions for problematic queries (e.g., use granularity: "none" for many rows) and warns about broken scopes that return API errors. This is strong, practical usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as a write operation and idempotent. The description adds crucial behavioral details: all fields are optional (patch-like semantics despite PUT) and the members field performs a full replacement when provided. This warns about a potentially destructive action, going beyond the annotation-provided safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences, opens with the HTTP method and resource, and every clause provides essential information. There is no filler or redundant repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with five parameters and no output schema, the description covers the core operation, optionality, and the key behavioral caveat about members replacement. This is sufficient for an agent to understand when and how to invoke the tool without missing critical semantics.
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 has 100% coverage with descriptions for every parameter, so the baseline is 3. The description complements it by clarifying that only provided fields are updated and that members replaces the entire list, adding practical meaning beyond individual field notes.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 'PUT /api/teams/{id} — Update an existing team by ID.' This identifies the specific verb (update), resource (team), and requires an ID, distinguishing it from sibling create_team and delete_team 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?
It conveys the update context and highlights partial update behavior ('All fields are optional; only provided fields are updated'), implying you should use this when modifying an existing team. However, it does not explicitly name alternatives or scenarios where this should not be used, so it falls short of a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses crucial runtime behavior beyond the readOnlyHint annotation: auto-pagination up to max_messages, the truncated=true flag for over-cap tickets, and chronological ordering (oldest first). This level of detail helps the agent understand response completeness and memory/processing implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded. Each of the four sentences adds distinct value: purpose/format, pagination behavior, truncation flag, and usage guidance. No wasted words 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 tool with no output schema, the description conveys the essential return characteristics (full thread, clean format, pagination, truncation, sort order). It also points to alternative tools for raw data and search. It doesn't spell out the exact fields in the clean format, but the overall behavior is sufficiently 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 coverage is 100%, providing definitions for both 'id' and 'max_messages'. The description adds value by elaborating on max_messages' purpose (pagination control), default value, hard cap, and the tradeoff for lowering it. This enriches the semantic understanding beyond the schema text.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Retrieve a ticket with its full conversation thread'. It further clarifies the output is 'projected to a clean format optimised for LLM consumption', and distinguishes itself from the raw 'gorgias_get_ticket' alternative, making its 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 Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided: 'Use gorgias_smart_search to find tickets first' and 'For raw API data, use gorgias_get_ticket instead'. It also explains when to tune max_messages (lower for cheap recall, raise for full audit history), giving clear context for effective use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the tool's non-functionality, the technical reason (multipart/form-data not supported by a JSON-only client), and a workaround. This goes far beyond the readOnlyHint=false and openWorldHint=true annotations, preventing wasted calls and setting accurate expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two efficient sentences, front-loaded with the essential 'NOT FUNCTIONAL' warning, then providing reason and alternatives. No unnecessary words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is non-functional, the description fully covers the limitation, cause, and alternative actions. No output schema or return values are needed because the tool cannot execute successfully.
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 documents both parameters thoroughly (100% coverage). The description adds critical context by stating the tool cannot actually upload, making the parameters effectively inert, and clarifies that the real upload must happen externally via multipart/form-data.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 intended operation (upload file via POST /api/upload) and immediately states it is NOT FUNCTIONAL, which is an explicit verb+resource+state. It distinguishes itself from sibling gorgias_download_file by focusing on upload and its critical limitation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells users not to use this tool and provides concrete alternatives: the Gorgias web interface or a multipart-capable HTTP client like curl with -F. This is unambiguous when-to-use/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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the return normalization behavior: 'Results are always returned as a flat array (the client normalizes both raw arrays and {data:[...]} wrappers from the API).' It also explains the effect of an empty query ('Defaults to empty string which returns all/recent resources'). These details go beyond the annotations, which only state readOnlyHint and openWorldHint, adding actionable behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured: purpose and alternative first, then a compact enumeration of type semantics, then the normalization caveat. Every sentence serves a distinct function—purpose, parameter guidance, and return behavior—with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter search tool with no output schema, the description is remarkably complete: it covers the API endpoint, the distinction from smart search, all meaningful type semantics, default query behavior, and result shape. The absence of pagination details is mitigated by the size parameter's max of 50 and the normalization note.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
While the input schema covers 100% of parameters, the description elevates understanding by mapping each enum value to its concrete search behavior, e.g., 'customer_profile' searches names, emails, and all channel addresses. It also clarifies the default of query as returning all/recent resources. This adds semantic depth that the schema's generic descriptions lack.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 'POST /api/search — Low-level search for Gorgias resources by text query', which clearly identifies the verb, resource, and mechanism. It further distinguishes itself from gorgias_smart_search by explicitly stating that smart_search is for 'intelligent ticket search', leaving no ambiguity about 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 Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides an explicit alternative: 'For intelligent ticket search with auto-detection of emails, names, views, tags, and keywords, use gorgias_smart_search instead.' This tells an agent when to choose the sibling tool over this one. The 'low-level' label also implies this tool is for precise, type-constrained searches.
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:

[![Gorgias-MCP-Server MCP server](https://glama.ai/mcp/servers/benpalmer1/Gorgias-MCP-Server/badges/card.svg)](https://glama.ai/mcp/servers/benpalmer1/Gorgias-MCP-Server)

Score Badge

Copy to your README.md:

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

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