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

Beyond the annotations (readOnlyHint=false, destructiveHint=true), the description discloses critical behaviors: the customer never sees the note, no email is sent, and the note serves as a draft for human approval. It also explains that markdown/plain text is converted to HTML, adding meaningful context not covered by 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 well-structured and concise: a clear first sentence, a rationale paragraph, and a processing note. Each sentence earns its place by conveying purpose, usage, or behavioral details without unnecessary 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 simple tool with three parameters and no output schema, the description covers all essential aspects: what it does, when to use it, privacy behavior, no email, and format handling. The schema sufficiently covers parameter-level details, so no gaps are evident.

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 67%, with body and notify_emails already described. The description mentions 'Accepts markdown or plain text' for body, which is redundant with the schema, and does not add semantics for ticket_id (which is implied by the tool name). It does not compensate for the missing ticket_id schema description, but this is a common and obvious parameter.

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

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

The description opens with 'Add a private note to a ticket', using a specific verb and resource. The title and description explicitly emphasize that the customer never sees it and no email is sent, clearly distinguishing this tool from freshdesk_reply_to_customer and freshdesk_add_public_note.

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

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

The description provides explicit guidance: 'Prefer this over freshdesk_reply_to_customer whenever a person should approve the wording first.' It also explains that this is where a draft reply belongs, giving a clear use case and effectively naming an 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?

The description adds behavioral context beyond annotations: it reveals that 'Freshdesk does not email a public note,' that it is 'quieter than a reply,' and that 'it cannot be unsent.' This aligns with destructiveHint=true and provides specific, valuable details about the note's visibility and permanence.

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 well-structured. It opens with a clear statement of purpose, follows with important behavioral nuances, and ends with alternative tool guidance. Every sentence contributes meaning 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 the simplicity of the tool (two parameters, no output schema) and the presence of annotations, the description is complete. It covers the action, the customer-facing implications, the lack of email, the permanence, and the relationship to sibling tools. No critical context 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 0% description coverage, so the description must compensate by explaining parameters, but it does not. While ticket_id and body are self-explanatory from names, the description does not explicitly clarify their meaning or format, adding no value beyond the schema's type constraints.

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

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

The description states a specific verb and resource: 'Add a note the requester CAN see on the support portal.' It clearly differentiates from siblings by noting the note is public, not emailed, and permanent, which distinguishes it from reply and private note 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?

Explicit usage guidance is provided: 'If you want the customer to actually receive the message, use freshdesk_reply_to_customer. If a human should approve it first, use freshdesk_add_private_note.' This directly contrasts with alternative tools and gives clear when-to-use versus when-not-to-use context.

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

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

Despite annotations already indicating read-only and non-destructive behavior, the description adds substantial behavioral detail: it does not trust ticket status, compares last reply times per ticket, excludes customer-waiting and terminal tickets, and orders by customer recency. This is exactly the kind of context that helps an agent predict behavior beyond the safety flags.

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

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

The description is well-structured and every sentence contributes. It opens with a clear one-liner, then expands into behavior, ordering, and next steps without redundancy. It is appropriately sized for the tool's complexity and 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?

Given the absence of an output schema, the description adequately covers what the tool returns (a queue ordered by recency) and how to proceed. It explains the filtering logic, the exclusion criteria, and the intended workflow, making it complete 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%, so the baseline is 3. The description goes beyond the schema by providing usage nuances: 'Widen it to catch quiet tickets' for days and 'Raise it on a busy instance' for pages, adding practical semantic value to the parameter descriptions already present.

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 what the tool does: it identifies the queue of tickets where the support team owes a reply. It uses a specific verb ('find'), names the resource ('tickets awaiting our reply'), and distinguishes itself from siblings by explaining it does not rely on ticket status. The contrast with status-based filtering and the mention of comparing reply timestamps clarify its unique scope.

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

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

