freshdesk

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

The description states the tool 'Add a note to a ticket', an additive and non-destructive operation, while the annotations include destructiveHint: true. This is a direct contradiction. The description does not disclose any destructive behavior, and the conflicting annotation means the agent cannot trust whether this action is safe.

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

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

The description is concise—only two sentences—and front-loaded with the main action. It includes essential details like the default privacy and API endpoint without any waste, earning a top score.

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 an add-note tool with 4 parameters fully described in the schema, the description gives the core action, default privacy, and API reference. It does not mention return values or side effects, but given the schema coverage and low complexity, it is reasonably complete. The contradiction with annotations is a transparency concern, not a completeness gap.

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

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

All four parameters have descriptions in the input schema, so the baseline is 3. The description repeats the `private` default and gives the REST endpoint, but does not add meaning beyond what the schema already provides. Therefore, a score of 3 is appropriate.

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

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

The description clearly states the action 'Add a note to a ticket' with a specific verb and resource, distinguishing it from sibling tools like freshdesk_reply_ticket. It also explains the default privacy and includes the REST endpoint, reinforcing the tool's purpose.

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

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

The description provides clear context by stating that notes are internal (private) by default and how to make them public, which guides usage. However, it does not explicitly mention when to use this tool versus alternatives like freshdesk_reply_ticket, so it lacks explicit exclusions or alternative references.

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

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

The description adds minimal behavioral context beyond the creation action itself. It does not disclose potential side effects, idempotency, error behavior, or authentication requirements. The annotation destructiveHint=true is misleading for a create operation, and the description does not clarify or correct this.

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

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

The description is extremely concise, consisting of two sentences that front-load the core purpose. Every word earns its place, and it avoids unnecessary detail.

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

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

The description is adequate for a simple create tool but lacks context about return values, custom field structure, or domain formatting. With no output schema, the agent is left unaware of the response shape. The schema covers parameter details, but the description does not compensate for missing behavioral or usage 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?

The input schema already provides descriptions for all five parameters, so the description adds little value. It only reiterates that 'name' is required, which is already in the schema's required array. The baseline of 3 is appropriate given high schema coverage.

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

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

The description clearly states the action 'Create a company' with a specific resource (company) and a direct reference to the REST endpoint. This distinguishes it from sibling tools like create_contact and create_ticket.

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

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

No guidance is provided on when to use this tool versus alternatives like update_company or list_companies. The description only mentions that 'name' is required, but does not explain conditions, exclusions, or comparisons to other tools.

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

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

The annotation destructiveHint: true contradicts the description 'Create a contact', as creating a contact is not a destructive operation. The description provides no additional behavioral context and actually conflicts with the annotation, so it scores 1.

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

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

The description is extremely concise and front-loaded: 'Create a contact' immediately conveys the action and target. The additional REST endpoint reference is useful and non-redundant. No fluff or wasted words.

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

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

With 12 parameters and no output schema, this minimal description leaves out important context such as response format, side effects, or prerequisites. The contradictory destructiveHint annotation adds confusion, and the description does not compensate for the lack of structural clarity.

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

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

Schema description coverage is 100%, so the input schema already documents every parameter. The description adds no extra meaning beyond what the schema provides, except highlighting name as required, which is also in the schema. Baseline 3 is appropriate.

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

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

The description clearly states 'Create a contact' — a specific verb and resource that distinguishes it from sibling tools like create_company and create_ticket. It also cites the REST endpoint, reinforcing the action.

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

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

There is no guidance on when to use this tool versus alternatives such as update_contact for existing contacts. The mention of 'name required' and the REST endpoint are parameter/implementation details, not usage 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?

The description adds behavioral context beyond the destructiveHint annotation by specifying required fields, HTML content for description, and the exact enum values for status, priority, and source. It also mentions the REST endpoint. This is useful, though it does not cover side effects like return values or error conditions.

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 states the action, then required fields, then enum mappings, then the REST endpoint. Every sentence adds direct value without verbosity. The information is front-loaded 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?

For a tool with 15 parameters and no output schema, the description covers the most critical aspects: the core action, required fields, requester options, and key enum values. Remaining optional parameters are documented in the schema. It does not explain return values, but that is less critical for a create operation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description largely repeats what the schema already provides (required fields, enum values, requester requirement). It does not add new meaning beyond the schema descriptions, so no higher score is warranted.

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 starts with a specific verb and resource: 'Create a ticket.' It clearly distinguishes from sibling tools like freshdesk_update_ticket, freshdesk_add_note, and freshdesk_create_company by naming the resource and action. The REST endpoint is also provided, further clarifying the operation.

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

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

