Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare destructiveHint=true, and the description adds the behavioral nuance that the comment is not visible to the requestor. It does not contradict annotations. The description does not disclose other side effects (e.g., logging time, updating custom fields), though these are partially covered in the schema. It adds some value beyond annotations but not extensive 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 sentence of ten words, with the key distinction (internal vs. requestor-visible) front-loaded immediately after the action. Every word earns its place; there is 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 tool with 6 parameters, nested attachment objects, and custom-field semantics, the description is brief, but the schema is richly detailed and fully covers parameter behavior. Annotations handle the mutation warning. The main missing element is return-value behavior, since there is no output schema, but that is a minor gap for a comment-adding 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?

The input schema has 100% parameter description coverage, including detailed notes on Content, TimeTaken, Attachments, and CustomFields. The description itself does not need to explain parameters, and it adds no additional parameter meaning. Baseline of 3 is appropriate given complete 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 names a specific action ('Add an internal comment') and a clear resource ('to a ticket'), and the parenthetical '(not visible to the requestor)' immediately distinguishes it from the sibling tool add_reply. There is no ambiguity about what operation this tool performs.

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 signals when to use this tool (for internal, non-requestor-visible comments) by explicitly stating the visibility characteristic. It implies that add_reply would be the alternative for visible comments, though it does not explicitly name that sibling or state exclusion criteria.

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 include destructiveHint=true, and the description does not contradict that; 'Add' clearly indicates a modifying operation. The description adds some functional context (supported field types, single vs bulk mode), but it does not disclose details such as whether additions are reversible, how duplicates are handled, or what effects the change has on existing data.

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 every part earns its place: the action and accepted field types are front-loaded, then the single-vs-bulk usage is stated clearly. There is no redundant jargon 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 destructive mutation tool with no output schema, the description is adequate but not complete. It does not specify behavior when both Name and Values are provided, duplicate handling, empty input behavior, or what a successful call returns. These gaps are not fatal because the schema covers parameters and the annotations cover destructiveness, but more behavioral detail 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?

Schema description coverage is 100%, so the baseline is 3. The description adds genuinely useful meaning by clarifying that Name is for adding a single value and Values is for adding multiple values, a key semantic distinction that the schema itself does not explicitly state. This disambiguation goes beyond what the structured 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 a specific action ('Add one or more selectable values') and a specific resource ('to a custom field'), and it distinguishes this from sibling tools like create_custom_field by focusing on adding option values rather than creating the field itself. The mention of Select/Autocomplete types further sharpens the purpose.

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 useful parameter-level guidance ('Pass a single value with Name, or multiple values with the Values array'), but it does not explicitly state when to use this tool versus alternatives such as create_custom_field or apply_custom_field. The usage context is implied by the phrase 'to a custom field' but no exclusions or alternative conditions are 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?

The annotations already indicate destructiveHint=true, and the description adds one useful behavioral fact: adding an existing member has no effect, implying idempotence. It does not disclose permissions, failure behavior, or whether the group must already exist, so it contributes a moderate amount 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?

Three concise sentences with no filler. The main action is front-loaded, followed by the input preparation hint and an idempotence note; every sentence serves a clear 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 two-required-parameter mutation with no output schema, the description provides enough to select and invoke the tool correctly: the action, how to resolve member IDs, and duplicate-member behavior. It omits error and permission details, but those are not essential for basic use.

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 meaningful context by clarifying that members are user IDs and by directing agents to lookup_user for resolving names or emails, which goes beyond the bare schema property descriptions.

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 operation ('Add one or more users to a group') and the resource being modified. It is distinct from siblings like remove_group_member or list_group_members by naming the exact mutation and specifying that members are user IDs.

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 gives a concrete preparatory instruction: 'Use lookup_user to find user IDs by name or email.' However, it does not explicitly state when to choose this tool over alternatives such as remove_group_member, so the usage context is more implied than fully spelled out.

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, covering the mutation/safety profile, so the bar is lower. The description adds one behavioral fact beyond the annotation — the reply is visible to the requestor — signaling an outward-facing side effect. It does not disclose return semantics or irreversibility, but the schema's CustomFields caveat covers a key failure mode. 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?

A single 12-word sentence with zero filler. The parenthetical '(correspondence)' and 'visible to the requestor' both earn their place by disambiguating the tool's intent, and the key scoping fact is 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?

The detailed schema and destructiveHint annotation carry most of the burden for this 7-parameter, nested-object tool. The main gaps are that there is no output schema and the description never says what a successful call returns (e.g., reply/transaction ID), and the reply-versus-comment distinction is left implicit. Adequate given schema richness, but the description alone would not fully complete the 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?

Schema description coverage is 100%, so the baseline is 3 even though the tool description contributes no parameter detail. The schema itself is unusually rich, explaining CustomFields replacement semantics and silent RT failures plus Attachments FilePath vs FileContent encoding, so it fully carries the parameter burden.

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?

States a specific verb ('Send'), resource ('a reply on a ticket'), and a scoping qualifier ('visible to the requestor') that carves out the customer-facing correspondence use case. It implicitly distinguishes from the sibling add_comment but never names or explicitly contrasts it, so differentiation is not fully explicit.

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 'visible to the requestor' qualifier provides context implying this tool is chosen when the message must be customer-facing rather than internal. However, there is no explicit when-to-use or when-not-to-use guidance, and the direct sibling add_comment is never mentioned as the alternative for non-visible notes.

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 provide destructiveHint=true, and the description goes beyond that by specifying exactly what gets destroyed: global application removes all specific object applications. This is a concrete, condition-specific behavioral disclosure rather than a generic warning. 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?

Three short, information-dense sentences. The main action is front-loaded, the LookupType example is relevant, and the destructive side effect is included without extra filler. Every sentence 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 two-parameter mutation with no output schema and no nested objects, the description covers the core invocation knowledge: how to target an object or global scope, what determines valid targets, and the key side effect. It does not describe return values or failure modes, but the absence of an output schema lowers that expectation and the destructive note covers the main risk.

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, but the description adds real semantic value. It explains how the custom field's LookupType governs valid ObjectId targets and elaborates the meaning of ObjectId 0 beyond the schema's simple '0 for global' by naming the destructive consequence.

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?

States a specific verb-resource pair: applying a custom field to a specific object or globally, and explains LookupType's role in determining valid target object types. This clearly distinguishes it from sibling tools like create_custom_field, add_custom_field_value, and remove_custom_field_application, which operate on creation, values, or removal rather than application.

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 context: use ObjectId 0 for global application and understand that LookupType controls what object types are applicable. However, it never explicitly names alternatives like remove_custom_field_application or list_custom_field_applications, so when-to-use-this-vs-others 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?