The description explicitly positions this as the entry point for 'what do I have to answer', providing clear context for when to use it. It also advises reading the full thread with freshdesk_get_ticket and freshdesk_get_conversations before drafting, which outlines a workflow. However, it lacks explicit 'when not to use' guidance or named alternatives (e.g., freshdesk_search_tickets for different queries), so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds that the output is markdown, which is useful but limited. It does not disclose any behaviors such as error handling, rate limits, or whether metadata is included alongside the body.

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 eight words, succinctly conveying the core output format without unnecessary detail. It is front-loaded and every word earns its place. The brevity is effective for a simple retrieval tool, though it sacrifices explanatory richness.

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 integer parameter, no output schema) and strong annotations, the description is minimally adequate. However, it lacks any connection to sibling search tools and does not clarify what fields beyond the body might be returned. It is functional but leaves gaps in expected 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 schema has one parameter, article_id, with zero description coverage. The tool description does not explain what article_id refers to or how to locate it, leaving the agent to rely solely on the parameter name. Since schema coverage is 0%, the description should compensate, but it fails to provide any meaningful context.

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 that the tool returns the full body of a solution article in markdown, which specifies both the resource and output format. The title explicitly states 'Get one knowledge base article,' reinforcing the action. It is distinguishable from sibling tools like freshdesk_search_knowledge, but the description alone lacks the explicit verb.

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 given on when to use this tool versus alternatives such as freshdesk_search_knowledge or freshdesk_get_canned_response. There is no mention of prerequisites or how to obtain an article_id. The description does not indicate whether this should be used after searching for an article or for direct retrieval.

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

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

Annotations already indicate read-only and non-destructive. Description adds valuable behavior: placeholders are left untouched and must be substituted manually, and the output is markdown. This goes beyond the structured fields.

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 sentence, front-loaded with the core output and a critical caveat. Every word adds value with no redundancy.

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

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

For a simple single-parameter read tool, the description covers the return format and a key behavioral nuance. No output schema exists, but the description sufficiently explains what the agent will receive.

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 0%, and the description does not explain canned_response_id beyond its name. The parameter name is self-explanatory, but no guidance is given on finding or using the ID.

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 it retrieves a single canned response's full body as markdown, distinguishing it from list_canned_responses. The verb 'get' plus 'one' precisely defines the scope.

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

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

The context is clear: use when you need the body of a specific canned response. It implies distinction from listing tools, but doesn't explicitly name alternatives or exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds that the response includes notes and custom fields, providing behavioral detail beyond the annotations. There is no contradiction.

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

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

The description is two sentences, front-loaded with the core definition, and every sentence contributes meaning. It is concise and well-structured without any fluff.

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

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

For a simple single-parameter read-only tool, the description is fairly complete: it defines the entity, indicates what is included (notes and custom fields), and states when it is useful. The only notable gap is the lack of parameter guidance, but overall it is adequate for the low complexity level.

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

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

The schema has zero description coverage for the single parameter (company_id), and the tool description does not mention the parameter at all. While the parameter name is self-explanatory, the description fails to compensate for the lack of schema documentation, leaving the agent without any semantic guidance beyond the name and constraints.

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

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

The title 'Get a company' provides a clear verb and resource, and the description adds that it returns notes and custom fields, distinguishing it from sibling tools like freshdesk_get_contact. However, the description itself is more of a definition of a company than an explicit statement of the retrieval action, so it doesn't fully earn a 5.

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

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

The description explicitly states a use case: 'Useful for tone and for knowing how much a ticket matters.' This gives clear context for when to use the tool, though it does not mention alternatives or exclusions, as a perfect 5 would.

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

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

Annotations indicate readOnlyHint=true and destructiveHint=false, and the description does not contradict them. It adds value by specifying the exact data returned (name, email, job title, company, custom fields) and the relationship to tickets, which is useful beyond the structured 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 short sentences, front-loaded with the outcome. Every word earns its place, and there is 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?

Given the simple nature of a get-by-ID operation, the description adequately covers the return fields and input provenance. It does not describe error cases, but the lack of an output schema makes the enumerated fields useful. It could mention 'not found' behavior, but this is a minor gap for a straightforward read tool.

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

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