The description clearly states the action and highlights the required fields and requester options, giving practical usage context. It does not explicitly mention when not to use this tool or point to alternatives, but the context is clear enough for a straightforward create operation.

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

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

The annotations include readOnlyHint=true, and the description's GET method aligns with that. It adds the REST endpoint as context, but does not disclose any additional behavior like error handling, response format, or authentication needs, though the bar is lowered by the annotation.

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

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

The description is extremely concise: two short sentences with front-loaded purpose. Every word earns its place, and there is no filler or redundant information.

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

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

For a simple read-only getter with one well-described parameter, the description is almost complete. It could explicitly mention that the response returns the agent object, but that is implied by the GET semantics and the simple nature of the tool.

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

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

The parameter 'id' has 100% schema description coverage in the input schema. The description simply restates 'by id' and adds no extra semantic value beyond what the schema already provides, which is acceptable given the high 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 action: 'Get a single agent by id.' The REST path 'GET /agents/{id}' reinforces the specific resource. It differentiates from the sibling 'list_agents' by emphasizing the singular nature.

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?

Usage guidance is only implied: the word 'single' suggests this is for retrieving one agent rather than listing all. No explicit when-to-use or alternatives are provided, such as when to use list_agents instead.

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

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

Annotations already provide readOnlyHint=true, signaling this is a safe read operation. The description adds the REST endpoint but doesn't disclose any additional behavioral traits such as error handling, rate limits, or response details. It adds minimal value beyond what annotations already convey.

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

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

The description is two short sentences with no fluff. It front-loads the core action and includes the REST endpoint as a useful reference. Every word earns its place.

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

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

For a simple read-only tool with one parameter, the description plus annotations and schema provide complete context. There is no output schema, but for a GET-by-id operation, the return is straightforward and doesn't need elaboration. The tool is adequately documented.

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

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

The input schema has 100% description coverage for the 'id' parameter ('The company id.'), so the baseline is 3. The description's 'by id' aligns with the schema but doesn't add any extra meaning or formatting details beyond what's 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 states a specific verb ('Get') and resource ('a single company by id'), clearly distinguishing it from list_companies (which retrieves multiple companies) and create_company. The REST endpoint reference adds precision and reinforces the intended operation.

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

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

The phrase 'single company by id' clearly indicates when to use this tool: when you have a specific company ID and need one record. It doesn't explicitly mention alternatives, but the context is clear enough that an agent would know to use list_companies for fetching all companies or search for finding by name.

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

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

The annotations already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds the underlying REST method (GET /contacts/{id}), which is useful but does not go beyond that. No additional behavioral traits (e.g., response format, error conditions, rate limits) are disclosed, so the added value over annotations is minimal.

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

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

The description is extremely concise: two short sentences with no redundant information. It front-loads the core purpose ('Get a single contact by id') and follows with the REST endpoint for clarity. Every word earns its place.

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

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

The tool is simple with one parameter (id) and no output schema or enums. The description, combined with the readOnlyHint annotation and schema coverage, provides enough context for an agent to use it correctly. It does not explain the response structure, but this is a straightforward lookup operation where the return value is implicit. The main gap is the lack of any error/edge case mentions, but these are not critical for a simple get-by-id.

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

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

The schema description coverage is 100%, with the 'id' parameter fully described as 'The contact id.' The description reinforces that the id is used to fetch a single contact. Since the schema already provides complete parameter meaning, the description adds no extra semantic value beyond confirming the purpose.

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 specific action: 'Get a single contact by id.' This distinguishes it from sibling tools like freshdesk_list_contacts (list all), freshdesk_search_contacts (search), freshdesk_create_contact, and freshdesk_update_contact. The inclusion of the REST endpoint further clarifies the exact operation.

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

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

Usage context is clear: you use this tool when you have a contact id and need the corresponding contact record. The description does not explicitly list alternatives or exclusion criteria, but the resource-specific framing ('contact by id') makes the intended use unambiguous given the sibling set.

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

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

The readOnlyHint annotation already declares this is a safe read operation, and the description's REST GET reference aligns with that. However, no additional behavioral details are provided (e.g., error handling, authentication, rate limits). With annotations covering the safety profile, this is acceptable but not enriched.

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

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

The description is one sentence, omits filler, and front-loads the core action. The REST endpoint reference is concise and relevant, adding no waste.

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

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

