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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only lists prerequisites and does not disclose side effects, return values, authorization needs, or any default behaviors (e.g., default status or priority). For a mutation tool, this is a significant gap.

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 conveys the essential purpose and key constraints without unnecessary words. No filler or repetition.

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

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

The tool has 11 parameters with no output schema or annotations. The one-sentence description does not cover return value, default values for status/priority, how contact resolution works, or any side effects. For a complex creation tool, richer context is needed.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by introducing the logical constraint that either email or requester_id must be provided, which is not encoded in the schema's required array. This helps the agent understand the business rule for identifying the requester.

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 'Create' and the resource 'Freshdesk ticket', making its purpose unmistakable. It implicitly distinguishes from sibling tools like update_ticket, delete_ticket, and search_tickets by focusing on creation.

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

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

The description provides clear context by stating the prerequisite fields needed for creation ('Requires email or requester_id, subject, and description'). It does not explicitly mention alternatives or when not to use the tool, but the creation context is obvious from the name and description.

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

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

With no annotations, the description shoulder the burden and discloses a key behavioral trait: the delete is soft and moves the ticket to trash (implying recoverability). This goes beyond the name itself, though it doesn't cover potential side effects or required permissions.

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, direct sentence with no filler. It is front-loaded with the action and behavior, earning its place efficiently.

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

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

For a simple tool with one parameter and no output schema, the description is sufficiently complete. It covers the core action and the soft-delete behavior. Lacking explicit return-value details is a minor gap given the low complexity.

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

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

The schema fully documents the only parameter (ticket_id) with type and description, achieving 100% coverage. The tool description adds no extra parameter semantics, so the baseline of 3 applies.

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

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

The description clearly states the action ('Soft-delete a ticket') with a specific verb and resource, and adds clarifying detail ('moves to trash'). This distinguishes it from sibling tools like update_ticket or create_ticket.

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

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

The description implies this is the deletion tool and clarifies the soft-delete nature, providing clear context. However, it does not explicitly mention when not to use it or compare to alternatives, but for a delete operation this is reasonably clear.

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

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

With no annotations, the description carries the burden of disclosing behavior. It clearly states that drafting does not post and that a draft_id is returned, adding useful transparency. However, it does not disclose side effects such as draft persistence, expiration, or permission requirements.

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

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

The description is two focused sentences: the first states purpose, the second provides critical behavioral instruction. Every word contributes, 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 description covers the core purpose, the non-posting behavior, and the return of a draft_id, which is essential given the absence of an output schema. It is nearly complete for a simple drafting tool, though it lacks any mention of error conditions or distinction from draft_reply, preventing a perfect score.

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

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

Schema coverage is 100% with all three parameters described (ticket_id, body as HTML, private defaulting to true). The description's mention of 'private or public' reinforces the private parameter but adds no new syntactic or semantic detail beyond what the schema already provides, meeting 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 'Draft a private or public note on a ticket for review' with a clear verb and resource, and explicitly distinguishes itself from sending via 'Does NOT post — call send_note with the returned draft_id to post.' This clearly separates it from sibling send_note and other drafting tools.

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

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

The description provides direct workflow guidance by instructing to call send_note with the returned draft_id to post, implying when to use each. However, it does not explicitly differentiate from sibling draft_reply or provide exclusions for when not to use this tool beyond the note-vs-reply distinction.

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

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

With no annotations, the description carries the full burden. It discloses the critical behavioral trait that the tool does not send and returns a draft_id for later sending. It does not detail side effects like draft persistence, but the essential safe/non-sending behavior is transparent.

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 filler. The first states the core purpose; the second delivers the critical caveat and alternative. 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 simple draft tool with no output schema, the description sufficiently conveys purpose, the non-sending behavior, and the follow-up action. It does not describe full return structure beyond draft_id, but that is enough to invoke send_reply correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no parameter-level detail beyond what the schema already provides, but it does not need to since parameter descriptions already exist; no gaps are introduced.

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

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