The schema only defines contact_id as an integer. The description explains that this corresponds to the requester_id from a ticket, adding meaningful semantic context that the schema lacks. With 0% schema description coverage, this hint is valuable.

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 gets a contact and enumerates the returned fields (name, email, job title, company, custom fields). It distinguishes from sibling tools like get_ticket and get_company by focusing on the person behind a 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 a concrete usage instruction: 'Use the requester_id from a ticket.' This indicates when to use the tool, though it doesn't explicitly mention alternatives or exclusions. The context is clear enough for the agent.

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

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

The description adds helpful context beyond the readOnlyHint annotation, such as message visibility categories and the presence of automated private notes. However, it states 'Every message on a ticket' while the schema's limit parameter (default 30) implies only the most recent subset is returned, creating a potential overstatement of 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 well-structured with a clear front-loaded statement, a bulleted list for message types, and two concise caveats. Each sentence adds value without redundancy, making it easy to scan and understand.

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 thoroughly explains the semantic content of the response (message types, ordering, visibility) and important caveats about ticket description and automated notes. It lacks explicit mention of the limit/truncation behavior, but the schema provides that detail, so overall it is sufficiently complete for a read-only tool.

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

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

Schema description coverage is only 33%, and the tool description does not explain the parameters. ticket_id, limit, and max_chars_per_message are not described beyond their names and schema constraints, so the description fails to compensate for the low coverage.

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

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

The description clearly states the tool reads the full ticket thread, lists messages oldest first, and labels each by author and visibility. It also distinguishes itself from freshdesk_get_ticket by noting the ticket description is fetched separately, 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?

The description provides context for use ('before drafting from this') and explicitly directs users to freshdesk_get_ticket for the ticket description, which is a relevant alternative. It does not enumerate all sibling tools or exclusions, but the main decision point is covered.

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 destructiveHint=false, covering the safety profile. The description adds semantic context about what related tickets mean, but does not disclose additional behavioral traits such as return format or pagination.

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

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

The description is two sentences long and efficiently conveys the core concept and a use case. Each sentence adds value, with no redundant information.

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

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

Given the simplicity of the tool (one parameter, no output schema) and the availability of annotations, the description is reasonably complete. However, it leaves ambiguity about the exact return type and the directionality of relationships (e.g., whether both parent and children are included), which could confuse an 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?

The schema has one parameter (ticket_id) with 0% description coverage. The description implies that 'this one' refers to the given ticket ID, providing some context, but it does not explicitly explain the parameter's purpose or constraints beyond what the schema defines.

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 resource (related tickets) and the relationship concept (parent/children/tracker), but it lacks a direct verb like 'retrieves' or 'lists'. It distinguishes itself from sibling tools by focusing on linked tickets rather than general ticket data.

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 (e.g., recurring incidents, finding the tracker for a tracked ticket) but does not explicitly mention alternatives or exclusions. The use case is illustrated with the 'recurring incident' example, making the intended scenario 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 declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable context beyond annotations: the description field is the original customer request converted from email HTML to markdown, not the latest message. This is meaningful behavioral context but stops short of richer detail like return format or pagination.

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, focused paragraphs. The first states what the tool returns; the second clarifies a subtle point about the description field and gives a directional pointer to a sibling tool. No filler words or redundant repetition of schema information.

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

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

For a simple read-only tool with one parameter and no output schema, the description is complete. It lists what detail is included, clarifies the meaning of the description field, and warns users not to mistake it for the latest message while directing them to the appropriate tool for the thread. The annotations cover safety aspects, so 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 only parameter, ticket_id, is not explicitly described in the text. The schema already documents it clearly (required integer with range). The description's mention of 'single ticket' implies an ID is needed but doesn't explicitly map 'the ticket's ID to the ticket_id parameter. With 0% schema coverage in the description, a more explicit link would help, though the parameter's meaning is self-evident from the tool name and 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 retrieves 'Full detail for a single ticket' and enumerates specific content (fields, requester, company, reply timestamps). It also differentiates from siblings by noting the description is the original request, not the latest message, and explicitly names freshdesk_get_conversations as the alternative for the thread.

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 explicit usage guidance: use this tool for full ticket detail, but if you need the thread/latest messages, use freshdesk_get_conversations instead. This directly addresses 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?

