mcp-atlassian

Server Quality Checklist

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

Latest release: v0.7.0
Disambiguation4/5
Most tools have distinct resource+action targets, but a few overlapping ones like jira_download_attachments vs jira_save_attachment_to_disk could cause confusion. Search/issue-listing tools (jira_search, jira_get_project_issues, jira_get_board_issues) also share similar behavior but differ in scope.
Naming Consistency4/5
All tools follow a product-prefix (jira_, confluence_, bitbucket_) with verb_noun structure, which is consistent. However, there are deviations like 'jira_jira_upload_attachment' (duplicated prefix), 'bitbucket_pull_request_activities' (missing verb), and mixed verb choices (get vs list) that prevent a perfect score.
Tool Count2/5
With 71 tools, the server is extremely large, exceeding even the 25+ threshold. While it covers three separate products (Jira, Confluence, Bitbucket), the sheer number makes it heavy and harder to navigate, and many tools are narrowly scoped.
Completeness4/5
Core workflows for Jira (issues, sprints, projects, attachments), Confluence (pages, comments, labels), and Bitbucket (repos, PRs, commits, file access) are well-covered. Obvious gaps like merging PRs, deleting branches/comments, or updating PRs are missing but can be worked around via other means.
Average 3.7/5 across 71 of 71 tools scored. Lowest: 2.3/5.
See the Tool Scores section below for per-tool breakdowns.
- 3 of 7 community issues answered or closed in the last 6 months
- 15 commits in the last 12 weeks
- Last stable release on August 13, 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 are provided, so the description must fully disclose behavior. It mentions a return value of 'JSON string containing commit history' but this contradicts the tool name's implication of getting changes. It does not indicate whether the operation is read-only, idempotent, or has side effects, nor does it specify any rate limits or authentication nuances.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is reasonably concise but includes an Args list that repeats the schema, making it slightly redundant. The structure is clear, but the first sentence is misleading given the tool name and sibling tools.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema (mentioned in context), the description's ambiguity about whether it returns commit history or changes for a specific commit undermines completeness. It fails to clarify the tool's exact behavior, which is critical for correct use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description does not need to add much. The Args list restates the schema parameters without adding new context (e.g., format or semantics of the returned JSON). Thus it adds marginal value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Get commit history for a repository branch' but the tool name is 'get_commit_changes', which typically refers to the diff of a specific commit. The parameters include commit_id and hash_newest, which suggest retrieving changes for a specific commit, not a branch history. This inconsistency with the sibling tool 'bitbucket_get_commits' (likely for history) further blurs the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives. The sibling tool 'bitbucket_get_commits' likely serves a similar purpose, but the description does not explain the difference or when to prefer one over the other.
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 disclose behavioral traits. It mentions returning a JSON string and raising ValueError, but fails to describe pagination, authorization requirements, or what types of activities are included. The mention of 'comments' in the parameter description is misleading.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short but contains an inaccuracy: the Returns section says 'list of pull requests' instead of 'list of activities.' This undermines trust. While concise, every sentence should be accurate.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description misstates the return value as 'pull requests' instead of activities, creating confusion. It also omits details about the scope of 'activities' (e.g., comments, status changes, approvals).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so the baseline is 3. The description repeats parameter names and adds context for workspace, but the schema already provides that context. No new semantic information is added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Get all activities on a pull request,' which identifies the action and resource. However, the parameter description for pull_request_id says 'to get comments for,' conflating activities with comments, creating ambiguity about the exact purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like bitbucket_get_pull_request or bitbucket_add_pull_request_comment. The description does not specify scenarios or exclusions.
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 all behavioral traits. It mentions raising ValueError for read-only mode or client unavailability, but does not detail possible side effects (e.g., closing a sprint changes state, impacts on issues), permissions required, or whether the operation is reversible. 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured as a Python docstring with Args, Returns, Raises sections, which is organized. However, it is somewhat verbose, repeating parameter information already in the schema. The purpose statement is front-loaded, but the rest could be more concise given schema coverage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a mutation tool with no annotations and an existing output schema (context signals indicate has_output_schema=true). The description does not explain what happens on success/failure beyond returning a JSON string, lacks information about idempotency, partial updates, or relationship to other sprint operations. The Raises section helps but is not enough for a complete picture.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents all 6 parameters with descriptions (100% coverage). The description merely lists the parameters without adding extra semantic detail (e.g., date format, valid state values beyond the enum hint, or constraints). Therefore, the description adds minimal value over the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update jira sprint', which is a specific verb and resource. It distinguishes the tool from siblings like jira_create_sprint, but does not explicitly contrast with other update tools, though the resource 'sprint' is distinct among siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives (e.g., jira_create_sprint for creating, or other update tools). The description does not mention prerequisites, typical use cases, or when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It only states the action and error conditions (ValueError for missing client). It omits behavioral details such as permission requirements, whether the comment is appended or replaces, side effects, rate limits, or state changes – essential for safe agent invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description contains useful sections (Args, Returns, Raises) but is somewhat redundant – the Args block largely duplicates the schema descriptions. The Raises section is helpful but could be more succinct. Overall, it wastes space on 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?
The description covers the basic action, parameters, return value, and error for a simple tool. However, it lacks context about the tool's position among siblings and does not explain the 'blocker' specificity. Given the presence of a detailed output schema (not shown here), the return description is sufficient, but behavioral gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description's 'Args' section repeats parameter names and types but adds negligible new meaning beyond the schema (e.g., 'comment: Comment text' is identical to schema). It does add default for severity, but that is already in schema. No extra syntax, format, or constraint details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Add a comment to a pull request' with a verb and resource. However, it does not differentiate from the sibling tool 'bitbucket_add_pull_request_comment' – the 'blocker' aspect is only in the name, not in the description, which limits clarity for distinguishing use cases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'bitbucket_add_pull_request_comment' or 'bitbucket_add_pull_request_inline_comment'. There is no mention of prerequisites, context, or exclusions, leaving the agent without decision 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?
Without annotations, the description carries full burden. It discloses that it raises ValueError if client is not configured, but does not mention other potential failures (e.g., missing branches, duplicate PRs). It also does not state the effect (creation/mutation) explicitly or any 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 concise with a clear list of arguments. The structure is front-loaded with the purpose, followed by parameter list, return type, and errors. However, the 'Args' section could be more compact.
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 schema coverage and presence of output schema (not shown), the description provides basic completeness. However, it lacks usage guidelines and behavioral context, which are important for a creation tool.
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 100%, so baseline is 3. The description repeats the parameter names and types but adds no additional meaning beyond the schema. For example, 'source_branch: Source branch name' is identical to the schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Create a new pull request.' It lists the required parameters and resource. While it doesn't explicitly differentiate from sibling tools, the verb 'create' and the specific parameters distinguish it from other PR-related tools like bitbucket_add_pull_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 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, such as bitbucket_list_pull_requests or bitbucket_get_pull_request. It does not mention prerequisites like the existence of branches or repository, nor does it specify situations where creation would fail.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses that the return is a JSON string with pagination info, which is useful. However, it does not cover auth requirements, rate limits, or the precise scope of 'all issues' (e.g., whether archived issues are included). The read-only nature is implied by 'get' but not explicitly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description starts with a clear one-sentence purpose, but then repeats schema information in an Args block and even includes a 'ctx' parameter that is not present in the input schema, which could confuse an agent. The Returns line is redundant given the output schema exists. It is not as concise as it could be.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple paginated list tool, the description covers the essential purpose and parameters, and the output schema handles return structure. However, it does not clarify how this tool relates to jira_search or jira_get_board_issues, nor whether the results are limited to certain issue types. This leaves some contextual 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?
Schema description coverage is 100%, so the schema already documents project_key, limit, and start_at with their constraints. The description restates these parameter names and basic purpose without adding new meaning, warranting the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets all issues for a specific Jira project, using a specific verb and resource. However, it does not distinguish this tool from siblings like jira_search or jira_get_board_issues, so it misses the top score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The description implies project-scoped retrieval but does not mention exclusions, prerequisites, or when to prefer another tool such as jira_search.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does mention that the tool returns a JSON string with created comment details and raises ValueError if the client is not configured, which adds useful context. However, it does not disclose permission requirements, whether the comment is appended as a general comment rather than inline, or any other 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 concise and well-structured with a clear one-line summary followed by Args, Returns, and Raises sections. It avoids unnecessary fluff, though the Args list is redundant with the schema, keeping it from being maximally efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The input schema fully covers all four parameters and the description mentions return and error behavior, so basic usage is sufficiently specified. However, the lack of usage guidance, alternative differentiation, and permission context leaves gaps for a complete picture, especially given that no annotations are present to fill in safety or auth details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% parameter description coverage, and the Args section in the description merely repeats the same names and one-line descriptions without adding extra meaning. Since the schema already documents all parameters clearly, the description provides no additional semantic value.
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 'Add a comment to a pull request,' which is a specific verb and resource. However, it does not explicitly differentiate from sibling tools like bitbucket_add_pull_request_blocker_comment or bitbucket_add_pull_request_inline_comment, so it misses the full distinction expected for a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus the blocker or inline comment variants, nor any mention of prerequisites, permissions, or context. The description only states what the tool does, offering no decision-support for an AI agent choosing among similar 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?
Without annotations, the description carries the full burden but only mentions return type and a ValueError for client configuration. It does not disclose other behavioral traits such as permissions, error handling for non-existent repos, 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is relatively concise, but includes boilerplate Args/Returns/Raises sections that largely duplicate schema info. It is front-loaded with the core purpose, which is good.
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 need for return value explanation is reduced. However, the description lacks details on failure modes (e.g., not found) and does not mention the context of workspace/project key differences, leaving some gaps for a read operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description repeats parameter names but adds no additional meaning beyond what is already in the schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'detailed information about a specific repository', which is distinct from sibling tools that list repositories or get pull requests.
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 like bitbucket_list_repositories or bitbucket_get_pull_request. There is no when-not-to-use or contextual advice.
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 does convey that the tool returns a JSON string of comment objects, but omits any details about error handling, pagination, sorting, permissions, or behavior when the page has no comments. Basic read-only intent is inferable from 'Get', but significant behavioral context is 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 extremely concise, front-loaded with the core purpose, and structured with Args and Returns sections. Every sentence is necessary and adds value; there is no redundant or tangential content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter read tool with an existing output schema, the description covers the essentials: it specifies the input (page_id) and that the return is a JSON string of comments. The output schema supplements return structure details, so the description need not enumerate them. Minor gaps exist around pagination and error cases, but overall it is adequate for the tool's low complexity.
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 already provides 100% coverage for the single parameter page_id, including a detailed description with an example URL. The description adds only a terse 'Confluence page ID,' which adds no new meaning beyond the schema. This aligns with the baseline of 3 when schema coverage is high.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb and resource: 'Get comments for a specific Confluence page.' It is distinct from sibling tools like confluence_get_page or confluence_add_comment. However, it does not explicitly differentiate itself from other comment-related tools or mention scope limitations (e.g., only retrieves top-level comments, not inline).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites (e.g., page existence), exclusions, or comparison to other confluence_get_* tools. The only implied usage is that a page_id is needed, but the description stops short of advising when this tool is the right choice.
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 it returns a JSON string, but does not mention that it is a read-only operation, potential authentication requirements, or any side effects. For a 'get' tool, the lack of explicit read-only indication reduces transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise, with two main sentences and separate lines for args and returns. It is front-loaded with the core purpose. No unnecessary words, but the format includes redundant information (e.g., 'args' and 'returns' are already implied by schema and output schema). Still, it is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (single parameter, output schema exists), the description provides the essential information. However, it lacks examples, notes on permissions, or information about pagination or worklog limits. It is adequate but not fully complete for all scenarios.
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 100%, and the parameter description in the schema is clear. The description's mention of 'issue_key: Jira issue key' adds no new information beyond the schema. Baseline 3 is appropriate as the schema already documents the parameter adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Get worklog entries for a Jira issue', which is a specific verb+resource combination. It clearly distinguishes from sibling tools like jira_add_worklog by focusing on retrieval. The inclusion of 'for a Jira issue' adds context beyond the tool name, avoiding tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, such as jira_add_worklog. There is no mention of prerequisites, limitations, or scenarios where another tool would be more appropriate. The description simply states what it does without usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the burden of behavioral disclosure. It adds value by mentioning ValueError when in read-only mode or if the Jira client is unavailable, and states the return format. However, it does not discuss permission requirements, reversibility, or side effects beyond mutation, leaving the behavioral profile only partially 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?
The description is well-structured with Args, Returns, and Raises sections, and is reasonably concise. The Args section duplicates schema information somewhat but does not hurt readability. No filler or wasted sentences, though it could be tightened by removing redundant parameter listings.
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 and 100% schema coverage, which reduces the need for explaining return values. The description includes error conditions and return format, making it functionally complete. However, it lacks guidance on when to use this general update tool versus specialized siblings like jira_transition_issue and jira_link_to_epic, so contextual completeness is only adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has 100% coverage with detailed descriptions for each parameter (e.g., assignee format, attachment examples). The description merely lists parameter names without adding new semantic meaning, so the schema does the heavy lifting and the description adds no extra value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates an existing Jira issue with a specific verb and resource, and lists example update types like changing status and adding Epic links. It distinguishes from create/delete/get, but does not explicitly differentiate from overlapping siblings like jira_transition_issue or jira_link_to_epic.
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 says what the tool does but provides no explicit guidance on when to use it versus alternatives such as jira_transition_issue or jira_link_to_epic. There are no exclusions, prerequisites, or preferred use cases, so an agent gets no selection help beyond the general 'update' scope.
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 fully disclose behavioral traits. It mentions that the tool updates a page and raises a ValueError if the client is misconfigured, but it does not disclose whether the operation is destructive (e.g., overwriting content), what permissions are required, or if there are rate limits. The description lacks important behavioral context for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured as a Python docstring, which is clear and front-loaded with the main action. However, it is somewhat verbose with repeated parameter details. A more concise summary would improve efficiency for AI agents, but the current structure is still effective.
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 complexity of 8 parameters (3 required) and the presence of an output schema, the description covers the input clearly, explains content format options, and notes conditional behavior (enable_heading_anchors only for markdown). It lacks details on output structure, but the output schema compensates. It is reasonably complete for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage with descriptions for all 8 parameters. The description essentially repeats the parameter list without adding significant new meaning. Baseline score of 3 is appropriate since the schema carries the semantic load.
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: 'Update an existing Confluence page.' It specifies the resource (Confluence page) and the action (update). The tool name itself is unambiguous, and sibling tools like 'confluence_create_page' and 'confluence_delete_page' provide clear differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool vs alternatives (e.g., when to create vs update). It does not list prerequisites, such as requiring the page to exist prior to update. The only context is the tool name and the sibling list, which does not compensate for the lack of explicit usage instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool modifies the issue (links appear in 'Links' section) and raises ValueError if in read-only mode or when Jira client is unavailable, providing useful behavioral context. However, it doesn't cover permissions, rate limits, or other side-effect details, leaving gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description starts with an effective one-sentence summary but then includes a full Args section that repeats information already present in the input schema, making it longer than necessary. The Raises and Returns sections are useful, but the Args block does not earn its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 6-parameter mutation tool with output schema, the description covers the operation, link placement, input expectations, return format, and error conditions. It lacks explicit differentiation from sibling link tools, but overall provides sufficient operational context. The output schema exists, so detailed return fields are not required.
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 100% with all six parameters described in the schema. The description's Args section largely duplicates the schema descriptions, adding marginal value (e.g., 'URL can be any web page or Confluence page') but not fundamentally explaining semantics beyond the schema. Baseline 3 is appropriate.
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 remote issue link (web link or Confluence link) for a Jira issue' with a specific verb and resource. It also explains that links appear in the issue's 'Links' section, but it does not explicitly contrast with sibling jira_create_issue_link for issue-to-issue links, so it lacks strong sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description communicates the use case ('allows you to add web links and Confluence links to Jira issues') and where the links appear, but it does not provide explicit when-to-use vs alternatives or exclusion criteria, such as pointing to jira_create_issue_link for linking issues together.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It does not disclose whether the operation is read-only, what error behavior occurs for invalid sprint IDs, or any rate limits or auth requirements. It simply describes the action and return format.
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 reasonably concise and structured with Args/Returns sections. However, it redundantly lists parameters already described in the schema, and includes a 'ctx' parameter not in the user-facing schema, adding minor noise.
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 and the input schema is complete, the description provides adequate context about the action and return format. It mentions pagination info in the return, which is useful, but lacks guidance on usage contexts, lowering completeness slightly.
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 covers all parameters with detailed descriptions, achieving 100% coverage. The description's Args section merely lists parameter names without adding semantic meaning beyond the schema, so it adds little value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb and resource ('Get jira issues from sprint'). This distinguishes it from siblings like jira_get_board_issues or jira_get_project_issues, which target different scopes.
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 is provided. The description only states what it does without mentioning prerequisites, exclusions, or comparing to similar tools like jira_get_board_issues or jira_search.
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 fully disclose behavior. It mentions that the tool raises ValueError in read-only mode or if the client is unavailable, but does not clarify whether the label is appended or replaced, or what happens if the label already exists.
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 but includes a docstring-like format for Args/Returns/Raises, which is slightly verbose. Nevertheless, it is well-structured and front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the basic action, parameters, return type, and exceptions, but lacks context on edge cases (e.g., duplicate labels) and authentication requirements. Given the tool's simplicity, it is minimally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already explains both parameters. The description does not add meaning beyond what is in the schema, resulting in a baseline score of 3.
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 label to an existing Confluence page,' which is a specific verb+resource combination. It is distinct from sibling tools like confluence_add_comment or confluence_update_page.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly guide when to use this tool versus alternatives (e.g., confluence_get_labels). While the purpose is clear, there is no when-to-use or when-not-to-use information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided. The description only states it returns a JSON string of transitions, but does not disclose behavioral traits such as idempotency, required permissions, or that it is a read-only operation. It carries the full burden of behavioral disclosure and falls short.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, with a clear purpose statement followed by Args and Returns sections. 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 tool is simple and has an output schema, the description is mostly complete. However, it could mention that transitions depend on the current status and is a read operation, which would make it more self-contained.
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 100% for the single parameter issue_key. The description repeats the parameter role but does not add significant meaning beyond what the schema provides (e.g., format example). Baseline 3 is appropriate.
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', the resource 'available status transitions', and the target 'Jira issue'. It effectively distinguishes from sibling tool jira_transition_issue which is for performing transitions.
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 any guidance on when to use this tool versus alternatives. It does not mention that it should be used before jira_transition_issue to see valid transitions, nor does it indicate when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the tool creates a sprint, returns a JSON string, and raises ValueError for read-only or unavailable client. However, it does not discuss permissions, duplicate checking, or side effects beyond creation.
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 follows a clean docstring format with a concise first line. The Args and Returns sections are useful, though some redundancy with the schema exists. Overall efficient.
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 (not shown) and full parameter coverage, the description covers the core purpose, exceptions, and return type. It is mostly sufficient but could include more about the created sprint's properties.
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 100%, so each parameter is already described in the schema. The description's Args section merely restates parameter names and types, adding minimal value 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 'Create Jira sprint for a board,' using a specific verb and resource. It distinguishes from sibling tools like jira_get_sprints_from_board or jira_update_sprint by focusing on creation.
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 lacks explicit guidance on when to use this tool versus alternatives. It mentions read-only mode errors but does not provide context for choosing this tool over jira_update_sprint or other board-related 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 bears full responsibility for behavioral traits. It lacks mention of authentication, rate limits, pagination, or what happens if the project key is invalid. The short description does not disclose these.
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?
Single sentence front-loaded with verb and resource. No wasted words; 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?
For a simple getter with output schema, the description is minimally adequate. However, it does not clarify if 'fix versions' includes only unreleased or all, or any ordering. Slightly incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (project_key is well-described). The description adds minimal value beyond the schema by stating 'for a specific Jira project', but this is redundant.
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 'all fix versions' for a specific Jira project. It distinguishes from sibling tools like jira_get_project_issues and jira_get_all_projects by specifying 'fix versions'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (when you need fix versions for a project) but provides no explicit guidance on when not to use it or alternatives. Given siblings like jira_create_version, some differentiation would help.
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?
There are no annotations, so the description must carry the transparency burden. It discloses the return format (JSON string) and a specific error condition (ValueError when client is not configured). However, it does not address potential domain errors (e.g., repository not found) or mention that this is a read-only operation (though it is implied by 'Get'). The disclosure is minimal but not entirely absent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a one-sentence purpose, followed by structured Args/Returns/Raises sections. Every line adds value—no filler. It is appropriately sized for a simple getter tool and follows a clean, readable format.
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 tool with fully documented schema parameters and an existing output schema, the description covers the essential aspects: purpose, inputs, return type, and an error condition. The main gap is lacking usage guidance, but given low complexity, the description is otherwise complete enough for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters fully described in the input schema (workspace and repository, including Cloud vs Server/DC distinction). The description's Args section simply repeats the schema text without adding additional meaning. Baseline 3 applies given the high 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 is specific and clear: "Get the default branch for a repository." It uses a strong verb and identifies the exact resource. This distinguishes it from sibling tools like bitbucket_list_branches (which lists all branches) and bitbucket_get_repository_info (which retrieves general repository details).
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, no prerequisites, and no exclusions. It simply states the operation. There is no mention of scenarios where this would be preferred over other Bitbucket tools, leaving the agent to infer usage solely from the tool name.
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 it returns a diff, notes platform differences, and raises ValueError if client is not configured. It does not explicitly mention that it is a read-only operation or discuss rate limits, but the behavior is reasonably clear for a read 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 well-structured: a clear first sentence, followed by explanation of output, platform differences, parameters, returns, and raises. No superfluous information; each sentence serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (not shown), the description reasonably covers the return format and platform differences. It lacks details on handling large diffs or pagination, but overall is sufficient for a diff retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for all three parameters. The description repeats the parameter names without adding additional meaning or constraints beyond what the schema already provides, so it does not add value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the full code diff for a pull request, using specific verbs and resource. However, it does not explicitly distinguish from sibling tools like `bitbucket_get_pull_request` or `bitbucket_get_commit_changes`, which could also be related to code review.
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 reviewing code changes in a PR but does not provide explicit guidance on when to use this tool versus alternatives (e.g., when to use `bitbucket_get_pull_request` for metadata only). No exclusion criteria are 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 provided, so description must carry the burden. It states it lists repositories (read-only) and raises ValueError if client not configured. However, it lacks details on pagination, rate limits, or what 'list of repositories with details' entails, which is essential for a 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?
The description is extremely concise and well-structured with Args, Returns, Raises sections. Every sentence adds value, no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one optional parameter and an output schema (not shown), the description covers the essential purpose and basic behavior. Could be improved with pagination info or result ordering, but overall adequate.
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 100%, and the parameter description already covers workspace being a workspace name or project key. The description adds no new semantics beyond the schema, so baseline 3 is appropriate.
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 repositories in a workspace/project or all accessible ones. It uses a specific verb and resource, and distinguishes from siblings like bitbucket_get_repository_info (single repo) and other list tools.
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., get_repository_info for details, list_branches for branches). It does not specify when not to use it or provide context for selection.
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 carries full burden. It mentions deletion and possible ValueError, but does not disclose irreversibility or permission requirements. Adequate but not detailed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise with no wasted words. Uses clear structured format for args, returns, and raises.
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 deletion tool with no output schema, it provides expected information: return format and exception. Could detail success/failure response more, but sufficient for simple operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description covers page_id fully; description adds no extra meaning. Baseline 3 due to high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Delete an existing Confluence page.' It uses a specific verb and resource, and distinguishes from sibling tools like create, update, get.
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. Lacks prerequisites, conditions, or scenarios for deletion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does disclose the CQL query format, includes quoting examples, and specifies a JSON return value. However, it does not mention read-only status, authentication requirements, potential errors, or pagination behavior beyond the limit parameter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and includes a clear Returns line. However, the Args section duplicates the parameter information already present in the schema, adding minor redundancy. It remains appropriately sized and 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?
For a relatively simple search tool, the description covers purpose, parameters, and return format. However, it lacks usage guidance and deeper behavioral context, such as read-only status or how it handles invalid CQL. The presence of an output schema reduces the need for return structure details, but the description could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides detailed descriptions for both parameters (100% coverage), so the description's Args block adds little new meaning beyond restating the schema. The schema itself includes examples and quoting guidance, making the description redundant in this dimension.
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 'Search Confluence users using CQL' which identifies a specific verb+resource and distinguishes it from sibling content search tools like confluence_search. The Returns line further clarifies that it produces a list of user search result objects, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given on when to use this tool versus alternatives like confluence_search or jira_get_user_profile. The usage context is implied by the tool name and description, but there are no named alternatives or exclusion criteria, leaving the agent to infer the appropriate scenario.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It mentions error conditions (read-only, client unavailable) but does not disclose side effects like workflow triggers, validation requirements, or whether the operation is idempotent. The Raises section adds some transparency 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with Args, Returns, Raises sections but repeats parameter descriptions already present in the schema. It could be more concise by reducing duplication, though it remains clear and organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description is complete for a creation tool: it covers all parameters, usage nuances (e.g., 'always ask the user' for project key), and error conditions. It does not need to explain return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. The description adds significant value beyond schema: clarifies assignee format, warns not to assume project_key, provides detailed examples for additional_fields (priority, labels, parent), and explains subtask requirements. This goes well above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new Jira issue' with specific mention of optional Epic link or parent for subtasks, using a specific verb and resource. It differentiates from siblings like batch_create_issues or create_issue_link by focusing on single issue creation with linking capabilities.
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 lacks explicit guidance on when to use this tool versus alternatives such as jira_batch_create_issues, jira_create_issue_link, or jira_update_issue. It does not mention exclusions or preferred scenarios, leaving the agent to infer from 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?
The description mentions that ValueError is raised if in read-only mode or if the Jira client is unavailable, which is useful. However, it does not disclose that deletion is permanent or irreversible, nor does it mention any side effects on linked issues or attachments. With no annotations provided, the description carries the burden but only partially covers it.
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, including Args, Returns, and Raises sections. It conveys the essential information without any fluff, making it easy to scan.
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 delete tool with one parameter and an output schema, the description covers the main action, arguments, return value, and a key exception. However, it could be enhanced by noting irreversibility and potential impacts on related data, but it is already reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully documents issue_key with an example, and the description merely repeats the parameter name without adding additional semantics. Since schema coverage is 100%, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete an existing Jira issue' with a specific verb and resource, which distinguishes it from sibling tools like create, update, or transition. The word 'existing' adds necessary scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives, no exclusions, or prerequisites beyond the implicit read-only mode check. It simply states what it does, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits beyond what is in the input schema. It does not mention rate limits, authentication requirements, or side effects. The return format (JSON string of sprint objects) is stated, but additional context is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with no wasted words. It is structured with a clear header, parameter list, and return type. Information is front-loaded, making it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and full schema description coverage, the description adequately covers parameters and return type. It lacks details about pagination behavior beyond start_at and limit but is sufficient for a simple retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining that setting 'state' to None returns all sprints, and it lists the parameter descriptions clearly. However, it does not significantly augment the schema's own 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 verb 'Get' and the resource 'jira sprints from board'. It distinguishes itself from sibling tools like jira_get_agile_boards and jira_get_board_issues by focusing specifically on sprints. The parameter details further clarify the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving sprints from a board but does not explicitly state when to use this tool versus alternatives (e.g., jira_get_sprint_issues for issues within a sprint). No exclusion criteria are provided.
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 carry the behavioral transparency burden. It does disclose the return format ('JSON string representing the search results including pagination info'), but it does not explicitly state read-only behavior, authentication needs, or potential side effects. 'Search' implies read-only, but a more explicit statement would improve the score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is mostly concise (one sentence plus Args/Returns sections), but the Args list is redundant with the schema's property descriptions. It is structured, but the redundant parameter enumeration keeps it from being highly concise.
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 rich schema (100% coverage) and existence of an output schema, the description provides adequate high-level context: purpose, key args, and return envelope. It lacks explicit guidance on when to use related project-specific or issue-specific search tools, but this is a minor gap for a well-documented search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema provides detailed parameter descriptions with examples. The description's Args list only reiterates parameter names without adding meaning, so it meets the baseline but does not enrich 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 'Search Jira issues using JQL', giving a specific verb and resource. This distinguishes it from sibling tools like jira_get_issue (specific issue lookup) and jira_search_fields (field metadata search).
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 use case is implied by the JQL mention: use this when you need flexible JQL-based issue search. However, there is no explicit guidance on when to choose this over alternatives like jira_get_project_issues or jira_get_issue, nor any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action (create), the default source branch, and raises ValueError if the client is not configured. However, it does not disclose whether branch creation is idempotent, what happens if the branch exists, or permission requirements. Basic behaviors are covered, but significant gaps remain.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections for Args, Returns, and Raises. It is concise at 9 lines with no unnecessary information. However, the Returns section could be more succinct (e.g., 'Returns JSON string of branch details') and might be slightly redundant with the output schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the description covers the essential aspects: parameters, return type, and error condition. An output schema exists, so return details are not needed in the description. The only missing element is potential failure modes (e.g., branch already exists). Overall, it is largely complete for a create tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage, describing all four parameters. The tool description repeats parameter names and the default for source_branch but adds no meaningful context beyond what the schema provides. For example, it does not explain that 'workspace' can be a project key for Server/DC (already in schema). Baseline 3 is appropriate as the description adds minimal value over schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new branch in a repository.' It uses a specific verb ('create') and resource ('branch'), which distinguishes it from sibling tools like bitbucket_list_branches (listing) and bitbucket_create_pull_request (creating PRs). The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/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. While the purpose is clear, there is no mention of when not to use it (e.g., if a branch already exists) or which sibling tool to use for related actions (e.g., bitbucket_get_default_branch for checking the default branch). The usage context is implied but not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses return format and a ValueError on missing client, but does not mention side effects, conflict behavior, or permission requirements beyond the basic creation. This is moderate transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Structured with Args/Returns/Raises sections, concise, and free of fluff. The inclusion of ctx is slightly redundant but not harmful.
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 create tool, the description covers purpose, parameters, returns, and a key error condition, supplemented by a rich output schema. It lacks deeper context like idempotency or permission requirements, but these are not critical for an MCP tool.
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 100% for the four parameters, so the baseline is 3. The description duplicates schema descriptions and adds only a non-schema ctx argument, which adds marginal value 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 states 'Create a new repository in a workspace/project' with a specific verb and resource, clearly distinguishing it from sibling tools like bitbucket_get_repository_info or bitbucket_list_repositories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by defining arguments (workspace, repo_slug) but does not explicitly state when to choose this over other Bitbucket tools or mention exclusions/alternatives. It provides some context about Cloud vs Server/DC naming but no direct comparative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It does add a 'Returns' clause indicating a JSON string and mentions a ValueError condition when the client is misconfigured. However, it omits details about pagination, commit ordering, or behavior when the branch/workspace doesn't exist, so the added context is useful but incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with a clear one-sentence purpose, followed by an Args list and Returns/Raises sections. It is front-loaded and easy to scan, though it repeats schema information verbatim, creating minor redundancy that prevents a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and full parameter documentation, the description adequately covers main usage and error conditions. The Returns and Raises sections add context not in structured fields. However, it lacks guidance on pagination/continuation for large histories, which is a minor gap for a list-type tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description's Args section mostly mirrors the schema descriptions (e.g., 'Workspace name or project key') without adding deeper meaning or clarifying edge cases. It provides no extra value beyond what the schema already documents.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get commit history for a repository branch,' which is a specific verb-resource pair that clearly states the tool's function. This distinguishes it from sibling tools like bitbucket_get_pull_request_commits (commits for a PR) and bitbucket_get_commit_changes (changes for a commit), making its niche evident.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by specifying 'for a repository branch,' but it does not explicitly state when to prefer this tool over related alternatives or provide exclusion criteria. No alternative tools are mentioned, leaving the agent to infer selection based on the resource type alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It states return type (JSON string) and raises ValueError, but does not explain pagination semantics, branch_filter pattern syntax, or whether 'base' limits to branches derived from that base. Some behavior is still opaque.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficient: a one-sentence summary followed by structured Args/Returns/Raises blocks. No fluff, but the Args block duplicates schema information which slightly reduces 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?
The tool has an output schema and a clear description of returns/errors, so it is reasonably complete for a list operation. However, it doesn't address potential pitfalls like large limits or how branch_filter matches (exact vs substring), 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 input schema covers all parameters with descriptions, and the description essentially repeats them. It adds no extra meaning beyond the schema, so baseline of 3 applies. The description does not clarify default behavior when base or branch_filter are omitted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'List all branches in a repository' with a specific verb and resource, clearly distinguishing from sibling Bitbucket tools such as list_pull_requests or get_commits.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the name and description ('when you need to list branches'), but there is no explicit guidance on when to choose this over alternatives or any exclusions. No sibling comparisons are made.
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 adds value by specifying the return format ('JSON string containing directory contents') and the error condition ('ValueError: If the Bitbucket client is not configured or available'). However, it does not disclose potential side effects, authentication requirements, or behavior for non-existent paths beyond the schema. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized with a one-sentence purpose followed by structured Args, Returns, and Raises sections. It is not overly long, but the Args section duplicates the schema. Overall, it is well-structured and front-loaded, earning a 4.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward listing tool, the description covers purpose, arguments, return format, and error conditions. It lacks contextual notes about sorting, hidden files, or path error handling, and could benefit from an explicit mention that it differs from get_file_content. Given the simplicity of the tool and the presence of schema descriptions, it is reasonably complete; score 4.
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 100%, with all four parameters already described in the schema. The description's Args section largely mirrors the schema, adding the 'empty for root' note for path and the 'default: main' for branch, both already present in schema defaults. No new semantic information is added, so baseline 3 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 opens with a specific verb+resource: 'List the contents of a directory in a repository.' This clearly distinguishes from sibling tools like bitbucket_get_file_content (which fetches a file) and bitbucket_list_repositories (which lists repositories). The scope is clear (directory contents).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool versus alternatives like get_file_content or list_branches. The usage is implied by the name and description. No exclusions or alternative recommendations are provided. This earns a 'minimal viable' score of 3.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears the full burden of behavioral disclosure. It discloses expected failure modes ('Raises ValueError: If in read-only mode or Jira client unavailable') and the return type ('JSON string representing the added worklog object'). It also documents optional parameter behaviors (e.g., 'started' defaults to current time) in the schema, but the description reinforces these. This goes beyond a typical one-line mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, starting with a one-sentence purpose followed by a structured Args/Returns/Raises format. It is front-loaded and avoids verbosity. The Args section is somewhat redundant with the schema, but the overall format is clean and scannable, 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.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essentials: the action, all parameters (via schema), the return value (JSON string), and error conditions (read-only mode, client unavailable). Given the tool's moderate complexity and the rich schema, this is sufficiently complete for an agent to invoke it correctly without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage with detailed parameter descriptions, including examples for time_spent and started and default behaviors. The description's Args section merely echoes parameter names and short descriptions without adding new meaning. Baseline of 3 is appropriate because the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Add a worklog entry to a Jira issue,' which clearly states the action (add) and resource (worklog on a Jira issue). This is distinct from sibling tools like jira_get_worklog (retrieve) and jira_add_comment (add a comment), making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention that this is for logging time on an issue or contrast it with jira_get_worklog for reading worklogs. The only context is the action itself, so the agent receives no explicit usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden of behavioral disclosure. It states that the tool takes a project key and a JSON array string of versions, and returns an array of results with success/error flags. However, it does not disclose whether failure of one version affects the others, whether the operation is atomic, or any side effects or rate considerations. For a batch mutation tool, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, structured with 'Args' and 'Returns' sections, and front-loads the core purpose in the first sentence. Every sentence provides necessary information without redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose, inputs, and return format, and the schema fully documents parameters while an output schema exists. However, it does not explain partial failure behavior, potential duplicates, or when this tool should be preferred over single-version creation. Given its moderate complexity, the description is adequate but leaves some behavioral 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?
Schema description coverage is 100%, and the schema already provides detailed descriptions for project_key and versions, including an example JSON array. The description adds only the 'ctx' parameter (a framework-injected context) and restates the purpose of the other parameters. This does not significantly enhance understanding beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Batch create multiple versions in a Jira project', which is a specific verb (batch create) plus a specific resource (versions in a Jira project). This clearly distinguishes it from sibling tools like 'jira_create_version' (single version) and 'jira_get_project_versions' (retrieval), so the purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Batch create multiple versions' implies this is the tool to use when creating more than one version at a time, which is a clear context. However, it does not explicitly state when not to use it or mention the alternative single-create tool (jira_create_version), so it lacks exclusions but still provides clear 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?
With no annotations, the description must carry the burden of behavioral disclosure. It states the return type ('JSON string representing a list of board objects') and mentions fuzzy search, which adds some context. However, it doesn't disclose potential side effects, authentication requirements, or how the fuzzy search behaves, leaving gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficient: a single introductory sentence followed by a parameter list. It's front-loaded with the core purpose. The Args block is somewhat redundant with the schema but is standard docstring format and not excessively verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the description covers the essential aspects: purpose, filters, and return value. The output schema handles the return structure, so the description doesn't need to explain it. The only missing piece is explicit usage guidance, but that's not critical for a straightforward read-only tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage with clear explanations for all five parameters. The description largely repeats the schema information without adding extra meaning beyond the 'fuzzy search' note already present in the schema. The description doesn't compensate for any schema gaps because there are none.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Get jira agile boards by name, project key, or type.' The verb 'Get' plus the specific resource 'jira agile boards' makes the purpose unmistakable. It also distinguishes itself from sibling tools like jira_get_board_issues or jira_get_sprints_from_board by focusing on board listing/filtering.
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 the tool via its filter parameters but provides no explicit when-to-use or when-not-to-use guidance. No alternatives are named. Since it's a straightforward listing tool with no closely competing sibling, the implicit context is acceptable, but it doesn't reach the level of explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full disclosure burden and does reasonably well: it notes fuzzy matching, the optional force-refresh behavior, and the JSON-string list return format. It implicitly reveals caching via the 'refresh' flag, though it does not explicitly state side-effect-free read-only behavior 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a one-sentence purpose and uses a clear Args/Returns structure. It is efficient, though the per-parameter lines largely duplicate the schema descriptions and add minor redundancy. Still, it is compact and easy to scan.
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 low-complexity search tool with full schema coverage and an output schema, the description is mostly complete: it states the purpose, refresh semantics, and return format. It could improve by clarifying that this is metadata-field discovery rather than issue search, but the core invocation is well-covered.
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 100%, so the baseline is 3. The description's parameter list mostly mirrors the schema descriptions and adds little beyond the 'ctx' context parameter and return type. The schema itself provides richer detail (e.g., empty keyword lists first limit fields) than the description does.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies a distinct resource ('Jira fields') and a specific search behavior ('by keyword with fuzzy match'), differentiating it from siblings such as jira_search (which searches issues). The return type ('matching field definitions') further disambiguates it from generic search tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, such as jira_search or jira_get_project_issues. The description only states the operation, with no exclusions, prerequisites, or conditions for choosing this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses that the tool returns a JSON string with content and metadata, and raises ValueError if client is unavailable. However, it does not mention authentication requirements, rate limits, file size limits, or what happens with binary files. Adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with Args, Returns, Raises sections. Every sentence adds value and the format is highly readable for an AI agent. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description appropriately summarizes return as 'JSON string containing file content and metadata.' It covers the core functionality but could mention encoding handling or binary file limitations. Still fairly complete for a file retrieval 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 100%, so baseline is 3. The description adds value beyond the schema, e.g., workspace can be name or project key, branch defaults to 'main', and sample parameter is explained with the -1 meaning. This extra context improves usability.
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 the content of a specific file from a repository.' It uses a specific verb and resource, distinguishing it from siblings like bitbucket_list_directory which lists file names without content.
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 such as bitbucket_list_directory or bitbucket_get_commit_changes. The description implies use for reading file contents but does not compare or contrast with 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 carries the full burden. It states the tool retrieves information and raises an error if the client is not configured, but it does not explicitly declare read-only behavior or other side effects. The description is adequate but not exhaustive.
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 clear purpose sentence followed by a structured list of arguments, returns, and raises. Every line adds value, and there is no extraneous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool has an output schema (indicated by context signals), the description does not need to detail return values. The three required parameters are clearly documented. However, additional context about when to use this tool over sibling PR tools would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all parameters. The tool description repeats parameter names and types without adding additional meaning beyond what the schema already provides. Therefore, baseline score of 3 is appropriate.
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 detailed information about a specific pull request,' which is a specific verb-resource combination. It distinguishes itself from sibling tools like bitbucket_list_pull_requests and bitbucket_get_pull_request_diff.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a specific pull request ID is known, but it lacks explicit guidance on when to use this tool vs alternatives (e.g., get diff, list, activities). No exclusion criteria or alternative mentions are provided.
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 exist, so the description carries the full burden. It discloses the return type (JSON list of label objects) but omits any error conditions, rate limits, or permissions. For a simple read operation, this is minimally acceptable.
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 for purpose and a structured docstring for args/returns. No redundant words; every line adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one required parameter, no nested objects, and an output schema present), the description sufficiently covers what the tool does and returns. It is not deeply detailed but is complete for a straightforward read operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the schema already provides a detailed description of the 'page_id' parameter. The description adds no further semantic context, so baseline score of 3 is appropriate.
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 ('Get labels') and the resource ('for a specific Confluence page'). This distinguishes it from sibling tools like 'confluence_add_label' (adds labels) and 'confluence_get_page' (retrieves page 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 implies usage for retrieving labels but does not specify when to use this over alternatives (e.g., when you need labels vs. comments or page content). No exclusions or context are provided, leaving the agent to infer from the name.
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 alone must convey behavioral traits. It mentions the return type (JSON string) but does not disclose side effects, idempotency, error conditions, or rate limits. For a create operation, this is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections (Args, Returns) and front-loaded with the main purpose. It is somewhat verbose but still concise enough, with no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers basic usage but lacks context about what a 'fix version' means, constraints, or default behavior. Since an output schema exists (indicated), return values are documented, but overall completeness is average for a simple create 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 100%, so the schema already documents parameters. The description adds value by listing parameters in a clear Args section with natural language, including the return type. 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 tool creates a new fix version in a Jira project, specifying the action (create) and resource (fix version). It distinguishes from siblings like jira_get_project_versions (list) and jira_batch_create_versions (batch).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit when-to-use or when-not-to-use guidance. It lacks prerequisites (e.g., permissions) and does not mention alternatives. Usage is implied but not clarified.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses return format (JSON string), raises ValueError, and reveals a side effect via update_history parameter. It doesn't mention authentication or rate limits, but for a read operation this is substantial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The opening sentence is clear and front-loaded. However, the Args section repeats the input schema parameter descriptions with less detail, adding redundancy. Returns/Raises are useful. It is not excessively long but could be trimmed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is well-specified by the schema and output schema. The description adds the defining feature (Epic links), notes the update_history side effect, and provides error info. It is sufficiently complete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description's parameter explanations largely repeat or simplify the schema entries (e.g., fields, expand, comment_limit) without adding meaningful new information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' and resource 'specific Jira issue' and adds unique detail 'Epic links and relationship information' which distinguishes it from sibling tools like jira_search or jira_get_project_issues.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit when-to-use guidance or alternatives. Usage is implied by the tool name and summary, but it doesn't tell agents to prefer this over jira_search for single issue retrieval or when NOT to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states it returns a JSON string of link types, implying a read-only operation. However, without annotations, it does not disclose authorization requirements, rate limits, or potential 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?
The description is concise with only three sentences. However, the inclusion of 'Args: ctx' may be unnecessary since no parameters are defined in the schema, causing slight confusion.
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 simplicity of the tool (no parameters, output schema exists), the description adequately covers the tool's purpose and output format. No additional context is essential.
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 the input schema is fully covered. The description does not need to add parameter details, and the baseline for zero parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the action ('Get all') and the resource ('available issue link types'), which is a distinct operation among sibling Jira tools that focus on issues, projects, or sprints.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, such as other get_* tools. The description lacks context about typical use cases or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It mentions the return format ('JSON string representing a list of simplified Confluence page objects') but does not disclose internal behavior such as default search type, error handling, or rate limits. Some behavioral details exist in the schema (e.g., siteSearch fallback), but the description itself adds only minimal context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with a purpose statement, Args block, and Returns block. However, the Args list largely duplicates schema descriptions, so not every sentence earns its place. Still, it is front-loaded with the main purpose and avoids verbosity.
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 a rich parameter schema (100% coverage) and an output schema, so the description does not need to explain return values in depth. The overall definition, combining description and schema, provides sufficient context for a search tool with complex CQL support. Minor gaps remain around error handling, but the existing structure is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description's argument list repeats the schema's parameter descriptions verbatim or nearly so. The description adds no semantic value beyond the schema; the extensive CQL examples and spaces_filter behavior are already in the parameter 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 'Search Confluence content using simple terms or CQL', naming the specific verb (search), resource (Confluence content), and scope (simple terms or CQL). This distinguishes it from sibling tools like confluence_get_page (direct retrieval) and confluence_search_user (user search). The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for searching Confluence content, which is clear but does not explicitly state when to use it over alternatives like get_page or search_user. It provides no exclusions or alternative tool names, but the purpose and parameters give sufficient context for when to search versus direct lookup.
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, but the description compensates by detailing the return format ('JSON string indicating success or failure') and failure conditions ('ValueError: If required fields are missing, invalid input, in read-only mode, or Jira client unavailable'). It also describes optional comment and visibility parameters.
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 uses a structured docstring style with clear sections and remains succinct. The first sentence states the purpose, while the Args/Returns/Raises sections are compact and informative.
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 tool with 5 parameters and an output schema, the description covers the purpose, parameters, return value, and error conditions. It could include guidance on valid link_type values or behavior on duplicate links, but it is functionally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already documents each parameter with examples. The description adds a slight clarification by labeling inward as 'source' and outward as 'target', but otherwise repeats schema information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a link between two Jira issues' and the args specify issue keys, distinguishing it from remote issue links and epic links among siblings. The specific verb and resource make it unambiguous.
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 through its action sentence but does not explicitly state when to use it compared to jira_create_remote_issue_link or jira_link_to_epic. No exclusions or alternative recommendations are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for behavioral disclosure. It mentions pagination via 'start_at' and 'limit' and notes the return is a 'JSON string... including pagination info,' which adds some transparency. However, it does not discuss important traits like rate limits, authorization requirements, or the fact that 'all issues' is constrained by pagination defaults.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a clear one-sentence summary and then organized into Args and Returns sections, making it easy to scan. The Args section duplicates much of the schema information, which adds some redundancy, but the overall structure is efficient and serves as a useful quick reference.
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 a rich input schema, an output schema, and six parameters, and the description adequately covers the core use case, parameters, and return format. It explains pagination info and JQL filtering, which is sufficient for an agent to invoke it correctly. It could be enhanced with sibling differentiation, but such guidance is not essential for basic invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% parameter coverage with rich descriptions, so the baseline is 3. The description merely lists parameter names and short hints (e.g., 'Comma-separated fields to return') without adding significant meaning beyond the schema's detailed explanations and examples. It adds marginal value by grouping the parameters in a readable Args block.
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 primary function: 'Get all issues linked to a specific board filtered by JQL.' This specifies the verb, resource (board issues), and filtering mechanism, and it distinguishes the tool from siblings like jira_search, jira_get_project_issues, and jira_get_sprint_issues by emphasizing the board scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'linked to a specific board' provides clear context that this tool is intended for board-scoped queries, which differentiates it from issue, project, or sprint searches. However, it does not explicitly mention when not to use this tool or name alternative tools, stopping short of the 'when/when-not/alternatives' standard.
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 carries full burden. It discloses that the tool updates the issue and returns a JSON string, and raises ValueError in readonly/unavailable client. However, it does not detail side effects, permission requirements, or if the link is reversible.
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?
Description is very concise with clear sections (Args, Returns, Raises). Every line adds value, no unnecessary information.
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 (2 required params) and the presence of a return value description and error handling, the description covers all necessary aspects for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% description coverage for both parameters, so schema already documents meaning. Description adds no additional semantic value beyond the schema. Baseline 3 is appropriate.
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 'Link an existing issue to an epic' with specific verb and resource. Distinct from sibling 'jira_create_issue_link' which handles general link types, so purpose is well-defined and differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives. The description includes error raising for readonly mode, which implies usage constraints, but lacks explicit when-not-to-use or alternative recommendations.
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?
The description discloses that the tool modifies data (deletes a link) and raises errors for missing link_id, read-only mode, or client unavailability. This adds context beyond what annotations might provide (none provided).
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 each sentence providing necessary information. The Args/Returns format adds structure but could be slightly shorter.
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 description covers the action, parameter, return type, and error conditions. With an output schema present, this is sufficient for a simple delete-link tool.
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?
Parameter link_id has full schema coverage with description. The tool description repeats the same info and adds minimal extra meaning. Baseline 3 is appropriate.
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 a link between two Jira issues,' specifying the action and resource. It is distinct from sibling tools like jira_create_issue_link or jira_delete_issue.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives, but the purpose is obvious. Missing mention of prerequisites such as needing a valid link_id.
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 present, so the description carries the full burden. It discloses the return format (JSON string) and raises ValueError if the client is not configured, adding useful behavioral context. It also mentions the state filter, clarifying that only PRs matching the given state are returned. It does not cover pagination or ordering, but for a simple list tool this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with clear Args, Returns, and Raises sections. It is front-loaded with the primary purpose and each section adds necessary information. No fluff or redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with three parameters and an output schema (signaled by 'Has output schema: true'), the description covers the essentials: purpose, parameters, return format, and an error case. It does not mention pagination or result limits, but given the tool's simplicity and the presence of an output schema, this is sufficiently complete. A score of 4 reflects a thorough but not exhaustive description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes all three parameters with 100% coverage. The description repeats the parameter names and purposes but adds no new semantic detail beyond what the schema provides. Baseline 3 is appropriate since the schema does the heavy lifting.
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 starts with 'List pull requests for a repository', which clearly identifies the action (list) and resource (pull requests scoped to a repository). This distinguishes it from sibling tools like 'bitbucket_get_pull_request' (single PR) and 'bitbucket_create_pull_request' (create). The verb and resource are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context for when to use the tool (to list PRs, optionally filtered by state) but does not explicitly state when not to use it or name alternatives. The existence of sibling tools like get_pull_request implies the distinction, but no direct guidance is given. This is implied usage rather than explicit guidance, so a 3 is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It explicitly states the read-only nature ('List'), specifies the return type as a JSON string, and discloses a ValueError condition for unconfigured clients. This is useful behavioral context, though it could further clarify empty-list behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a one-sentence purpose, followed by 'Returns' and 'Raises' sections. No redundant wording; every sentence contributes necessary information and the main verb 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?
For a zero-parameter list tool with an output schema, the description is nearly complete: it covers purpose, return format, and error condition. A minor gap is not addressing the empty-list scenario, but this is not critical given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description's scope ('all accessible') correctly implies no filtering arguments, and the schema already confirms no parameters, leaving nothing for the description to add.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' with a clear resource 'accessible workspaces (Cloud) or projects (Server/DC)', and the scope 'all accessible' adds precision. It distinguishes from sibling tools like bitbucket_list_repositories which list repositories, not workspaces/projects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention sibling tools, prerequisites, or cases where this tool should be preferred, leaving the agent to infer usage from the name and context signals alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral transparency burden. It discloses that it raises ValueError in read-only mode or when the client is unavailable, and states the return format. However, it does not elaborate on side effects or other failure conditions beyond these, so a 3.
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 clear sections for Args, Returns, and Raises. Each sentence adds value, and it is front-loaded with the purpose statement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params), a full output schema, and the inclusion of error conditions, the description is sufficiently complete for an agent to invoke it correctly. It could mention page existence checks, but that's a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides full descriptions for page_id and content, with 100% coverage. The description repeats this information but adds no additional semantic details; the mention of ctx is an internal context parameter not part of the user-facing schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Add a comment to a Confluence page,' which is a specific verb+resource statement. It clearly distinguishes from sibling tools like jira_add_comment and confluence_add_label.
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 context for when to use this tool: to add comments to Confluence pages. It does not explicitly name alternatives or exclusions, but the 'Confluence' qualifier differentiates it from Jira comment tools, giving a clear context without exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that the tool raises ValueError for read-only mode, unavailable client, or invalid content_format. However, it does not mention rate limits, idempotency, or what happens if a page with the same title exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with Args, Returns, Raises sections and is front-loaded with the main purpose. It is slightly verbose for a simple create operation but remains 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?
The description covers all 6 parameters, return value, and error cases. Given an output schema exists, the return description is extra but harmless. The tool has moderate complexity and the description is fully adequate.
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 100%, so baseline is 3. The description adds no significant meaning beyond the schema; it restates parameter roles (e.g., 'Optional parent page ID') and return format ('JSON string representing the created page object'), which is already covered by the output schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new Confluence page,' specifying the verb and resource. It differentiates from siblings like confluence_update_page and confluence_delete_page by being the creation tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly mention when to use this tool versus alternatives (e.g., update vs create, or using other Confluence tools). It impliedly guides by listing creation parameters but lacks context exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of transparency. It discloses that ValueError is raised in read-only mode or when the Jira client is unavailable, and states the return type (JSON string). This provides meaningful behavioral context beyond the tool name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with Args, Returns, and Raises sections. Every sentence contributes essential information, with no redundancy or padding.
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 two-parameter mutation tool, the description is sufficiently complete. It covers error conditions and return value, and the schema already documents parameters. Minor gaps like permissions or side effects are not critical given the tool's simplicity.
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 100%, so the baseline is 3. The description restates issue_key and comment with minimal detail ('Jira issue key', 'Comment text in Markdown') that does not add value over the schema descriptions. No new parameter semantics are introduced.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'Add a comment to a Jira issue', which uses a specific verb and resource, clearly distinguishing it from siblings like jira_create_issue or jira_add_worklog. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly discuss when to use this over alternatives or provide exclusions. The usage context is implied by the clear purpose and the read-only mode error, but no direct guidance 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 must carry the burden. It discloses the return type (JSON string), Cloud-only limitation, and raises (NotImplementedError, ValueError). However, it omits the nuance that 'limit' only limits the response and the function still fetches all data, which is a notable behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear Args, Returns, and Raises sections. It is concise and front-loaded with the core purpose and scope, with no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose, key restriction (Cloud only), return format, and error conditions. With an output schema present, it doesn't need to detail every return field. The missing fetch-all-data nuance is already captured in the input schema, so the overall context is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description largely repeats parameter info from the schema. It adds minimal value beyond what the schema already states, such as 'None for all fields'. The schema provides the more detailed notice about limit behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Get changelogs for multiple Jira issues', with an explicit scope 'Cloud only'. This clearly distinguishes it from sibling tools like jira_get_issue or jira_get_transitions.
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 states the tool is for multiple issues and includes a 'Cloud only' restriction, which is an important exclusion (not supported on Server/Data Center). However, it does not explicitly name alternatives or provide when-not-to-use guidance beyond the Cloud-only constraint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the URL is short-lived (with ttl parameter) and returns a JSON structure. However, it omits error behavior, such as what happens if the attachment is not cached or the key is invalid. This is a minor gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a summary line, usage context, and clear 'Args' and 'Returns' sections. Every sentence is informative, no redundancy. It is concise yet complete.
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 but indicated), so the description does not need to detail return values beyond the high-level JSON fields. It covers the tool's purpose, prerequisites, parameters, and return types adequately. Missing only minor error handling details.
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?
Input schema coverage is 100%; each parameter has a description. The description adds marginal value by clarifying that 'filename' must match exactly as returned by sibling tools and reinforcing the ttl_minutes maximum (10). This aligns with baseline expectations for high 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 begins with a clear verb ('Return a short-lived authenticated download URL') and resource ('cached Jira attachment'). It distinguishes itself from sibling tools like jira_download_attachments and jira_construct_upload_endpoint by specifying its purpose for clients needing an HTTP URL instead of an MCP resource URI.
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 the intended use case ('for clients that need a regular HTTP URL instead of an MCP resource URI') and the prerequisite ('attachment must already be present in the in-memory cache, typically by running jira_download_attachments with return_content=true'). It could be improved by explicitly mentioning when not to use this tool, but the guidance is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/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 only accessible projects are returned, keys are uppercase, include_archived filter, and the optional env-var filter. It also notes the ValueError for client issues. This is good, though it omits details on pagination 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 concise with 5-6 sentences, structured with clear Args, Returns, and Raises sections. Every sentence adds value, and the most critical information 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?
Given the simple tool (one optional param, no side effects) and the presence of an output schema, the description covers the main aspects: behavior, return format, and exception. It does not mention pagination or rate limits, but for this tool it is adequate.
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 100% for the single boolean parameter, so baseline is 3. The description's Args section restates 'include_archived' but adds no additional semantic meaning beyond the schema. The context about JIRA_PROJECTS_FILTER is related but not a parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get all Jira projects' with the scope 'accessible to the current user.' It also specifies important details like uppercase keys and filtering via environment variable, making the tool's purpose distinct from sibling tools that focus on specific issues or projects.
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 mentions the effect of JIRA_PROJECTS_FILTER but does not explicitly state when to use this tool versus alternatives (e.g., when to use jira_get_project_issues instead). There is no guidance on exclusion or comparison, though the unique purpose is 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, so the description bears full burden. It mentions raising ValueError for read-only mode or missing inputs, and that some transitions require specific fields. However, it does not disclose potential irreversibility, permission requirements, or side effects like status changes. Adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise and well-structured: one-line purpose, then Args/Returns/Raises sections. Every sentence adds value. Front-loaded with clear purpose. 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?
With 4 parameters (2 required), 100% schema coverage, and output schema present (though not shown), the description covers return format and errors. It is fairly complete, though could benefit from mentioning that transitions are typically irreversible and require appropriate permissions.
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 100% and description adds useful context beyond the schema: provides examples for fields (e.g., {'resolution': {'name': 'Fixed'}}), explains transition_id usage (pointing to jira_get_transitions), and clarifies optionality of fields and comment. Adds meaningful guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool transitions a Jira issue to a new status, using specific verb+resource. It distinguishes from sibling tools like jira_update_issue (which updates fields) and jira_get_transitions (which lists available transitions).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives. It implies a prerequisite by mentioning using jira_get_transitions first, but lacks clear when-to-use or when-not-to-use guidance. Siblings include many similar Jira tools, but no comparative context is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully details the analysis logic (resolved status, reply keywords), output fields, and error condition. Could be improved by stating it's read-only or required permissions.
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, well-structured with a clear first sentence, bullet points for logic, then return summary, args, and raises. Every sentence adds 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 an output schema exists, the description still adequately covers input, logic, output fields, and errors, making it fully complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description adds minimal extra over schema descriptions. It repeats parameter names and provides a brief context for workspace but not significant new 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 'analyze' and the resource 'pull request comment threads' to determine addressed vs pending feedback. It distinguishes from sibling tools like adding comments or fetching PR diffs.
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 when to use (to review comment status) but lacks explicit guidance on when not to use or comparisons to alternatives like bitbucket_get_pull_request.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the return format (JSON string with commit details), the limit semantics (all commits if unspecified), and raises ValueError when the client is not configured. This is good coverage for a read-only tool, though it omits details like ordering or auth requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear Args, Returns, and Raises sections. It front-loads the main purpose. Minor redundancy: 'If limit is not specified, all commits are returned' appears twice, but overall it is concise and organized.
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 moderate complexity and rich sibling context, the description adequately covers purpose, return value, error handling, and limit behavior. It does not detail pagination or ordering, but these are not critical for basic invocation. The presence of an output schema (JSON string) reduces the need to describe return structure further.
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 100%, so baseline is 3. The description repeats parameter info already present in the schema (e.g., workspace, repository, pull_request_id). It adds little beyond the schema; the limit description in the text is even slightly less detailed than the schema's. No extra semantic value is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get the list of commits included in a pull request', using a specific verb and resource. It further details the returned fields (hash, author, timestamp, message) and distinguishes itself from sibling tools like bitbucket_get_commits by scoping to a pull request.
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 context for when this tool is appropriate, mentioning you can 'trace what changes were introduced and by whom'. It also explains the limit parameter's behavior. However, it does not explicitly name alternatives or exclusions, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses behavior: creates an inline comment, returns JSON details, and raises ValueError if client not configured. It does not mention permissions or rate limits, but for a creation tool this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with Args, Returns, and Raises sections. It is slightly verbose but every sentence adds value. Could be more concise, but it's acceptable.
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 (not shown but indicated), the description adequately explains the return value as a JSON string. It covers all necessary aspects for a create tool with no missing 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?
Schema coverage is 100%, baseline 3. The description adds value by clarifying that 'line_type' is only used for Server/DC, and provides concise context for each parameter beyond the schema's 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 action: 'Add an inline comment on a specific line of a file in a pull request.' It uses specific verb and resource, and distinguishes from sibling tools like 'blocker comment' or general 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 does not provide explicit guidance on when to use this tool versus alternatives like blocker comment or general comment. Usage is implied but not clarified with exclusions.
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 the description carries the burden. It explains pagination (start, limit), optional content inclusion, and markdown conversion, giving a clear behavioral picture. However, it does not mention ordering, recursion depth, or performance characteristics, which are minor omissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with Args and Returns sections, and each parameter is listed clearly. It is slightly verbose due to parameter duplication with the schema, but overall concise and 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?
Given the presence of an output schema (not shown but indicated), the description adequately covers the tool's behavior. All parameters are documented, pagination is addressed, and optional behaviors are specified. No obvious gaps for a retrieval 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 100%, so baseline is 3. The description adds value by explaining that convert_to_markdown is only relevant if include_content is true, and it lists parameters in order with brief clarifications beyond the 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 'Get child pages of a specific Confluence page,' which is a specific verb-resource pair. It distinguishes itself from sibling tools like confluence_get_page (single page) and confluence_search (search across pages).
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 fetching children given a parent_id, but does not explicitly state when to use this over alternatives or mention any prerequisites or exclusions. Sibling tools are many, but no guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It discloses return behavior ('JSON string representing the Jira user profile object, or an error object if not found') and a raised ValueError when the Jira client is unavailable, providing useful behavioral context beyond the input schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a compact docstring with clear sections (Args, Returns, Raises) and front-loads the purpose. It is slightly redundant by repeating parameter info already in the schema and listing ctx, but overall it is well-organized and not overly verbose.
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 one-parameter lookup tool, the description is complete: it states the purpose, return format, error behavior, and a key prerequisite (client configuration). It covers essential information an agent needs to invoke and interpret the result without relying on an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes user_identifier in detail with examples, so the description adds little new parameter meaning. It repeats the identifier types and also lists 'ctx' in Args even though ctx is not part of the input schema, which is a minor source of confusion; schema coverage is 100%, so the baseline 3 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 begins with a specific action and resource: 'Retrieve profile information for a specific Jira user.' This clearly states what the tool does and is distinct from sibling tools like jira_get_issue or jira_get_project_issues, which target different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context by specifying 'for a specific Jira user' but does not explicitly mention when not to use it or alternative tools. It implies this is the go-to tool for fetching a user profile, but lacks explicit exclusions or references to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the return content (build state, key, name, URL), the behavior of returning all builds when limit is omitted, and raises ValueError for client misconfiguration. This is solid transparency for a read-only tool, though it does not discuss edge cases like invalid commit hashes or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear purpose statement, a returns section, an Args list, and a Raises section. It is front-loaded with the core intent and each section serves a functional purpose without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and read-only, the schema covers all parameters, and an output schema exists. The description adds important context such as usage scenarios, return value shape, and error handling, leaving no critical gaps for an agent to successfully invoke this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides complete descriptions for all 4 parameters (100% coverage). The Args section largely repeats the schema verbatim, adding no new semantic meaning. Baseline 3 is appropriate because the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Get all CI/CD build statuses for a specific commit.' It clearly differentiates from sibling Bitbucket tools like get_commits or get_pull_request by focusing narrowly on build statuses for a commit.
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?
Explicit usage context is provided: 'Use this to check whether all required pipelines passed before merging a PR or to identify which specific build failed.' It also explains limit behavior. However, it does not mention alternatives or when not to use, so it misses the 'when-not' criterion for a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does well: it discloses the return format, validation mode, and error conditions (ValueError for read-only mode, unavailable client, invalid input). It could mention atomicity or partial-failure behavior, but what's included is solid.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with Args, Returns, and Raises sections, front-loaded with the core purpose. Every section earns its place, and there is no redundant or vague wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers inputs, return behavior, validation mode, and error conditions, making it self-sufficient despite no annotations. An output schema exists, so the return explanation is an extra bonus, not a requirement.
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 100%, and the schema already provides detailed parameter descriptions including an example. The description adds only the 'ctx' argument (FastMCP context), which is a technical framework detail rather than a user-facing semantic improvement, so it stays at baseline.
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 immediately states 'Create multiple Jira issues in a batch,' which is a specific verb-resource-scope statement. This clearly distinguishes it from sibling single-create tool jira_create_issue, and the mention of 'validate_only' further clarifies its dual purpose.
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 batch nature and 'multiple' explicitly signal when this tool is appropriate, and the validate_only flag adds context for validation-only usage. It does not explicitly name alternatives or exclusions, but the contrast to a single-create sibling 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 carries the full burden. It discloses that attachments expire after 10 minutes, that images render inline, and the URI format. It does not mention any destructive behavior or potential staleness beyond the 10-minute expiry.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a clear purpose statement, followed by URI format details, behavior notes, and return type. 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.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with an output schema, the description covers the essential aspects: what the tool does, how to use the URIs, cache expiration, inline rendering, and return format. It is complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, and schema coverage is 100% (none). The description adds context about the URI format and return type, compensating for the absence of parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list', the resource 'cached attachments', and the scope 'currently cached'. It distinguishes from siblings like jira_download_attachments and jira_save_attachment_to_disk by focusing on cached resources available via MCP resources.
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 browsing cached attachments via MCP resource browser but does not explicitly state when to use this tool versus alternatives like jira_download_attachments or jira_save_attachment_to_disk. No direct comparisons or exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses caching behavior, URI format, 10-minute validity, and default parameter interactions. It does not explicitly mention read-only nature or authentication.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with clear sections (purpose, caching, examples, args, returns). Every sentence serves a purpose, and the most critical information is 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 moderate complexity and the presence of an output schema, the description thoroughly covers all aspects: inputs, outputs, caching behavior, default logic, and resource URI format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds substantial meaning beyond the schema, including dynamic default rules for return_content, MCP resource URI examples, and explanations of how parameters affect behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Download attachments from a Jira issue to disk, MCP resources, or both.' This is a specific verb-resource pair with clear scope, distinguishing it from upload and listing tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the caching mechanism and default behavior but does not explicitly guide when to use this tool versus siblings like jira_list_cached_attachments or jira_save_attachment_to_disk.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the use of MarkItDown, detailed extraction behavior per file type, handling of unsupported types (listed under 'skipped'), truncation behavior, and a package dependency. It could further clarify whether the operation is read-only or has side effects, but the summary nature strongly implies non-mutating.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear opening, bullet-pointed file type breakdown, and distinct sections for behavior and arguments. It is somewhat verbose and repeats schema information, but each section serves a purpose, making the length acceptable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's complexity thoroughly: supported/unsupported file types, extraction method, truncation, package requirement, and alternative tool for images. Since an output schema is present, the return value (JSON string with 'skipped' key) is adequately described without requiring further detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description's Args section largely repeats schema descriptions without adding new semantics, though it does restate the default values and the meaning of 0. No additional parameter insight is provided beyond what the schema already offers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Scan and summarize attachments (PDFs, images, Office documents) from a Jira issue.' It identifies the specific verb (scan/summarize), resource (attachments on a Jira issue), and scope, distinguishing it from the sibling jira_get_attachment_images, which is explicitly contrasted for image viewing.
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?
Explicit guidance is provided on when to use this tool versus the alternative: 'To have a vision-capable model *see* image attachments (screenshots, diagrams, charts), use jira_get_attachment_images instead.' It also clarifies supported vs. unsupported file types, ensuring the agent can decide when this tool is appropriate.
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 full burden. It discloses output format (JSON string), error conditions ('or an error if not found'), and behavioral nuances like markdown conversion vs raw HTML, including the token-cost warning. This is strong transparency, though it doesn't cover auth/permissions or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with Args and Returns sections and stays on point. Every line adds relevant guidance; the token-cost caveat on HTML justifies its inclusion. Moderately lengthy due to six parameters, but appropriately organized.
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 six-parameter read tool with an output schema and no annotations, this description covers purpose, identification methods, return shape, and error handling. The raw HTML warning and sample behavior round out practical usage. It is comprehensive without needing to restate schema fields.
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 100% and the description's Args section reinforces and extends schema docs—clarifying precedence between lookup parameters, the requirement to use title with space_key, and sample semantics. This adds real meaning beyond the struct, though some repetition of schema text exists.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear action: 'Get content of a specific Confluence page by its ID, or by its title and space key.' It identifies the resource (Confluence page) and the two lookup methods, which effectively distinguishes it from sibling tools like confluence_search or confluence_get_page_children.
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 explicit parameter usage rules: page_id takes precedence, title must be paired with space_key, and sample returns only top N lines. No explicit alternatives are named (e.g., use confluence_search to find pages), but the context is clear enough for a known-page retrieval tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the full burden and delivers richly: it discloses side effects (staged files are removed after success), automatic expiry after 30 minutes, technical approach (direct REST upload, no base64), and error conditions (ValueError in read-only mode or without Jira client).
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 longer than the two-sentence ideal but every sentence adds value, covering purpose, flow position, technical details, side effects, expiry, and errors. It is well-structured with Args/Returns/Raises sections, making it scannable despite the length.
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 multi-step upload flow, the description thoroughly covers prerequisites (staging), the operational process, postconditions (file removal and expiry), and failure modes. An output schema is present, so the Returns line is a bonus rather than a necessity. There are no missing pieces for an agent to correctly select and invoke the 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?
Both parameters have complete schema descriptions (100% coverage), and the description adds flow-specific context: upload_uris are explicitly tied to the /upload endpoint response with an example, and issue_key is given a concrete format. It also documents a 'ctx' argument not present in the schema, which adds a bit of confusion but still contributes useful context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Upload' and the resource 'one or more staged files to a Jira issue as attachments'. It explicitly identifies this as step 3 of a client-side file upload flow, distinguishing it from construct_upload_endpoint and other attachment-related 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?
It provides explicit when-to-use guidance by stating this is step 3 after construct_upload_endpoint and POSTing files to /upload. However, it doesn't mention when not to use it or list alternative tools, so it falls short of a perfect 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that saving occurs on the server filesystem, not the client, and adds warnings about the destination. While it could mention overwrite behavior or permissions, it provides sufficient behavioral context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a warning, use cases, args, returns, and an example. Every section earns its place, and the information is front-loaded with the critical warning.
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 complexity and the presence of an output schema (as per context), the description covers all needed aspects: it explains the return format, references sibling tools, and provides enough detail for correct invocation.
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 100%, but the description adds value by explaining cache_key's origin from download_attachments and providing context for target_path. The example also clarifies usage, enriching the 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 saves a cached attachment to the MCP SERVER's filesystem, using specific verb and resource. It differentiates from client-side saving and provides use cases, distinguishing it from sibling tools like jira_download_attachments.
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 explicitly says when to use (e.g., server running locally, need server-side processing) and when not to use (for client-side saving, use the resource URI). It includes a clear warning and alternative guidance, making it easy for the agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden, and it excels: it discloses that each image is returned as an MCP image content block, that non-image attachments are ignored, that no MarkItDown extraction or MCP sampling is required, and that the structured content includes metadata and download failures. This gives the agent a clear picture of the tool's behavior and edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the main purpose, then organized with clear Args and Returns sections. However, the Args section partially duplicates the schema's parameter descriptions, making it slightly longer than strictly necessary, though the Returns detail is non-redundant given there is no output schema.
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 lack of annotations and output schema, the description is exceptionally complete: it explains the exact return format (ToolResult with image blocks and structured content), the client compatibility requirements, the exclusion of non-image files, and provides an alternative tool. It covers all key aspects an agent needs to invoke and interpret this tool 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?
The input schema already provides 100% coverage for the three JSON parameters, so the baseline is 3. The description adds value by documenting the `ctx` FastMCP context argument, which is absent from the schema, and by clarifying defaults (e.g., max_images=10) in the Args section, though this mostly repeats 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 opens with 'Fetch image attachments from a Jira issue as viewable image content,' a specific verb+resource+output combination. It explicitly contrasts with jira_summarize_attachments, which handles documents, thereby distinguishing from a sibling tool.
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 states when to use this tool: when you need image attachments as viewable content for vision-capable models. It also provides an explicit alternative: 'use jira_summarize_attachments for documents (PDF / DOCX / XLSX / CSV / …)' when non-image attachments are involved.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses key behavioral traits: session expiration ('Sessions expire after 30 minutes'), configurability of TTL and base URL, and the exact return structure including required_headers and usage example. This exceeds the basic expectations and provides transparency about operational constraints.
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 long but every sentence adds value. It is structured with a numbered flow, code samples, environment variable notes, and return format. The front-loaded purpose is immediately clear, and the details are organized logically. Nothing feels redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is fully complete for this tool's complexity. It explains the entire upload flow, session mechanics, configuration options, return values, and how to use the results with a sibling tool. Even though an output schema exists, the description already provides a precise return shape, making the tool independently understandable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, so the baseline is 4. The description mentions 'Args: ctx: The FastMCP context' but this is internal and not in the schema. The description adds no parameter semantics because there are none, but it does add value by documenting the return object and usage flow, covering any ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool's purpose explicitly: 'Return the URL and session token needed to upload local files to the MCP server.' It uses a specific verb ('return') and resource (upload endpoint/session token), and clearly distinguishes itself from siblings like jira_construct_download_endpoint by focusing on uploads and describing the upload flow.
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 provides explicit step-by-step usage instructions and names the alternative/next tool: 'This is step 1 of the client-side file upload flow' and 'Pass the returned upload:// URIs to jira_upload_attachment.' It also includes OS-specific curl examples, making it clear when and how to use the tool.
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:

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

Score Badge

Copy to your README.md:

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

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/SharkyND/mcp-atlassian'

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