For a simple get-by-id operation with full schema and a read-only annotation, the description is largely complete. It does not describe the response format or error codes, but for this trivial tool, that is not a critical gap.

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

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

The schema provides 100% coverage with descriptions for both 'id' and 'include'. The description only repeats the 'by id' notion and adds no new meaning beyond the schema. Baseline 3 applies due to high schema coverage.

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

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

The description clearly states the action ('Get') and the resource ('a single ticket by id'), which distinguishes it from sibling tools like freshdesk_list_tickets and freshdesk_search_tickets. The REST endpoint reference reinforces the specific operation.

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

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

The description implies the appropriate usage scenario: when you have a specific ticket ID and need that one ticket. It does not explicitly mention alternatives, but the 'by id' wording and the schema's required 'id' parameter make the context clear.

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

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

The readOnlyHint annotation already discloses the read-only nature. The description adds only the REST endpoint reference, which provides no additional behavioral context about pagination, filtering semantics, or limitations. Beyond the annotation, it adds essentially no transparency.

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

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

The description is a single, front-loaded sentence that states the purpose immediately and includes no unnecessary words. It is highly concise and well-structured.

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

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

Given the fully documented schema and read-only annotation, the description is minimally sufficient for a list tool. However, it lacks usage guidance and does not describe the return shape, which leaves some ambiguity for a tool with no output schema. It is adequate but not complete.

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

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

The input schema documents all 6 parameters with descriptions (100% coverage). The description itself adds no parameter-level detail beyond what the schema provides, so the baseline score of 3 applies.

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

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

The description 'List/filter agents' clearly identifies the action (list/filter) and resource (agents), and the REST endpoint reference adds precision. It distinguishes from sibling tools like freshdesk_get_agent by explicitly targeting the list operation.

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

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

The description implies use for listing or filtering agents, but it does not explicitly state when to prefer this tool over alternatives such as freshdesk_get_agent, nor does it mention any exclusions or prerequisites. This is implied usage rather than explicit guidance.

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

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

The readOnlyHint annotation already declares the operation is safe, so the description does not need to repeat that. It adds the REST method, which is a minor detail but does not disclose deeper behaviors like return format, pagination defaults, or rate limits. With annotations covering safety, this is an acceptable but not enriched transparency level.

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

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

The description is extremely concise with two short sentences that state the purpose and the REST endpoint. Every sentence earns its place without redundant or verbose content, making it well-structured and easy to parse.

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

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

Given the tool's simplicity (two optional pagination parameters, no output schema), the description combined with the readOnlyHint and complete schema provides sufficient context for an agent to invoke it correctly. While return details are not specified, it remains a basic list operation. This is more complete than a bare tautology but less rich than tools that need extra behavioral caveats.

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

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

The input schema covers 100% of parameters with descriptions for page and per_page. The description adds no additional parameter semantics beyond what the schema already provides, so the baseline 3 is appropriate.

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

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

The description clearly states 'List companies' with a specific verb and resource, and further specifies the Freshdesk REST endpoint 'GET /companies'. This distinguishes it from sibling list tools like freshdesk_list_agents or freshdesk_list_tickets by naming the resource directly.

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

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

No guidance is provided on when to use this tool versus alternatives such as freshdesk_get_company for a single company or other list_* tools. The description only restates the tool's function without any contextual when-to-use or exclusion information.

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

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

The annotations already declare readOnlyHint=true, and the description adds the HTTP GET method, which reinforces the non-destructive nature. However, it does not disclose pagination defaults, response format, or any rate-limit behavior, but with annotations present, this is a minimal acceptable disclosure.

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

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

The description is one short sentence plus the REST path, with zero filler or redundant information. It is front-loaded and entirely focused on the core purpose, making it highly efficient.

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

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

With a read-only annotation and fully self-documenting parameters, the description is minimally adequate. However, it lacks any mention of the return format or pagination behavior, and the absence of an output schema means the agent relies on assumptions about the response structure. This is a clear gap, though not severe for a straightforward list endpoint.

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

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

The input schema provides full descriptions for all 8 parameters (100% coverage), so the description does not need to elaborate. The description's generic 'List/filter contacts' adds no specific parameter detail, but the baseline score of 3 is appropriate because the schema does the heavy lifting.

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 'List/filter contacts' with a specific resource and verb, and includes the REST endpoint GET /contacts. It clearly identifies the operation but does not explicitly distinguish itself from sibling freshdesk_search_contacts, which also lists contacts with filters.

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

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