The annotations include destructiveHint=true, so the agent already knows this is a state-changing operation. The description adds useful behavioral context beyond the annotation: a newly created custom field is not automatically applied, and Select-type fields require additional value population. There is no contradiction with 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 with no wasted words. The primary action is front-loaded, and the follow-up guidance is directly actionable. Every sentence 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?

For a tool with 7 parameters, the schema covers all parameter details, and the description covers the essential post-create workflow. There is no output schema, so the description could have mentioned expected return behavior, but the critical creation and follow-up context is present. Minor gap only.

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 already fully documented in the schema. The description adds a small workflow note relevant to the Type parameter (Select-type fields need values), but it does not substantially explain the parameters themselves. The baseline of 3 is appropriate given full 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 a specific action ('Create a new custom field') with a clear resource. It also distinguishes itself from related tools by referencing apply_custom_field and add_custom_field_value as follow-up actions, making its role in the workflow 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 explicit workflow context: after creating a custom field, apply it with apply_custom_field, and add values to Select-type fields with add_custom_field_value. It does not explicitly list when not to use this tool, but the guidance is clear enough for an agent to select it appropriately among the sibling 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 annotation destructiveHint=true already signals a mutating operation. The description adds the 'user-defined' distinction and workflow guidance, but does not disclose potential side effects, permission requirements, or what happens on duplicate names. This is adequate but not rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences: the first states the core purpose and the second provides actionable next steps. Every sentence earns its place with no redundant wording.

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 creation tool with full schema coverage and a mutation annotation, the description covers the essential flow. It could mention permissions or return values, but those are not critical for invoking 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 Name and Description are fully documented in the schema. The description adds no parameter-specific meaning beyond the overall purpose, which is acceptable given full 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 a specific verb ('Create'), a clear resource ('a new user-defined group'), and distinguishes it from sibling tools like create_queue or create_ticket. It also names group-specific follow-up tools, making the tool's role obvious.

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 context by explaining the next steps after creation: use add_group_members and grant_rights. It does not explicitly state when not to use this tool or name alternatives, but for group creation no direct alternative exists among siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already include destructiveHint=true, so the description isn't required to repeat that. It adds useful behavioral context: the lifecycle can be cloned from an existing one and it defines statuses and transitions for tickets. 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?

Three concise sentences front-load the core purpose and provide meaningful follow-up routing without redundancy. Every sentence 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 creation tool with only three parameters and full schema coverage, the description covers the purpose, the clone option, and the next recommended step. It doesn't describe the return value, but this is a minor gap 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 documents all three parameters with descriptions, so the baseline is 3. The description adds a helpful nuance for the 'clone' parameter ('clone an existing one as a starting point') and reinforces that 'name' is required, but it doesn't substantially extend 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 primary action: 'Create a new lifecycle' with a specific resource. It also distinguishes itself from siblings by explicitly pointing to update_lifecycle for subsequent customization.

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 when to use this tool ('Create a new lifecycle') and provides an explicit alternative for follow-up work: 'After creating, use update_lifecycle to customize statuses and transitions.' It does not mention when not to use it, but the resource scope is 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 discloses that the tool returns a new queue ID and URL, which is useful behavioral context. The destructiveHint annotation already signals mutation, so the description doesn't need to restate that. However, it doesn't mention failure behaviors, uniqueness enforcement beyond the schema, or permission requirements, so full transparency is limited.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, with no wasted words. The primary purpose and return value are front-loaded in the first sentence, and the second sentence provides actionable follow-up steps without overexplaining. Every sentence 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?

Given the full schema coverage and the destructiveHint annotation, the description is mostly complete. It includes the key return information and post-creation setup steps. It could be slightly stronger by mentioning what happens on duplicate queue name or by pointing to list_queues for validation, but the essential information is present.

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 input schema already documents all six parameters and their meanings. The description adds no parameter-level detail beyond what the schema provides, which matches the baseline score of 3.

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 creates a new RT queue, names the resource ('RT queue'), and differentiates it from siblings like update_queue or create_ticket. It also adds the return value (queue ID and URL), which strengthens purpose clarity.

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 by instructing which follow-up tools to use after creation (manage_queue_watchers, grant_rights, create_custom_field + apply_custom_field). It does not explicitly state when not to use this tool versus alternatives, but the guidance is practical and context-rich.

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 annotation destructiveHint=true already indicates this operation changes system state, and the description does not contradict it. The description adds no additional behavioral context such as side effects, permissions, or response behavior, but with annotations covering the safety profile, a neutral score is appropriate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with zero filler. Given the enormous amount of parameter detail already in the schema, keeping the tool-level description minimal is appropriate and efficient.

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 complex (25 params, nested objects, no output schema), and the description provides no return-value guidance or explicit note about response messages. The rich schema and annotations cover most invocation needs, but the absence of any output behavior disclosure leaves a notable gap for an agent handling the result.

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 the schema provides extensive detail for all 25 parameters, including formats, defaults, enums, nested structures, and special caveats (e.g., Priority labels, Description HTML rules). The tool description itself contributes nothing about parameters, so it relies fully on the schema, matching the baseline for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action ('Create') and resource ('a new ticket in RT'), which clearly identifies the tool's purpose and distinguishes it from siblings like update_ticket or search_tickets. However, it is largely a restatement of the tool name and does not elaborate on scope or explicitly differentiate from other create tools (e.g., create_queue).

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 intended usage is implied: use this when you need to create a new ticket. The description does not explicitly state when to use this tool versus alternatives, nor does it provide exclusions or conditions, but the verb-resource pair makes the primary use case obvious.

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?

destructiveHint already signals the operation is destructive. The description adds value by disclosing a specific failure condition (dependencies block deletion), the prerequisite (reassign first), and a diagnostic path (get_lifecycle/used_by). It could go further by noting whether deletion is reversible, but the key operational behavior is covered.

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?

Every sentence earns its place: the primary action, the critical failure mode, the remedy, and the intended use case. It is compact and front-loaded, with no redundant or tangential 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 single-parameter destructive tool with no output schema, this description is complete. It explains what the tool does, when it fails, what to do before calling it, and why one might call it at all. Nothing essential 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 schema already documents 'name' with 100% coverage, so the baseline applies. The description does not add extra meaning about the parameter beyond what the schema provides, but no compensation is needed because the single required parameter is fully explained.

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 verb and resource: 'Delete a lifecycle.' This clearly distinguishes it from lifecycle siblings like create_lifecycle, update_lifecycle, and get_lifecycle, and the rest of the description reinforces the delete semantics.

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 practical context: it fails when a queue or catalog still uses the lifecycle, and it directs the agent to reassign those references first, pointing to get_lifecycle for discovering them via used_by. It does not explicitly contrast with update_lifecycle as the reassignment tool, so it stops just short of full alternative 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?

