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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.