The description provides no guidance on when to use this tool versus alternatives like freshdesk_search_contacts. It only states the basic list/filter capability, leaving the agent to infer usage from the endpoint and filter parameters.

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

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

The readOnlyHint annotation already covers safety, and the description adds the REST endpoint (GET /groups) and semantic context. However, it does not disclose pagination behavior or return format beyond what the schema implies, so it offers only modest additional transparency.

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

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

The description is a single sentence with a parenthetical clarification and a REST endpoint reference. Every part is useful, and it is front-loaded with the core action and resource.

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

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

For a simple list operation with well-documented pagination parameters and a read-only annotation, the description is mostly complete. The only minor gap is the absence of an explicit statement about the return value (a list of groups), but the verb 'List' makes this implicit.

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

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

Schema coverage is 100%, with both page and per_page having clear descriptions. The description itself adds no parameter-specific meaning beyond the schema, meeting the baseline for well-documented 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 uses a specific verb and resource ('List groups') and clarifies the domain concept ('agent groups tickets are routed to'). It clearly distinguishes itself from sibling tools like list_agents or list_tickets by identifying the exact resource.

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

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

The description clearly implies when to use this tool: when the user needs to retrieve agent groups. It provides context about what groups are, but no explicit exclusions or alternatives are named, which is acceptable for a simple read-only list 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?

The annotation readOnlyHint=true already signals a safe read operation, and the description adds the specific content ('replies and notes') and the REST GET method. While it doesn't detail pagination or ordering, the annotation covers safety, making this sufficiently 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 two concise, front-loaded sentences with no verbose content. The first sentence states the purpose, the second provides a precise API reference, making it efficient and to the point.

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 this is a read-only list tool with pagination parameters fully described in the schema and a clear annotation, the description is complete. It states what is listed (conversations), the scope (ticket), and the API endpoint, while the output schema absence doesn't require further elaboration for a standard list operation.

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

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

The schema provides 100% description coverage for all three parameters, so the description doesn't need to add parameter details. The REST endpoint in the description does reinforce that 'id' is a ticket id, but this is marginal beyond the schema's own description.

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

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

The description uses a specific verb ('List') and resource ('conversations on a ticket'), clearly distinguishing it from siblings like get_ticket or list_tickets. It also includes the REST endpoint, reinforcing exactly what the tool does.

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

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

The description implicitly states when to use the tool (when needing replies/notes on a ticket), and no sibling tool performs this exact function, so the context is clear. However, it doesn't explicitly discuss alternatives or when not to use it, which would warrant a 5.

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

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

The readOnlyHint annotation already covers safety, so the description adds marginal value with 'max page 300' and the REST method. It does not disclose pagination quirks, rate limits, or response structure, but the annotation lowers the burden.

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 core action, and contains no filler. Every word contributes meaning, making it highly concise and well-structured.

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

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

With 10 parameters and no output schema, the description does not explain the return format, pagination behavior, or how parameters interact. It mentions 'max page 300' but lacks the context needed for confidently invoking the tool, especially given the presence of similar 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%, with each parameter having a description. The tool description does not add any parameter-level meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly states the action ('List/filter tickets') and the resource (tickets), distinguishing it from sibling tools like get_ticket (single ticket) and search_tickets (search). The REST endpoint reference reinforces the operation.

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

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

No guidance is given on when to use this tool versus alternatives such as search_tickets or get_ticket. The description does not mention exclusions or prerequisites, leaving the agent to infer usage from the name alone.

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

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

Beyond the destructiveHint annotation, the description adds that the reply is 'sent to the requester', indicating external visibility and potential notifications. This is meaningful behavioral context. It doesn't cover all side effects (e.g., email triggers) but provides good value beyond 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 concise sentences, front-loaded with the primary action and audience. It includes the REST endpoint as useful technical context without unnecessary 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 mutation tool with 4 parameters and no output schema, the description adequately explains the purpose and key behavior (public reply sent to requester). It lacks explicit return value or error details, but for a simple reply action, the description is largely complete.

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

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

Schema description coverage is 100% with detailed parameter descriptions for id, body, cc_emails, and bcc_emails. The tool description adds no additional parameter semantics beyond the REST endpoint template, so the baseline of 3 applies.

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

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

The description clearly states 'Add a public reply to a ticket' with a specific verb and resource, and adds 'sent to the requester' to clarify scope. It distinguishes itself from sibling tools like freshdesk_add_note by emphasizing 'public'.

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

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

The description implies when to use this tool (for public replies visible to the requester) and implicitly differentiates from private notes. It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to select it appropriately.

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

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

