DeskCrew

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

No annotations provided, but description discloses recording an assignment event, authorization requirement ('send' tier), and agent membership constraint, plus cost information.

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-loading the core action and purpose, with no unnecessary words.

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

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

For a simple assignment tool with no output schema, description covers action, prerequisites, side effects (timeline event), and cost. Lacks response format but overall sufficient.

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

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

Schema coverage is 100% and schema already describes parameters adequately. Description adds context about tenant membership but does not add significant new meaning beyond the schema.

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

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

Description clearly states verb 'assigns' and resource 'existing ticket to a human agent', and distinguishes from sibling tools like create_ticket, resolve, triage.

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?

States when to use ('route or hand off a ticket') and provides prerequisites (agent must be member, need 'send' tier). Implicitly excludes other uses but lacks explicit 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?

No annotations are provided, so the description carries full burden. It states it is a write operation but only adds a new issue without modifying existing ones, which is transparent. It also includes a cost indicator ($0.02). It could mention required permissions, but overall is adequate.

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

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

The description is two sentences long, front-loaded with the core purpose, and contains no redundant wording. 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?

Given no output schema, the description explains what the tool does and when to use it. It lacks return value details and error scenarios, but for a creation tool this is often acceptable. The inclusion of a price note adds useful context.

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%, but the description adds contextual guidance on how to populate each parameter (e.g., 'Compose this from the conversation' for body, 'Write this yourself' for title). This aids the agent beyond the schema's technical 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 it creates a new bug report or feature-request issue in the tenant's issue tracker, specifying the action and resource. It distinguishes from sibling tools like list_issues (read-only) and create_ticket (likely different tracker).

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

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

It explicitly says 'Reach for this when a user (or your own analysis) surfaces a defect or a feature idea that should be recorded for the team to triage', providing clear context for use. However, it does not explicitly mention when not to use or alternatives, though the context implies it's for new issues only.

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 burden. It discloses key behaviors: find-or-creates customer by email, optionally records first message, does not send email, and returns specific fields. However, it omits details about error handling (e.g., what happens if customer creation fails) and authentication or rate limits.

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

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

The description is concise, front-loading the main purpose and key outcomes, then adding important details like the find-or-create behavior and lack of email notification. It is a single paragraph without wasted words, though it could be broken into bullet points for easier scanning.

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 has 5 parameters and no output schema, the description covers the main functionality (returned fields, behaviors) but lacks completeness on error scenarios, input validation, and what happens when the customer already exists. It provides sufficient context for typical use but not for edge cases.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds limited extra value beyond the schema, such as explaining the find-or-create behavior for customerEmail and that customerName is only applied on new records. The price mention is also extra but not parameter-specific.

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 (files a new support ticket), the resource (ticket for an end customer), and the key outputs (ticketId, customerId, status). It also distinguishes from siblings by noting that it does NOT send email or notify the customer.

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

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

The description explicitly says when to use the tool ('when an agent needs to log a new customer issue or request') and provides important context about find-or-create behavior and lack of email notification. However, it does not explicitly list when not to use it or provide direct 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?

No annotations are provided, so the description carries full burden. It discloses that the draft is not sent, is recorded with `delivered: false`, notifies the ticket thread, and returns specific fields. It also mentions cost. Missing details about permission requirements or draft editing, but overall strong.

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 only two sentences, front-loads the core action, and contains no redundant information. Every sentence serves a purpose.

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

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

Given the tool's simplicity (2 params, no output schema, no annotations), the description covers behavior, return fields, and cost. It lacks error details beyond NOT_FOUND, but schema covers that. Overall sufficient for informed 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% and both parameters have descriptions. The description adds value by explaining the body as the proposed reply for human review and reiterating that ticketId must belong to the tenant. It goes beyond schema by clarifying usage intent.

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 proposes a reply as a draft in the human approval queue, not sending it directly. It uses specific verbs and resource, and distinguishes from `send_reply` by emphasizing the draft and approval process.

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 'Reach for this once you have a ready answer... and want a human to review and send it, rather than to look up or send anything directly.' This provides clear when-to-use guidance and contrasts with sibling tools, though it could explicitly name sibling 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 fully discloses behavior: it is read-only, returns a bundle of data, and has a cost of $0.02. It lists all returned components, making side effects and outputs 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?

