jira-service-desk-mcp

Server Quality Checklist

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

Latest release: v0.1.1
Disambiguation5/5
Each tool targets a distinct resource and action (e.g., add vs remove, customer vs organization), and even similar resources like comments have separate create/get/list tools. There is no confusion between tool purposes.
Naming Consistency5/5
Tool names consistently follow the verb_noun pattern in snake_case (e.g., list_service_desks, add_customers_to_service_desk). Minor deviations like get_service_desk_info are rare and do not break the pattern.
Tool Count4/5
40 tools cover a broad domain (desks, organizations, customers, requests, comments, approvals, queues, transitions, attachments). While slightly heavy, each tool serves a distinct purpose and the count is justified for the complexity of Jira Service Management.
Completeness3/5
Core CRUD and lifecycle operations are present for requests, comments, attachments, and organizations, but notable gaps exist: no update/delete for customers, no update for organizations, and no direct tool to update request fields (only transitions).
Average 4/5 across 40 of 40 tools scored. Lowest: 3.1/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 0 commits in the last 12 weeks
- Last stable release on March 18, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
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

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only mentions 'permanently delete' without detailing side effects beyond member associations, permissions, or implications for dependent data.
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?
Very concise, two sentences, no unnecessary words. Straightforward and 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?
Minimally adequate for a simple one-parameter tool with an output schema, but lacks warnings about irreversibility, permissions, or broader cleanup.
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 merely restates the parameter name 'organization_id' without adding meaning, format, or 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?
Clearly states the action ('Permanently delete') and the resource ('organization'), with additional detail about removing member associations. Distinguishes from siblings like create_organization and get_organization.
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 alternatives (e.g., update or archive). No prerequisites or conditions 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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It implies a read-only operation but does not explicitly state that it has no side effects, requires no special permissions, or what constitutes a valid organization ID. The description is minimal and does not disclose potential errors or limits.
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 at two sentences, with no unnecessary words. It is front-loaded with the main action. However, it could be slightly expanded to include more context without sacrificing conciseness.
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 present), the description is adequate but not rich. It does not explain what details are returned or that the ID is required (though schema indicates required). The output schema likely covers return values, so the description is 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 only parameter, organization_id, is described simply as 'The numeric organization ID.' The schema type is string, but the description says numeric, which is slightly misleading. No additional constraints, format, or examples are provided. With 0% schema description coverage, the description adds little meaning beyond the parameter 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 'Get details of a specific organization by its ID,' specifying the verb ('Get'), resource ('organization'), and identifier method. This distinguishes it from sibling tools like list_organizations, create_organization, and delete_organization.
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. For instance, it does not explain that this tool should be used when an organization ID is known, while list_organizations is for browsing. No exclusions or alternatives 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, the description must convey behavioral traits. It only states it creates an organization, but does not disclose side effects, required permissions, or constraints like name uniqueness. The presence of an output schema reduces the need to describe return values, but behavioral aspects are still missing.
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: two sentences front-load the purpose and the parameter description. No wasted words, making it 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 simple creation tool with one parameter and an output schema, the description is adequate but could be more complete by explaining what a 'customer organization' entails or its relationship to other entities like customers and service desks.
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?
Despite 0% schema description coverage, the description adds meaning by specifying that 'name' is a display name. This compensates well for the single parameter, ensuring the agent understands its purpose.
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 'Create a new customer organization,' specifying the verb and resource. However, it does not differentiate from sibling tools like 'create_customer' or 'create_customer_request', which could cause confusion.
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, nor any prerequisites or exclusions. The description lacks context for the agent to decide between creation 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 exist, and the description only mentions 'link' without elaborating on effects (e.g., whether it creates a new association, updates existing, or is idempotent), permissions needed, or side effects.
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: two sentences of purpose plus a two-parameter list. No unnecessary words or repetition.
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 exists (not shown), so return values are covered. However, the description lacks information on error cases (e.g., invalid IDs, duplicate linking) and expected behavior.
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 coverage is 0%, but the description's Args section provides minimal explanations ('The numeric ID of the service desk', etc.). This adds some meaning beyond the schema's title and type, but not enough to be highly informative.
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 'link' and the resources 'organization' and 'service desk', and explains the benefit ('so its members can raise requests'). It distinguishes from sibling tools like 'remove_organization_from_service_desk' and 'add_customers_to_service_desk'.
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, prerequisites, or conditions under which it should not be used (e.g., if organization is already linked).
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 states the operation without mentioning side effects, permissions, or error conditions, which is insufficient for a mutating 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 extremely concise, using one sentence and a straightforward argument list with minimal verbosity. Every word serves a purpose.
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 unlinking operation, the description is minimally adequate. However, it lacks information about the return value (despite having an output schema) and any prerequisites, leaving some gaps.
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, but the description minimally explains each parameter as 'The numeric ID of the service desk' and 'The numeric organization ID'. However, the type of 'service_desk_id' is string while described as numeric, causing potential confusion.
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 ('unlink') and the resource ('organization from a service desk'), distinguishing it from sibling tools like 'add_organization_to_service_desk'.
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 (e.g., 'add_organization_to_service_desk' or 'remove_users_from_organization'). The agent must 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, and the description lacks behavioral details such as required permissions, idempotency, side effects, or error conditions. It only states the action and purpose.
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 (one sentence plus parameter details) and front-loaded with the primary purpose. The parameter descriptions are well-structured.
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 has an output schema, but the description does not elaborate on return values or edge cases. It adequately covers the basic function but lacks completeness for complex scenarios.
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 explains the meaning of each parameter beyond the schema: issue_id_or_key as issue key or numeric ID, usernames and account_ids as optional comma-separated lists. This is helpful given 0% schema description 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 clearly states the tool's action ('Add participants') and resource ('customer request'), with a specific purpose ('so they receive updates'). It distinguishes itself from sibling tools like remove_request_participants and list_request_participants.
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 a usage context ('so they receive updates') but no explicit guidance on when to use this tool versus alternatives, nor any when-not-to-use conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 read-only nature, authentication needs, ordering, or error behavior. It only lists parameters, missing critical behavioral context.
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: one sentence for purpose and a clear parameter list. Every word earns its place with no 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 list with pagination and an output schema present, the description covers basic usage. Could mention ordering or validation, but overall adequate.
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%, but the description adds meaning: 'numeric organization ID', '0-based offset', and default limit. This compensates for the schema's lack of 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 the specific verb 'List' and resource 'users who belong to an organization', clearly distinguishing from siblings like 'list_organizations' and 'add_users_to_organization'.
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 on when to use this tool versus alternatives (e.g., search tools). The context is implied by the resource name but lacks when-not-to-use or alternative 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 carries full burden for behavioral traits. It fails to disclose effects like immediate removal, reversibility, permission requirements, or side effects, leaving the agent with minimal insight.
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 relatively concise with a clear 'Args' section. It could be more front-loaded, but every sentence adds value without waste.
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 has an output schema (not shown), the description partially covers inputs but omits return values, error conditions, and behavioral context like whether removal is immediate or requires permissions. For a removal operation with 3 parameters, more completeness is needed.
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%, but the description adds essential meaning: it explains the issue_id_or_key format with an example ('X000') and clarifies that usernames are for Server/DC while account_ids are for Cloud, which is not 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 clearly states the action and resource: 'Remove participants from a customer request.' This distinguishes it from sibling tools like 'add_request_participants', which performs the opposite operation.
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 when to use alternative parameters (usernames for Server/DC, account_ids for Cloud) but does not explicitly state when to use this tool versus alternatives like 'add_request_participants' or other removal 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 must disclose behavioral traits. It only states the action (approve/decline) but omits side effects such as whether the action is reversible, if notifications are triggered, or if any state changes beyond the approval status. This 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a single-sentence purpose and a structured Args list. Every sentence adds value without redundancy. It is front-loaded with the purpose.
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 simple tool (3 required parameters, no nested objects) and the presence of an output schema, the description covers the basics adequately. However, it lacks information about prerequisites (e.g., obtaining the approval ID) and does not hint at any side effects or errors, 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?
Schema coverage is 0%, but the description adds significant meaning for all three parameters: it specifies the format for issue_id_or_key (e.g., 'X000'), confirms approval_id is numeric, and lists the exact decision strings. This goes well beyond the schema's simple string type definitions.
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-resource pair: 'Approve or decline an approval request.' This directly distinguishes it from siblings like 'get_approval' and 'list_approvals' which are read-only.
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 Args section provides clear parameter formats (e.g., issue key, numeric approval ID, decision values) but does not explicitly state when to use this tool versus alternatives like 'get_approval' or 'list_approvals'. Usage context is implied rather than specified.
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 adds 'experimental API' as a behavioral note. It lacks disclosure of permissions needed, side effects, rate limits, or error handling, which are critical for safe invocation.
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 three sentences. It front-loads the primary purpose, adds a key outcome, and lists parameters efficiently. 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?
Output schema exists, reducing the burden. The description covers purpose and parameters adequately for a simple creation tool. However, it omits error scenarios, idempotency, or validation rules, which would enhance completeness.
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?
Although schema coverage is 0%, the description compensates by documenting both parameters with meaningful examples (e.g., 'Jane Doe' for full_name). This adds clarity beyond the schema's type-only definition.
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?
Description clearly states it creates a new customer account in JSM and explains the outcome (customer can raise requests). It distinguishes from siblings like create_customer_request and add_customers_to_service_desk by focusing on account creation.
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 (creating new customer accounts) but does not explicitly state when to use this tool versus alternatives like add_customers_to_service_desk. No exclusions or prerequisites 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?
With no annotations, the description implies a read operation but does not disclose side effects, authentication needs, error behavior, or any restrictions. It minimally covers the purpose but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: one sentence for purpose followed by a short parameter list. It is front-loaded but could benefit from structured formatting (e.g., bullets) for readability.
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 retrieval tool with an output schema, the description covers the essential: what is retrieved (approval details including decisions) and required parameters. It is adequate but does not mention error cases or data scope.
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?
Despite 0% schema coverage, the description adds meaning: issue_id_or_key is explained as 'issue key (e.g. 'X000') or numeric issue ID', and approval_id as 'numeric approval ID'. This clarifies the format beyond the schema's generic 'string' type.
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 'Get details of a specific approval including approver decisions.' It specifies the verb (get) and resource (approval details), and distinguishes from siblings like list_approvals (list all) and answer_approval (action).
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 alternatives like list_approvals. No prerequisites, context, 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must cover behavior. Only states 'Get details' implying read-only, but lacks info on permissions, side effects, or limits.
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?
Concise two-part structure: purpose sentence upfront, then parameter list. Zero unnecessary words, easy to parse.
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?
Tool has output schema covering return values. Description states return fields (name, description, help text). All necessary context provided for a simple retrieval.
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 has 0% description coverage, but description adds clear explanation for each parameter: numeric IDs with examples (e.g., '1', '10'), compensating well.
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?
Description clearly states 'Get details of a specific request type' with specific return fields (name, description, help text). Distinct from sibling 'list_request_types' which lists all.
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 alternatives like 'list_request_types'. The description only provides parameter details without contrast.
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. It only states it gets details, but does not mention that it is read-only, what happens if ID is invalid, or any required permissions. Minimal behavioral context beyond the action itself.
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: one main sentence plus a docstring-style args section. Every sentence provides value, front-loaded with the core action. No superfluous 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?
Given the tool is simple (1 param, no nested objects) and has an output schema, the description adequately covers purpose, prerequisite, and parameter meaning. It could mention return type or error handling, but the output schema likely covers return values, making it 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?
Schema coverage is 0%, but the description adds 'The numeric ID of the service desk (e.g. '1')', clarifying the expected format (numeric string) with an example. This adds significant meaning beyond the schema's type string alone.
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 'Get details of a specific service desk by its numeric ID', providing a specific verb and resource. It distinguishes from list_service_desks by referencing it to find the ID, but doesn't explicitly distinguish from get_service_desk_info, leaving slight ambiguity with sibling tools.
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 explicitly advises using list_service_desks first to find the ID, giving clear context for when to use this tool. However, it does not mention when not to use it or provide explicit alternatives among 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 must disclose behavioral traits. It only lists what the tool returns (status, reporter, field values) but fails to mention that it is a read-only operation, any authorization requirements, or rate limits. Minimal behavioral context.
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: two sentences plus an Args section. Every sentence is informative, and the key information is front-loaded. No wasted words.
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 complexity (1 parameter, output schema present), the description adequately covers the core functionality. It mentions the returned fields (status, reporter, field values). Could optionally mention that it returns a single request object, but not necessary since output schema exists.
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 parameter 'issue_id_or_key' is described with a format example (e.g., 'X000') and explanation (issue key or numeric ID). This adds significant value beyond the schema, which only specifies type string with no description. The description also hints at the expected format.
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 purpose: 'Get full details of a customer request including status, reporter, and field values.' This distinguishes it from sibling tools like get_customer_request_status, which only returns status.
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 guidelines for when to use this tool versus alternatives (e.g., get_customer_request_status). The usage is implied by the purpose, but no exclusions or comparative context 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 must disclose behavioral traits. It does not mention read-only nature, side effects, or error conditions, which are critical for an unannotated 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 two sentences, front-loaded with the purpose, and contains no superfluous 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?
Given an output schema exists, the description succinctly states what is returned. However, it omits error handling or prerequisites, but the focused scope and sibling tools cover broader context.
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?
With 0% schema description coverage, the description compensates by explaining the parameter 'issue_id_or_key' with an example format, adding meaning beyond the schema's type-only definition.
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 retrieves 'current status and status category' of a customer request, which is specific and distinguishes it from sibling tools like 'get_customer_request' that likely return full details.
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 parameter format but lacks guidance on when to use this tool versus alternatives such as 'get_customer_request' or 'get_approval', leaving selection ambiguous.
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 states 'Get', which implies a read operation, but it does not mention error handling (e.g., missing SLA), authorization requirements, rate limits, or any side effects. For a tool with no annotation support, this is insufficient to inform safe invocation.
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 sentence for the purpose and two lines for parameter explanations. No extraneous information, no redundant phrases. It is front-loaded with the core operation, making it easy for an AI agent to parse quickly. Every part 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?
Given that an output schema exists (so return structure is documented elsewhere), the description covers the essential purpose and parameter semantics. It does not explain the return shape or common error cases, but for a simple lookup tool with a defined schema, this is acceptable. A minor addition about needing the SLA from get_request_sla would improve completeness.
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 (only titles). The tool description compensates by explaining each parameter: 'issue_id_or_key' is described as 'The issue key (e.g. "X000") or numeric issue ID.' and 'sla_id' as 'The SLA metric ID.' This adds meaningful context beyond the bare schema titles, though it could include constraints like format or source (e.g., obtained from get_request_sla).
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 'Get a specific SLA metric by its ID for a customer request.' It specifies the verb ('Get'), the resource ('SLA metric'), and the means ('by its ID'). This distinguishes it from the sibling tool 'get_request_sla', which likely lists all SLAs or provides general SLA info. The specificity ensures an agent understands exactly what resource is targeted.
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 implicitly indicates usage when you have an SLA ID to retrieve a specific metric, but it does not explicitly state when to use this tool versus alternatives like 'get_request_sla'. No guidance is given on preconditions (e.g., needing the SLA ID from another tool) or when not to use it. The usage context is implied but not fully 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 provided. Description only states it 'grants access' without detailing side effects (e.g., idempotency, whether it overwrites, permissions needed). Minimal behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Short, structured with bullet points for arguments. Every sentence adds value with no 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?
Covers purpose and parameter usage, but omits edge cases like handling both parameters simultaneously, error conditions, or idempotency. Output schema exists, so return values are not needed.
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%, but the description explains the comma-separated format and environment distinction for usernames/account_ids. Adds meaning 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 clearly states the action ('Grant one or more users access to a service desk as customers') with a specific verb and resource. It distinguishes from sibling tools like remove_customers_from_service_desk.
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?
Provides clear guidance on parameter usage: usernames for Server/DC, account_ids for Cloud. Does not explicitly mention when not to use the tool or alternatives, but the context is sufficient.
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 exist, so the description must fully disclose behavioral traits. It only says 'Add users' without explaining side effects (e.g., invitations, idempotency, behavior when user already exists). This leaves significant gaps for an AI agent.
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, using bullet points to separate parameter usage. It front-loads the primary action in a single line, then efficiently explains the parameter distinction. No unnecessary words or repetition.
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 an existing output schema, the description covers essential usage scenarios. However, it lacks behavioral context (e.g., error handling, idempotency, permissions) that would be needed for an AI agent to use it robustly without further assumptions.
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?
With 0% schema coverage, the description adds critical meaning: it explains that 'usernames' are for Server/DC and 'account_ids' for Cloud, and mentions they are comma-separated. It also clarifies that organization_id is numeric. This compensates well for the schema's lack of 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 'Add users to an organization' – a specific verb and resource. It distinguishes the tool from siblings by detailing the parameter split between Server/DC (usernames) and Cloud (account_ids), making the tool's role unambiguous.
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 guidance on when to use usernames vs account_ids based on deployment type. However, it does not explicitly mention when not to use this tool or specify prerequisites (e.g., admin rights), though no direct alternative tool exists for this action.
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 provided, so description must disclose behavior. It specifies return values (remaining time, breach status, goal durations) and pagination, but does not explicitly state read-only nature or permissions required. The description is moderately transparent but lacks explicit safety or side-effect statements.
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 consists of three sentences plus a bullet list of parameter descriptions. It is structured, front-loaded with the purpose, and each part adds value. No unnecessary words.
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 output schema exists, the description need not detail return values, but it does summarize them. It covers all parameters and explains pagination. The tool is simple, and the description provides sufficient context for an agent to use it correctly.
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%, but the description adds meaning for all three parameters: issue_id_or_key with example format, start as pagination offset, and limit with default. This goes beyond the schema's titles and types, compensating 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 the tool gets SLA metrics for a customer request, specifying it returns remaining time, breach status, and goal durations. The use of 'Get' and resource 'SLA metrics' is specific, and it is differentiated from sibling 'get_request_sla_by_id' by the parameter issue_id_or_key.
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 SLA metrics for a request are needed, but does not explicitly state when to use versus alternatives or any prerequisites. No guidance on when not to use is given.
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 states the tool lists pending and completed approvals but does not disclose behavioral traits such as read-only nature, pagination behavior, or error handling. With the output schema present, the return structure is implied, but the description lacks explicit behavioral context.
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: one introductory sentence followed by parameter documentation. No wasted words, front-loaded with the purpose, and efficiently structured.
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 3 parameters, no annotations, and an output schema, the description covers purpose and parameter details adequately. It does not explain return values (permitted since output schema exists) but could mention that it lists approvals for a specific request. Overall, it is complete for the complexity level.
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 fully. It provides explicit docstrings for each parameter: issue_id_or_key format ('X000' or numeric ID), start as pagination offset, limit with default. This adds significant meaning beyond the schema's basic type and title.
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 pending and completed approvals for a customer request', specifying the verb (list), resource (approvals), and scope (by customer request). This distinctively separates it from sibling tools like get_approval (singular) and answer_approval.
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 does not provide explicit guidance on when to use this tool versus alternatives like get_approval. It only implies usage for listing multiple approvals for a request, but no when-not-to-use or context for choosing 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?
With no annotations, the description carries full burden. It discloses that participants receive notifications and explains pagination behavior (start, limit). However, it lacks details about permissions, rate limits, or any non-obvious side effects.
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 structured with a clear heading and Arg section. The first sentence directly states the purpose. The optional note about notifications adds minor context but could be removed for conciseness.
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 (assumed to document return values), the description adequately covers behavior and parameters. It explains pagination and the resource being listed, making it complete for a simple list tool.
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%, but the description clearly explains each parameter: issue_id_or_key with an example, start as pagination offset, and limit as max results with default. This adds significant value 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 the tool lists users who participate in a customer request. It uses specific verb 'list' and resource 'request participants', distinguishing it from sibling tools like add_request_participants and remove_request_participants.
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 viewing participants of a request and mentions they receive notifications, but does not explicitly state when to use this over other participant-related tools or provide any exclusion criteria.
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 implies a destructive operation but does not disclose permissions, side effects, rate limits, or error behavior (e.g., what happens if users are not found). The description adds minimal behavioral context beyond the obvious removal action.
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 with two sentences and an Args list. The main purpose is front-loaded. Every sentence adds value, and the structure is clear. No unnecessary 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?
With an output schema present, the description does not need to explain return values. However, it lacks discussion of edge cases (e.g., providing both usernames and account_ids, or error handling). It is adequate but has gaps.
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%, but the description compensates by explaining that usernames are for Server/DC and account_ids for Cloud, and notes they are comma-separated. It also adds that organization_id is numeric, though the schema says string (minor inconsistency). This adds meaningful meaning 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 clearly states 'Remove users from an organization.' It specifies the verb 'remove' and the resource 'users from an organization.' It distinguishes itself from siblings like add_users_to_organization and remove_customers_from_service_desk. The description also clarifies the context for different deployment types.
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 explicitly explains when to use usernames (Server/DC) or account_ids (Cloud), providing clear context. However, it does not explicitly state when not to use this tool or mention alternatives, but the guidance is sufficient for selecting the correct parameter.
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 fails to mention that the tool is read-only, any rate limits, authentication needs, or the structure of the response. While a list operation is inherently non-destructive, the lack of such disclosure leaves 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 extremely concise: one sentence for purpose, one line for prerequisite, and a compact param list. No fluff, 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 existence of an output schema, the description sufficiently covers purpose, prerequisites, and parameter meanings. It could be more complete by noting what the response format contains, but the output schema fills that gap.
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%, but the description adds explanations for all parameters: 'numeric ID', 'pagination offset', 'maximum number of results'. This compensates well for the schema's lack of 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?
Describes a specific verb ('list'), resource ('customer requests'), and scope ('sitting in a specific queue'), which clearly distinguishes it from sibling tools like list_queues.
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?
Explicitly instructs the agent to use list_queues first to discover queue IDs, providing a prerequisite step. Does not mention when not to use, but the sibling list is extensive and the tool's function is self-contained.
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?
Describes the creation action and input parameters, but lacks details on permissions, idempotency, error handling, or side effects such as notifications. With no annotations, the description carries the full burden and could be more transparent.
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?
Well-structured with a front-loaded tip and clear parameter list. Compact but covers necessary details. Could be slightly more concise by removing redundancy with schema titles.
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?
Covers input and a prerequisite, but does not mention output format, error handling, or relationships with sibling tools like attach_file_to_request. An output schema exists, which alleviates some burden, but still missing context for full usage.
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?
Adds significant value beyond the input schema (0% coverage). Explains each parameter's purpose with examples for values_json and clarifies the format for raise_on_behalf_of and request_participants.
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?
Clearly states 'Create a new customer request (ticket) in a service desk' with a specific verb and resource. Distinguishes from siblings like get_request_type_fields via the tip.
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?
Provides a helpful tip to call get_request_type_fields first, guiding on prerequisite discovery. However, does not explicitly mention when not to use this tool or compare with alternatives like attach_file_to_request.
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?
Without annotations, the description carries the full burden. It states the action (revoke access) which implies modification. However, it does not disclose if the operation is reversible, if authorization is required, or potential side effects (e.g., impact on active requests). The presence of an output schema means return format is not needed, but behavioral traits beyond the basic action are lacking.
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 with two sentences plus bullet-like args. It is front-loaded with the main action. Every sentence adds value, though the args section could be more structured (e.g., using a table). Overall, it is efficient and clear.
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 has 3 parameters (one required, two optional alternatives) and an output schema, the description covers the key information: how to specify customers by platform. However, it lacks operational context such as batch processing limits, error conditions, or whether the operation affects only specified customers or all. It is adequate but not fully comprehensive.
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 explains each parameter: service_desk_id as numeric ID, usernames as comma-separated for Server/DC, account_ids as comma-separated for Cloud, and implies that at least one of the optional parameters is needed. This adds essential meaning beyond the schema's titles 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 clearly states 'Revoke customer access from a service desk,' specifying the action, target, and resource. It distinguishes between usernames for Server/DC and account_ids for Cloud, which is explicit and unambigsuous. Among siblings like add_customers_to_service_desk and remove_organization_from_service_desk, the purpose is uniquely identified.
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 guidance on when to use usernames vs account_ids based on deployment type (Server/DC vs Cloud). However, it does not explicitly state when to use this tool over similar removal tools like remove_organization_from_service_desk or remove_request_participants, nor does it mention prerequisites or permissions.
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 states a read operation ('Get') but does not disclose any other behavioral traits like authorization needs or side effects. Adequate for a simple retrieval.
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: a single sentence stating the purpose, followed by a structured Args list. Every sentence adds value, and the main action is front-loaded.
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?
With an output schema present, the description does not need to explain return values. It adequately describes the two parameters and their intended usage, making it complete for the tool's function.
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 only defines parameter types as strings. The description adds meaning by explaining issue_id_or_key as 'issue key (e.g. 'X000') or numeric issue ID' and comment_id as 'numeric comment ID.' This clarifies formats beyond 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 clearly states the tool's purpose: 'Get a single comment by its ID.' It specifies the resource (comment) and action (get), which distinguishes it from siblings like add_request_comment or list_request_comments.
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 indicates when to use the tool (to retrieve a specific comment by ID). It does not explicitly exclude other scenarios or compare to alternatives, but the context of sibling tools makes the usage clear.
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. The description mentions pagination via start and limit, indicating list behavior, but does not explicitly state that the tool is read-only or disclose any authentication or rate-limit considerations.
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, with a clear opening line stating the main function, followed by a brief supplementary explanation and then a structured parameter list. Every sentence adds value with no 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?
Given the low complexity (3 optional parameters) and the presence of an output schema, the description covers all necessary user-facing aspects. However, it omits mention of default sorting or ordering, which could be useful but is not critical.
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 carries the burden. It explains each parameter's purpose: service_desk_id as optional filter, start as pagination offset, and limit as max results with default. This adds 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 the tool lists organizations with optional scoping to a service desk. It effectively differentiates from siblings like create_organization and delete_organization by specifying the read/list action.
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 explains the optional service_desk_id parameter for scoping, giving context on when to use it. However, it does not specify when not to use this tool or mention alternatives like get_organization for a single entity.
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 cover behavioral traits. It states that the tool adds a comment (write operation) and explains the public visibility. However, it does not disclose any destructive effects, authorization requirements, or rate limits. The output schema exists but is not mentioned. The public parameter explanation adds some 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?
Highly concise and well-structured: one-sentence action, then parameter details in a clear list. No redundant or wasted words. Front-loaded with the main action, making it easy to parse quickly.
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 add operation with 3 parameters and existing output schema, the description is sufficiently complete. It explains all parameters and the key distinction of public visibility. It does not cover prerequisites or error handling, but that is acceptable given the tool's simplicity and the presence of an output 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%, so description must compensate. It does so thoroughly: explains issue_id_or_key with example 'X000', body as plain text or Jira wiki markup, and public as true/false with clear meaning. This adds significant meaning 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?
Description clearly states the action: 'Add a comment to a customer request.' It distinguishes from sibling tools like get_request_comment and list_request_comments by focusing on the add operation. The public parameter is explained, differentiating between customer-visible and internal notes.
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?
Provides clear guidance on when to use public=true vs false, which is key for this tool. Does not explicitly mention when not to use or alternatives, but the sibling list includes related tools, so context is implied. Could be more direct about avoiding use when wanting to retrieve comments.
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 full burden. It explains that the attachment can be public or internal and allows an optional comment, but does not disclose side effects, auth requirements, or constraints (e.g., file size limits, whether the request must be open). This is adequate for a simple mutation but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized, uses a clear docstring format with an Args section, and front-loads the purpose. Every sentence serves a purpose, with no redundancy or wasted words.
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 (not shown) and the description does not need to explain return values. It covers prerequisites (calling upload first), parameter details, and the optional comment. However, it omits constraints like file size limits or permissions. Given no annotations and 0% schema coverage, the description does a solid job, but some completeness is missing.
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 thoroughly explains each parameter: issue_id_or_key as key or numeric ID, temp_attachment_id as output of upload, public as visibility, and comment as optional text. This adds essential meaning beyond 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 clearly states that the tool attaches a previously uploaded temporary file to a customer request, specifies the prerequisite tool (upload_temporary_attachment), and distinguishes it from the sibling upload tool by mentioning the required context (issue and temp ID).
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 explicit instructions to call upload_temporary_attachment first and explains each parameter's role. However, it does not explicitly state when not to use this tool or offer alternatives, but the prerequisite guidance and parameter explanations give sufficient 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 provided; description lists parameters but lacks extra behavioral details like permissions, rate limits, or side effects. Adequate but minimal.
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?
Concise title sentence followed by bullet-like Args. Slightly verbose due to full param explanations, but front-loaded and clear.
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?
Covers purpose, all parameters with defaults, and uses output schema (not shown) for return values. Complete for a listing tool without needing sorting details.
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?
0% schema description coverage, but the description's Args section adds detailed meaning for all parameters (type, format, defaults, behavior), fully compensating.
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?
Specific verb 'list' and resource 'customers' with clear scope 'who have access to a service desk'. Distinguishes from sibling tools like add/remove customers.
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?
Provides context on optional filtering and pagination, but does not explicitly state when to use vs alternatives. Still clear from purpose and sibling names.
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 explains the tool's purpose and parameters but does not explicitly state that the operation is idempotent or read-only, which would be helpful context.
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 compact and well-structured, with a short introduction followed by a clear bullet list of arguments. Every sentence adds value, no 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?
Given that an output schema exists, the description does not need to detail return values. It covers purpose, parameters, pagination, and provides examples of queue content. Slightly lacking context on sorting or behavior when no queues exist, but overall 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?
Schema description coverage is 0%, but the description compensates fully by explaining each parameter: service_desk_id (numeric ID), include_count (toggle for counts), start (offset), limit (max results, default 50). This adds meaning beyond the schema's property 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 clearly states it lists agent queues defined in a service desk, provides examples like 'All open', and distinguishes from sibling tools that list other entities (e.g., list_service_desks, list_request_comments).
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 explains the use case: to triage requests via saved JQL filters. It implies when to use but does not explicitly state when not to use or provide alternative tools.
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?
It discloses the read-only nature, default values, pagination via start/limit, and boolean filters. No annotations exist, so the description carries the full burden, which it handles adequately.
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?
A single sentence for purpose plus a bullet-style argument list. Every sentence provides value; no 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?
Parameters are fully documented, pagination and filtering explained, and an output schema exists for return values, making this complete for a list tool.
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?
With 0% schema description coverage, the description adds full meaning for all 5 parameters, including format, defaults, and behavior, far exceeding schema-only info.
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 'list', the resource 'comments on a customer request', and the filtering capability by visibility, distinguishing it from sibling tools like get_request_comment or add_request_comment.
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 listing comments with filters but does not explicitly state when to use this tool versus alternatives like getting a single comment.
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 provided; description mentions mutation (perform transition) and optional comment. Lacks details on side effects, permissions, or reversibility, but provides basic behavioral context.
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?
Four sentences, front-loaded with purpose. Arguments listed clearly with concise explanations. No 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?
Given 3 parameters, no annotations, and presence of output schema, description covers parameter semantics, usage flow, and purpose. Could mention return behavior briefly, but output schema handles that.
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%, but description adds meaning: issue_id_or_key explained with example format, transition_id noted as numeric, comment optional. Compensates well for absence 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?
Description clearly states the tool performs a workflow transition on a customer request with examples (resolve, close). It differentiates from siblings by explicitly referencing the required precursor call to list_customer_transitions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to call list_customer_transitions first to discover transition IDs, providing clear when-to-use guidance. No alternative usage is 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?
No annotations are provided, so the description bears full responsibility. It accurately describes a read-only operation that returns version and runtime details. It could mention authentication requirements, but the description is adequate for a simple info 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 two sentences with no extraneous information. It is front-loaded with the core purpose and provides immediate value.
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 presence of an output schema, the description does not need to detail return values. It covers the essential use case: verifying connectivity and version. The tool is simple and well-defined.
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?
There are no parameters, so schema coverage is 100%. The description adds value by explaining what the output contains (version and runtime details), which is 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 clearly states it gets information about the Jira Service Management application, specifically version and runtime details. This distinguishes it from sibling tools that focus on specific entities like service desks, requests, or organizations.
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 explicitly states to use it for verifying connectivity and checking the JSM version. It does not mention when not to use it, but the context is clear given the sibling tools.
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?
No annotations exist, so description carries full burden. It explains the filtering logic (user is reporter or participant), which is sufficient for a simple list 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?
Two sentences, no wasted words. Front-loaded with main purpose, then scope and use case. Ideal conciseness.
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 zero parameters and simple purpose, description covers everything needed: what it lists and for whom. Output schema exists for return details, so 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?
No parameters exist, and schema coverage is 100%. Description does not need to add param details; baseline 4 applies.
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 lists customer requests for the current user, specifying the scope as reporter or participant. It distinguishes from sibling tools like 'get_customer_request' and 'list_customers'.
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?
Provides context with 'useful to see my open tickets at a glance,' indicating when to use. No explicit when-not or alternatives, but the helpful hint aids selection.
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?
No annotations provided, so description carries full burden. Discloses access scope ('accessible to current user', 'authenticated user') and return format. Does not detail rate limits or pagination, but tool is simple with no 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?
Three sentences, no wasted words. Front-loaded with main action, then return details, then usage guidance. Each sentence earns its place.
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?
For a zero-parameter listing tool with an output schema, the description fully covers purpose, return values, and usage context. No gaps.
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?
Tool has zero parameters, baseline score is 4. Description does not need to explain 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?
Clearly states it lists all service desks accessible to the current user, specifies return fields (IDs, project keys, names), and distinguishes from siblings like 'get_service_desk' by being a list operation. Suggests use as a starting point.
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?
Explicitly advises using this tool as a starting point before querying request types, queues, etc. Implies it's for discovery. Lacks explicit when-not-to-use, but context is clear given sibling 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?
No annotations are provided, so the description must disclose behavioral traits. It reveals that the tool returns fields, IDs, and valid values, but does not mention permissions, side effects, or result structure. 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: a single line stating purpose, followed by a usage instruction and parameter explanations. Every sentence adds value; no 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?
For a simple query tool with two parameters and an output schema (not shown), the description covers what the tool does, when to use it, and parameter format. It even hints at the output content. Complete for its 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?
Schema coverage is 0%, and the description adds crucial meaning: both parameters are explained with examples ('The numeric ID of the service desk (e.g. '1')' and similar for request_type_id). This goes beyond 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 clearly states the verb 'get' and the resource 'fields required to create a request of this type'. It distinguishes itself from the sibling tool 'create_customer_request' by explicitly instructing to call this tool before that one.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage guidance: 'Always call this before create_customer_request' and explains the purpose (to learn required fields, IDs, valid values). This clearly tells when to use the tool and hints at the workflow.
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?
No annotations are provided, so the description carries the burden. It correctly implies a read operation (list) and mentions no destructive side effects. For a simple listing tool, this is adequate 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?
Two sentences with no wasted words. The first sentence states the purpose, the second links to the sibling tool. Perfectly front-loaded.
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, the description covers purpose, usage, and relationship to perform_transition. The presence of an output schema (not shown) further reduces the need to describe return values.
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 has one parameter with no description. The description adds concrete value by explaining that issue_id_or_key can be an issue key like 'X000' or numeric ID, which is essential for correct invocation.
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 lists transitions for a customer request based on its current status, and specifies that the returned IDs are used with perform_transition. This verb-resource-scope formulation is precise and distinguishes it 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly tells the agent to use the returned transition IDs with perform_transition, indicating a follow-up action. While it doesn't state when not to use it, the context is clear and no direct alternatives exist among siblings.
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?
No annotations, but description implies read-only list operation. Provides parameter format. Lacks details on pagination but output schema handles return values.
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?
Very concise with essential info front-loaded. Each sentence is meaningful with no 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?
Simple tool with one param and output schema; description covers purpose and usage context completely.
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 has 0% description coverage; description adds value by explaining service_desk_id is numeric and giving example '1'.
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?
Clearly states it lists all request types for a service desk, with examples like 'Report a bug'. Distinguishes from sibling get_request_type which is for a single type.
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?
Explicitly says to use before creating a customer request. Could mention alternatives like get_request_type for known IDs, but context is clear.
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?
No annotations provided, so description carries full burden. It reveals important behavioral details: the attachment is temporary and must be permanently attached, and filename is an absolute path on the server. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short paragraphs, front-loaded with key purpose and then Args. Every sentence adds value without redundancy or 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?
Given simple tool with 2 parameters and no annotations, the description covers what, how, and follow-up actions adequately. Output schema exists but description doesn't need to detail returns. Complete for 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?
Schema coverage is 0%, but description adds full meaning: service_desk_id is the numeric ID (though schema says string), filename is absolute path on server. This compensates completely 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?
Clearly states it uploads a file as a temporary attachment, explicitly ties to attach_file_to_request for permanent attachment, and distinguishes from sibling tools by specifying the temporary nature and required follow-up step.
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?
Provides clear usage context: the returned ID must be passed to attach_file_to_request. However, it does not explicitly state when not to use or compare to alternatives like add_request_comment, but the sequence is well explained.
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:

[![jira-service-desk-mcp MCP server](https://glama.ai/mcp/servers/CzSadykov/jira-service-desk-mcp/badges/card.svg)](https://glama.ai/mcp/servers/CzSadykov/jira-service-desk-mcp)

Score Badge

Copy to your README.md:

[![jira-service-desk-mcp MCP server](https://glama.ai/mcp/servers/CzSadykov/jira-service-desk-mcp/badges/score.svg)](https://glama.ai/mcp/servers/CzSadykov/jira-service-desk-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/CzSadykov/jira-service-desk-mcp'

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