The description adds meaningful behavioral detail beyond the readOnlyHint annotation: text content is returned decoded, binary content as MIME Base64. This informs the agent about response format, which is valuable for a retrieval tool.

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, front-loaded with the action, then encoding details, then alternative guidance. Every sentence earns its place with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple, single-parameter read-only tool with no output schema, the description covers purpose, behavior, and alternatives. It is fully sufficient for an agent to select and invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% (id with 'Attachment ID'). The description says 'by ID' but doesn't add further meaning beyond the schema. Baseline 3 is appropriate; no additional parameter context is provided.

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 retrieves a single attachment by ID, which is specific and distinguishes it from siblings like get_ticket_attachments (likely list) and get_transaction. The phrase 'single attachment' differentiates it from batch 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?

Explicitly names alternative tools for finding attachment IDs (get_ticket_attachments or get_transaction), giving when-to-use guidance. It implies the tool is for when you already have an ID, and the alternative instructions cover when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

While readOnlyHint already signals a safe read operation, the description adds substantial behavioral context: rights are grouped by category, the available categories depend on the object, queues and global objects can have a Status category, and consumers should read categories dynamically. No contradiction with the annotation exists.

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 front-loaded with the core purpose and then adds necessary behavioral nuance without redundancy. Every sentence earns its place, including the final instruction not to assume a fixed set of categories.

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 there is no output schema, the description gives a useful high-level shape: categories with rights, varying by object type. It could be even more complete by describing the exact response fields or how rights are represented, but it 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 coverage is 100%, so the baseline is 3. The description adds extra meaning to object_type by explaining how different object types change which categories are returned, going beyond the schema's simple 'Type of object' text.

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: getting the rights that can be granted on a named set of object types, plus globally. This clearly differentiates it from the sibling list_rights, which would enumerate rights rather than object-scoped grantable rights.

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 useful context about how available categories vary by object type, but it never explicitly says when to use this tool versus alternatives like list_rights, grant_rights, or revoke_right. Usage is implied rather than directly guided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, and the description adds the critical context that the returned user is tied to the auth token, clarifying identity semantics. It goes beyond structured data without overclaiming behavior.

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: the first states the action and resource, the second explains when to use it. No wasted words, and the critical usage guidance is 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 no-parameter getter with readOnly annotation, the description fully covers what the tool does and when to use it. No output schema exists, so explaining the return value is not necessary beyond identifying the resource.

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 tool has zero parameters and 100% schema description coverage, so the description need not explain parameters. Baseline 4 is appropriate for this parameterless interface.

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 specifies a concrete verb ('Get') and resource ('RT user account') tied to the configured auth token. It clearly differentiates from sibling lookup_user by focusing on the current user identity rather than arbitrary search.

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 states when to use: 'to determine who "I" or "me" refers to' in ticket assignment and search contexts. It does not explicitly name alternatives, but the usage context is unambiguous and self-contained.

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?

readOnlyHint=true already declares the operation safe, and the description is consistent with that annotation. The 'by numeric ID' detail adds a small behavioral constraint beyond the annotation, but the description provides no information about return format, permissions, or error behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One short, front-loaded sentence contains the action, the resource, and the key constraint. There is no filler or redundant elaboration.

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, read-only getter, the description is largely sufficient: an agent knows what to call and what input to provide. It falls slightly short of a perfect score because there is no output schema and no explicit statement about what 'details' are returned or what happens for an unknown ID.

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 single parameter is fully documented in the schema, including that the ID is numeric and that RT has no name route for groups. The tool description merely repeats 'numeric ID' and adds no new meaning beyond the schema, 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?