The description is a single paragraph that is reasonably concise but packs in multiple pieces of information. It is front-loaded with key attributes ('Read-only') and efficiently conveys purpose, contents, and usage. Slightly verbose but still effective.

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 thoroughly explains the return value by listing the components of the bundle. It also covers the single required parameter and optional parameters' context. The addition of cost information further completes the context for the agent.

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?

Input schema has 100% description coverage, so the schema already documents all parameters with clear descriptions. The tool description does not add additional meaning or usage details beyond what the schema provides, earning a 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 is read-only and returns a complete working bundle for a ticket, including specific components like message thread, customer profile, etc. It explicitly distinguishes from sibling tools by noting it writes nothing, which differentiates it from tools like create_ticket or 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?

Explicitly advises to 'Reach for this first when you have a ticketId and need everything required to understand and answer it,' providing clear when-to-use guidance. It also clarifies what it does not do (writes nothing, sends nothing to customer), helping the agent avoid misuse.

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 fully discloses behavioral traits: it records an issue_link entry on the ticket timeline optionally with a note, does NOT change ticket status, does NOT notify the customer, and fails with NOT_FOUND if entities don't exist. No annotations are provided, so the description carries the full burden and meets it excellently.

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 slightly long but every sentence is meaningful, covering purpose, usage, behavior, constraints. The price note is extraneous but does not detract much. Well-structured with clear front-loading of core purpose.

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

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

Given the tool has 3 params, no output schema, but complex behavior, the description explains the side effects, constraints, and error case completely. It covers what the tool does and does not do, and when it fails.

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%, baseline 3. The description adds value by explaining that the note parameter is optional and that when omitted, a default note referencing the issue id and title is recorded. This goes beyond the schema's description of max length and optionality.

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 specific verbs and resources: 'Associate an existing support ticket with a tracked issue'. It clearly distinguishes this tool from siblings like create_issue or assign by focusing on linking existing entities without creating new ones.

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 use: 'Reach for this when a customer's ticket is caused by, or asks for, a known issue'. It also implies when not to use by noting that both must already exist, guiding the agent to check existence or use creation tools first.

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 explicitly marks the tool as read-only and explains filtering behavior (only published entries, excluding drafts and scheduled). No annotations are provided, so the description carries full burden and is sufficient for a simple list 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 with key information front-loaded. It uses two sentences, but the second sentence is slightly long; however, every part adds value. 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?

Given the simple tool with one optional parameter and no output schema, the description is complete. It explains the purpose, usage, filtering behavior, and return fields, leaving no significant 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% with a clear description of the limit parameter. The description adds value by listing the fields returned (id, title, body, publishedAt) and the default value of 25, which enriches understanding 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 specifies the tool lists published changelog entries sorted newest-first, with specific fields returned (id, title, body, publishedAt). It distinguishes itself from sibling tools by targeting changelog entries rather than tickets or issues.

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 use cases: informing customers of recent changes or checking if a feature/fix is announced. It also clarifies that only published entries are returned, but does not explicitly state when not to use it or provide 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?

Declares 'Read-only' upfront, disclosing the key behavioral trait of no side effects. It also describes ordering (newest first), optional filtering by status, result capping, and the exact set of returned fields, providing comprehensive transparency beyond the schema's parameter descriptions.

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 that are front-loaded with the core purpose, followed by usage context and parameter details. Every word earns its place with no redundant phrasing.

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 two optional parameters, the description covers purpose, usage, behavioral traits, parameter semantics, and return fields. No gaps remain given the context signals.

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 describes both parameters with 100% coverage, but the description adds value by explaining the return structure (id, type, title, status, vote total) and the default limit of 25, which is not present in the schema due to no output 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?