The description clearly states the tool drafts a reply to a ticket for review, using a specific verb and resource. It also distinguishes itself from siblings by explicitly noting it does NOT send, directing the agent to send_reply.

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 when-to-use context ('for review') and an explicit when-not/alternative directive: 'Does NOT send — call send_reply with the returned draft_id to send.' This is a clear exclusion and names the sibling alternative.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It indicates a read operation via 'Get' and suggests completeness via 'full details', but does not disclose error behavior (e.g., not found), authentication requirements, or whether it modifies anything. For a simple read tool this is minimally acceptable but lacks depth.

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 no wasted words. It conveys the essential purpose and key qualifier immediately, making it highly readable 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?

For a simple single-parameter read tool with no output schema, the description is sufficiently complete to set expectations: a full contact record returned by ID. It leaves room for ambiguity about the exact fields, but the simplicity of the operation makes this acceptable.

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

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

The schema provides 100% coverage with the parameter description 'Contact ID', so the baseline is 3. The tool description adds no further meaning beyond restating that the lookup is 'by ID'—no format, types, or additional context is given beyond the schema.

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

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

The description clearly states the action ('Get full details') and resource ('contact') with the key qualifier 'by ID', making the purpose unambiguous. It implicitly distinguishes from sibling tools like list_contacts (which lists multiple contacts) and get_ticket (different resource), but does not explicitly name alternatives.

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

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

The phrase 'by ID' implies this tool is for retrieving a single contact when the ID is known, which is a clear usage context. However, it does not explicitly state when not to use it or name alternatives like list_contacts, leaving the guidance at an implied level.

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?

No annotations are provided, so the description carries the full burden. It discloses that it returns all fields and custom fields, and offers optional includes, but it does not state read-only status, error behavior, or authentication requirements. 'Get' implies a read, but the absence of explicit safety context is a minor gap.

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 sentences, front-loaded with the main action and then optional parameters. 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 single-ticket retrieval with 2 parameters, the description covers the core behavior and optional fields. However, it does not mention any error handling or distinguish itself from sibling list/search tools, making it slightly incomplete.

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

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

The schema already provides full descriptions for both parameters (ticket_id and include), with 100% coverage. The description adds little beyond restating the include options, so it does not elevate meaning beyond the schema.

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

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

The description clearly states 'Get a single ticket with all fields and custom fields,' using a specific verb and resource. It distinguishes from sibling tools like list_tickets and search_tickets by emphasizing 'single ticket.'

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

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

The description implies usage for retrieving a single ticket by ID, but it does not explicitly contrast with sibling tools like list_tickets or search_tickets, nor does it state when not to use it. The optional include hint provides some context, but no explicit alternatives.

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

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

With no annotations, the description carries the full burden for behavioral disclosure. It implies a read-only operation but does not explicitly confirm safety, mention pagination behavior, or describe the return format. No additional context is provided about potential side effects or permissions.

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

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

The description is a single, focused sentence that immediately conveys the core action and the optional filter. Every word earns its place, with no redundancy or irrelevant detail.

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 listing tool, the description is minimally adequate but lacks details about pagination parameters, return structure, or any prerequisites. Given the absence of an output schema and annotations, a bit more context (e.g., 'returns a paginated list of agents') 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 coverage is low (33%), with only group_id having a description. The description explicitly mentions group filtering, which aligns with group_id, but page and per_page remain undocumented, forcing the agent to infer their purpose. The description does not fully compensate for the low schema coverage.

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

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

The description uses the specific verb 'List' and identifies the resource 'agents', clearly distinguishing it from sibling tools like list_tickets and list_groups. The optional filter by group adds a precise scope, making the purpose unmistakable.

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

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

The phrase 'optionally filtered by group' implies a use case (listing agents with an optional group filter) but does not explicitly state when to prefer this over alternatives like list_contacts or list_groups. No exclusions or alternative tools are mentioned, but the naming makes primary usage 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?