Uses a specific verb ('Get'), a clear resource ('a specific group'), and a concrete identifier route ('by numeric ID'). This distinguishes it from list_groups, create_group, and similar group-related tools even without naming them explicitly.

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 single-object retrieval rather than listing groups, and the numeric-ID constraint indicates how to target the group. However, it does not explicitly state when to prefer this tool over alternatives like list_groups, nor does it name any excluded routes.

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 annotation already signals safety, and the description adds meaningful behavioral detail by specifying exactly what configuration aspects are returned: statuses, transitions, defaults, and usage by queues/catalogs. This gives the agent a clear picture of the tool's output scope without needing an output schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is one efficient sentence that front-loads the core purpose and then lists the relevant return contents. Every word adds value, and there is no redundant or filler text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple, read-only tool with one parameter and no output schema, the description adequately captures the return contents. It could mention error behavior (e.g., lifecycle not found) or response format, but these are minor gaps given the tool's simplicity and the identifying `name` parameter.

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 only parameter `name` is documented as 'Lifecycle name'. The description does not add additional semantics (e.g., exact name format, case sensitivity, or whether partial names match), but with full 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 ('Get') with a clear resource ('a lifecycle's full configuration') and enumerates the key information returned: statuses, allowed transitions, default statuses, and queue/catalog usage. This clearly distinguishes it from sibling tools like list_lifecycles or update_lifecycle.

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 a read-only retrieval of a single lifecycle's full configuration, with a required `name` parameter signaling that a specific lifecycle must already be known. However, it does not explicitly say when to prefer this over list_lifecycles or how it relates to lifecycle validation/update 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 readOnlyHint annotation already indicates a safe read operation. The description adds no additional behavioral context such as return format or side effects; it only restates the identification method which is already 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?

A single sentence that conveys the action, target, and identifier method with no redundant 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 read-only tool with one parameter, the description is adequate. However, the lack of an output schema means the description could clarify what 'details' includes, especially given the sibling get_queue_fields to avoid ambiguity.

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 describes the sole parameter 'id' as 'Queue ID or name', providing full coverage. The description's mention of 'by ID or name' adds no 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 tool's function: retrieving details for a specific queue, identified by ID or name. This distinguishes it from sibling list_queues (listing all queues) and get_queue_fields (field definitions).

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 a specific queue identifier is known, but does not explicitly mention alternatives like list_queues for browsing or get_queue_fields for field-specific data. No exclusions or when-not-to-use 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 only provide readOnlyHint=true, but the description adds substantial behavioral detail: three return groups, ContentFormat rendering semantics for all seven formats, the DetailsUnavailable edge case (fields applied but unreadable), that every applied field is always listed, and that QueueCustomFields entries still carry CurrentValues. This far exceeds what the annotation alone conveys and discloses tricky response behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but front-loaded with the core purpose in the first sentence. Each subsequent sentence adds genuinely useful information: group distinctions, ContentFormat details, and edge-case behavior. It could be slightly tightened (e.g., the RTIR parenthesis is contextual but not essential), but every sentence earns its place for a tool with this subtlety.

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 there is no output schema, the description does an excellent job of explaining return structure: three groups, fields carrying ContentFormat, allowed values in types, and how to interpret DetailsUnavailable entries. It also covers how to present results to the user. No critical information needed to call and interpret this tool 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 has only one parameter, 'id', described as 'Queue ID or name', so schema coverage is 100%. The description does not add extra parameter-level semantics, but it doesn't need to because the schema already fully documents the parameter. 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 opens with a specific, actionable statement: 'Get custom fields (with types and allowed values) and lifecycle name for a queue.' It clearly identifies the resource (queue custom fields), the operation (get), and the return content (types, allowed values, lifecycle name). It further distinguishes three subgroups, which prevents confusion with siblings like get_queue or search_custom_fields.

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 concrete guidance on when each group is relevant: CustomFields are for ticket creation/update, QueueCustomFields for queue-level settings, TransactionCustomFields for comments/replies. It also explicitly instructs the agent to report all three groups when a user asks about queue custom fields. It does not name alternative tools or provide explicit when-not-to-use conditions, so it stops short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The readOnlyHint annotation already indicates this is a safe read operation. The description does not add any behavioral context beyond that, such as the exact contents of the response or any permission requirements. It is not contradictory, but it also doesn't expand on 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, concise sentence that immediately front-loads the verb and resource. There is no unnecessary wording or 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 straightforward getter with a well-defined schema and readOnly annotation, the description adequately conveys the core purpose. It does not specify return format or optional parameter usage, but the schema fills in those gaps. The overall context is sufficient for an agent to select this 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 provides complete descriptions for all three parameters (id, fields, subfields), so the schema covers the meaning. The description only mentions the ID, adding no extra semantics for the optional fields. Since schema coverage is 100%, 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 clearly states the action ('Get detailed information') and the resource ('a specific ticket by its ID'), using a specific verb and resource. It does not explicitly differentiate from sibling tools like get_ticket_history or get_ticket_attachments, but the scope is evident from the description.

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 context is implied—when you have a ticket ID and need full details—but the description provides no explicit guidance on when to use this tool instead of alternatives like search_tickets or get_ticket_history. No exclusions or preferred scenarios are mentioned.

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 establish readOnlyHint=true, and the description adds useful context about what the operation returns. It does not disclose pagination behavior or the fields-override semantics, though those are documented in the schema. There is no contradiction with 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?

A single sentence with the verb and resource front-loaded, followed by a tight parenthetical of return fields. Every word earns its place with zero 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?

With a readOnly annotation and a 100%-covered schema, the description does what remains necessary: it tells the agent what the response contains. The small default-fields mismatch and the absence of any pointer to get_attachment for content retrieval are the only notable gaps.

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; all four parameters are already documented in the schema. The description's list of returned fields aligns loosely with the schema's default field set, though it mentions 'IDs' where the schema default lists 'Subject,' a minor inconsistency.

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 names a specific verb ('List') and resource ('attachments on a ticket') and specifies the returned metadata (names, MIME types, sizes, IDs), clearly characterizing it as a metadata-listing tool. The plural scoping ('all attachments on a ticket') and the metadata parenthetical implicitly differentiate it from the get_attachment sibling, though it never names that sibling explicitly.

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 intended usage is implied rather than stated: an agent can infer this is the tool for enumerating attachment metadata on a ticket, and that get_attachment is for a single attachment's payload. However, there is no explicit when-to-use, when-not-to-use, or alternative-routing 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 provide readOnlyHint=true, so the description did not need to restate that. The description adds significant behavioral nuance beyond annotations: it reveals that some entries have Field populated with a numeric field ID rather than a name, that OldValue/NewValue for owner/watcher changes are numeric user IDs that cannot be resolved with available tools, and that OldReference/NewReference are unresolved row IDs. This is exactly the kind of trap-avoidance context that makes invocation and response interpretation safe.

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 compact for the amount of caveat it encodes. The core purpose is front-loaded, and the two special cases are stated efficiently with exact Type names. The only minor cost is a dense run-on sentence for the custom field case; splitting that into two sentences would help scanning. Still, every sentence earns its place and the length is justified by real trap-avoidance 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 read-only list endpoint with 100% schema coverage and no output schema, the description covers what an agent needs: what comes back, how to interpret the common shape, and how to handle the two anomalous shapes. It also names the only mapping assistant (get_queue_fields) and explicitly states that numeric user IDs and row IDs cannot be resolved here. The only gap is a few structural details (e.g. default ordering), but none of that is essential for 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?

The input schema covers 100% of parameters with descriptions: id is a Ticket ID, page and per_page have default/max values, and fields is a comma-separated list. Given that high coverage, the baseline is 3. The description does not add much beyond the schema for the parameters themselves, but it does add context about how the returned Field/OldValue/NewValue fields should be interpreted, which is more behavioral than parameter-level. The schema already carries the parameter documentation weight, so a 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 opens with a specific verb phrase, 'Get the transaction history for a ticket,' identifying both the resource (ticket) and the precise scope (transaction history). It further specifies that it returns a list of transaction types and even catalogs the structural variants, which distinguishes it cleanly from the immediate sibling get_transaction and from search_tickets without needing to open those schemas.

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 strongly implies when to use it: when you need the history/transactions for a single ticket, as opposed to searching tickets or fetching a single transaction. It also gives situational guidance for interpreting the output, e.g. getting owner/watcher changes and custom field changes. It does not explicitly enumerate sibling alternatives or state 'use get_ticket for current state,' but the context is clear for a caller that needs to understand a ticket's audit trail.

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 annotation already establishes that this is a safe read operation. The description adds useful context by identifying the exact version (RT 6.0.3) and framing the tool as a reference, but it does not describe the return format or content structure. With no output schema, a bit more behavioral detail about what the returned reference contains would be helpful.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no filler. The key action is front-loaded, and the second sentence gives concrete guidance about when to consult the reference. 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?

For a zero-parameter, read-only reference tool, the description is fully sufficient. It tells the agent what the tool returns, the version it applies to, and when to consult it. No output schema exists, but the nature of this tool makes the response predictable enough.

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 tool has zero parameters, so there is no parameter burden to document. The baseline of 4 applies because no parameter explanation is needed, and the description uses its space for usage guidance instead.

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?

States a specific verb ('Returns') and a specific resource ('TicketSQL grammar reference for RT 6.0.3'). It clearly distinguishes itself from sibling ticket-query tools by being the grammar reference rather than a data-fetching tool.

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 tells the agent when to consult it: before writing any TicketSQL query. It calls out the tricky areas where syntax is non-obvious (Status, date/time, custom fields, link fields), which helps the agent decide to use this tool proactively.

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 annotation readOnlyHint=true already signals a safe read operation, and the description adds that it returns 'decoded message content,' which is a useful behavioral detail beyond the annotation. No contradiction exists. It doesn't discuss return format or errors, but for a simple get operation this is reasonable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the primary purpose, and every word earns its place. It avoids redundancy and is highly efficient.

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 lacking an output schema, the description explains what is returned (full details plus decoded content) and provides clear usage context via the sibling reference. For a simple single-parameter tool with strong annotations, this is 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 schema has 100% coverage with a single parameter 'id' described as 'Transaction ID.' The description adds no new parameter-level detail beyond referencing 'single transaction,' which is already in the schema. Baseline 3 is appropriate since the schema carries the burden.

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: 'Get the full details of a single transaction including decoded message content.' It uses a specific verb ('Get'), identifies the resource ('single transaction'), and distinguishes itself from siblings like get_ticket_history by noting the decoded content 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?

Explicit usage guidance is provided: 'Use this after get_ticket_history to read the actual text of a reply or comment.' This directly tells the agent when to use this tool relative to a sibling, fulfilling the dimension fully.

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?

destructiveHint=true already signals mutation, and the description adds the useful conflict behavior 'Returns 409 if a right is already granted.' It does not disclose permission requirements, reversibility, or success response details, but the added 409 context gives some behavioral transparency beyond the annotation 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?

Three short sentences with no filler: the main action and targets come first, then the two invocation modes, then the conflict behavior. Every sentence earns its place and the structure is easy to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a six-parameter mutating tool, it covers both call shapes, all six object types, and the duplicate-grant outcome. It could add more about permissions or reversibility, but the current information is sufficient for correct invocation when combined with the schema.

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 carries most parameter meaning, but the description adds conditional usage semantics: a single grant pairs Right with User or Group, while bulk uses the grants array. It also reinforces that global is a valid object type, which helps construct valid calls.

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 ('Grant rights') and enumerates every target object type it applies to: queue, custom field, group, class, catalog, or global. It is clearly distinct from the sibling revoke_right by semantic polarity, though it does not name that alternative explicitly.

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 gives explicit usage modes ('Specify a single right with Right + (User or Group), or pass an array of grants for bulk operation') and lists object types. However, it does not state when to choose this tool over revoke_right or get_available_rights/list_rights; the selection 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?

The readOnlyHint=true annotation already covers the safety profile, lowering the bar. The description adds one useful behavioral detail beyond the annotation — that the result includes global application status — but discloses nothing about pagination behavior, empty results, or invalid-ID handling. 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?

A single 17-word sentence that leads with the action verb and states the exact scope of the result. Every word earns its place, with no filler, caveats, or redundant restatement of the tool name.

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 listing tool, the definition is nearly complete: all three parameters are documented in the schema, the read-only nature is in annotations, and the description conveys what the return conveys (applied objects plus global flag). It stops short of a 5 only because there is no output schema and no description of the response shape.

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%: id, page, and per_page each have meaningful descriptions in the schema. The tool description adds no parameter-level meaning beyond what the schema already provides, so the baseline score of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('List') and a specific resource ('objects a custom field is currently applied to'), making the action unmistakable. It also adds the 'including whether it is applied globally' nuance, which differentiates the returned information from a bare list. The purpose is clearly distinct from mutation siblings like apply_custom_field and remove_custom_field_application.

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 context is implied by the purpose statement: an agent can infer this is the tool for finding where a custom field is applied. However, there is no explicit when-to-use guidance, no mention of alternatives, and no exclusions relative to sibling tools such as search_custom_fields.

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 annotation already establishes that this is a safe read operation. The description adds valuable behavioral context beyond that: the API returns only id and type, ignores a fields parameter, and cannot return names. This helps the agent set expectations about the response without needing to call the tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences with no filler. It front-loads the core purpose, then provides the most important limitation and the routing guidance to get_group. Every sentence earns its place and the structure makes the key facts easy to scan.

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?

With six parameters fully covered by the schema, a readOnly annotation, and no output schema, the description covers the critical non-obvious behavior: fields are ignored and names cannot be requested. It also gives an alternative for the common named-members use case. This is sufficient for a read-only list endpoint, though it does not describe envelope or error details.

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 six parameters. The description does not add per-parameter meaning beyond what the schema provides, though it does clarify a general API limitation around requesting fields. This meets the baseline without exceeding it.

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 verb and resource: 'List the members of a group.' It further clarifies the exact output shape (id and type per member) and explicitly contrasts itself with get_group, which resolves member names. This makes the tool's purpose unambiguous and distinguishable from nearby member-related 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 explicitly states when to prefer an alternative: 'Use get_group when the user needs members named rather than listed as bare ids.' It also explains why list_group_members cannot fulfill that need, giving the agent a clear decision rule for selecting between the two 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 declare readOnlyHint=true, and the description aligns with that by saying 'List' and 'Returns'. It adds useful behavioral context by specifying that only user-defined groups are included and what data is returned, going beyond the annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short, purposeful sentences. The main action and return value are front-loaded, and the usage guidance is stated efficiently without 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 list tool with one optional parameter, read-only annotation, and no output schema, the description covers purpose, return contents, and usage context. It is sufficiently complete, though it does not detail default field behavior beyond what the schema already provides.

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% for the single 'fields' parameter, so the schema already carries the parameter meaning. The description does not need to add parameter details, earning the baseline score of 3.

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 ('List') with a clear resource ('user-defined groups') and states the return contents (names, descriptions, IDs). It also distinguishes itself from create_group by framing its use as a pre-check before creating groups.

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 says to use this tool to check for existing groups before creating new ones, giving clear usage context. It does not mention exclusion cases like using get_group for a single group, but no direct sibling alternative is suggested elsewhere.

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 annotation already signals this is a safe read operation, and the description's 'List' verb is consistent with that. The description adds some domain context about what lifecycles define, but it does not disclose additional behavioral traits such as pagination, ordering, or authorization requirements.

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 short sentences with the action front-loaded and no redundant restatement of the tool name or schema fields. The second sentence adds useful domain context without padding.

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 list tool with one optional, well-documented parameter, the description is nearly sufficient. It is slightly incomplete because it does not mention the asset lifecycle type reflected in the schema, and there is no output schema to clarify the exact return shape.

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 optional 'type' parameter is fully documented with enum values and a default note. The description adds no further parameter-level detail, so the high-coverage 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 clearly states the operation: 'List all available lifecycles' with a specific resource and scope, distinguishing it from get_lifecycle and lifecycle mutation tools. However, the explanatory sentence says lifecycles are for tickets in queues, while the input schema's type enum also includes 'asset', making the scope slightly narrower than the tool actually supports.

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 phrase 'List all available lifecycles' implies the tool is for full enumeration rather than retrieving a single lifecycle, but it does not explicitly mention get_lifecycle as the alternative for specific lifecycle lookups. There is no clear when-not-to-use guidance, so usage guidance is only implied.

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 annotation already communicates that this is a safe read operation, so the annotation carries most of the safety signal. The description adds only the vague qualifier 'available' and does not clarify behavior such as whether disabled queues are included, pagination, ordering, or access-based filtering.

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 clear phrase with no filler. It is front-loaded with the core operation and resource, making it easy to scan.

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 list operation with one optional parameter and a read-only annotation, the description is minimally viable. However, the meaning of 'available' is ambiguous and there is no mention of output shape or default field behavior, which matters because no output schema exists.

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 the 'fields' parameter is well documented in the schema, including the notable replacement behavior. The description adds no parameter-level information, but the baseline of 3 applies because the schema fully compensates.

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?

States a specific verb ('List') and resource ('queues'), clearly identifying it as an enumeration operation. It is distinguishable from get_queue (single queue) but does not explicitly name that sibling or define what 'available' means.

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 such as get_queue or search-related tools. The phrase 'all available queues' implies a general listing scenario, but there are no explicit conditions, exclusions, or alternative tool references.

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 modest context beyond the annotation: the operation reflects rights 'currently granted' (a point-in-time snapshot) and supports filtering by user or group. It does not describe return shape or pagination behavior, but for a read-only list tool with the readOnly annotation in place, 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?

Two sentences with zero fluff. The first sentence front-loads the verb, resource, and full scope enumeration; the second adds the filter dimension. Every phrase earns its place, including 'or globally,' which communicates the special object_type that requires no object_id.

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 six-parameter read-only list tool with 100% schema coverage and a readOnly annotation, the description is nearly complete: it identifies the resource, the object types, and the filtering options. The only minor gap is that with no output schema, the description does not state what each returned list entry contains, though 'List rights' makes this reasonably inferable.

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 all six parameters are already fully documented in the schema, including the group-name caveat. The description only adds that filtering by user or group is possible, which restates the user/group parameters without adding new meaning. Baseline 3 is appropriate since the schema carries the semantic burden.

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 ('List') with a specific resource ('rights currently granted') and enumerates the exact scope: queue, custom field, group, class, catalog, or global. This makes it immediately distinguishable from the sibling mutation tools grant_rights and revoke_right, and from get_available_rights, without needing to open the schema.

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 — listing existing rights across object types — and states the filtering capability ('Can filter by user or group'). However, it never explicitly names alternatives or exclusion conditions, such as when an agent should use get_available_rights instead, or notes the read-only relationship to grant_rights/revoke_right. Usage context is clear but no when-not guidance 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?

The readOnlyHint annotation already signals a safe read operation, lowering the bar. However, the description adds no behavioral context beyond the annotation: it does not mention pagination behavior, substring matching, field selection semantics, or anything about what the search returns. The schema covers some of this indirectly, but the description itself contributes no transparency beyond the annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded sentence with no filler. Every word contributes to the core purpose, 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?

For a simple search tool with a fully described schema, the description is largely sufficient. The main gap is the absence of guidance on when this tool should be preferred over sibling user-related tools, but the basic call shape and parameter meaning are fully covered by the schema.

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 complete descriptions for all four parameters, including the special behavior of 'fields' replacing defaults. The description does not need to add parameter details; baseline 3 is appropriate because the schema carries the weight.

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 ('Search') and resource ('RT users') with explicit search criteria ('by name or email address'). It clearly distinguishes this tool from siblings like get_current_user or list_group_members, which serve different user-related purposes.

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 about when to use this tool versus alternatives such as list_group_members or get_current_user. It implies a simple user lookup by name or email, but does not state exclusions or preferred contexts.

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 destructiveHint=true already being annotated, the description adds rich behavioral disclosure beyond it: full replacement of existing members, silent skip-and-report behavior for unresolvable members while the call still succeeds, and the constraint that system groups and role groups do not resolve. The explicit warning to 'confirm every member you passed was actually added' surfaces a genuine partial-failure trap that annotations alone would not reveal.

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 core operation is front-loaded in the first sentence, and every subsequent sentence addresses a distinct failure mode or constraint (bare-name lookup failure, system/role group exclusion, single-value role exclusion, partial update reporting). It is dense but economical; a minor structural refinement would be breaking the qualification rules into a list, but nothing here is wasted.

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 destructive tool with 4 parameters, a nested CustomRoles object, and no output schema, the description covers the inputs thoroughly, including member formats and role constraints, and even hints at return behavior via 'returned messages.' The only gap is the dangling 'see PARTIAL UPDATES' reference — that section is not present in the description — and the exact output format is never specified in the absence of an output schema.

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 earns a point above baseline by adding semantic details the schema lacks: the group: prefix convention, the replace-not-append semantics of the lists, and the eligibility restriction on single-value custom roles. It does not restate the schema's per-parameter 'username, email, or ID' text, which is correctly left to 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 opens with a specific verb+resource: 'Set the members of a queue role (Cc, AdminCc, or a multi-value custom role).' It goes beyond a bare statement by clarifying the scope (which roles are affected) and the set-replacement semantics, which distinguishes it from adjacent tools like update_queue (settings) and the group membership 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 provides substantial operational context: members are passed as a complete list that replaces existing ones, groups require a 'group:' prefix, and only multi-value custom roles are eligible. It does not explicitly route to or away from sibling alternatives, but there is no close competing sibling for this operation, so the exclusion guidance is not strictly needed.

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 destructiveHint=true, and the description adds meaningful context about exactly what is destroyed: the application of a custom field to a specific object, or its global application. This goes beyond the annotation alone and clarifies the two destructive scopes.

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 primary action and the key parameter nuance without wasted words. Every part earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter destructive tool, the description plus annotations cover the essential context: what is removed, the two scopes, and how to indicate global removal. It is sufficiently complete for correct invocation, even though it does not describe possible side effects or return values.

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 both parameters with 100% coverage. The description adds the important semantic that ObjectId 0 means the global application, which is not derivable from the schema alone. This extra detail justifies a score above the high-coverage baseline.

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 ('Remove') with a clear resource ('custom field application') and distinguishes two targeted behaviors: removal from a specific object or from global application. This clearly differentiates it from sibling tools like apply_custom_field or list_custom_field_applications.

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 for how to target removal (specific object vs. global using ObjectId 0). However, it does not explicitly discuss when to choose this tool over alternatives or mention any exclusions, leaving some usage context 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?

The description states the core destructive action (removing a member), which is consistent with destructiveHint=true. But it adds no behavioral context beyond the annotation—no mention of irreversibility, permission requirements, or side effects. The annotation already signals destructiveness.

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 action-first sentence with no filler. Every word contributes to the meaning, and the description is appropriately sized for a simple two-parameter removal tool.

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 mutation with complete parameter documentation and a destructive annotation, this is nearly sufficient. The main gap is the description's 'user' wording versus the schema's broader 'user or group ID', which could slightly mislead an agent, and there's no mention of the return value, though no output schema is expected for such an 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?

The input schema covers 100% of parameters with useful descriptions, including the numeric group ID constraint and the fact that member_id can be a user or group ID. The description adds no additional parameter meaning, so the baseline score of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description has a specific verb and resource: 'Remove' a 'user from a group'. It clearly contrasts with sibling tools like add_group_members and list_group_members. However, 'user' is slightly imprecise because the schema allows member_id to be a user or group 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?

No guidance is provided about when to use this tool or how it relates to alternatives such as add_group_members or manage_queue_watchers. The agent must infer usage from the tool name and sibling list.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the destructiveHint annotation by disclosing the non-obvious 404-for-group-name behavior and the distinction between a bad parameter and an ungranted right. This is the kind of behavioral detail that prevents an agent from misinterpreting failures.

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?

Each sentence in the description earns its place: purpose, the path/ID quirk, the 404 ambiguity, and the lookup recommendation. It is front-loaded with the core operation and has 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?

For a destructive tool with no output schema and only a destructiveHint annotation, the description covers the most critical traps and provides a clear lookup path for the needed ID. It could additionally point to list_rights or get_available_rights for valid right names, but the existing guidance is already strong.

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 meaningful context by explaining where the principal goes (URL path rather than request body), clarifying group ID requirements, and noting that email addresses are not resolved. It does not elaborate on the 'Right' parameter, but the schema already names it 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?

Begins with a specific verb and object: "Revoke a right from a user or group" and enumerates the exact object types covered. It clearly differentiates from sibling tools like grant_rights and list_rights by stating the reverse operation and its supported targets.

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?

Provides explicit, actionable guidance: the principal must be in the URL path, groups require a numeric ID, and a group name will produce a misleading 404. It even directs the agent to get_group or list_groups to obtain the ID, and contrasts behavior with grant_rights, making the correct invocation path unambiguous.

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 states 'MCP server writes the file directly', clearly indicating a write operation, but annotations declare readOnlyHint=true. This is a direct contradiction and severely misleads the agent about the tool's safety profile.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences, front-loaded with the primary action. Every sentence contributes meaningful information (operation, platform note, path handling) 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?

The tool is simple with few parameters and no output schema, so the description need not explain return values. However, the contradiction with readOnlyHint leaves the agent without reliable safety information. Additionally, important details like overwrite behavior, error handling, and return values are omitted, reducing completeness for a write 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 already covers both parameters with descriptions (100% coverage). The description adds extra value by explaining path behavior when a directory is provided ('original filename is used'), which goes beyond the schema's description. This additional semantic clarification justifies a score above the baseline of 3.

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?

Clearly states the action ('Save an attachment to a local file'), the resource (attachment), and the destination. It is distinct from sibling tools like get_attachment which retrieves content, making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides context that the server writes the file directly and works on any platform, implying cross-platform reliability. However, it does not explicitly mention when to prefer this over get_attachment or other alternatives, nor does it list exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations provide readOnlyHint=true, and the description confirms it returns matching fields. The description also discloses that Type filtering expects the stored base type (not the composite name) — a non-obvious behavioral nuance. It does not detail pagination behavior beyond schema parameters, but the read-only safety profile is already covered by annotations, so no contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the action and purpose, followed by search dimensions and return values. The description is efficient, though the return-value sentence is slightly redundant with the schema's field descriptions. 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?

The description is complete for a read-only search tool with 100% schema coverage. It covers why to use it, how to search, return values, and the Type nuance. It doesn't explain pagination defaults, but the schema already defines them. Given no output schema exists, a bit more detail on result ordering or default match behavior could help, but it's adequate.

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%, including per-parameter descriptions. The description still adds value by clarifying the Type filter pitfall (composite names like SelectSingle won't match), and names the default output fields. This exceeds the baseline 3 by providing practical semantic guidance 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 verb (Search), the resource (existing custom fields), and the purpose (avoid duplicates before creation). It also specifies search dimensions (Name, Type, LookupType) and return values (IDs, types, descriptions). This differentiates it from sibling tools like create_custom_field and list_custom_field_applications.

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 instructs to use this tool before creating new custom fields to avoid duplicates, and names the searchable fields. It provides clear context on when to use it versus creating new fields, and implicitly distinguishes from application-listing 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?

Beyond the readOnlyHint annotation, the description discloses two genuinely non-obvious behaviors: the automatic default field set with Queue/Owner expanded to names, and the fact that fields/subfields replace rather than add to defaults. It also reveals the Status meta-value semantics (__Active__/__Inactive__), which an agent could not infer from the schema, and the description's read-only framing is consistent with the readOnlyHint 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 purpose is front-loaded in the first sentence, immediately followed by the most critical warning (consult the grammar). Each remaining sentence covers a distinct non-obvious point — meta-values, examples, default field semantics — with no filler, though the description is on the longer side for an API tool.

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 covers the highest-risk area thoroughly: the query language's non-obvious syntax, the Status meta-value gotcha, and the default-field replacement behavior. With no output schema present, it leaves return-format details unstated, but pagination and field semantics are well documented in the schema, so the coverage is strong overall.

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, but the description adds real value above the schema: it teaches the TicketSQL syntax rather than just labeling the query parameter, provides concrete examples ('Queue = 'General' AND Owner = 'Nobody''), and explains when to pass fields or subfields (only when the default set is insufficient). This goes beyond the schema's plain 'TicketSQL query string' and 'Comma-separated fields' descriptions.

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 opening sentence 'Search for tickets using RT's TicketSQL query language' names a specific verb, resource, and method, so the tool's job is unambiguous. This clearly distinguishes it from single-ticket retrieval siblings like get_ticket and get_ticket_history, which an agent can tell apart at a glance.

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 names get_ticketsql_grammar as a prerequisite ('consult get_ticketsql_grammar before writing any query involving Status, date conditions, custom fields, or special values'), which is concrete when-to-first-do guidance. However, it never states when to prefer a sibling such as get_ticket over this search tool, so there are no explicit 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?

The annotation already marks destructiveHint, and the description goes much further: it states replacement semantics, key omission behavior, in-memory default filling, metadata stripping for clones of 'default', and 400 on validation warnings. There is no contradiction with destructiveHint.

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 dense but each sentence covers a consequential behavior or workflow step. It is front-loaded with the action and replacement warning, and later sentences add edge-case detail rather than filler. A little more structural separation would improve scannability, but there is no wasted 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 destructive, 11-parameter tool with no output schema, the description covers the main workflow, validation failure mode, key-dropping behavior, and special metadata/default cases. It does not state the return value or explicitly identify the required lifecycle-name parameter, but the schema covers parameters and the invocation path is clear from get_lifecycle.

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 meaningful parameter-level guidance: the full definition must include initial/active/inactive/transitions/rights/actions/defaults; omitted status_metadata and transition_metadata are lost; and actions can accept the native array form that get_lifecycle returns. This goes beyond the schema's property descriptions.

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 uses a specific verb ('Update'), identifies the resource ('a lifecycle's configuration'), and immediately clarifies that it replaces the stored configuration. This clearly distinguishes it from create_lifecycle and update_lifecycle_maps by emphasizing full-definition replacement.

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 instructs the agent to call get_lifecycle first, modify the current config, and send the whole thing back, and warns that omitted keys are dropped. It does not discuss alternatives like update_lifecycle_maps or validate_lifecycle, but the workflow and the destructive-replacement precondition are 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 include destructiveHint=true, and the description adds context about the map format but does not disclose whether the update replaces existing mappings entirely or merges with them. This is a key behavioral trait for a destructive operation, so the description only partially supplements 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 compact and front-loaded: two sentences and a format example with no redundant wording. The purpose is stated first, and the example earns its place by clarifying the non-obvious map structure.

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 covers the parameter format well, but given the destructiveHint annotation and absence of an output schema, it should clarify whether the update is a full replacement or a merge, and ideally what happens to existing mappings. This is a meaningful gap for an agent deciding how to invoke the tool safely.

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%, but the schema descriptions are vague ('Status mappings between lifecycles'). The tool description adds significant meaning by giving the exact JSON format and explaining what maps represent, greatly clarifying the expected parameter structure.

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 ('Update') and a specific resource ('status mappings between this lifecycle and other lifecycles'), clearly distinguishing it from sibling update_lifecycle, which concerns lifecycle settings generally. It unambiguously states 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 provides clear context by explaining that maps define how statuses translate when tickets move between queues with different lifecycles. It does not explicitly name alternatives or say when not to use the tool, but the usage context is evident.

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 destructiveHint annotation, the description discloses a critical behavior: fields are applied independently, the call succeeds even when some changes fail, and the returned messages must be checked. This is strong, non-obvious 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?

Three sentences, each with a distinct purpose: stating the operation, routing watcher-related work elsewhere, and warning about partial updates. There is no filler or 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 tool with 100% schema documentation and no output schema, the description supplies the key missing operational detail: partial success and the need to inspect returned messages. Combined with the destructiveHint annotation, this is sufficient for 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 coverage is 100%, so parameter descriptions already carry the details. The tool description only adds a high-level field list and does not provide extra syntax or formatting guidance, matching the baseline for fully documented schemas.

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 ('Update') and names the resource ('an existing queue's settings'), while enumerating representative fields. It explicitly differentiates itself from manage_queue_watchers by pointing to that sibling for watcher changes.

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 an explicit when-not-to-use instruction: for watchers, use manage_queue_watchers instead. It also clearly implies this tool modifies an existing queue rather than creating one, so an agent can route accordingly.

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 destructiveHint annotation, the description and parameter docs disclose multiple silent-failure and destructive behaviors: a bare relation name causes RT to silently remove every other link of that type; unrecognized Priority labels are silently coerced to 0 with a success response; unknown CustomFields names are silently ignored; and HTML Description input silently deletes disallowed tags and their contents. This far exceeds the disclosure burden and directly prevents an agent from causing unintended data loss.

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 sentences with no filler. The purpose is front-loaded, the calling convention follows, and the highest-risk failure mode (link replacement) is flagged immediately. Every sentence earns its place, and the density of useful information per word is very high.

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 29-parameter destructive mutation tool with no output schema, the documentation is nearly complete: the description covers global calling conventions and the schema covers every parameter with rich behavioral warnings. The only gaps are minor — no overall statement of what the response contains (though the Priority note references it) and no mention of permission requirements. Given the tool's complexity, this is thorough.

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, but the main description adds a global semantic the schema cannot convey: all properties must be top-level and a nested "fields" object is invalid. The link-handling rule (only Add/Delete variants accepted, bare relation names refused) likewise adds semantics that apply across many parameters. This lifts the score above baseline, though the per-parameter meaning is already well carried by 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 opening phrase "Update an existing ticket" states a specific verb and resource, and the contrast with create_ticket and get_ticket among siblings is clear from context. The second sentence adds the tool's distinctive calling convention (top-level parameters, no nested fields object), which sharpens what this tool is and is not.

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 context: how to pass fields, which link names are refused, and the destructive consequence of passing a bare relation name. The parameter notes add explicit cross-tool guidance ("read them with get_ticket first", "Use get_queue_fields to check a field's ContentFormat"). It stops short of explicitly stating when not to use this tool in favor of create_ticket or add_comment, hence 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?

Goes far beyond the sparse readOnlyHint annotation, disclosing non-obvious behavior: RT validates only the payload sent and never reads the stored lifecycle, the name merely labels warnings and need not exist, and partial payloads produce false positives where every transition status is reported as nonexistent. This is exactly the kind of behavior an agent would otherwise discover by failing.

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?

Lengthy at five sentences but front-loaded with the core purpose and every sentence carries distinct guidance about scoping, false positives, or workflow. The double-why construction ('which is why... and why...') is slightly wordy, but the complexity of the behavior justifies most of the length.

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 having no output schema, it specifies the return contract ('reports whether RT would accept it, with a warning for each problem found'), enumerates warning types, and fully explains the scoping pitfalls for an 11-parameter nested-object tool. An agent has everything needed to call it correctly without opening sibling schemas.

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 already covers all 11 parameters (100% coverage), so the baseline is 3. The description adds genuine semantic value on top: it equates the payload shape with update_lifecycle's, clarifies that name is label-only and need not exist, and warns that transitions and statuses interact during validation (sending transitions alone flags every status as nonexistent).

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?

Opens with a specific verb+resource pair ('Check a lifecycle definition without saving it') that immediately separates it from update_lifecycle and create_lifecycle. The contrast with update_lifecycle (which rejects whole payloads) makes the validation-only role 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?

Gives explicit when-to-use ('Use this to dry-run a custom lifecycle before writing it') and explains why the alternative (update_lifecycle) is worse for this purpose since it rejects the entire payload. Also prescribes the full workflow: read with get_lifecycle, change, then validate the whole definition.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.