Annotations already declare readOnlyHint, openWorldHint, and destructiveHint, so the description adds valuable semantic context beyond those flags: it explains that statuses are account-defined and that default codes like 2=Open may be unused. This helps the agent understand the data's reliability without contradicting the annotations.

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

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

The description is efficient: the first sentence captures the full scope, and the second adds an essential warning. No filler or repetition; every sentence earns its place. The structure front-loads the purpose and then provides practical context.

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 metadata tool with no output schema, the description is highly complete. It enumerates all data categories returned (codes, labels, choices) and explains why the tool is important for filtering and writing. The sibling tools are all operational, so this description fully covers the tool's role.

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?

There are no parameters, so the baseline is 4 per the rubric. The description does not mention parameters (there are none), and the empty schema fully covers this aspect, so no additional parameter information is needed.

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 returns the full field inventory for the account, listing statuses, priorities, sources, ticket types, and custom fields. It uses specific verbs and resource scope ('real field inventory') and is distinct from sibling tools that operate on tickets or articles.

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 read this tool 'before filtering or writing', which is a concrete usage recommendation. It also warns against relying on Freshdesk defaults because accounts define their own statuses, effectively specifying when this tool is necessary and preventing 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 adds behavioral context beyond the annotations: it reveals that the canned responses contain approved wording, tone, legal caveats, and escalation phrasing, which explains the tool's value. It also discloses the dual behavior depending on folder_id presence. No contradiction with readOnlyHint=true.

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, using two short paragraphs. It front-loads the key purpose in the first sentence, then provides actionable usage guidance and parameter behavior. 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 tool's simple interface (one optional parameter, no output schema) and the annotations indicating a safe read operation, the description covers the essential details: what is listed, when to use it, and how the parameter affects results. It is complete enough for an agent to invoke correctly.

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

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

With only one optional parameter and no schema descriptions, the description compensates by explaining the folder_id parameter's meaning: 'Pass a folder_id to list its responses, or omit it to see the folders.' This adds functional semantics beyond the schema's integer type, though it does not specify the expected value beyond the parameter name.

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 what the tool does: it lists the team's canned responses, organized by folder. It distinguishes from siblings like freshdesk_get_canned_response by focusing on listing vs retrieving a single response, and the folder_id guidance further clarifies scope.

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

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

The description explicitly instructs when to use this tool: 'Reach for this before inventing a phrasing' and explains the purpose of using approved wording. It also provides conditional usage for folder_id, which serves as guidance on when to pass the parameter. While it doesn't name sibling tools directly, it gives clear context and an implicit 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds that the tool returns 'every recent ticket' from the same person, which is a completeness claim beyond the annotations. It doesn't disclose sorting or pagination, but with the annotations providing the safety profile, this 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, front-loaded with a clear definition and followed by a usage rationale. Every sentence earns its place; there is no fluff or redundant information.

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

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

The tool is simple (3 params, no output schema), and the description gives a clear purpose and usage context. However, it lacks parameter explanations and does not explicitly contrast with sibling list/search tools. This leaves the agent with some ambiguity about input semantics and return format, making it minimally complete.

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

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

Schema description coverage is 0%, so the description must compensate. It does not explain any of the three parameters (requester_id, days, limit). 'Recent' hints at days but does not clarify defaults or constraints. The parameter names are somewhat self-explanatory, but the description fails to provide necessary details for correct invocation.

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 that the tool lists every recent ticket from the same person, which directly addresses the question 'have they asked this before?'. This is a specific verb+resource (list tickets) with a clear scoping (by requester), distinguishing it from siblings like freshdesk_list_tickets (all tickets) or freshdesk_get_related_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 gives a strong when-to-use directive: 'Read this before drafting anything that explains a known issue'. It also implies a workflow (point back to previous answers rather than repeating them). It does not explicitly name alternative tools, but the context is clear enough for an agent to know when to invoke this tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable context: statuses are validated against the account so invalid statuses won't silently return empty results, and empty statuses means all non-terminal statuses. It also notes that reply state is not derivable from status, which is a useful limitation 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?

