Freshservice MCP Server

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v1.0.0
Disambiguation3/5
Most tools are clearly separated by entity type, but there is notable overlap between list, filter, and search tools for the same entities (e.g., get_assets vs search_assets vs filter_assets, get_changes vs filter_changes). An agent may struggle to choose the right variant.
Naming Consistency5/5
All tools use a consistent snake_case verb_noun pattern (get_, create_, update_, delete_, filter_, search_). Even variations like get_ticket_by_id or get_agent_group_by_id are predictable and follow the same convention.
Tool Count1/5
With 70 tools, this is far beyond the 50+ threshold for 'extreme mismatch'. The server tries to cover every Freshservice module, resulting in an overwhelming surface that is unlikely to be navigated efficiently by agents.
Completeness2/5
Tickets, changes, and assets have solid CRUD coverage, but many other entities (agents, groups, products, contracts, etc.) are read-only with no create/update/delete operations. This creates significant gaps where agents can retrieve data but cannot complete lifecycle workflows.
Average 3.5/5 across 70 of 70 tools scored. Lowest: 2.3/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 1 commit in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
Add a LICENSE file by following GitHub's guide. Once GitHub recognizes the license, the system will automatically detect it within a few hours.
If the license does not appear after some time, you can manually trigger a new scan using the MCP server admin interface.
MCP servers without a LICENSE cannot be installed.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden. It only says 'Get all tasks' with no mention of pagination, ordering, return format, required permissions, or side effects. For a read operation with no annotation safety signals, this absence of behavioral disclosure is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief (one sentence plus an explicit Args block), which is efficient. However, the Args section largely duplicates the schema without adding semantic value, so while structured, it does not fully earn its place. It is under-specified rather than minimally sufficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema and a single parameter, the description omits crucial context such as how tasks relate to changes, pagination behavior, or what fields are returned. The output schema may cover return values, but the tool's invocation context is not fully explained, making it incomplete for an agent to confidently select and use it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one required parameter (change_id) with 0% description coverage, so the description must add meaning. It merely restates 'The change ID', adding no information about the format, range, source, or relationship to changes. This does not aid the agent beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Get all tasks associated with a change' with a specific verb and resource, clearly distinguishing it from siblings like get_change_by_id (which returns change details) and get_tickets (which may return tickets but not change tasks). However, it does not explicitly clarify whether 'tasks' refers to change-specific tasks or a broader concept, which is a minor gap.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It implies usage when you need tasks for a given change_id, but there are no explicit exclusions, prerequisites, or comparisons to sibling tools. This leaves the agent to infer context 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It only states the basic action (view) without disclosing any behavioral traits such as behavior when the ID is not found, required permissions, or whether it's a safe read. The description adds almost no value beyond what the tool name implies.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, but it is under-specified to the point of being mostly redundant. The Args block restates schema information, and the main sentence is minimal. It is not inefficient, but it also doesn't earn its place by adding value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter) and the presence of an output schema, the description doesn't need to detail return values. However, it provides no context about use cases, prerequisites, or error behavior, which is especially important because annotations are absent. The contrast with sibling tools is also missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description merely restates the parameter name ('software_id: The software ID.') without adding any meaning such as where to obtain the ID, accepted formats, or edge cases. This is purely redundant with the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a clear verb 'View' with a specific resource 'a specific software entry', conveying both the action and the singular scope. This distinguishes it from sibling 'get_software' (which presumably lists entries), though it doesn't explicitly name the alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives like get_software or other get_by_id tools. The requirement for a software_id is implicit from the argument list, but there is no explicit instruction on selecting this tool over siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure, but it says nothing about return format, error conditions, permissions, or idempotency. The existence of an output schema covers structure, but the description adds no context about what 'details' includes or what happens if the group does not exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and front-loaded, but it consists of little more than a restatement of the tool's purpose. It is concise, yet the minimal content does not earn its place by adding meaningful guidance; it is more under-specified than efficiently concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter get tool, the description is incomplete because it lacks any usage context, safety notes, or relationship to sibling tools. Although an output schema exists and reduces the need to explain return values, the description still fails to provide enough behavioral or usage context for an agent to confidently select and invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description lists 'group_id: The group ID', which merely restates the parameter title from the schema. Schema coverage is 0% and the description adds no extra meaning (e.g., format constraints, whether it is a numeric identifier from a specific API, or relationship to other entities). This fails to compensate for the schema's minimal information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and resource ('details of a specific requester group'), and the name implies a single-record fetch. However, 'details' is vague, and the description does not explicitly differentiate itself from the sibling list tool get_requester_groups beyond the word 'specific'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. It does not mention that this is the single-record counterpart to get_requester_groups, nor does it discuss any prerequisites or exclusions. Users must infer usage from the tool name and sibling context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only states 'Get a specific canned response by ID' and does not disclose read-only behavior, failure modes, response format, or any side effects. This is minimal disclosure for a tool with no annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very brief and to the point, consisting of one sentence and an Args list. However, the Args section redundantly repeats the schema information and could be integrated more cleanly. It is not overly verbose, but also provides minimal added value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of a get-by-ID operation with one parameter and an output schema, the description is minimally sufficient. However, it lacks any context about behavior on missing IDs, authorization, or differentiation from similar lookup tools, leaving gaps for a complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage and only provides the parameter name and type. The description adds 'The canned response ID,' which provides slight semantic clarification but largely restates the parameter name. No additional constraints or format details are given.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'canned response' identified by ID. It is specific about the operation, though it does not explicitly differentiate from sibling tools like get_ticket_by_id beyond naming the resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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, nor any prerequisite conditions. It is implied that a response ID is needed, but no explicit context or exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden. It only says 'List all locations' and lists pagination parameters, but does not disclose whether authentication is required, whether the list is scoped to a workspace, how pagination behaves, or what the response structure is. For a read-only operation, it at least implies non-destructive behavior, but that is weak.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and front-loaded, with the core purpose in the first sentence and parameter details after. It earns its place without redundant fluff. However, it is perhaps too terse, leaving out usage and behavioral context that would justify a longer description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of a paginated list tool, the description is minimally viable: it states what it does and the two parameters. The output schema exists, so return values are covered by schema. However, it lacks any guidance on when to use the tool, alternative tools, or behavioral notes, making it incomplete for an agent that needs to choose among many sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides a one-line explanation for each parameter ('Page number', 'Results per page'), but these add almost no value over the schema's titles and defaults. With 0% schema description coverage, the description was expected to compensate, yet it merely restates the obvious. No parameter constraints, formats, or edge cases are mentioned.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all locations' with a specific verb and resource. It distinguishes the tool from other resource-specific getters like get_tickets or get_assets, and there are no competing location-related siblings. However, it lacks any additional scope detail (e.g., filtering, ordering) that would make it stand out beyond the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. The description does not mention any prerequisites, exclusions, or situations where a different tool (e.g., search_assets or filter_tickets) would be more appropriate. This is a clear gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits beyond the act of creation. It omits details about side effects, required permissions, duplicate handling, or return behavior, leaving the agent without critical safety information for a mutation operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence plus two parameter lines, with no unnecessary words. It is front-loaded, concise, and appropriately sized for a simple two-parameter creation tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter create tool, the description covers the basic purpose but omits behavioral expectations and edge cases. While an output schema exists to indicate return values, the absence of any usage guidance or constraints makes the description only minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description lists parameters as 'Category name' and 'Category description,' which essentially restates the schema property names. With schema description coverage at 0%, the description fails to explain constraints (e.g., uniqueness, max length) or the semantic role of the description field, adding minimal value over the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Create a new solution category,' clearly identifying the verb (create) and resource (solution category). However, it does not explicitly differentiate from sibling tools like create_solution_folder or create_solution_article, though the resource type is implicitly distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. No prerequisites, use cases, or exclusions are mentioned. The description is purely declarative and gives no context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility for behavioral disclosure. It does not state whether the operation is read-only, how the query matching works (exact, partial, case-sensitivity), or what happens with pagination/sorting. The args list only names parameters without explaining behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a one-sentence purpose followed by a minimal argument list. Every sentence adds value, and the structure is clean and front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although the tool is simple and an output schema exists, the description lacks usage context and critical behavioral details. It doesn't explain query semantics or distinguish from related tools, making it incomplete for an agent to select and invoke correctly in all situations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameter descriptions (0% coverage), so the description's args list adds meaning. It gives an example for 'query' (email, name, department, active status) but the descriptions for 'page' and 'per_page' are generic and provide limited value. This partially compensates for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action ('Filter agents') with a specific resource. It distinguishes itself from sibling tools like get_agents by focusing on filtering, though it doesn't explicitly name alternatives or scope. The phrase 'by various criteria' is vague but supplemented by the args list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 the many sibling tools (e.g., get_agents, get_agent_by_id). It does not mention any exclusions or alternatives, 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says 'Filter requesters' and lists params, without mentioning read-only status, return format, pagination behavior, or any side effects. This is insufficient for a tool with no annotation safety hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and to the point, with a clear 'Args:' block listing parameters. The query examples sentence adds useful context. It is concise and well-structured, though slightly informal and could benefit from clearer formatting.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a filter tool with no annotations and a sparse description, it lacks critical context: what fields are searchable, how query matching works, pagination behavior, and how it relates to other requester tools. The output schema exists, so return values need no explanation, but the input semantics and usage context are under-described.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds minimal meaning to the parameters, e.g., 'query: Filter query string' and 'per_page: Results per page', and the query examples (email, name, department) suggest usage. However, with 0% schema description coverage, it does not fully compensate by explaining query syntax or supported operators, so it only partially clarifies parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Filter requesters', which is a clear verb+resource combination, and provides query examples (email, name, department) that specify the scope. However, it does not explicitly differentiate this from sibling tools like get_requesters or filter_agents, so it lacks clear sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool instead of alternatives. The query examples hint at typical use cases, but no context is given about prerequisites, when not to use it, or what distinguishes it from get_requesters or other filter tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are available, and the description only says 'View,' which implicitly indicates a read operation but without any details about return behavior, error cases, or side effects. It doesn't disclose what information is retrieved or any dependencies.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and front-loaded, but the param line adds no value since it duplicates the schema. It's structurally fine but not substantive.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple fetch with an output schema, the description may suffice for the basic action, but it omits usage context and any behavioral caveats, making it incomplete for an AI agent that needs to know when to select this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description repeats the parameter name and type ('contract_id: The contract ID') without adding semantics beyond the schema. With 0% schema coverage, more detail about the parameter (e.g., format, uniqueness, required) would be needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the clear verb 'View' with the resource 'a specific contract,' indicating this tool fetches a single contract by ID. This distinguishes it from the sibling tool get_contracts, which likely lists contracts, though it doesn't explicitly name the sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives such as get_contracts or filter_contracts. It only states it views a specific contract, leaving the appropriate context to be inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It only says 'View' (implying read-only) but provides no additional context such as return format, error handling, permissions, or whether the response is a single object or list. The description adds no content beyond what the tool name implies.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and avoids extraneous content, but the 'Args' section is redundant with the input schema and does not add value. While it is efficient, it is under-specified and does not make every line earn its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
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 an output schema present, the description is minimally adequate. However, it lacks guidance on alternative tools, fails to mention behavior on missing IDs, and does not state what the response contains beyond the output schema, leaving gaps in the overall context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description repeats 'article_id: The article ID' which is essentially a restatement of the parameter name and schema type. With 0% schema coverage, the description fails to add any meaningful semantics beyond the field name, such as expected format, examples, or how to obtain the ID.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'View a specific solution article' with a clear verb and resource. The word 'specific' distinguishes it from sibling tools like get_solution_articles (which lists multiple) and search_solution_articles, 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.
Usage Guidelines2/5
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 get_solution_articles or search_solution_articles. The description does not mention context, exclusions, or alternative selection criteria, 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden. 'List' implies a read-only operation, but the description doesn't explicitly state that, nor does it mention pagination behavior, authentication requirements, or return structure. The description adds no behavioral context beyond the action word 'List'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short lines plus parameter explanations, all front-loaded with the purpose. No wasted words, efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and presence of an output schema, the description is minimal but incomplete: it omits guidance on alternative tools and doesn't disclose whether it's a safe read-only call. For a list endpoint, a bit more context (e.g., 'Use this to browse categories; use get_solution_category_by_id for a specific one') would round it out.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description's brief 'Page number' and 'Results per page' provide minimal but helpful clarification. It doesn't explain pagination semantics like default values or maximums, but suffices for these simple parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and identifies the resource ('all solution (knowledge base) categories'), clearly distinguishing from singular retrieval by ID. However, it doesn't explicitly differentiate from sibling tools like get_solution_category_by_id, though the use of 'all' implies the difference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No information is provided about when to use this tool versus alternatives such as get_solution_category_by_id or create_solution_category. The description only lists parameters, not usage context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description is the sole source of behavioral information. 'Get details' implies a read-only operation, but it does not disclose behavior for missing IDs, error handling, permissions, or return format. The output schema covers return values, but the description adds limited transparency beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise, with a front-loaded purpose statement and no extra filler. However, the 'Args' section redundantly repeats the schema, which slightly reduces efficiency. Still, it remains appropriately small.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-id tool, the description is mostly adequate, especially with an output schema present. However, it omits important context such as error behavior, permissions, and explicitly clarifies when to use this tool versus the plural 'get_products'. Given the lack of annotations, this leaves notable gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must compensate. It repeats the parameter name and a trivial description ('product_id: The product ID') that essentially mirrors the schema title 'Product Id'. No additional meaning, constraints, or formats are provided, so the compensation is minimal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves details of a specific product, using a specific verb ('Get') and resource ('product'). It is distinguishable from the sibling 'get_products' by the qualifier 'specific', but it does not explicitly mention the alternative, so it falls short of a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 'get_products' or 'get_ticket_by_id'. It lacks any context for selecting this tool over others, offering only a straightforward retrieval statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says 'Get details' without explaining return format, error behavior, permissions, or any side effects, leaving the agent to infer the tool's behavior solely from its name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two lines and avoids unnecessary words, though the Args section largely duplicates schema information. Still, it is not verbose or redundant, making it appropriately concise for a simple getter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the presence of an output schema, the description covers the basic purpose, but it omits any context about when to use this over get_agent_groups, how to find a group_id, or potential error cases. The agent has minimal guidance beyond the tool name.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description repeats 'The group ID' for group_id, which adds no insight beyond the schema's property name and integer type. It does not explain what constitutes a group ID, how to obtain it, or any validation constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Get' with the resource 'agent group', clearly distinguishing this single-item retrieval tool from list-oriented siblings like get_agent_groups. The 'by_id' suffix in the tool name further clarifies the scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit when-to-use guidance or alternative recommendations. The name and the required group_id parameter imply it is for retrieving a specific group, but this is not stated in the description itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It only states the action ('List all agent groups') without disclosing behavior like pagination semantics, default page size, sorting, or potential rate limits. The args section mentions 'page' and 'per_page' but does not clarify whether 'all' means all pages or a single page.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the main action. However, the 'Args' section duplicates information already present in the input schema, making it slightly redundant. Still, it is appropriately sized and has no unnecessary filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with pagination and an output schema (presumably an array of agent groups), the description is fairly complete. However, the use of 'all' is ambiguous given pagination, and there is no mention of sorting or whether the output includes pagination metadata. It does not explicitly distinguish from related list tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description restates the parameter names as 'Page number' and 'Results per page', which adds minimal meaning beyond the schema's existing titles ('Page' and 'Per Page') and default values. With 0% schema description coverage, the description does not sufficiently compensate for the lack of parameter detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List all agent groups' uses a specific verb ('List') and clearly identifies the resource ('agent groups'). It distinguishes from sibling tools like 'get_agent_group_by_id' (single group) and 'get_requester_groups' (different resource type).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. It does not mention that 'get_agent_group_by_id' retrieves a single group, nor does it note any filtering capabilities. There is no 'when to use' or '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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It only uses the word 'Retrieve' to indicate a read operation, but does not disclose what happens when the change_id is not found, error handling, return format (partially covered by output schema), or any access requirements. This is a minimal disclosure for a retrieval tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the main purpose. However, the Args section is redundant with the input schema and does not earn its place. Overall, it is appropriately short but contains minor fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
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, the description is minimally viable. It states the core action, and an output schema exists so return values are covered. However, it lacks usage guidance and behavioral disclosure, making it incomplete in context. The presence of many sibling tools makes the lack of distinction more significant.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, so the description must compensate. However, the Args section simply restates 'change_id: The change ID', which adds no meaning beyond the parameter's name and schema title. It provides no examples, constraints, or additional context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Retrieve a single change by ID', using a specific verb and resource. This distinguishes it from sibling tools like 'get_changes' (plural, lists all) and 'filter_changes' (searches).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention that 'get_changes' or 'filter_changes' should be used for listing or searching, nor any exclusions or prerequisites. Usage is implied only by the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It merely says 'View a specific department' without mentioning error behavior (e.g., 404 when not found), permissions, rate limits, or any side effects. For a simple read operation this is thin, but not misleading.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceedingly concise, with one purpose sentence and an argument list. It is front-loaded and contains no fluff. Every word earns its place, making it highly efficient for an agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (single required parameter, no nested objects), the description covers the basic invocation. An output schema exists, so return values are presumably documented there. However, the lack of annotations and absence of any behavioral notes (e.g., handling of invalid IDs) leaves some gaps, though not severe for a get-by-id tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter, department_id, with type integer and no description (0% coverage). The description adds 'The department ID', which is tautological and adds no meaningful semantics beyond the parameter name and type. It does not explain where the ID comes from or how to obtain valid IDs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'View a specific department' which is a clear verb+resource combination. It clearly indicates a read operation for a single department, but it does not explicitly differentiate from the sibling tool get_departments, which lists departments. The tool name and argument make the 'by ID' aspect evident.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage is implied: you use this tool when you need a specific department's details. However, there is no explicit guidance about when to prefer this over get_departments or other related tools, and no exclusions are stated. The sibling list shows a get_departments tool, but the description does not address the distinction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are available, so the description carries the full burden. It does not disclose whether this is a read-only operation, how pagination behaves (e.g., whether 'all' means all pages in one call), or any potential rate limits. The ambiguity of 'all' with pagination args is a notable gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very brief, front-loaded, and free of unnecessary words. The Args section is compact and easy to parse, though it largely replicates schema information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple paginated list tool, the description provides the core purpose, and the output schema likely covers return values. However, the lack of clarity about the 'all' vs pagination behavior and the absence of any note on usage context leave some gaps, though not severe for such a low-complexity tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description restates the parameter names ('Page number', 'Results per page') with minimal definitions that add little value beyond the schema's default values and obvious names. With 0% schema coverage, the description should enrich the semantics but does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the action 'List' and the resource 'all departments' clearly, using a specific verb and resource. It distinguishes from sibling get_department_by_id by indicating a list operation rather than a single-item fetch.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives like get_department_by_id, or how pagination works in practice. The description simply states what it does without any contextual or exclusionary information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry full burden for behavioral disclosure. It only says 'List all software entries' and lists parameters, offering no additional context about pagination behavior, sorting, rate limits, or potential errors. The read-only nature is implied but not explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with a single clear sentence for the action and only two lines for parameters. Every word earns its place, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of a paginated list tool, the description covers the basic purpose and parameters. However, it omits critical context such as usage guidance, pagination behavior, and limitations. The presence of an output schema helps complete return-value knowledge, but the overall description is minimal for an agent to fully rely on.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no property descriptions (0% coverage), and the description provides basic definitions: 'page: Page number' and 'per_page: Results per page'. This adds some clarity but does not go beyond what the property names already imply, lacking any constraints or behavioral details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all software entries' with a specific verb and resource, making the core purpose clear. However, it does not explicitly differentiate from sibling tools like get_software_by_id, though the use of 'all' implies a collection listing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. There is no mention of exclusions, alternative tools for specific needs, or recommended use cases. The description only provides the basic action and parameters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full burden of behavioral disclosure. It only states the action and parameter names, but does not explain side effects (e.g., status change), reversibility, required permissions, or what happens to the change record. This is a significant gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded, with a clear purpose statement followed by a compact parameter list. It avoids fluff, though it could include more behavioral context without becoming overly long.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of annotations and a simple schema, the description is under-specified. It does not explain the closing workflow, expected outcomes, or error conditions. While an output schema exists (not shown), the description still leaves key contextual details missing for a mutation operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The Args section simply restates parameter names with minimal explanations (e.g., 'change_id: The change ID'), adding little beyond the schema. There is no elaboration on expected formats, semantics, or relationships, and schema coverage is 0%, so the description fails to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action and resource: 'Close a change with a result explanation.' This clearly distinguishes it from sibling tools like update_change or delete_change, and the phrase 'result explanation' adds meaningful scope beyond just the verb.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage context is implied: it is used to close a change with an explanation. However, there is no explicit guidance on when to choose this over update_change or delete_change, nor any mention of prerequisites or lifecycle position. The description fails to provide exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It only states 'Create a new requester / contact,' which essentially restates the tool's name, and does not mention side effects, permission requirements, duplicate handling, or reversibility. For a mutation tool, this is a significant transparency gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: one sentence for the purpose and a clear list of args. It is front-loaded and contains no fluff or redundant details. Every line earns its place, especially given the schema has no parameter descriptions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description covers the basic action and all parameters, it does not provide usage context, business rules, or caveats. Since an output schema exists, the lack of return-value documentation is acceptable, but for a create tool, an agent would benefit from knowing what happens on success, whether there are duplicate constraints, or any required relationships (e.g., department_ids must exist). The description is incomplete for reliable use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 lists each parameter with a brief phrase (e.g., 'Requester first name,' 'List of department IDs'), adding some clarity beyond the schema's property titles. However, it lacks format constraints, examples, or relationships, providing only minimal semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Create a new requester / contact,' using a specific verb ('create') and a clear resource ('requester / contact'). This immediately distinguishes it from sibling read/filter tools like get_requesters, get_requester_by_id, and filter_requesters, and also clarifies that 'requester' and 'contact' are synonymous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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, nor does it mention any prerequisites or exclusions. For example, it does not say whether to use this for creating a contact that may already exist, or if there is an update path. This leaves the agent without context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are available, so the description must carry the burden. It only states the delete action without mentioning permanence, cascading effects on related change notes/tasks, permission requirements, or whether deletion is soft or hard. This is a significant gap for a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded with the action statement. The parameter line is somewhat redundant but still acceptable. There is no unnecessary prose, so it is concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter interface with an output schema, a minimal description could suffice. However, for a delete tool, it fails to mention preconditions (e.g., whether the change must be closed), consequences (irreversibility, cascading deletion of related entities), or success/failure semantics. Given sibling tools for change notes and tasks, these aspects are relevant and unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description merely restates 'change_id: The change ID,' adding no meaning beyond the schema's property title 'Change Id.' It does not explain how to obtain the ID or any constraints, offering no additional guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a change request,' with a specific verb and resource. It distinguishes itself from sibling tools like get_change_by_id, update_change, and close_change by its action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use versus alternatives is provided. The name and simple action imply it is for removing a change request, while siblings handle creation, updates, closing, and retrieval. This is implied usage, not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only says 'List all contracts' and repeats parameter names, without mentioning read-only status, pagination behavior, permissions, or limits. The meaning of 'all' is ambiguous given pagination parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: the main action 'List all contracts' is front-loaded, followed by clear parameter definitions. Every word serves a purpose, with no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is too sparse for the tool's context. Although an output schema exists, the description fails to explain that results are paginated, how to request specific pages, or whether any filtering is possible. It also lacks any usage guidance or alternates, leaving the agent without sufficient context to choose this tool appropriately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must compensate. It defines 'page' as 'Page number' and 'per_page' as 'Results per page', which adds minimal semantic meaning beyond the schema titles 'Page' and 'Per Page'. This is a slight, albeit minimal, compensation for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all contracts' with a specific verb and resource. It distinguishes from the sibling tool 'get_contract_by_id' by indicating a list operation rather than retrieving a single contract.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives. There is no mention of using 'get_contract_by_id' for fetching a single contract, nor any discussion of filtering or conditions that would make this tool appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure, but it only says 'Update an existing asset.' It does not specify whether updates are partial or full replacements, how missing fields are handled, whether validation occurs, error behaviors, or permission requirements. This is a significant gap for a write operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of a one-sentence purpose and an 'Args' section. Every word earns its place; there is no fluff or repetition. The structure is clear and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although the tool has an output schema (so return values need not be explained), the description is incomplete for an update operation. It does not clarify update semantics (e.g., partial vs. replace), valid fields, or behavior when the asset does not exist. With many sibling tools, it also fails to differentiate usage context. The description is minimal and leaves critical ambiguities.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only titles with 0% description coverage, so the description must compensate. It does give brief meanings for both parameters: 'display_id' as the asset display ID and 'updates' as a dictionary of fields to update. This is basic but helpful; however, it lacks specifics about allowed update fields, nested object support, or dictionary format beyond being an object.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update an existing asset' with a specific verb and resource. It distinguishes this from create/delete/read asset tools by implying the asset already exists and is being modified. The sibling tools include create_asset and delete_asset, so the purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 create_asset, delete_asset, or other update tools. It does not mention prerequisites (e.g., asset must exist) or situations where this tool is preferred over others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral consequences such as required permissions, side effects, or the shape of the response. It merely states 'Create a new problem' and lists parameters, which is insufficient for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the core action, followed by a straightforward argument list. Each line serves a purpose, though the list format is slightly redundant with the schema structure and some parameter labels are minimal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While an output schema exists and parameter semantics are covered, the lack of usage guidance and behavioral transparency leaves significant gaps. The agent cannot fully anticipate the tool's behavior or when to select it among many siblings, making the description incomplete for a create operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description compensates for the 0% schema description coverage by explaining all 8 parameters with meaningful labels, including enum mappings for priority, impact, and status, and noting that description is HTML. However, some entries like 'subject: Problem subject' and 'requester_id: Requester ID' are somewhat tautological, preventing a 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Create a new problem,' which is a specific verb and resource. It clearly distinguishes itself from sibling tools like create_ticket, create_change, and create_asset by focusing on the problem entity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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, no prerequisites, no exclusions. The description simply states the action and lists arguments, leaving the agent without context on when create_problem is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so the description must disclose behavioral traits. It only states the delete action but does not mention irreversibility, permissions, validation of the note's association with the ticket, or side effects. This is a significant gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately concise and front-loaded, with the action stated first and parameters listed clearly. Every word earns its place; there is no unnecessary content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter delete tool, the description is minimally complete. It omits information about side effects, return values, and validation, but the output schema (if available) would cover returns, and the low complexity reduces the burden. Still, some behavioral context is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds basic semantic meaning for both parameters, clarifying that conversation_id is the note ID. However, the schema titles already convey 'Ticket Id' and 'Conversation Id', and the description does not explain relationships or constraints. It compensates modestly for 0% schema coverage but lacks depth.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete') and the resource ('a note from a ticket'). It distinguishes itself from sibling delete_ticket (which deletes entire tickets) and add_ticket_note (which adds notes), providing a specific and unambiguous purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 vs alternatives, nor any context about prerequisites or exclusions. The description only says what it does, not when to choose it over related tools like list_ticket_conversations or reply_to_ticket.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description must carry the burden of disclosing behavioral traits. It does not mention whether the operation is read-only, how filtering semantics work (e.g., AND/OR logic), or any permissions or rate limits. The description only restates the core filtering action and parameter meanings, adding no behavioral context beyond what is obvious.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and well-structured: one purpose sentence followed by a formatted Args list. Every sentence is useful and there is no fluff or repetition of schema metadata.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a simple filtered list operation with an output schema, so the description need not explain return values. However, it lacks usage context (when to choose this over siblings), query language details, and any behavioral notes. It is minimally viable but not fully complete for an agent to invoke correctly without further guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 provides brief meanings for each parameter and two query examples for the 'query' field, which adds value over the bare schema. However, it does not explain query syntax nuances (e.g., operators, combining conditions) or pagination behavior in detail, leaving gaps for a new user.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Filter assets using Freshservice query language' with a specific verb ('filter') and resource ('assets'). It distinguishes from sibling tools like get_assets (which likely lists all assets) and search_assets (which may use a different search mechanism).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 get_assets or search_assets. While query examples are given, there is no explicit statement of appropriate use cases, exclusions, or how this tool differs from siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. Saying 'List all products' adds little beyond the tool name itself. It does not disclose pagination behavior, return format, potential rate limits, or that it is a read-only operation. The absence of any behavioral detail beyond the basic action is a notable gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a one-line purpose followed by a compact args list. Every sentence earns its place, with no redundant words or boilerplate. The front-loaded purpose statement immediately clarifies the tool's function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (two pagination params, no nested objects) and an output schema exists, so the description need not document return values. However, with no annotations and no usage guidance, the description leaves gaps in behavioral context and differentiation from siblings. It is adequate for a basic list operation but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero description coverage, so the description must compensate. It does provide brief explanations for both parameters: 'page: Page number' and 'per_page: Results per page.' These add some meaning beyond the bare schema titles, but they are minimal and do not mention defaults or constraints. This is a marginal improvement, but not thorough enough for full compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'List all products.' This is a specific verb (list) and resource (products), and it clarifies that it returns all items, distinguishing it from get_product_by_id which fetches a single product. The scope is explicit and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention get_product_by_id for single-product lookups or any other filtering capabilities. There is no explicit 'when to use' or 'when not to use' context, leaving the agent to infer based solely on the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It only says 'List all purchase orders' without disclosing that this is a read-only operation, that results are paginated, or any potential side effects or requirements. The pagination parameters hint at behavior, but the description does not explicitly explain the retrieval semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the main purpose. The Args list is minimal but earns its place since the schema lacks descriptions. No wasted words, though the structure is a bit mechanical.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with only two integer parameters and an output schema, the description is adequate on the surface. However, it leaves ambiguity around whether 'all' means the entire dataset or a single page, and it does not clarify pagination behavior or ordering. It lacks enough context to be considered fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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 provides only terse one-line explanations ('Page number', 'Results per page') that do not go beyond what parameter names already imply. It fails to mention defaults, ranges, or how pagination interacts with 'all'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all purchase orders' – a specific verb ('list') and resource ('purchase orders'). The name itself is unambiguous, and no sibling tool targets purchase orders, so it distinguishes from alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by stating the core action, but it does not explicitly mention when to use this tool versus alternatives or when not to use it. Since no alternative purchase-order list tool exists among siblings, the guidance is solely implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It only states 'List all' and provides pagination args, but doesn't disclose read-only nature, potential large result sets, default pagination behavior, or ordering. Minimal transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise with a clear Args block. Every sentence serves a purpose—the one-line purpose and two parameter definitions. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with pagination parameters, the description is acceptable but incomplete: it doesn't mention output format, ordering, or any usage constraints. The existence of an output schema is not leveraged to explain return structure, leaving some uncertainty.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no descriptions (0% coverage), and the description barely compensates by restating 'Page number' and 'Results per page' which add little beyond the parameter names themselves. It doesn't explain defaults (though schema has defaults) or how pagination works together.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all service catalog items' with a specific verb and resource. It distinguishes itself from the sibling tool get_service_catalog_item (singular) by indicating it returns the full collection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use or alternative tool guidance is provided. It doesn't mention that get_service_catalog_item should be used for a specific item or any context for when to use this list endpoint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of disclosing side effects and safety. The verb 'View' implies a read-only operation, but no further behavioral context is given (e.g., whether it requires specific permissions, what happens if the folder is not found). The description simply restates the purpose without 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded, with no fluff. However, the Args section duplicates information already present in the input schema (parameter name, type, title), making it slightly redundant. Excluding that duplicate content would make it more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-ID tool with an output schema present, the description is minimal but adequate for basic invocation. However, it lacks usage guidelines and behavioral transparency, which are important for an agent to correctly select and use the tool, especially given the lack of annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate for lack of parameter explanations. The Args section states 'folder_id: The folder ID', which is essentially a restatement of the parameter name and schema title. This adds no meaningful semantic value, such as the source or format of the ID, and does not fully compensate for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'View a specific solution folder' uses a specific verb and resource, clearly indicating that this tool retrieves a single solution folder by ID. It distinguishes from the sibling 'get_solution_folders' (which lists folders) and other get-by-id tools (e.g., get_solution_article_by_id).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the phrase 'View a specific solution folder' and the presence of folder_id parameter, suggesting it is used when a single folder's details are needed. However, there is no explicit guidance on when to use this tool over alternatives or any exclusions, so it falls short of full clarity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only states that it searches by keyword but does not disclose whether it searches titles, bodies, or metadata, nor does it mention result format, pagination, or matching behavior. This is a significant gap for a search tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded with the main action. However, the 'Args:' section largely duplicates what the schema already provides, adding little new value. Still, it is economical and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is too sparse for a tool with no annotations. It doesn't explain return structure (though output schema exists), search scope, or any filtering/pagination behavior. Sibling tools are not referenced, so the agent lacks context on what distinct functionality this provides.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds the meaning 'Text to search for in articles' for search_term, which is absent from the bare schema (just type and title). This clarifies the parameter's purpose, but it does not provide examples, format constraints, or search behavior details. Given low schema coverage, this is minimal compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Search' with resource 'solution articles' and qualifier 'by keyword', clearly distinguishing this from sibling tools like get_solution_articles (list all) and get_solution_article_by_id (by ID). The scope is explicit and matches the tool's name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'by keyword' implies usage for keyword-based search, but there is no explicit guidance on when to use this vs. alternatives like get_solution_articles or get_solution_article_by_id. No exclusions or alternative tool names are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the read-only intent via 'Retrieve', but it does not disclose non-obvious traits such as behavior when the ID is not found, authentication requirements, or rate limits. This is minimal disclosure, scoring 2 as per the rubric for no annotations and lack of added context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise and front-loaded, with no fluff. However, the Args section duplicates schema information that is already present in the input schema, so it does not earn its place fully. Still, it is efficient and under control, earning a 4.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a simple get-by-ID operation, and an output schema exists, so return format is covered. The description covers the core purpose and parameter adequately for a low-complexity tool. However, it lacks any usage guidance relative to sibling tools, preventing a 5. Overall, it is reasonably complete for the context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, so the description must compensate. The Args section says 'agent_id: The agent ID', which is essentially tautological and adds no meaning beyond the parameter name and type in the schema. It does not explain format, constraints, or how it is used in the retrieval. This is weak compensation, scoring 2.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Retrieve') and resource ('a single agent'), with the scope 'by ID'. This clearly distinguishes it from sibling tools like get_agents (which lists) and filter_agents (which filters), matching the 5 criterion of specific verb+resource and differentiation from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have an agent ID, but it does not explicitly state when to use this tool over get_agents or filter_agents, nor does it mention exclusions such as 'only when you know the exact ID'. This is implied rather than explicit, matching the 'implied usage' level.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of disclosing behavior. It only says 'Retrieve', giving no information about read-only guarantees, error handling when the ID is not found, permission requirements, or potential side effects. This is a significant gap for a tool with no annotation metadata.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with the core purpose front-loaded in the first sentence and only a minimal Args block. Every word earns its place, with no wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, output schema provided), the description is minimally adequate. However, it lacks usage guidance and behavioral transparency, and does not mention known alternatives like get_problems. The output schema covers return values, but the description does not set expectations for edge cases or relationship to related tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must compensate. However, it only repeats the parameter name ('problem_id') and says 'The problem ID', adding little meaning beyond the schema's integer type and title. No details on where to find the ID or any format constraints are provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Retrieve a single problem by ID' with a specific verb (retrieve), resource (problem), and scope (by ID). This distinguishes it from sibling tools like get_problems (which lists problems) and other get_*_by_id tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a problem ID is known, but there is no explicit guidance on when to use this tool versus alternatives like get_problems, nor any stated exclusions. It leaves the comparison to the reader.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the full burden of behavioral disclosure. It only states the action ('Retrieve a single requester by ID') and does not mention important behavioral traits such as whether it returns null/404 if not found, authentication requirements, or any read-only constraints. The behavior is largely assumed but not explicitly disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with a clear opening line and a minimal Args listing. Every word earns its place; there is no fluff or redundancy. The structure is straightforward and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-ID tool with an output schema, the description covers the core purpose but leaves gaps: it does not mention error handling, auth requirements, or why this tool is preferred over alternatives. Given the simplicity, it is minimally viable but not fully contextualized.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter, requester_id (integer), and schema description coverage is 0%. The description's Args section merely restates 'The requester ID', which adds no meaningful semantics beyond the schema's title 'Requester Id'. It fails to provide additional context such as the expected format, range, or uniqueness of the ID.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Retrieve') and a specific resource ('a single requester') with a clear scope ('by ID'). This clearly distinguishes it from siblings like get_requesters (plural) and filter_requesters, which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies its use case: when you have a requester ID and need the individual requester record. However, it provides no explicit guidance on when to use this over alternatives like get_requesters or filter_requesters, nor does it mention exclusions. The usage is implied but not clearly articulated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. The description only mentions listing and pagination parameters, but does not disclose any behavioral traits such as authentication requirements, rate limits, whether it returns all groups across pages or just a single page, or any error conditions. This is insufficient for a tool with no annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with a one-line summary followed by a compact parameter list. Every element adds value without unnecessary filler, and the structure is front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple paginated list tool, the description covers the essential purpose and parameter semantics. An output schema is indicated to exist, so return-value documentation is not required from the description. Minor gaps include lack of any mention of sorting, filtering, or edge cases, but these are less critical for a straightforward list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no descriptions for its parameters (coverage 0%), so the description attempts to compensate by explaining 'page: Page number' and 'per_page: Results per page'. However, these explanations add little beyond the parameter names themselves, which are self-explanatory, and fail to provide context-specific details such as acceptable ranges or behavior when parameters are omitted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all requester groups' with a specific verb and resource, and the word 'all' distinguishes it from the sibling tool 'get_requester_group_by_id' which retrieves a single group. This is a clear, unambiguous statement of 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.
Usage Guidelines2/5
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, nor does it mention any exclusions or prerequisites. It simply states what the tool does, leaving the agent to infer appropriate usage from the name and sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden for behavioral disclosure. It only says 'View,' which implies a read operation, but it does not mention permissions, visibility constraints, error behavior, or any side effects. This is a significant gap for a tool lacking annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one purpose sentence and one parameter line. Every word earns its place, and the key information is front-loaded in the first sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple get-by-id tool with an output schema available, so return-value documentation is not required. However, the description lacks usage context, alternative guidance, and any behavioral caveats. It is minimally viable but has clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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 states 'item_id: The service catalog item ID,' but this largely restates the schema's title 'Item Id' and adds little semantic value. The description does not explain the expected format, source, or meaning beyond the obvious.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'View a specific service catalog item,' which uses a specific verb and resource. It clearly distinguishes from the sibling tool get_service_catalog_items (plural) by emphasizing a single item.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have a specific item_id, but it does not explicitly state when to choose this tool over alternatives like get_service_catalog_items, nor does it provide exclusions or context. The guidance is minimal and inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for behavioral disclosure, but it only repeats the base functionality. It does not mention read-only nature, pagination behavior, rate limits, or response content beyond the output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and front-loaded, with the core action in the first sentence and parameter explanations following. No extraneous information is included.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple paginated list endpoint with an output schema present, the description is mostly adequate. It could mention that it returns a list of workspace objects, but the output schema reduces the need for explicit return value explanation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds minimal semantic value by explaining 'page: Page number' and 'per_page: Results per page', which the schema lacks. However, this essentially restates the parameter names without adding detail like starting index or maximum values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List all workspaces' clearly states the tool's function with a specific verb and resource. It is unambiguous and distinguishes itself from sibling tools, none of which target workspaces.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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, nor does it mention any prerequisites or contexts. There are no explicit exclusions or alternative tool references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must stand alone. It only restates the action without disclosing behavior like error handling, authentication, rate limits, or what happens when the asset is not found. The description adds little beyond the tool's name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise, with a clear front-loaded purpose statement and an Args section. It contains no filler, making every sentence useful and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-id tool with an output schema, the description is minimally sufficient. It does not mention error cases, prerequisites, or special behavior, but the operation is straightforward and the output schema covers return values. However, given the lack of annotations, it is adequate but not rich.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains the parameter—'display_id: The asset display ID.'—which provides minimal context beyond the schema's type and title. Since the schema has no description, this is the only source of parameter meaning, but it doesn't clarify what a 'display ID' is or whether it is unique.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the function with a specific verb ('Retrieve') and resource ('single asset'), and identifies the key parameter (display ID). It distinguishes itself from sibling tools like get_assets (list) and search_assets by focusing on a single asset lookup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage via the name and phrase 'Retrieve a single asset by its display ID,' but does not explicitly state when to use this over alternatives such as search_assets or filter_assets. There are no exclusions, scenarios, or comparisons with siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. 'View' implies a read operation, but it adds no context about authentication, error behavior, or any side effects. This is minimal and does not enrich the agent's understanding beyond the verb itself.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the tool's purpose. The Args section is redundant with the schema but does not harm. It could be slightly leaner by omitting the redundant parameter restatement, but overall it is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-id tool with an output schema, the description is adequate but lacks guidance on when to use this vs. the list alternative and what happens if the ID does not exist. It covers the core invocation but not the surrounding context needed for robust tool selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter description, 'The category ID', simply restates the parameter name without adding meaningful detail. With 0% schema description coverage, the description should compensate, but it does not clarify the format, purpose, or any constraints beyond the name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'View a specific solution category', using a specific verb and resource. It distinguishes from sibling tools like get_solution_categories (which lists all) and create_solution_category by indicating 'specific' rather than general operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The word 'specific' implies this tool is used when you have a particular category ID in mind, providing clear context for when to use. It does not explicitly mention alternatives or exclusions, but the sibling context makes the usage scenario evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only repeats parameter meanings and does not disclose behavioral traits such as pagination behavior (though page/per_page hints at it), ordering, error handling, or what happens if the category_id is invalid. The statement 'List all' could mislead without noting pagination.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized: a single clear purpose sentence followed by a compact args list. Every sentence earns its place, and the structure is front-loaded with the main action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple paginated list tool with an output schema present, the description is minimally viable. It covers the core operation and arguments but lacks behavioral nuances like pagination defaults, ordering, or error scenarios. It is not rich, but it is not critically incomplete for a basic list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description's brief parameter explanations ('parent category ID', 'Page number', 'Results per page') add some meaning beyond the schema. However, they are extremely terse and do not provide details like allowed ranges, format, or relationships between parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List'), the resource ('solution folders'), and the scoping ('in a category'). This distinguishes it from siblings like get_solution_folder_by_id (which fetches a single folder) and get_solution_categories (which lists categories).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: you need a category_id to list folders under it. However, it does not explicitly mention alternatives or when not to use this tool. The context is clear but no exclusions or comparisons are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only states the action and parameters, without disclosing whether the update is partial or full, side effects, error behavior, permissions, or idempotency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with a clear action statement followed by a minimal Args block. No unnecessary words or repetition; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema is present, so return values are covered. However, for a mutation tool without annotations, the description omits key context like update semantics (partial vs full), required permissions, and typical use cases. It is minimally complete but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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. It defines change_id and change_fields, and lists common fields (status, priority, impact, etc.), adding some meaning. However, it stops short of a full field list or value formats.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update') and the resource ('existing change request'), which distinguishes it from siblings like create_change, delete_change, and close_change. This is a specific verb+resource pair.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for modifying existing change requests, but it does not explicitly mention alternatives or when not to use this tool. The Args section lists parameters but provides no decision guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the update operation and the updates dictionary, but does not disclose whether the update is a partial merge or full replacement, what permissions are required, whether changes are reversible, or what response the caller can expect beyond what an output schema might imply. This falls short for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded with the core purpose in the first sentence. The Args section is compact and organized, listing parameters and examples without unnecessary prose. Every sentence contributes useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is relatively simple with only two parameters, and an output schema is present so return values need not be described. However, the description lacks behavioral caveats such as merge semantics, required permissions, or error conditions, and provides no usage exclusions relative to sibling tools. It is minimally adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description compensates well by explaining both parameters: ticket_id is the ticket to update and updates is a dictionary of fields, with a helpful list of common fields (status, priority, group_id, etc.). This adds significant meaning beyond the bare schema, though it does not detail value formats or constraints for each field.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update an existing ticket' uses a specific verb and resource, clearly distinguishing this from sibling tools like create_ticket, get_tickets, and delete_ticket. The action scope is obvious and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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, such as create_ticket for new tickets or update_change for changes. 'Existing' implies a prerequisite, but no explicit context, exclusions, or alternative tool references are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It only states 'Create a new change request' and details parameters. It fails to mention side effects, permission requirements, validation behavior, or what happens on success. It does add minor parameter-level trait (e.g., HTML supported for description, ISO 8601 format for dates), but overall tool behavior remains opaque.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a well-organized docstring with a lead sentence and a bulleted-like Args list. Each line is concise and adds unique information. It is somewhat lengthy due to 13 parameters, but every line is necessary given the schema lacks descriptions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with 13 parameters, the description covers all parameter meanings and formats. An output schema exists, so return values need not be described. However, it lacks guidance on when to use the tool and any overarching behavioral context, which slightly detracts from completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
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 provides extensive semantic detail for every parameter, including exact numeric mappings for priority, impact, status, risk, and change_type, plus format expectations for dates. This goes far beyond the bare type/default information in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Create a new change request', a specific verb+resource statement that clearly distinguishes this tool from siblings like update_change, delete_change, and get_changes. It unambiguously conveys 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.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given for when to use this tool versus alternatives. While the first line implies its purpose, there is no mention of exclusions, prerequisites, or comparison with related tools like create_ticket or create_asset. The description is purely a parameter list, offering no usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description must disclose behavior. It provides query syntax examples and pagination parameters, which gives some insight. However, it does not explain search semantics like case sensitivity or wildcard support, nor what the response contains, leaving notable gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with an opening summary, query examples, and an args list. It is concise with no fluff, though the Args section restates parameter names with brief explanations, which is slightly redundant but still useful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description does not need to explain return values. It covers the key aspects of constructing a query and pagination. Minor missing details like case sensitivity or wildcard support are acceptable for a first encounter, but more explicit behavior would make it fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no descriptions for its parameters (0% coverage), so the description needs to compensate. It defines query as 'Asset search query' and page/per_page as 'Page number' and 'Results per page', which adds basic meaning. The query examples further clarify valid field:value syntax, going beyond what the schema offers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Search assets by various fields' with a clear verb and resource, and query examples specify exact fields like name, asset_tag, and serial_number. However, it does not explicitly distinguish this from sibling tools such as filter_assets or get_assets, so it misses the top score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The query examples imply this tool is for searching assets by specific fields, but there is no explicit guidance on when to use it versus filter_assets or other asset search methods. No alternatives or exclusions are mentioned, so the usage context is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only restates the parameter list. It does not disclose side effects, required permissions, validation behavior, or result format. The agent learns nothing beyond 'creates' which is already in the name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise: one sentence for purpose, then a bullet-style Args list. Every line adds information; no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists, the description need not explain return values. It covers all parameters and names the parent category's role. However, it omits any mention of prerequisites or error scenarios, and does not explicitly connect to the solution-folder hierarchy context. Still, for a simple create operation with full parameter coverage, it is adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides a concise meaning for every parameter, including an explicit numeric mapping for visibility (1=All, 2=Logged-in users, 3=Agents only). This is especially valuable given the input schema has zero descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear, specific verb+resource pair ('Create a new solution folder') that matches the tool name and distinguishes it from sibling operations like create_solution_category or create_solution_article.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus others. It lacks context about typical use cases, prerequisites (e.g., existing category), or alternatives. The bare instruction leaves the agent to infer 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses a key behavioral trait: 'soft delete / trash', which is beyond the empty annotations. However, it does not mention permissions, reversibility details, or side effects, leaving part of the behavioral burden unaddressed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, front-loaded with the action, and includes a structured Args block. There is no wasted or repetitive language.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with one parameter and an output schema, the description covers the core purpose and parameter meaning. It notes the soft-delete behavior but lacks details on restrictions, permissions, or operational consequences, making it adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds a brief semantic explanation for the single parameter: 'The asset display ID.' This is more informative than the schema's 'Display Id' title, but it is minimal and does not go beyond a basic clarification.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Delete' and the resource 'asset', and adds the clarifying behavior '(soft delete / trash)'. This distinguishes it from sibling tools like update_asset and create_asset.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use case is implied by the tool name and description, but there is no explicit guidance on when to use it versus alternatives, or any exclusions (e.g., permanent delete usage). It is not misleading, but the guidance is minimal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are given, so the description carries the full burden. It adds only basic pagination info via parameter names, but does not disclose behavior like total count, empty results, or any potential limitations, making the description too thin for full transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and front-loaded, with no filler words. It states purpose in one sentence and then lists parameters clearly in a compact format.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with a simple schema and output schema, the description covers purpose and parameters. However, it lacks usage context, any caveats, and could benefit from explaining what announcements are, making it minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema lacks descriptions (0% coverage), but the description explicitly explains both parameters ('page: Page number', 'per_page: Results per page'), adding meaning beyond the raw schema fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all announcements' with a specific verb and resource, and it is distinct from sibling tools that focus on tickets, changes, assets, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives is provided. The use case is implied by the verb 'list', but there is no mention of exclusions, prerequisites, or alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description indicates a read-only listing operation and discloses pagination via the page and per_page arguments. However, it does not clarify behavior such as defaults for pagination, sorting, or any limits. Since there are no annotations, the description carries the full transparency burden but only partially meets it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with a clear purpose statement, followed by a minimal Args block. No extraneous information is included, though the docstring format is slightly more structured than necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the presence of an output schema, the description covers the essential purpose and parameters. However, it lacks usage guidance or edge-case information, but this is not critical for a straightforward listing endpoint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description includes an Args section explaining page as 'Page number' and per_page as 'Results per page.' This compensates for the schema's 0% description coverage, adding semantic meaning beyond the parameter names and types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'List all asset types,' using a specific verb and resource with scope. This clearly distinguishes it from sibling tools like get_assets and get_asset_by_id, which target assets rather than asset types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives. There are no mentions of use cases, exclusions, or references to sibling tools like get_assets or search_assets.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosure. 'List' implies a read-only operation, which is a useful behavioral cue, but it does not mention potential side effects, sorting/pagination, authorization requirements, or error behavior. The simple, non-destructive nature of the operation makes this acceptable but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with a clear 'Args:' section. Every word is relevant and there is no waste. It is appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity, an output schema exists, and the parameter is well described, the description is minimally complete. However, it lacks usage context and does not guide an agent on when to select this tool over related ones. It does not mention return value pitfalls or relationship to sibling tools, which a richer context would provide.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, and the description provides a clear semantic for the only parameter: 'folder_id: The canned response folder ID.' This adds meaning beyond the schema's bare type/title and fully explains the required input, compensating for the missing schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 all canned responses within a folder') and clearly distinguishes itself from siblings like 'get_canned_response' (singular) and 'get_canned_response_folders'. There is no ambiguity about the tool's scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 such as 'get_canned_response' or 'get_canned_response_folders'. It does not mention prerequisites (e.g., that the folder_id must come from 'get_canned_response_folders') or any context where this tool is preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description bears full responsibility for behavioral disclosure. It simply states 'List all requesters with pagination' with no mention of authentication, rate limits, inclusion criteria, or side effects. This provides minimal extra context for an agent planning a call.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise: a one-sentence summary followed by a compact parameter list. No redundant words, and the key purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool, this description is minimally viable: it conveys purpose and basic parameter semantics. However, it lacks details about pagination structure, return value shape, or guidance on when to use this vs. filter_requesters/get_requester_by_id. The output schema may cover return format, but behavioral aspects remain under-specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no parameter descriptions (0% coverage), but the description includes an Args section. 'per_page: Results per page (max 100)' adds a max constraint absent from the schema. However, 'page: Page number' just restates the parameter name and doesn't clarify starting index or edge cases, so it barely compensates for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' with resource 'requesters' and scope 'all', plus pagination. This clearly distinguishes it from siblings like get_requester_by_id, filter_requesters, and create_requester, so the agent knows exactly what this tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear context: use this when you want all requesters with pagination. However, it does not explicitly mention alternatives like filter_requesters for filtered lists, so it lacks explicit exclusion or alternative guidance, preventing a score of 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states that the tool lists replies and notes, which clarifies the scope, and the verb 'List' implies a read-only operation. However, it does not mention any side effects, authentication requirements, ordering, or whether both public and internal notes are included. It adds some context but not rich behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the purpose, and the Args block is clearly structured. Every sentence serves a purpose, and there is no unnecessary verbosity or repetition of schema information that is already visible.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with 3 parameters and an output schema, the description covers the core purpose and parameter semantics adequately. The output schema handles return values, so the description need not explain them. It lacks some context around pagination behavior (e.g., what pages represent, total count) and sibling tool differentiation, but the tool's simplicity keeps it relatively complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage (properties only have types/defaults). The description's parameter documentation is mostly tautological: 'ticket_id: The ticket ID' and 'page: Page number' add no real semantics beyond the property names. Only 'per_page: Results per page (max 100)' adds a meaningful constraint. The description only partially compensates for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and clearly specifies the resource ('all conversations (replies and notes) for a ticket'). It distinguishes this from sibling tools like get_ticket_by_id, reply_to_ticket, and add_ticket_note by focusing on reading existing conversations rather than creating or fetching ticket metadata.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies the use case (retrieving all conversations for a ticket) but does not explicitly mention when to use this tool versus alternatives or any exclusions. For example, it doesn't say 'use this to view replies and notes, but get_ticket_by_id for ticket details' or note any pagination limits. Context is present but not fully explicit about relative use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description is the only source for behavioral context. It discloses that body supports HTML and explains the private flag (agent-only vs public), which is useful. However, it does not mention required permissions, reversibility, or the response structure, leaving some behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the purpose, followed by a compact Arg list. Every sentence contributes useful information, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple three-parameter mutation tool, the description is largely complete: it covers the action, parameter semantics, and important nuances like HTML support and public/private behavior. The presence of an output schema satisfies return value documentation. Minor omissions (e.g., authorization requirements) prevent a higher score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only types and defaults with no field descriptions (0% coverage). The description compensates by explaining each parameter: ticket_id is "The ticket ID," body is "Note body (HTML supported)," and private is clarified as "True for private (agent-only) note, False for public." This adds meaningful semantics beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with "Add a note to a ticket," which is a specific verb+resource pair that clearly distinguishes this from sibling tools like delete_ticket_note and reply_to_ticket. It unambiguously states the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 such as reply_to_ticket or create_ticket. It only states the action itself, leaving the agent to infer appropriate usage. There is no mention of exclusions or alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It clearly indicates this is a read-only listing operation and provides pagination details (page, per_page, max 100). However, it does not explicitly state that no side effects occur, nor does it describe ordering, default behavior, or response structure beyond what the schema indicates.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with a clear two-part structure: a one-sentence summary followed by a brief Args section. Every sentence earns its place, and the front-loaded verb makes the purpose immediately obvious.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple paginated list tool with an output schema present, the description is mostly complete. It covers the resource and pagination parameters. However, it lacks any mention of ordering, filtering alternatives, or the fact that output schema describes each agent, though these are partially covered by the output schema and sibling tool names. Slightly more detail would make it fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description is the primary source for parameter meaning. It adds value by explaining 'page' as 'Page number' and 'per_page' as 'Results per page (max 100)', which is more informative than the schema's generic titles and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') with a clear resource ('agents') and scope ('all agents with pagination'). It clearly distinguishes itself from sibling tools like get_agent_by_id (single agent) and filter_agents (filtered search).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. It does not mention that get_agent_by_id should be used for individual agents or that filter_agents is better for searching with criteria. The description simply states its behavior without usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It adds the behavioral trait of including conversations and stats, which is useful, but it does not disclose permissions, rate limits, or whether conversations are complete or partial. For a read operation, this is adequate but not fully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, using two sentences and a simple Args block. It front-loads the main purpose and contains no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-ID tool with an output schema available, the description is complete enough. It specifies the resource, the selection criterion, and the included content (conversations and stats). It does not describe return format details, but the output schema covers that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no description for the only parameter (0% coverage), so the description's 'Args' section is the only semantic explanation. It states 'The numeric ticket ID', which is slightly redundant with the integer type but clarifies the parameter's role. This is minimal but sufficient for a single self-explanatory parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves a single ticket by ID, and additionally notes that conversations and stats are included. This distinguishes it from sibling tools like get_tickets (which lists tickets) and filter_tickets (which filters).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage is implied by the phrase 'single ticket by ID' but there is no explicit guidance on when to use it over alternative tools, nor any exclusions. It does not mention that it should be used when you have a specific ticket ID and need full details, but this is reasonably inferable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits, but it only states 'List all vendors' and the parameters. It does not mention whether the operation is read-only, any rate limits, or pagination behavior beyond the basic 'page' and 'per_page' parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with a clear front-loaded purpose statement followed by succinct parameter definitions. There is no unnecessary verbiage or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple paginated list tool, the description covers the essential behavior. The output schema is available to define the response structure, so the lack of return-value details is acceptable. However, it omits any mention of ordering or filtering capabilities, which could be useful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explicitly explains both parameters ('Page number' and 'Results per page'), which the input schema lacks. This adds meaningful semantic value beyond the schema's type and default information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all vendors' with a specific verb (list) and resource (vendors). This unambiguously conveys the tool's function, and while there are no vendor-specific sibling tools, the purpose is distinct and easily understood.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives, but the simple list operation implies its use when vendor data is needed. No exclusions or alternative tool references are provided, making the guidance implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It adds useful context by specifying status and article_type values and noting HTML support in the body, but it does not disclose side effects, permission requirements, or validation behaviors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a clear purpose sentence, followed by a structured Args list. It is slightly verbose but each line earns its place by explaining a parameter. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While output schema exists, the description omits important context like needing an existing folder or relationship with categories. It explains parameters well but lacks usage prerequisites and any mention of validation or constraints beyond the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description's Args block adds meaningful explanations for all six parameters, including enum-like meanings for status and article_type, HTML support for description, and optionality of tags. This significantly supplements the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new solution article' with a specific verb and resource. This distinguishes it from sibling tools like create_solution_category or create_solution_folder.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when creating a solution article but provides no explicit when/when-not guidance or alternatives. It does not mention prerequisites like needing a valid folder_id or relationships to other entities.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full transparency burden. It only states 'Create a new asset' and lists parameters; it does not disclose side effects, required permissions, validation behavior, or potential errors. This is minimal disclosure for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise introductory sentence followed by a tidy arg list with no redundant text. Every line adds parameter information, making it efficient and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers parameter meanings but does not explicitly indicate which fields are required (only the schema does). It also omits that most ID fields refer to existing records from other getters, though it does source asset_type_id. Given the output schema exists, the description is adequate but leaves gaps for a tool with 10 parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides semantic meaning for all 10 parameters, including impact level mapping (1=Low, 2=Medium, 3=High) and the source for asset_type_id. Since the schema has zero field descriptions, this fully compensates and makes each parameter's purpose clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Create a new asset,' a specific verb+resource combination. It clearly distinguishes from sibling CRUD tools like update_asset and delete_asset, and the parameter list reinforces its function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives, but it provides clear context by naming the operation and referencing get_asset_types as a source for asset_type_id. There are no exclusions, and the tool name makes its usage obvious among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that this is a soft delete ('Trash'), a key behavioral trait distinguishing it from a permanent delete. However, it does not address permissions, side effects on related entities, or recoverability beyond the soft-delete implication.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long and front-loaded with the action and its behavior. The Args section is minimal and directly relevant; no redundant or filler content exists.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (single required param, output schema present), the description covers the essential action and parameter. It lacks contextual information such as when to use soft delete vs. permanent deletion, but the core is complete for a simple delete operation. The presence of an output schema covers return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has a single parameter with no property description (0% coverage). The description compensates by including an Args section that defines ticket_id as 'The ticket ID to delete,' adding meaningful semantics beyond the schema's bare type of integer.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Trash' and explicitly clarifies 'soft delete', clearly distinguishing this from sibling tools like delete_ticket_note or delete_change. It clearly identifies the resource as a ticket.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when this tool should be used versus alternatives. The mention of 'soft delete' implies usage for non-permanent deletions, but no alternative is named and no exclusion or prerequisite is given. Usage guidance is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It mentions pagination (a key behavior) and the max limit for per_page, but does not explicitly state whether the operation is read-only or describe other side effects. Given the listing nature, it's adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short lines, front-loaded with the core purpose, and every sentence provides useful information. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, has an output schema, and the description covers the primary behavior and parameters. It lacks guidance on when to use this vs. filter/search variants, but overall it is sufficiently complete for a listing operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, leaving the parameter meanings undefined. The description compensates by explicitly documenting both 'page' and 'per_page', including the max 100 constraint, adding essential meaning beyond the schema's bare types and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all assets with pagination', which identifies the specific operation (list) and resource (assets). This distinguishes it from siblings like get_asset_by_id or search_assets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the phrase 'List all assets' - meaning use this to retrieve the full asset list. However, no explicit comparison or guidance is provided for when to use this tool versus alternatives like search_assets or filter_assets.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It indicates a read-only operation via the verb 'Retrieve' and clarifies scope with 'all' and 'built-in and custom,' but does not mention any rate limits, permissions, pagination, or other notable behaviors. This is minimal but not contradictory.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that immediately states the purpose and scope. It is front-loaded with the action and resource and contains no redundant or extra content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and an output schema exists (to describe return values), the description covers the essential purpose and scope. It could include a note about how the field definitions might be used, but for a simple getter it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters; the input schema is empty. Therefore, the description correctly does not add parameter semantics. The baseline score for zero parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Retrieve all ticket field definitions (built-in and custom).' This clearly specifies the action (retrieve) and the resource (ticket field definitions), distinguishing it from sibling tools like get_tickets or get_ticket_by_id that retrieve ticket records. The scope is also explicit with 'all' and 'built-in and custom.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives. It only describes what it does, leaving the usage to be implied: if an agent needs ticket field definitions, this tool is appropriate. No alternatives or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds useful behavioral details beyond the schema: it specifies that body supports HTML and explains the private flag semantics ('True for agent-only note, False for public'). However, with no annotations provided, the description carries the full burden and does not disclose other side effects such as permissions, notification behavior, or reversibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a one-line purpose, followed by a cleanly formatted Args block. It is concise and contains no redundancy; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the description covers the essential purpose and parameters thoroughly. The existence of an output schema means return values are handled elsewhere. Minor gaps like prerequisites (e.g., the change must exist) are not mentioned, but these are reasonably inferred from the context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides meaningful explanations for all three parameters—change_id, body, and private—going beyond the bare schema types. For example, it clarifies that body supports HTML and that private controls visibility. Since schema description coverage is 0%, the description fully compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Add a note to a change request,' using a specific verb and resource. It distinguishes this from sibling ticket note tools like add_ticket_note by specifying 'change request.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The tool's purpose implies when to use it (for adding notes to change requests), but it does not explicitly reference alternatives or when not to use it. There is no mention of using add_ticket_note for ticket notes, so the usage guidance remains implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It discloses one meaningful side effect—'Creates a new contact if not found' for the email parameter—but does not discuss permissions, reversibility, error conditions, or other write-behavior implications beyond the obvious creation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized as a clear 'Args' list with one line per parameter, each providing compact yet complete meaning. No fluff or redundancy; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create operation with 16 parameters, the description covers all input semantics and the output schema exists to describe return values. It lacks only explicit usage context and broader behavioral notes, but it is largely complete 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.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates by explaining every one of the 16 parameters, including enums for priority, status, and source, as well as defaults and types. This is exemplary parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new Freshservice ticket' with a specific verb and resource. The parameter list further clarifies the tool's scope, distinguishing it from sibling tools like update_ticket or delete_ticket.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the 'create' semantics, but there is no explicit guidance on when to use this tool versus alternatives like update_ticket or create_problem. The description does not mention prerequisites or situations where a different tool would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. 'List all' discloses a read-only, unfiltered operation, which is useful. However, it does not mention potential pagination, ordering, authentication requirements, or whether archived/inactive folders are included, leaving some behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence: 'List all canned response folders.' It is concise with no wasted words and effectively conveys the core action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters), the existence of an output schema, and the clear distinction from sibling tools, the description is complete. It fully captures what the tool does without needing to describe return values, which are covered by the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema coverage is 100%, so the baseline is 4. The description does not need to add parameter details; it correctly signals that no arguments are required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List'), identifies a clear resource ('canned response folders'), and specifies scope ('all'). It distinguishes this tool from siblings like 'get_canned_responses_in_folder' and 'get_canned_response', which operate on individual responses or folders' contents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving the full set of canned response folders, but it does not explicitly state when to use this tool versus alternatives or provide workflow guidance. No exclusions or context are given, so usage is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description partially carries the burden. It discloses key behavioral traits: pagination with per_page max 100, and the requirement that query must be in double quotes with example syntax. This conveys important usage constraints not visible in the schema. However, it does not mention sorting or default behavior beyond pagination, and 'List' implies a read but no explicit read-only confirmation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and front-loaded with the main purpose. The Args section is compact and each line adds specific value (page, per_page, query syntax). No wasted words or redundant info.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema, so return values need not be described. The description covers the three optional parameters and their constraints, making it reasonably complete for a listing tool. It lacks a note on how this tool differs from filter_changes, but the essential behavior is captured.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It does for query by explaining the mandatory double-quote format and providing examples, and for per_page by stating the max 100. For page, it simply restates the parameter name ('Page number'), which adds little over the schema title, so not all parameters get equally enriched.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all changes' with a specific verb and resource, and mentions optional filtering. It distinguishes from get_change_by_id which is for a single change, but does not explicitly distinguish from the similarly-named filter_changes tool, so it lacks explicit sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: pagination parameters and optional query filtering. It does not explicitly state when to use this tool instead of filter_changes or get_change_by_id, but the context implies it is for broad listing with optional filters, which is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It does disclose a critical constraint (quotes required) and shows query syntax examples, but it does not state whether the operation is read-only, how pagination behaves, or what error/edge cases exist. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a brief purpose statement, an important note about quoting, three illustrative examples, and a compact Args list. Every element earns its place, and it's front-loaded with the action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and the simplicity of page/per_page parameters, the description covers the complex part (query syntax) thoroughly with examples. It does not explain the response structure (handled by output schema) or mention that query is required (in schema). It lacks a note on when to prefer this over get_changes, but overall it is sufficiently complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 provides an 'Args' section explaining each parameter (query as Freshservice filter query string, page, per_page) and enriches the query parameter with examples of valid filter syntax. This adds meaning beyond the bare schema types and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Filter changes with advanced queries,' clearly stating the verb (filter), resource (changes), and the distinguishing feature (advanced queries). It also provides concrete examples that differentiate it from sibling tools like filter_tickets or get_changes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for query-based filtering (e.g., 'Query MUST be wrapped in double quotes' and examples of status/approval queries), giving clear context for when to use it. However, it does not explicitly mention alternatives like get_changes for unfiltered lists or when not to use this tool, so it misses the top score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It states the pagination capability and the per_page limit of 100, which is useful. However, it does not mention any other behaviors such as sorting, default ordering, or that results might be incomplete without pagination. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a single overview sentence followed by parameter bullet-points. Every sentence provides necessary information without waste. It is well-structured and front-loaded with the primary purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (2 simple parameters, list operation, output schema present in the context), the description is complete enough. It covers the purpose and all parameters. It does not describe return values (output schema exists), and no filtering or sorting is relevant to a plain 'list all' operation. It could be improved by mentioning that pagination is necessary to retrieve all results, but overall it is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description compensates by explaining both parameters: 'page: Page number' and 'per_page: Results per page (max 100)'. The 'max 100' constraint is not present in the schema, adding useful semantic detail. The explanations are brief but sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 all problems with pagination.' This clearly distinguishes it from get_problem_by_id, which fetches a single problem, and from create_problem, which creates one. The scope ('all problems') and the pagination behavior are explicitly stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates this tool is for listing all problems with pagination. It does not explicitly mention when not to use it or provide alternatives (e.g., 'for a specific problem, use get_problem_by_id'), but the context is clear enough for a simple list-resource tool. No exclusions are given, but the intended use is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full burden. It discloses the listing behavior and pagination via the page and per_page parameters, but does not address edge cases like permissions, whether subfolder articles are included, or error conditions. The simplicity of a list operation mitigates this, but more context would be valuable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of a one-sentence summary and a simple argument list. There is no fluff, and each sentence serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with an output schema, the description covers the essential purpose and parameters. It could be improved by noting that search_solution_articles exists for search scenarios, but it is generally sufficient for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 provides one-line explanations for all three parameters: folder_id as 'parent folder ID,' and page/per_page as standard pagination controls. This adds meaning beyond the bare schema titles, though the explanations are terse.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List all solution articles in a folder' clearly identifies the action (list), the resource (solution articles), and the scope (within a folder). This distinguishes it from siblings like get_solution_article_by_id (single article) and search_solution_articles (search-based retrieval).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for listing articles in a specific folder, which is a clear context. However, it does not explicitly mention alternatives or exclusions, such as when to use search_solution_articles instead. Sibling names provide some differentiation, but explicit guidance is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It reveals pagination behavior and parameter constraints (page starts at 1, per_page max 100). However, it does not mention potential prerequisites, rate limits, or characteristics of the returned data (e.g., ordering, status inclusion), leaving some behavioral aspects undisclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences followed by a clean args list. It is front-loaded with the primary purpose and contains no filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with two optional integer parameters and an output schema, the description is largely sufficient. It covers purpose and pagination constraints. However, without annotations, a bit more context about behavior (e.g., "all tickets" including closed ones) would make it fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds crucial meaning to both parameters: page starts at 1 and per_page has a maximum of 100. Since the input schema only provides types and defaults with no descriptions, and schema description coverage is 0%, this fully compensates for the schema's lack of semantic detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb "List" with resource "tickets" and explicitly states "all tickets", clearly distinguishing it from siblings like get_ticket_by_id (single ticket) and filter_tickets (filtered query).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase "List all tickets" provides clear context that this tool fetches the full set of tickets without filtering. However, it does not explicitly mention when to prefer this over filter_tickets or get_ticket_by_id, so it lacks explicit exclusions or alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does disclose the key side effect that the reply is visible to the requester, but it does not mention other potential behavioral traits like email notifications, permission requirements, or effects on ticket status, leaving some gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise: one purpose sentence followed by a compact Args list. Every word earns its place, with no repetition of schema types or unnecessary filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with only 3 parameters, an output schema is present, and the description covers purpose, visibility semantics, and all parameters. Nothing essential is missing for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully compensate for the schema's lack of explanations. It does this exceptionally well: ticket_id is identified as the ticket ID, body is described with HTML support, and cc_emails is marked optional with its purpose stated.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Reply' with the resource 'a ticket' and adds the crucial scope 'visible to requester,' which distinguishes this from internal note-taking tools like add_ticket_note. It clearly states what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'visible to requester' provides clear context that this tool is for public replies, implying it should be used when the customer should see the response. However, it does not explicitly name alternatives or state when not to use it, such as for internal notes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the full burden of behavioral disclosure. It discloses critical constraints: the query must be wrapped in double quotes and per_page has a max of 100. It also explains pagination via page and per_page. It does not mention authentication or side effects, but as a filter/read operation, immutability is implied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a one-sentence purpose, a critical syntax note with five illustrative examples, and a clear Args list. Every sentence contributes useful information without unnecessary fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, return-value details are not needed. The description covers the query language syntax, quoting requirement, pagination, and parameter constraints, making it complete for correct invocation. It also provides practical examples for typical use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides no property descriptions (0% coverage), but the description explains each parameter thoroughly: query with the double-quote requirement, page as a page number, and per_page with a max of 100. This adds substantial meaning beyond the raw schema types and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the tool's function: 'Filter tickets using Freshservice query language.' This distinct verb+resource pairing differentiates it from sibling tools like get_tickets (which likely lists without filtering) and get_ticket_by_id. The mention of the query language adds precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides concrete usage context through examples such as 'status:2' and 'priority:4', which imply when to use this tool. However, it does not explicitly state when not to use it or mention alternatives like get_tickets, so it lacks explicit exclusions and alternative references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![freshservice-mcp MCP server](https://glama.ai/mcp/servers/matthewlboyd/freshservice-mcp/badges/card.svg)](https://glama.ai/mcp/servers/matthewlboyd/freshservice-mcp)

Score Badge

Copy to your README.md:

[![freshservice-mcp MCP server](https://glama.ai/mcp/servers/matthewlboyd/freshservice-mcp/badges/score.svg)](https://glama.ai/mcp/servers/matthewlboyd/freshservice-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/matthewlboyd/freshservice-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server