No annotations are provided, so the description carries full burden. It doesn't disclose read-only nature explicitly (though implied), doesn't describe pagination behavior, and doesn't explain what happens if both email and search_term are provided. It does mention autocomplete behavior but that's 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?

Two sentences, front-loaded with the core action, no filler.

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

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

The tool has 4 parameters with 50% schema coverage, no output schema, and no annotations. The description is sufficient for basic usage but misses pagination and filter-combination behavior.

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 description adds a mild distinction between email (exact match) and search_term (autocomplete) beyond the schema descriptions, but it adds nothing about page/per_page, which are undocumented. With 50% schema coverage, description should compensate but doesn't fully.

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 lists contacts and offers two distinct search modes (email exact match and name/phone autocomplete). This distinguishes it from ticket/group tools, though it doesn't explicitly contrast with get_contact.

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 guidance on which parameter to use for which intent (email for exact match, search_term for autocomplete). However, it doesn't mention alternatives like get_contact for single-contact retrieval, so it lacks explicit when-to-use vs alternatives.

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

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

With no annotations, the description must disclose behavioral traits. It merely says 'list all agent groups' without mentioning that it is a read-only operation, pagination behavior, or response format. The presence of page/per_page parameters suggests pagination, but this is not disclosed.

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

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

The description is a single, efficient sentence that front-loads the verb and resource. It is appropriately sized for a simple list operation and contains 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 tool has pagination parameters but no output schema or annotations. The description fails to mention pagination behavior, return details, or any potential limits, making it incomplete for effective use in complex scenarios.

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 0%, and the description adds no meaning for the two parameters (page, per_page). The agent cannot infer pagination semantics or parameter usage from the description, leaving a complete gap for parameter understanding.

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

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

The description 'List all agent groups' uses a specific verb ('List') and resource ('agent groups'), clearly distinguishing it from sibling tools like list_agents and list_contacts. It accurately states the tool's function without ambiguity.

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 no guidance on when to use this tool versus alternatives. It only states the action, leaving the agent to infer context. There are no exclusions, prerequisites, or comparisons to 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?

No annotations exist, so the description carries full responsibility. It only states the listing action and default scope, omitting details about pagination, response format, or non-mutating guarantees. For a tool with 9 parameters, this is insufficient behavioral disclosure.

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 no filler. It efficiently conveys the core action and default behavior, and 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?

With 9 parameters, no output schema, and a very brief description, the tool lacks context for pagination, filter behavior, and return structure. The description doesn't explain how 'filter' relates to other parameters or what an agent should expect as a response.

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

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

Schema description coverage is 100%, so all parameters are already documented in the schema. The description adds no parameter-specific meaning beyond that, so the baseline of 3 applies.

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

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

The description clearly states it lists tickets using Freshdesk predefined filters and defaults to all tickets. It specifies the resource and scope, and the mention of 'predefined filters' distinguishes it from search_tickets, though not 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?

No explicit when-to-use or alternative guidance is provided. The description implies use for filter-based ticket listing, but doesn't explain when to prefer this over search_tickets or other 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?

With no annotations, the description carries full responsibility for behavioral disclosure. It mentions key behaviors: query length limit, 300-result cap, and exclusion of archived tickets. It does not detail pagination, return format, or authentication, but for a read-only search tool these are less critical. No contradiction with annotations.

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

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

The description is extremely concise, using two short sentences to convey the tool's purpose, query syntax, limits, and archived-ticket exclusion. No unnecessary words or fluff.

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

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

Given the tool's simplicity (one parameter, no output schema), the description covers the essential aspects: what it does, how to use it, and key constraints. It doesn't explicitly state return type or pagination, but these are minor omissions for a search tool of this complexity.

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

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

Schema coverage is 100%—the single query parameter is described with its max length in both the schema and the tool description. The description adds little beyond what the schema already provides, only redundantly stating the Freshdesk query syntax and max length.

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 uses a specific verb ('Search') and resource ('tickets'), and specifies the mechanism ('Freshdesk query syntax'). This distinguishes it from siblings like list_tickets (which likely lists all tickets) and get_ticket (which fetches a single ticket).

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

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