Description clearly states the tool lists tracked issues from the public roadmap/issue tracker, newest first, specifying verb (list), resource (issues), and scope (this tenant's tracked issues). It effectively distinguishes from siblings like create_issue and link_issue by focusing on reading existing items.

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 recommends using this tool to check existing issues before reporting new ones, to check status or vote counts, and to avoid duplication. This provides clear when-to-use guidance and implicitly advises against using it for creating or modifying issues.

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 provided, but the description fully discloses behavior: read-only, sorted by most recent message, filter capabilities, limit defaults/max, and return fields. It explicitly states it never creates or modifies anything.

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 yet comprehensive, front-loaded with the read-only and listing purpose. Every sentence provides meaningful information 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?

Given 5 parameters, no output schema, and no annotations, the description is fully complete: it explains purpose, filters, limit, return fields, and safe behavior, and provides practical use cases that differentiate it from sibling tools.

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

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

Schema coverage is 100%, and the description adds value by explaining the purpose of each filter (e.g., polling with since), default/max limit, and sorting behavior 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 lists support tickets (verb+resource), is read-only, and specifies use cases like discovering ticket IDs, triaging, and polling. It implicitly distinguishes from sibling tools that create or modify tickets.

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 usage context: use for discovery, triage, and polling. It does not explicitly mention when not to use or name alternatives, but the read-only nature and sibling list imply limitations.

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 burden. It comprehensively discloses: submission as draft, queued for human review, not sent to customer, ticket lookup by id within tenant, refusal if ticket missing, and price. No hidden behaviors.

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 dense sentence but each clause adds essential information. While it could be broken into shorter sentences for readability, it is front-loaded with the core purpose and contains no filler. Effective use of space.

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 (2 required params, no output schema, no annotations), the description effectively covers purpose, usage, behavior, and parameter guidance. It provides all necessary context for an agent to use it correctly, including the price note.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by clarifying the intent for 'summary' ('customer-ready answer or fix') and reiterating that it remains a draft until human approval. This surpasses the schema's 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?

Description clearly identifies the verb ('Submit'), resource ('proposed resolution for an existing support ticket'), and key constraints ('as a DRAFT for human approval', 'not sent to customer', 'does not close the ticket'). It effectively distinguishes from siblings like 'resolve' and '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?

Provides explicit guidance: 'Reach for this once you have diagnosed a ticket and have a concrete, customer-ready answer or fix to suggest.' Implies when not to use (e.g., without a concrete answer). Though it doesn't name alternative tools, the sibling list offers context. Clear enough for typical use.

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?

Since no annotations are provided, the description carries full burden and excels: it discloses the tool sets status to closed, records internal note, is idempotent (no-op if already closed), reversible, requires 'send' tier, and notes the internal note is not sent to customer. Also mentions cost. No contradictions.

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

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

Four sentences, well-structured with main action first, followed by usage context, behavioral details, and credential/cost info. No wasted words.

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

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

For a tool with 2 parameters, no output schema, and no annotations, this description fully covers behavior, constraints (idempotent, reversible, tier requirement), side effects (note internal), and cost. No 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%, but the description adds significant value: explains that the note is internal and defaults to 'Resolved by agent,' and clarifies ticketId scoping to tenant. This goes beyond schema 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?

Clearly states the tool marks a ticket as resolved by closing it and recording an internal note. The verb 'resolve' is specific, and the description differentiates it from siblings like 'assign' or 'send_reply' by focusing on closing out handled issues.

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 says 'Reach for this once the issue has been handled and you want to close it out,' providing clear when-to-use guidance. Also notes idempotency and reversibility, and mentions credential requirement ('send' tier). No when-not-to-use needed given clarity.

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 fully discloses behavior: read-only, published-only articles, AND search semantics, return fields (id, title, snippet, updatedAt), tenant fixed by credentials, and the '[free]' note. No contradictions.

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

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

The description is a single paragraph with multiple sentences, front-loaded with the core action. It efficiently conveys all key information, though it could be slightly more structured for readability.

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 search tool with 2 params and no output schema, the description covers scope, restrictions, semantics, return fields, and usage priority. It is fully adequate for an agent to invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context beyond the schema: explains AND semantics, gives query examples ('refund policy'), and states limit defaults. This adds value but not drastically.

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

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

The description clearly identifies the tool as a read-only full-text search over published knowledge-base articles of the tenant, distinguishing it from sibling tools like search_tickets by specifying 'KB articles' and 'tenant-specific guidance'.

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 to 'Reach for this FIRST' before replying or drafting a resolution, providing clear when-to-use guidance. It also notes that drafts are excluded, but does not name alternative tools for different use cases.

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

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

No annotations are provided, so the description carries the full burden. It discloses the read-only nature, tenant scoping, ranked search with substring fallback, and the lightweight summary returned. Minor gaps: no mention of rate limits or pagination beyond the limit parameter, but for a search tool the transparency is good.

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 paragraph that front-loads the core functionality and is packed with useful information without unnecessary fluff. It could be slightly more structured (e.g., bullet points), but it's already concise and effective.

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 3 parameters, no output schema, and no annotations, the description covers the essentials: what the tool does, how it works, what it returns, and how to use the IDs with other tools. It provides enough context for an agent to select and invoke it correctly.

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

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

Schema coverage is 100%, but the description adds significant value beyond the schema by explaining the fallback search algorithm, what the query matches against, and the default limit behavior. It also clarifies the status filter and how results relate to other tools.

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 performs a read-only full-text search over support tickets, matching against subject and first customer message. It specifies the fallback mechanism and distinguishes itself from sibling tools like list_tickets (browsing) and search_kb (knowledge base).

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

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

Explicitly advises using this tool to find specific tickets by keyword rather than browsing the full list, and provides concrete use cases (checking for duplicates, locating related conversations). While it doesn't state when NOT to use it, the positive guidance is clear and actionable.

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

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

Despite no annotations, the description discloses that the reply is delivered immediately and reaches the customer, requires a 'send'-tier credential (draft-tier refused), and that the call is rejected if no customer email on file. Also mentions pricing.

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

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

Single paragraph, no fluff. All sentences are necessary and packed with information. Front-loaded with main action.

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

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

Given no output schema and only 2 parameters with full schema coverage, the description covers purpose, usage guidelines, behavior, parameter details, and pricing. Complete for an AI agent.

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 has descriptions for both parameters (100% coverage). Description adds context: body is final customer-ready message, ticketId comes from list_tickets or get_ticket, and recipient is the ticket's customer. Adds extra meaning beyond schema.

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

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

The description clearly states the tool sends a reply to a customer on an existing ticket and delivers it immediately, distinguishing it from the draft tool. The verb 'sends' and resource 'reply on ticket' are specific.

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 says to use when you have a final customer-ready answer, and to instead queue for approval use the draft tool. Also mentions credential requirements and that ticket must have a customer email.

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 provided, so description fully covers behavior: it is a non-destructive metadata update, never changes status, never contacts customer, and includes pricing ($0.03). These details go beyond the basic 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?

Three tightly-packed sentences: purpose, usage condition, behavioral caveats. No filler, front-loaded with the primary action, efficient and clear.

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 no output schema, the description covers the return behavior by stating what does NOT happen (status change, customer contact). It provides sufficient context for an AI agent to understand the tool's scope and side effects.

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 descriptions cover all parameters in detail (100% coverage). The description adds only the constraint 'at least one must be provided', which is a slight enhancement but not substantial 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?

Description clearly states the specific verb 'classify', the resource 'existing support ticket', and the exact attributes (priority, tags, category). It distinguishes itself from sibling tools like 'assign' and 'resolve' by mentioning it only updates metadata and does not change status.

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?

Description advises 'reach for this after reading a ticket to route or label it for the team', providing explicit context. It also states the condition 'at least one of priority, tagIds, or category must be provided', but lacks explicit when-not-to-use scenarios or alternative tools.

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