The description is two short paragraphs, front-loaded with the main purpose, followed by status behavior and a clear alternative. Every sentence earns its place—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 read-only list tool with good annotations and schema, the description covers purpose, usage, and status behavior. It omits a precise definition of 'recent activity' and 'non-terminal status', but these are minor gaps given the defaults and sibling context, making it largely complete.

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

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

Schema description coverage is only 25%, with only the statuses parameter having a schema description. The description explains statuses can be names or codes and are validated, but days, limit, and pages are left to their self-evident names and schema defaults. This partially compensates for the low coverage but does not fully detail all parameters.

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 'List tickets by recent activity, optionally filtered by status' — a specific verb, resource, and scope. It clearly distinguishes from siblings by contrasting with freshdesk_find_unanswered_tickets and mentioning the 'what is going on' use case.

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: 'This answers "what is going on"' and when not to: 'for "what do I owe an answer on", use freshdesk_find_unanswered_tickets instead'. Also clarifies that leaving statuses empty returns every non-terminal status, which is important usage guidance.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, covering the mutation aspect. The description adds the valuable behavioral trait that the entry is internal and invisible to the customer. It does not elaborate on other side effects, authorization needs, or return details, but given annotation coverage, this 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 short sentences, front-loaded with the action and resource, and every word earns its place. No fluff 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 simple logging tool with 5 parameters and no output schema, the description gives the key context (internal bookkeeping, customer invisible) and annotations cover safety. However, it lacks mention of return behavior, prerequisites (e.g., ticket must exist), and permissions. It is minimally complete but leaves gaps that an agent might need to infer.

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 low (40%), and the tool description does not compensate by explaining parameter meanings. The description provides no additional information about ticket_id, time_spent, note, agent_id, or billable. While names are self-explanatory, the description adds no value beyond the schema.

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

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

The description clearly states the action ('Record a time entry') and the resource ('a ticket'). This distinctly separates it from sibling tools like adding notes or updating tickets, 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?

The description provides clear context for when to use this tool: 'Internal bookkeeping: the customer never sees it.' This implies it is for internal time tracking and not for customer-facing communication. However, it does not explicitly name alternatives or exclusions, 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 description adds substantial behavioral context beyond the annotations: 'cannot be unsent' reinforces destructiveHint=true, and the two-step preview explains that a retry costs a preview, not an email. It also details what the preview returns (recipients, subject line, rendered HTML), making side effects 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?

Three concise paragraphs front-load the critical warning about emailing the requester, then explain the two-step flow, and end with an alternative. Every sentence earns its place; there is no repetition 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?

Given the tool's moderate complexity and no output schema, the description covers the essential behavioral contract: what is sent, the preview/send flow, safety against accidental sends, and the appropriate alternative for human approval. It is complete enough for an agent to use correctly without further clarification.

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 meaning for the confirm parameter ('called without confirm... returns a preview; call it again with confirm:true to actually send'), and the preview mention implies cc_emails/bcc_emails are included in recipients. However, it does not elaborate on from_email, cc_emails, or bcc_emails beyond the schema's existing descriptions. With 50% schema coverage, this is adequate but not exceptional.

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: 'Send a public reply on a ticket.' It immediately clarifies the key distinction from sibling tools by emphasizing 'THIS EMAILS THE REQUESTER and cannot be unsent,' which differentiates it from freshdesk_add_public_note and freshdesk_add_private_note.

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 usage guidance: the two-step confirm flow with preview, and a clear when-not-to-use directive: 'If a human is supposed to approve the wording, do not use this at all: put the draft in freshdesk_add_private_note and let them send it.' This names an alternative and defines the boundary.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, but the description adds significant behavioral context: it explains that Freshdesk has no v2 search endpoint, so the tool walks the category/folder tree, costs several rate-limit calls, and caches nothing. This goes beyond the annotations and is valuable for the agent.

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

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