The description provides clear context for when to use the tool: when a search query is needed, with explicit constraints like max length and result limit. However, it does not explicitly name alternatives or state when not to use it, leaving some usage guidance 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It says 'Post' but does not explain whether the draft is consumed, what permissions are required, or what happens on success/failure. This is a significant gap for a write operation.

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

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

The description is two sentences, front-loaded with the action, and contains no superfluous information. 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 simple tool with one parameter and no output schema or annotations, the description covers the core purpose and prerequisite. It could mention side effects (e.g., draft consumption) but given the low complexity, it is sufficiently 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 already fully describes the parameter (draft_id) with 100% coverage, so the baseline is 3. The description adds value by specifying the source ('from draft_note') which disambiguates from the schema's broader 'draft_reply or draft_note', thereby clarifying the intended use.

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 ('Post') and resource ('note'), and clarifies it is for a previously drafted note, distinguishing it from sending replies or creating new content. This clearly 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 explicitly states the prerequisite: 'Requires a draft_id from draft_note.' This tells the agent when to use the tool (after drafting a note). However, it does not mention alternatives or exclusions, such as using send_reply for replies, so it is not a full usage guide.

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

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

With no annotations provided, the description has the full burden of behavioral disclosure. It only says 'send' and mentions the draft requirement, but does not disclose potential side effects, return values, or whether the action is idempotent or destructive. This is a significant gap for a mutating operation.

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

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

The description is concise and front-loaded: two short sentences that state the primary purpose and the required prerequisite. Every word earns its place, and the format is easy to parse.

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

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

Given the simplicity of the tool (one parameter, no output schema), the description is still incomplete. It does not explain what constitutes a 'reply' in this system, what happens after sending (e.g., ticket status changes), or any expected return value. The contradiction between the description and schema regarding valid draft sources further undermines 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?

While the schema covers the parameter at 100%, the tool description adds a misleading restriction by saying the draft_id must come from draft_reply. The schema itself states 'Draft ID from draft_reply or draft_note,' which directly contradicts the description. This reduces the helpfulness of the description and could mislead the agent into rejecting valid draft_note IDs.

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 'Send a previously drafted reply' clearly states the action (send) and target resource (a drafted reply), distinguishing it from sibling tools like send_note by the specific term 'reply' and the reference to draft_reply. It also states the required dependency on a draft_id, which is explicit and useful.

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 by stating 'Requires a draft_id from draft_reply,' indicating this tool is used after the drafting step. However, it does not explicitly contrast with send_note or other alternatives, nor does it mention when not to use the tool. Usage is implied but not fully clarified.

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

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

With no annotations, the description carries the full burden. It only says 'update' but does not disclose whether the update is a partial merge or full replacement, whether fields can be cleared, or any side effects or permission requirements. This is a significant transparency gap for a mutation tool.

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

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

The description is a single, concise sentence that front-loads the verb and resource. It wastes no words, but the inaccuracy with 'assignee' slightly detracts from its effectiveness.

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

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

The tool has 10 parameters, a nested custom_fields object, no output schema, and no annotations. The one-sentence description omits key fields (subject, group_id, description, type, responder_id) and fails to explain how these fields relate to each other or to ticket updates. It is insufficient for an agent to correctly use the tool in many scenarios.

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 only 10% (only ticket_id has a description). The description lists some field categories but does not explain value constraints (e.g., status range 2-5, priority range 1-4) or clarify that 'assignee' corresponds to responder_id. It adds only superficial meaning.

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 updates ticket fields and enumerates several examples (status, priority, tags, custom fields). However, it mentions 'assignee' which does not directly match the schema's 'responder_id', creating minor ambiguity.

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 like create_ticket or delete_ticket. The description implies an existing ticket must be referenced but does not state prerequisites or scenarios.

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