Beyond the readOnlyHint annotation, the description discloses automatic double-quoting of the query value and the underlying REST endpoint. This adds useful behavioral context. It doesn't mention rate limits or response shape, but for a read-only search tool, the added details are sufficient.

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-loaded with the core purpose, and each sentence adds value: purpose, auto-quote behavior, and REST endpoint. No unnecessary words 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 tool with two params and no output schema, the description covers the essential aspects: query DSL, auto-quoting, and endpoint. It doesn't explicitly state the response format, but for a contact search tool, the expected return is implicit. Overall, it's adequate without 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?

The schema already covers both parameters with 100% description coverage, so the baseline is 3. The description adds value by providing multiple query examples and explicitly stating the auto-quote behavior, which clarifies how to format the query parameter beyond the schema's single example.

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 searches contacts using the Freshdesk query DSL, with a specific verb and resource. It distinguishes from sibling list tools by emphasizing the query-based search mechanism, though it doesn't explicitly name alternatives.

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

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

The description implies usage by providing example queries and noting the auto-quote behavior, but it does not explicitly state when to prefer this over list_contacts or other search tools. No exclusions or alternative guidance is given.

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

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

Beyond the readOnlyHint annotation, the description reveals that query values are automatically wrapped in double quotes and provides example syntax. It does not mention return format or rate limits, but the auto-quote behavior is a valuable addition.

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?

Description is concise and front-loaded with the core purpose, followed by a behavioral note, useful examples, and REST endpoint. No wasted sentences.

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 two-parameter search tool, the description explains the DSL, quoting, and provides examples, which is sufficient. It does not describe the return payload, but with the tool being a search this is not critical; schema covers pagination.

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

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

Schema already covers both parameters with descriptions, giving a baseline of 3. The description adds concrete query examples and the auto-wrap note, which helps the agent format queries correctly 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?

Clearly states the tool searches tickets using Freshdesk's query DSL, with a specific verb and resource. The examples and REST endpoint further clarify its function and distinguish it from sibling tools like list_tickets and get_ticket.

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

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

The description implies use for complex ticket searches via the DSL, but does not explicitly state when to prefer this over list_tickets or get_ticket. The examples illustrate capability, but no alternatives or exclusions are named.

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 destructiveHint annotation already signals mutation, but the description adds valuable context that only provided fields are changed, preventing assumptions about full replacement. It does not describe response format or permission requirements, but this is partially covered by the annotation.

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

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

The description is two sentences plus a REST endpoint reference. Every word is purposeful, front-loaded with the action, and free of redundancy.

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

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

The description adequately covers the main behavior and partial-update semantics for an update tool with a well-covered schema. It lacks explicit return value information, but this is not critical given the absence of an output schema and the straightforward nature of an update operation.

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

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

The schema covers all 11 parameters with descriptions, so the description does not need to add parameter-level detail. The description adds no extra parameter semantics beyond the schema, warranting the baseline score of 3.

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

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

The description clearly states the tool's action: 'Update fields on an existing contact.' This specifies the verb (update) and resource (existing contact), distinguishing it from sibling tools like create_contact, get_contact, and update_ticket.

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

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

The description implies usage context by saying 'existing contact' and emphasizes partial updates ('Only provided fields are changed'), which guides when to use it. However, it does not explicitly mention alternatives or when not to use it, so it falls short of a 5.

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

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

Annotations already declare destructiveHint=true, and the description adds valuable behavioral detail: only provided fields are changed, preventing accidental overwrite of unmentioned fields. The REST endpoint reference also provides implementation context. No contradiction with annotations.

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

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

The description is two concise sentences, front-loaded with the core action, followed by compact enum mappings and endpoint. Every sentence contributes meaningful information without 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?

With 13 parameters and no output schema, the description explains the purpose and update semantics but does not mention return values or error behavior. The schema handles parameter details, but for a destructive, complex operation, some indication of response expectations would improve completeness.

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

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

Schema descriptions cover 100% of parameters, so the baseline is 3. The description repeats enum values for status and priority already present in the schema, adding no extra semantic value beyond what structured fields already provide.

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

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

The description explicitly states 'Update fields on an existing ticket' with a specific verb and resource, clearly distinguishing it from sibling tools like create_ticket or update_contact. Including the REST endpoint further clarifies the exact operation.

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

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

The phrase 'existing ticket' and 'Only provided fields are changed' gives clear context for partial updates, implying this tool is for modifying existing tickets rather than creating new ones. However, it does not explicitly name alternative tools or state when-not-to-use conditions.

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