The description is concise and front-loaded with the main purpose. The second paragraph adds important technical context without fluff. Every sentence carries meaning, so it earns a 5.

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 no output schema, the description does not explicitly state what the tool returns (e.g., a list of matching articles). It also doesn't explain the effect of limit or include_drafts. While the purpose and cost are clear, the lack of return-value detail leaves gaps for an agent invoking the tool.

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

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

Schema description coverage is only 33% (only 'term' has a description). The tool description does not compensate by explaining the 'limit' or 'include_drafts' parameters. It mentions 'published' articles but does not address how include_drafts overrides that, leaving parameter semantics unclear.

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

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

The description clearly states the tool's purpose with a specific verb and resource: 'Search published solution articles by keyword'. It also provides the context of pointing a reply at a documented answer, which distinguishes it from sibling tools like freshdesk_search_tickets or freshdesk_get_article.

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 a clear use case ('so a reply can point at the documented answer') and practical guidance ('worth calling with a narrow term'). However, it does not explicitly mention when not to use it or name alternative tools, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral detail beyond that: query character limit (512), pagination (30 per page, 10 pages max, 300 results cap), and exclusion of archived tickets. It also explains that these are hard API limits, not server-side choices, which helps the agent set expectations.

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

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

The description is dense but well-organized: purpose statement, query syntax, then hard limits. Every sentence contributes necessary information for using the tool correctly. It is appropriately sized for the complexity of a flexible search endpoint, with no fluff.

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

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

Given the lack of an output schema, the description covers the main usage complexity (query syntax, limits, archived exclusion) thoroughly. It does not explicitly describe the return format, but for a search tool returning ticket objects, this may be inferred from related tools. The absence of a response structure mention is a minor gap, not a critical one.

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 only 50% (query has a description, page does not). The description adds significant semantic value by detailing the Lucene-like query syntax, supported fields, date formats, and comparison operators. It also clarifies the page limit ('only 10 pages are reachable'), complementing the schema's minimum/maximum for page. This fully compensates for the coverage gap.

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

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

The description clearly states the tool's purpose as a filter/search endpoint for tickets, specifically 'for questions a plain listing cannot express.' This distinguishes it from the sibling tool freshdesk_list_tickets, which handles plain listings. The verb and resource are 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 description provides clear context: use this when a plain listing cannot express the query, implying a complex, filter-based search. It does not explicitly name alternatives like freshdesk_get_ticket for single-ticket retrieval, but the contrast with 'plain listing' gives adequate guidance. No exclusions are stated, 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 description adds substantive behavioral context beyond the annotations (destructiveHint, idempotentHint, readOnlyHint=false). It discloses that the customer is not emailed, that status changes are visible on the portal, that Freshdesk automations may react, and that status/priority values are validated server-side with a helpful listing of valid values. These details give the agent a clear picture of side effects and failure modes.

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 the action and scope in the first sentence, followed by two sentences each adding unique behavioral information. There is no redundancy or filler; every sentence earns its place, making it easy for an agent 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 mutation tool with 8 parameters, no output schema, and rich annotations, the description covers the key behavioral outcomes (customer notification, portal visibility, automation triggers, validation). The main gap is that it does not explicitly clarify whether unspecified fields remain unchanged (partial update vs full replacement), and it omits any mention of the return value. These are non-fatal but leave minor 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 already documents several parameters (tags replacement semantics, status name/code, priority values, custom_fields keying). The description adds value by mapping human-friendly names (assignee, group) to the actual parameters (responder_id, group_id) and by explaining the validation behavior for status and priority, which goes beyond the schema. However, it does not describe every parameter in detail, so a 4 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 clear verb 'Move a ticket' and explicitly lists the exact fields it modifies (status, priority, assignee, group, type, tags, custom fields). This immediately distinguishes it from communication-oriented siblings like freshdesk_reply_to_customer by indicating it changes ticket properties rather than sending messages. The additional note that 'the customer is not emailed by this' further clarifies its scope.

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

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

The description clearly implies when to use this tool: when a ticket's fields need to be updated. It provides important contextual guidance by noting that the customer is not emailed but that status changes are portal-visible and automations may react. However, it does not explicitly name alternative tools or state when-not-to-use, falling slightly short of a full 5.

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