mcp-server-bitbucket

Server Quality Checklist

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

Latest release: v1.0.0
Disambiguation4/5
Most tools have distinct purposes targeting specific resources and actions, such as pull requests, branches, pipelines, and permissions. However, some tools like 'get_commit' and 'list_commits' or 'get_branch' and 'list_branches' have overlapping retrieval functions that could cause minor confusion, though their descriptions clarify the single vs. list distinction.
Naming Consistency5/5
Tool names follow a highly consistent verb_noun pattern throughout, using snake_case uniformly. Examples include 'create_pull_request', 'list_branches', 'delete_webhook', and 'update_user_permission', making the set predictable and easy to navigate.
Tool Count2/5
With 58 tools, the count is excessive for a single server, likely overwhelming for agents. While the domain (Bitbucket API) is broad, this many tools suggests poor scoping, as many could be consolidated or omitted without losing functionality, leading to potential confusion and inefficiency.
Completeness5/5
The tool set provides comprehensive coverage of the Bitbucket domain, including full CRUD operations for repositories, pull requests, branches, tags, pipelines, permissions, webhooks, and more. There are no obvious gaps; agents can perform end-to-end workflows without dead ends.
Average 3.4/5 across 58 of 58 tools scored.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 3 commits in the last 12 weeks
- Last stable release on December 8, 2025
- 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.
This repository includes a glama.json configuration file.
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 carries the full burden. It mentions 'Confirmation of deletion' in the Returns section, which hints at output, but fails to disclose critical behavioral traits like whether this is a destructive operation, permission requirements, or error handling. This is inadequate for a deletion tool with no annotation coverage.
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 sections for Args and Returns, and each sentence is essential. It is front-loaded with the main purpose and avoids unnecessary details, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a deletion tool with no annotations and no output schema, the description is incomplete. It lacks information on behavioral aspects like safety, permissions, and error cases, which are crucial for proper tool invocation in this 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?
Schema description coverage is 0%, but the description lists both parameters ('repo_slug' and 'tag_name') with brief explanations, adding meaning beyond the bare schema. However, it does not provide details on format, constraints, or examples, so it only partially compensates for the low coverage.
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 action ('Delete') and target resource ('a tag from a repository'), which is specific and unambiguous. However, it does not differentiate from sibling tools like 'delete_repository' or 'delete_webhook' beyond the resource type, so it's not fully distinguished.
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 when to delete a tag versus other deletion tools like 'delete_repository'. The description lacks context about prerequisites or scenarios for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states this is a read operation ('get'), which implies it's non-destructive, but doesn't mention authentication requirements, rate limits, error conditions, or what happens if the commit doesn't exist. The description adds minimal behavioral context beyond the basic operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and appropriately sized. It starts with a clear purpose statement, then lists parameters and return values in separate sections. Every sentence adds value, though the 'Args' and 'Returns' labels could be more integrated with the main text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with 2 parameters and no output schema, the description is minimally complete. It covers the basic operation and parameters but lacks behavioral details (like error handling) and doesn't fully explain the return format beyond listing fields. Given the low complexity, it's adequate but has clear 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 description provides parameter semantics in the 'Args' section, explaining what 'repo_slug' and 'commit' represent. Since schema description coverage is 0%, this adds valuable meaning beyond the bare schema. However, it doesn't specify format details (e.g., what constitutes a valid repo_slug or commit hash format), keeping it at a baseline level.
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: 'Get detailed information about a specific commit.' It uses a specific verb ('get') and resource ('commit'), but doesn't explicitly differentiate it from sibling tools like 'list_commits' or 'compare_commits' beyond the singular vs. plural distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description doesn't mention sibling tools like 'list_commits' (for multiple commits) or 'compare_commits' (for comparing commits), nor does it specify prerequisites or contextual constraints for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states this is a 'Get' operation, implying read-only behavior, but doesn't explicitly confirm it's non-destructive or safe. It mentions returns 'details including restrictions and variables,' giving some output context, but lacks information about authentication needs, rate limits, error conditions, or pagination. For a tool with zero annotation coverage, this leaves significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and appropriately sized at four sentences. It front-loads the core purpose, then details Args and Returns in clear sections. There's minimal waste, though the 'Args' and 'Returns' labels are slightly redundant given the schema context. Overall, it's efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (2 required parameters, no output schema, no annotations), the description is partially complete. It covers the purpose and parameters well but lacks output details beyond a high-level mention ('Environment details including restrictions and variables'). Without an output schema, more specifics on return structure would be helpful. It's adequate but has clear gaps in behavioral and output 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 description adds meaningful context for both parameters in the Args section: 'repo_slug: Repository slug' and 'environment_uuid: Environment UUID (from list_environments).' This clarifies what these parameters represent and where to obtain the UUID. However, with 0% schema description coverage, the schema provides only titles ('Repo Slug', 'Environment Uuid') without descriptions. The description compensates adequately but doesn't fully detail format constraints or examples, keeping it at baseline 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's purpose as 'Get details about a specific deployment environment,' which is a specific verb ('Get') and resource ('deployment environment'). It distinguishes from siblings like 'list_environments' (which lists multiple) and 'get_repository' (different resource). However, it doesn't explicitly contrast with all siblings, so it's not a perfect 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?
The description provides no explicit guidance on when to use this tool versus alternatives. While it mentions 'environment_uuid (from list_environments)' in the Args section, this is parameter documentation rather than usage guidance. There's no discussion of prerequisites, when-not-to-use scenarios, or comparisons to similar tools like 'get_repository' or 'get_project'.
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 states the tool retrieves permission data, implying it's a read-only operation, but doesn't clarify authentication needs, rate limits, error conditions, or what happens if the group or repository doesn't exist. For a tool with zero annotation coverage, this leaves significant gaps in understanding its behavior.
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 concise, with three clear sections: purpose, arguments, and returns. Each sentence earns its place by providing essential information without redundancy. It could be slightly improved by integrating the sections more fluidly, but it's efficiently front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (2 parameters, no output schema, no annotations), the description is somewhat complete but has gaps. It covers the purpose and parameters adequately but lacks behavioral details (e.g., error handling) and doesn't fully explain the return value ('Group's permission level' is vague without examples). For a read operation with simple inputs, it's minimally viable but could be more informative.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description lists the parameters ('repo_slug' and 'group_slug') and their roles, but schema description coverage is 0%, meaning the schema provides no descriptions. The description adds basic meaning by specifying what each slug represents, but it doesn't explain format (e.g., string patterns), examples, or constraints. With 2 parameters and low schema coverage, this is adequate but minimal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get a specific group's permission for a repository.' It specifies the verb ('Get'), resource ('group's permission'), and target ('repository'), making it easy to understand. However, it doesn't explicitly differentiate from sibling tools like 'list_group_permissions' or 'get_user_permission', which would be needed for a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'list_group_permissions' (for listing all permissions) or 'get_user_permission' (for user-specific permissions), nor does it specify prerequisites or exclusions. Usage is implied by the purpose but not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states the tool returns 'Diff content as text' which adds some behavioral context about output format. However, it doesn't disclose important traits like whether this is a read-only operation, authentication requirements, rate limits, error conditions, or pagination behavior for large diffs.
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 appropriately sized with three sentences that each serve a purpose: stating the tool's purpose, listing parameters, and describing the return value. It's front-loaded with the core functionality. Minor improvement could be made by combining the parameter documentation into a more structured format.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 2 parameters with 0% schema coverage and no output schema, the description provides basic parameter documentation and return format. However, for a tool that fetches potentially complex diff data, it lacks details about diff format specifics, size limitations, error handling, and authentication requirements that would be needed for robust usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It documents both parameters ('repo_slug' and 'pr_id') with brief explanations, adding meaning beyond the bare schema. However, it doesn't provide format details (e.g., what constitutes a valid repo_slug), examples, or constraints, leaving gaps in parameter understanding.
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 with a specific verb ('Get') and resource ('diff of a pull request'). It distinguishes from siblings like 'get_pull_request' by focusing on the diff content rather than general PR information. However, it doesn't explicitly contrast with 'compare_commits' which might also provide diff-like functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives. The description doesn't mention prerequisites, appropriate contexts, or comparisons to sibling tools like 'get_pull_request' (for general PR info) or 'compare_commits' (for commit diffs). Usage is implied but not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states it 'Get[s] information' and returns 'PR info', implying a read-only operation, but doesn't disclose behavioral traits like authentication needs, rate limits, error handling, or pagination. For a tool with no annotations, this is a significant gap in transparency about how it behaves beyond basic functionality.
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 appropriately sized and front-loaded: the first sentence states the purpose clearly, followed by structured sections for args and returns. There's no wasted text, and each sentence adds value. However, the structure could be more integrated (e.g., combining purpose with usage) for optimal flow.
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 no annotations, no output schema, and low schema coverage, the description is minimally complete. It covers the basic purpose and parameters but lacks behavioral context, usage guidelines, and detailed return values (only high-level info like 'state, author, reviewers, and merge status'). For a simple read tool, it's adequate but has clear gaps in providing a full picture for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the schema provides no parameter details. The description adds minimal semantics by listing args ('repo_slug', 'pr_id') and their purpose ('Repository slug', 'Pull request ID'), but doesn't explain format (e.g., string patterns for repo_slug) or constraints. It compensates slightly but not fully for the low coverage, aligning with the baseline for partial compensation.
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 as 'Get information about a pull request' with a specific verb ('Get') and resource ('pull request'). It distinguishes itself from siblings like 'list_pull_requests' (which lists multiple) and 'get_pr_diff' (which gets diff content), though not explicitly. However, it doesn't fully differentiate from 'get_commit' or 'get_branch' in terms of resource type, which slightly limits clarity.
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 doesn't mention siblings like 'list_pull_requests' for multiple PRs or 'get_pr_diff' for diff details, nor does it specify prerequisites or contexts (e.g., after listing PRs). Usage is implied by the name but not explicitly stated, leaving gaps for an AI agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions the tool lists environments but doesn't disclose behavioral traits such as whether it's read-only (implied by 'List' but not explicit), pagination behavior, rate limits, authentication needs, or error handling. The description is minimal and lacks crucial operational 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 appropriately sized and front-loaded, starting with the core purpose followed by parameter and return details in a structured format. Every sentence adds value, with no wasted words, though it could be slightly more detailed without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (a simple list operation with 2 parameters), no annotations, and no output schema, the description is minimally complete. It covers the purpose, parameters, and return type, but lacks behavioral context and usage guidelines, making it adequate but with clear gaps for effective tool selection.
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 description coverage is 0%, so the description must compensate. It adds meaning by explaining 'repo_slug' as 'Repository slug' and 'limit' with its default value, which clarifies beyond the bare schema. However, it doesn't detail parameter formats (e.g., what a 'repo_slug' looks like) or constraints, leaving some ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('deployment environments for a repository'), making the purpose specific and understandable. However, it doesn't explicitly differentiate from sibling tools like 'get_environment' (singular) or 'list_deployment_history', which might be related but serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage 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. For example, it doesn't mention when to choose 'list_environments' over 'get_environment' (which fetches a single environment) or 'list_deployment_history' (which might include environment-related data). The description only states what it does, not when it's appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states the action ('Request changes') which implies a mutation, but doesn't disclose behavioral traits like whether this requires specific permissions, if it's reversible, what happens to the PR status, or if it sends notifications. For a mutation tool with zero annotation coverage, this is a significant gap in 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 appropriately sized and front-loaded with the core purpose in the first sentence. The Args/Returns sections are structured but could be more concise (e.g., merging into a single sentence). Every sentence adds value, with no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (a mutation tool for PR reviews), lack of annotations, and no output schema, the description is incomplete. It doesn't cover behavioral aspects like permissions, side effects, or error conditions, and the return value is vaguely described as 'Confirmation of change request' without details. This leaves significant gaps for an agent to use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It lists the parameters ('repo_slug', 'pr_id') and provides basic semantics ('Repository slug', 'Pull request ID'), which adds meaning beyond the bare schema. However, it doesn't explain format details (e.g., what a 'slug' is, where to find the PR ID) or constraints, leaving some ambiguity.
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 action ('Request changes') and target resource ('on a pull request'), which is specific and unambiguous. It distinguishes from siblings like 'approve_pr' or 'decline_pr' by indicating a review action that requests modifications rather than approving or rejecting outright. However, it doesn't explicitly differentiate from 'add_pr_comment', which could also be used for feedback.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description doesn't mention prerequisites (e.g., needing review permissions), when it's appropriate (e.g., during code review to request fixes), or what alternatives exist (e.g., using 'add_pr_comment' for non-blocking feedback). This leaves the agent to infer usage from context alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states the action ('stop') but doesn't describe permissions required, whether the stop is reversible, rate limits, error conditions, or what 'Updated pipeline status' entails. This leaves significant gaps 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 appropriately sized and front-loaded with the core purpose. The Args and Returns sections add structure, though some sentences could be more informative. There's minimal waste, but it could be slightly more efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations, 0% schema description coverage, and no output schema, the description is incomplete. It doesn't explain behavioral aspects like side effects, error handling, or the meaning of 'Updated pipeline status', leaving the agent with insufficient 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?
Schema description coverage is 0%, so the description must compensate. It lists both parameters ('repo_slug' and 'pipeline_uuid') but provides no additional meaning beyond their names. The baseline is 3 since it documents the parameters minimally without adding semantic context like format examples or relationships.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('stop') and resource ('a running pipeline'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'trigger_pipeline' or 'get_pipeline', which would require explicit comparison to achieve a score of 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?
The description provides no guidance on when to use this tool versus alternatives, prerequisites, or contextual constraints. It lacks any mention of when-not-to-use scenarios or comparisons with related tools like 'trigger_pipeline' or 'get_pipeline'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states this is an update operation, implying mutation, but doesn't disclose important behavioral traits like whether this requires specific permissions, if changes are reversible, what happens on failure, or rate limits. The mention of 'Returns: Updated variable info' hints at output but lacks detail about format or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured with a clear purpose statement followed by parameter documentation and return information. Every sentence serves a purpose with minimal waste. The parameter documentation is appropriately brief given the straightforward nature of the parameters. It could be slightly more front-loaded with usage context, but overall maintains good conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 3 parameters, 0% schema description coverage, no annotations, and no output schema, the description is incomplete. While it documents parameters and return concept, it lacks crucial context about permissions, error handling, side effects, and what 'Updated variable info' actually contains. The agent would need to guess about important behavioral aspects of this write operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the schema provides no parameter documentation. The description compensates by listing all three parameters with brief explanations: 'repo_slug: Repository slug', 'variable_uuid: Variable UUID (from list_pipeline_variables)', and 'value: New variable value'. This adds meaningful semantics beyond the bare schema, particularly the source hint for variable_uuid, but doesn't provide format details, constraints, or examples.
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 action ('Update') and resource ('pipeline variable's value'), making the purpose immediately understandable. It distinguishes itself from sibling tools like 'create_pipeline_variable' and 'delete_pipeline_variable' by focusing on modification rather than creation or deletion. However, it doesn't explicitly differentiate from other update tools like 'update_group_permission' or 'update_repository' beyond the resource type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It mentions that 'variable_uuid' comes from 'list_pipeline_variables', which is helpful for parameter sourcing, but doesn't specify prerequisites like needing existing variables or appropriate permissions. There's no mention of when not to use it or what happens if the variable doesn't exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states the tool updates or adds permissions, implying a mutation, but doesn't cover critical aspects like required authorization levels, whether changes are reversible, error conditions (e.g., invalid user), or side effects. The mention of 'Returns: Updated permission info' hints at output but lacks detail. This is inadequate for a mutation tool with zero annotation coverage.
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 efficient: a clear purpose statement followed by parameter and return sections. Each sentence adds value without redundancy. It could be slightly more concise by integrating the purpose with parameter details, but overall, it's appropriately sized and front-loaded with the core function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 3 parameters, 0% schema coverage, no annotations, and no output schema, the description is incomplete. It covers basic parameter semantics but lacks behavioral context (e.g., auth needs, error handling), usage guidelines, and detailed return information. The agent would struggle to use this tool correctly without additional context or trial-and-error.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the schema provides no parameter details. The description compensates by listing all three parameters with brief explanations: 'repo_slug: Repository slug', 'selected_user: User's account_id or UUID', and 'permission: Permission level - "read", "write", or "admin"'. This adds meaningful semantics, especially for 'permission' with its enum values. However, it doesn't fully cover format specifics (e.g., UUID format for selected_user) or constraints.
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: 'Update or add a user's permission for a repository.' It specifies the verb ('Update or add'), resource ('user's permission'), and target ('repository'), making the function unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'update_group_permission' or 'delete_user_permission' beyond the obvious scope difference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing admin access), when not to use it (e.g., for group permissions), or how it differs from similar tools like 'update_group_permission' or 'delete_user_permission'. The agent must infer usage from the name and description alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool deletes a pipeline variable and returns a confirmation, which covers the basic action and output. However, it lacks critical details such as whether this operation is destructive/permanent, what permissions are required, if there are rate limits, or how errors are handled. For a deletion tool with zero annotation coverage, this is insufficient.
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 concise, using a brief purpose statement followed by clear sections for Args and Returns. Each sentence adds value without redundancy. However, the 'Returns' section is vague ('Confirmation of deletion'), which slightly reduces efficiency by not specifying the confirmation format.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (a destructive operation with 2 parameters), no annotations, and no output schema, the description is incomplete. It covers the basic action and parameters but misses critical behavioral details like permanence, error handling, and authentication needs. The lack of output schema means the description should explain return values more thoroughly, which it doesn't do.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaningful context for both parameters beyond the input schema, which has 0% coverage. It explains that 'repo_slug' identifies the repository and 'variable_uuid' is the UUID from 'list_pipeline_variables', clarifying their roles and relationships. This compensates well for the lack of schema descriptions, though it doesn't detail format constraints (e.g., UUID format).
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 action ('Delete') and target resource ('a pipeline variable'), making the purpose immediately understandable. It distinguishes itself from sibling tools like 'create_pipeline_variable' and 'update_pipeline_variable' by specifying the destructive operation. However, it doesn't explicitly mention the repository context, which is implied but could be more specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides minimal guidance on when to use this tool. It mentions that 'variable_uuid' should come from 'list_pipeline_variables', which hints at a prerequisite but doesn't explicitly state when to choose this over alternatives like 'update_pipeline_variable' or warn about irreversible deletion. No context on permissions or constraints is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states 'Delete a webhook' and 'Returns: Confirmation of deletion', which implies a destructive mutation but lacks details on permissions required, whether deletion is permanent, error conditions, or side effects. This is inadequate for a destructive tool with zero annotation coverage.
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 appropriately sized with three brief sections: purpose, args, and returns. It's front-loaded with the core action. However, the 'Args:' and 'Returns:' headings add minor structural overhead without enhancing clarity significantly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a destructive mutation tool with no annotations, no output schema, and 2 parameters, the description is incomplete. It lacks critical behavioral details like authentication needs, irreversible effects, or error handling. The return value mention is vague ('Confirmation of deletion'), failing to specify format or content.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds meaning by explaining 'repo_slug: Repository slug' and 'webhook_uuid: Webhook UUID (from list_webhooks)', clarifying the source of the UUID. This provides useful context beyond the bare schema, though it doesn't detail format constraints for repo_slug.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Delete' and resource 'a webhook', making the purpose unambiguous. It distinguishes from siblings like 'create_webhook' and 'list_webhooks' by specifying deletion, though it doesn't explicitly contrast with other deletion tools like 'delete_repository'.
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 mentions 'webhook_uuid: Webhook UUID (from list_webhooks)' which hints at prerequisite data, but offers no explicit when/when-not instructions or comparisons with sibling tools like 'delete_repository' or 'update_webhook' (if it existed).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states the tool 'Update or add' permissions, implying a mutation operation, but doesn't specify required permissions, whether changes are idempotent, error handling, or what 'Updated permission info' entails. This leaves significant gaps 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 efficiently structured with a clear purpose statement followed by parameter and return sections. Every sentence adds value, though the return statement could be more specific. It's appropriately sized for a 3-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description is incomplete. It lacks details on authentication requirements, side effects, error cases, and the structure of 'Updated permission info'. Given the complexity of permission management, more behavioral context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It clearly explains all three parameters: 'repo_slug' and 'group_slug' are identified, and 'permission' is detailed with allowed values ('read', 'write', or 'admin'). This adds substantial meaning beyond the bare 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 the action ('Update or add') and resource ('group's permission for a repository'), making the purpose immediately understandable. However, it doesn't explicitly differentiate this tool from sibling tools like 'update_user_permission' or 'delete_group_permission', which would require 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?
The description provides no guidance on when to use this tool versus alternatives like 'delete_group_permission' or 'update_user_permission'. There's no mention of prerequisites, error conditions, or typical use cases, leaving the agent with minimal contextual 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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action ('Approve') but doesn't describe what approval entails (e.g., whether it's reversible, if it requires specific permissions, what happens to the PR status, or any side effects). This is a significant gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured with clear sections (purpose, Args, Returns) in just three sentences. Every element serves a purpose with no wasted words, though the 'Returns' section could be slightly more informative.
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 mutation tool with no annotations and no output schema, the description adequately covers the basic purpose and parameters. However, it lacks important context about behavioral aspects (permissions, side effects, return format) and usage guidelines relative to sibling tools, leaving gaps for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explicitly documents both parameters ('repo_slug' and 'pr_id') in the Args section, providing clear semantic meaning. Since schema description coverage is 0%, this documentation fully compensates for the schema's lack of descriptions, making parameters well-understood.
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 action ('Approve') and resource ('a pull request'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'unapprove_pr' or 'merge_pull_request' which are related approval/merge operations on 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 about when to use this tool versus alternatives like 'unapprove_pr', 'decline_pr', or 'merge_pull_request'. The description lacks any context about prerequisites, permissions needed, or typical workflow scenarios.
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 states it 'Get information' and returns 'Branch info with latest commit details,' which implies a read-only operation, but doesn't cover aspects like error handling, authentication needs, rate limits, or what specific information is included in the return. This leaves significant gaps for a tool with no annotation coverage.
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 and front-loaded with the main purpose, followed by clear sections for 'Args' and 'Returns.' Every sentence earns its place without redundancy, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (2 parameters, no output schema, no annotations), the description is somewhat complete but has gaps. It covers the basic purpose and parameters but lacks usage guidelines and detailed behavioral context. For a simple read tool, this is minimally adequate but could be improved with more 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 description lists the parameters ('repo_slug' and 'branch_name') and their purposes, but the schema description coverage is 0%, so the schema provides no additional details. The description adds basic semantics by explaining what each parameter represents, but it doesn't provide format examples, constraints, or deeper context beyond naming them.
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 with 'Get information about a specific branch,' which includes a specific verb ('Get') and resource ('branch'). It distinguishes from siblings like 'list_branches' (which lists multiple branches) by focusing on a single branch, though it doesn't explicitly name this distinction.
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 doesn't mention when to use 'get_branch' over 'list_branches' or 'get_commit' for related information, nor does it specify any prerequisites or exclusions for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states it 'Get[s] information,' implying a read-only operation, but does not disclose behavioral traits such as authentication requirements, rate limits, error handling, or what happens if the project does not exist. This is inadequate for a tool with zero annotation coverage.
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 appropriately sized and front-loaded with the core purpose. The 'Args' and 'Returns' sections are structured clearly, though the 'Returns' section could be more concise by omitting redundant phrasing like 'Project info including'.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (1 parameter, no output schema, no annotations), the description is minimally adequate. It covers the purpose and parameter semantics but lacks usage guidelines and behavioral details, making it incomplete for optimal agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaningful context for the single parameter: it explains that 'project_key' is a key like 'DS' or 'PROJ,' which is not covered in the schema (0% coverage). This compensates well for the lack of schema descriptions, though it could specify format constraints more explicitly.
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: 'Get information about a specific project.' It specifies the verb ('Get') and resource ('project'), but does not explicitly differentiate it from sibling tools like 'list_projects' or 'get_repository', which would require 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?
The description provides no guidance on when to use this tool versus alternatives. It does not mention sibling tools like 'list_projects' for listing all projects or 'get_repository' for repository-specific details, leaving the agent without context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions filtering and pagination via 'limit', but lacks critical details: whether this is a read-only operation, potential rate limits, authentication requirements, error handling, or pagination beyond the default limit. For a tool with 4 parameters and no annotation coverage, this is insufficient.
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 appropriately sized. It front-loads the purpose in one sentence, then lists args and returns in clear sections. Every sentence adds value, with no redundancy or fluff. Minor improvements could include briefer formatting, but it's highly 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 tool's moderate complexity (4 parameters, no annotations, no output schema), the description is partially complete. It covers parameters and return values adequately, but lacks behavioral context (e.g., safety, errors, pagination). Without annotations or output schema, it should do more to guide usage, especially for a list operation in a sibling-rich environment.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant meaning beyond the input schema, which has 0% description coverage. It explains each parameter's purpose: 'repo_slug' (repository slug), 'branch' (filter by branch), 'path' (filter by file path), and 'limit' (maximum results with default). This compensates well for the schema's lack of descriptions, though it doesn't detail format constraints (e.g., slug structure).
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: 'List commits in a repository.' It specifies the verb ('List') and resource ('commits'), and distinguishes it from siblings like 'get_commit' (singular) or 'compare_commits'. However, it doesn't explicitly differentiate from other list tools (e.g., 'list_branches'), which keeps it from a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention siblings like 'get_commit' (for single commits) or 'compare_commits' (for commit comparisons), nor does it specify prerequisites or contextual usage scenarios. The absence of such guidance limits its utility for an AI agent.
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 mentions the return format ('List of pipeline variables with key, secured status, and value'), which adds some context. However, it lacks critical details like whether this is a read-only operation, if it requires authentication, pagination behavior beyond the 'limit' parameter, or error conditions. For a list operation with zero annotation coverage, this is insufficient.
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 and front-loaded with the core purpose, followed by parameter and return details. Every sentence earns its place: the first states the action, the 'Args' section clarifies inputs, and the 'Returns' section explains outputs. It's appropriately sized with zero waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (2 parameters, no annotations, no output schema), the description covers the basics: purpose, parameters, and return format. However, it lacks behavioral context (e.g., safety, pagination) and doesn't reference sibling tools. For a list operation, this is adequate but leaves gaps that could hinder agent effectiveness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description includes an 'Args' section that documents both parameters ('repo_slug' and 'limit') with brief explanations, adding meaning beyond the input schema (which has 0% description coverage). However, it doesn't elaborate on format (e.g., what a 'repository slug' is) or constraints (e.g., 'limit' range). With schema coverage low, the description compensates partially but not fully.
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: 'List pipeline variables for a repository.' It specifies the verb ('List') and resource ('pipeline variables') with scope ('for a repository'), making it unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'get_pipeline_variable' (singular) or 'create_pipeline_variable', though the plural vs. singular naming provides implicit distinction.
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 doesn't mention sibling tools like 'get_pipeline_variable' (for a single variable) or 'create_pipeline_variable', nor does it specify prerequisites or contextual constraints. The agent must infer usage from the name and description alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool lists permissions, implying a read-only operation, but doesn't clarify aspects like authentication requirements, rate limits, pagination behavior (beyond the 'limit' parameter), or error handling. For a tool with zero annotation coverage, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and concise, with zero wasted words. It starts with the core purpose, followed by clear sections for 'Args' and 'Returns', making it easy to parse. Every sentence earns its place by directly contributing to understanding the tool's functionality.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (2 parameters, no output schema, no annotations), the description is minimally complete. It covers the basic purpose and parameters but lacks behavioral details (e.g., pagination, errors) and usage guidelines. Without annotations or output schema, the agent must rely on the description alone, which is adequate but leaves gaps in operational 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 description adds minimal semantics beyond the input schema. It explains 'repo_slug' as 'Repository slug' and 'limit' as 'Maximum number of results (default: 50)', which are already clear from the schema titles and default value. With 0% schema description coverage, the description doesn't compensate by providing additional context (e.g., format of 'repo_slug' or constraints on 'limit'), so it meets the baseline for adequate but unhelpful parameter documentation.
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: 'List user permissions for a repository.' It specifies the verb ('List') and resource ('user permissions for a repository'), making it easy to understand what the tool does. However, it doesn't explicitly differentiate from sibling tools like 'get_user_permission' or 'list_group_permissions', which would be needed for a score of 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?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'get_user_permission' (which might retrieve a single user's permission) or 'list_group_permissions', nor does it specify prerequisites or exclusions. This lack of context leaves the agent to infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states the action is a merge but doesn't disclose critical behavioral traits: whether this is a destructive/write operation (implied but not explicit), permission requirements, rate limits, or what happens on failure. The description lacks behavioral context beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections (Args, Returns). The first sentence states the purpose directly. Each parameter explanation is brief but informative. No wasted words, though the 'Returns' section is minimal given no output schema.
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 no annotations and no output schema, the description covers parameters well but lacks behavioral context (permissions, side effects, error handling). For a mutation tool with 5 parameters, it's adequate but has clear gaps in completeness regarding how the tool behaves beyond basic parameter semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It provides meaningful semantics for all 5 parameters: explains what repo_slug and pr_id are, lists merge_strategy options with default, clarifies close_source_branch behavior, and notes message is optional. This adds substantial value beyond the bare 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 the action ('Merge a pull request') and identifies the resource. It's specific about the verb and resource, but doesn't explicitly differentiate from siblings like 'approve_pr' or 'decline_pr' which are related PR operations.
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. The description doesn't mention prerequisites (e.g., PR must be approved), nor does it contrast with sibling tools like 'decline_pr' or 'approve_pr' that might be alternatives in different scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions triggering a pipeline run but doesn't describe what happens after triggering (e.g., asynchronous execution, side effects, permissions required, rate limits, or whether this is a destructive/mutative operation). The return info is mentioned but not elaborated.
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 appropriately sized with clear sections (Args, Returns) and front-loaded purpose. Every sentence adds value, though the 'Returns' section could be slightly more detailed given no output schema.
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 no annotations, 0% schema coverage, and no output schema, the description does a decent job explaining parameters but lacks behavioral context. For a tool that triggers pipeline runs (likely a mutative/destructive operation), more information about side effects, permissions, or execution behavior would be needed for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant value beyond the 0% schema coverage by explaining all three parameters: 'repo_slug' (repository slug), 'branch' (branch to run on with default), and 'variables' (custom key-value pairs, optional). This compensates well for the lack of schema descriptions.
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 action ('trigger a pipeline run') and the target ('on a repository'), providing specific verb+resource. However, it doesn't explicitly differentiate from sibling tools like 'stop_pipeline' or 'get_pipeline', which would be needed for a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'create_pipeline_variable' or 'stop_pipeline'. It lacks context about prerequisites, timing considerations, 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states this is a 'Get' operation, implying read-only behavior, but doesn't disclose any behavioral traits like authentication requirements, rate limits, error conditions, or response format details. For a tool with no annotation coverage, this leaves significant gaps in understanding how it behaves.
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 and front-loaded, starting with the core purpose, followed by clear sections for Args and Returns. Every sentence adds value without redundancy, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (1 parameter, no nested objects) and lack of annotations or output schema, the description is minimally adequate. It covers the purpose and parameter semantics but lacks behavioral details and usage guidelines, leaving room for improvement in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaningful context for the single parameter 'repo_slug' by explaining it's a 'Repository slug' and providing an example ('anzsic_classifier'). With schema description coverage at 0%, this compensates well by clarifying what the parameter represents, though it doesn't detail constraints like format or length.
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: 'Get information about a Bitbucket repository.' It specifies the verb ('Get') and resource ('Bitbucket repository'), making it easy to understand what the tool does. However, it doesn't explicitly differentiate from sibling tools like 'get_project' or 'list_repositories', which would require 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?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when to choose 'get_repository' over 'list_repositories' for a single repo, or 'get_project' for project-level info. Without such context, the agent lacks clear usage instructions.
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 mentions the return value ('User's permission level') but doesn't specify what that level entails (e.g., read, write, admin), whether it's a read-only operation, or any error conditions. This leaves significant gaps for a tool that retrieves permission data.
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 efficiently structured with a clear purpose statement followed by bullet points for arguments and returns. Every sentence adds value without redundancy, making it easy to scan and understand quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (2 parameters, no output schema, no annotations), the description covers the basics but lacks depth. It explains parameters well and states the return type, but doesn't detail the permission level format or potential errors, leaving room for improvement in behavioral 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?
The description adds meaningful context for both parameters beyond the schema's 0% coverage: 'repo_slug' is explained as 'Repository slug' and 'selected_user' as 'User's account_id or UUID'. This clarifies the expected format and purpose of each parameter, compensating well for the lack of schema descriptions.
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 with a specific verb ('Get') and resource ('user's permission for a repository'), making it easy to understand what it does. However, it doesn't explicitly differentiate from its sibling 'list_user_permissions' or 'get_group_permission', which would be needed for a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'list_user_permissions' or 'get_group_permission'. It simply states what the tool does without context about appropriate 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.
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 mentions the return format ('List of branches with commit info'), which is helpful, but lacks critical details like pagination behavior (beyond the limit parameter), authentication requirements, rate limits, error conditions, or whether results are sorted/filtered.
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 efficiently structured with clear sections (Args, Returns) and uses minimal, purposeful sentences. Every line adds value—no redundant or verbose phrasing—making it easy to parse quickly.
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 read-only list tool with 2 parameters and no output schema, the description covers the basics (purpose, parameters, return format) but lacks depth. Without annotations, it should ideally include more behavioral context (e.g., pagination, auth). The return format hint is helpful, but overall completeness is adequate yet minimal.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explicitly documents both parameters ('repo_slug' and 'limit') with brief explanations, including the default value for 'limit'. Since schema description coverage is 0%, this adds significant value beyond the bare schema, though it doesn't elaborate on format details (e.g., what a 'repository slug' entails).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('branches in a repository'), making the purpose immediately understandable. However, it doesn't differentiate from similar sibling tools like 'list_repositories' or 'list_tags', which follow the same pattern for 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 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 doesn't mention sibling tools like 'get_branch' (for single branch details) or 'list_commits' (for commits within branches), leaving the agent to infer usage context from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the return format ('List of branch restrictions with kind, pattern, and settings'), which adds some context, but fails to address critical aspects like pagination (implied by 'limit'), authentication needs, error conditions, or rate limits. For a read operation with zero annotation coverage, this is insufficient.
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 and front-loaded, with a clear purpose statement followed by concise sections for arguments and returns. Every sentence earns its place by providing essential information without redundancy, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (2 parameters, no output schema, no annotations), the description is partially complete. It covers the purpose, parameters, and return structure adequately, but lacks behavioral details (e.g., authentication, errors) and usage guidelines. Without annotations or output schema, it should do more to compensate, resulting in an average score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaningful semantics beyond the input schema, which has 0% description coverage. It explains that 'repo_slug' identifies the repository and 'limit' controls the maximum number of results with a default of 50, clarifying their roles. However, it doesn't detail format constraints (e.g., slug syntax) or the effect of 'limit' on pagination, leaving minor gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('branch restrictions (protection rules) in a repository'), making the purpose specific and understandable. It distinguishes from siblings like 'create_branch_restriction' and 'delete_branch_restriction' by focusing on listing rather than modifying. However, it doesn't explicitly differentiate from other list tools (e.g., 'list_branches'), which prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description lacks context about prerequisites (e.g., repository access), exclusions, or comparisons with similar tools like 'list_branches' or 'get_branch'. This omission leaves the agent without clear 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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states it's a list operation, implying read-only behavior, but doesn't mention critical details like pagination (only a limit parameter), authentication requirements, rate limits, or error conditions. This leaves significant gaps for an AI agent to understand how to use it effectively.
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 and front-loaded with the core purpose, followed by clear sections for Args and Returns. Every sentence earns its place by providing essential information without redundancy, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (2 parameters, no output schema, no annotations), the description is adequate but incomplete. It covers the basic purpose and parameters but lacks behavioral details (e.g., pagination, auth) and usage guidelines. Without annotations or output schema, it should do more to compensate, but it meets a minimum viable standard.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaningful context beyond the input schema, which has 0% description coverage. It explains that 'repo_slug' identifies the repository and 'limit' controls the maximum results with a default of 50, clarifying their roles. However, it doesn't detail format constraints (e.g., slug syntax) or that 'limit' is optional due to the default, though the schema indicates this.
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 with a specific verb ('List') and resource ('group permissions for a repository'), making it immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'list_user_permissions' or 'get_group_permission', which would require mentioning it's specifically for groups (not users) and listing (not getting a single permission).
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 doesn't mention sibling tools like 'list_user_permissions' for user permissions or 'get_group_permission' for a specific group's permission, nor does it specify prerequisites or exclusions (e.g., requires repository access).
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 mentions the tool lists 'recent' pipeline runs, implying a time-based filter, but does not specify what 'recent' means (e.g., time range, ordering). It also lacks details on permissions, rate limits, pagination, or error handling, which are important for a read operation with no annotation coverage.
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 and concise, with a clear purpose statement followed by Args and Returns sections. Each sentence earns its place by providing essential information without redundancy. It is appropriately sized for a simple list tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (2 parameters, no output schema, no annotations), the description is minimally adequate. It covers the basic purpose and parameters but lacks behavioral details like ordering, time range for 'recent', or error cases. Without annotations or output schema, more context would improve completeness for safe agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaningful semantics beyond the input schema, which has 0% description coverage. It explains that 'repo_slug' is a 'Repository slug' and 'limit' is the 'Maximum number of results (default: 10)', clarifying purpose and default values. However, it does not detail format constraints (e.g., slug syntax) or behavioral effects (e.g., how limit affects ordering), preventing a score of 5.
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: 'List recent pipeline runs for a repository.' It specifies the verb ('List'), resource ('pipeline runs'), and scope ('for a repository'). However, it does not explicitly differentiate from sibling tools like 'get_pipeline' or 'list_pipeline_variables', which reduces the score from 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?
The description provides no guidance on when to use this tool versus alternatives. It does not mention sibling tools like 'get_pipeline' (for a specific pipeline) or 'list_pipeline_variables', nor does it specify prerequisites or exclusions. Usage is implied by the purpose but not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions a default limit and return format, but lacks details on pagination, error handling, permissions, rate limits, or whether it's read-only. For a list tool with zero annotation coverage, this is insufficient behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (Args, Returns) and uses only three sentences with zero waste. It's front-loaded with the core purpose and efficiently covers key details without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and low schema coverage, the description is minimally adequate. It covers purpose, parameter, and return format, but lacks behavioral context (e.g., pagination, errors) and usage guidelines, leaving gaps for a list operation in a complex API with many siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It documents the single parameter 'limit' with its default value, adding meaning beyond the bare schema. However, it doesn't explain constraints (e.g., min/max values) or usage context, keeping it from a perfect score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and resource 'projects in the workspace', making the purpose explicit. However, it doesn't differentiate from sibling tools like 'list_repositories' or 'list_pull_requests', which follow the same pattern, so it lacks sibling distinction for a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There are many sibling list tools (e.g., list_repositories, list_pull_requests), but no indication of context, prerequisites, or exclusions for selecting this specific list operation.
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 mentions filtering by state and pagination via 'limit', but doesn't describe the return format (e.g., what 'basic info' includes), whether results are sorted, authentication requirements, rate limits, or error conditions. For a list tool with no annotation coverage, this leaves significant gaps in understanding its 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 appropriately sized and front-loaded: the first sentence states the purpose clearly, followed by a structured breakdown of args and returns. Every sentence adds value without redundancy, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (3 parameters, no output schema, no annotations), the description is partially complete. It covers parameters well but lacks details on return values (e.g., structure of 'basic info'), behavioral aspects like sorting or pagination, and context for usage among siblings. This leaves room for improvement in guiding an AI agent effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaningful semantics beyond the input schema, which has 0% description coverage. It explains 'repo_slug' as 'Repository slug', 'state' with allowed values and default, and 'limit' with default and max values. This compensates well for the schema's lack of descriptions, though it doesn't detail 'repo_slug' format (e.g., 'owner/repo') or 'limit' constraints beyond max.
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: 'List pull requests in a repository.' It specifies the verb ('List') and resource ('pull requests'), and distinguishes it from siblings like 'get_pull_request' (singular) and 'list_pr_comments' (comments only). However, it doesn't explicitly differentiate from 'list_repositories' or other list tools beyond the resource type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention siblings like 'get_pull_request' (for a single PR), 'list_pr_comments' (for PR comments), or 'list_repositories' (for repositories instead of PRs). There's no context about prerequisites, such as needing repository access, or when filtering by state is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool 'adds' a comment, implying a write operation, but doesn't cover critical aspects like required permissions, whether comments are editable/deletable, rate limits, or error conditions. The mention of markdown support is useful, but overall behavioral context is insufficient for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and appropriately sized. It starts with a clear purpose statement, followed by a brief feature note, then detailed parameter explanations, and ends with return info. Every sentence earns its place, though the 'Returns' line is vague ('Created comment info') and could be slightly more informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (5 parameters, mutation operation) and lack of annotations or output schema, the description is partially complete. It thoroughly documents parameters but lacks behavioral context (e.g., permissions, side effects) and output details. It's adequate for basic use but leaves gaps for robust agent operation.
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 excels in parameter semantics. With 0% schema description coverage, it fully compensates by detailing all 5 parameters in the 'Args' section, explaining their purposes, optionality, and interdependencies (e.g., 'line' requires 'file_path'). This adds significant value beyond the bare schema, making parameter usage clear and actionable.
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: 'Add a comment to a pull request' with the additional detail that it can add 'general comments or inline comments on specific lines.' This is a specific verb+resource combination. However, it doesn't explicitly differentiate from sibling tools like 'list_pr_comments' or 'request_changes_pr,' which keeps it from a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides minimal usage guidance. It mentions the tool can add general or inline comments, but offers no explicit advice on when to use this tool versus alternatives like 'request_changes_pr' or 'approve_pr.' There's no mention of prerequisites, permissions, or typical use cases, leaving the agent with little contextual 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 carries the full burden. It discloses that it returns 'Variable details including key, secured status, and value (if not secured)', which adds some behavioral context about the output. However, it lacks details on permissions required, error conditions, rate limits, or whether it's a read-only operation (implied by 'Get' but not explicit). For a tool with no annotations, this is a significant gap in 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 appropriately sized and front-loaded: the first sentence states the purpose clearly, followed by structured 'Args' and 'Returns' sections. Every sentence earns its place by adding necessary information, though the structure could be slightly more streamlined (e.g., integrating the explanation into a single paragraph).
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 no annotations and no output schema, the description provides basic purpose, parameter semantics, and return value details. However, for a tool with 2 parameters and no structured safety or output information, it lacks completeness in areas like error handling, authentication needs, or behavioral nuances. It's adequate but has clear gaps for a read operation in a complex system.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds meaning by explaining 'repo_slug' as 'Repository slug' and 'variable_uuid' as 'Variable UUID (from list_pipeline_variables)', clarifying the source and purpose of parameters beyond the schema's basic titles. This effectively documents both parameters, though it could provide more context on format or constraints.
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: 'Get details about a specific pipeline variable.' It specifies the verb 'Get' and resource 'pipeline variable', making it distinct from siblings like 'list_pipeline_variables' (which lists multiple) or 'create_pipeline_variable' (which creates). However, it doesn't explicitly differentiate from siblings like 'update_pipeline_variable' or 'delete_pipeline_variable' in terms of action specificity.
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 referencing 'variable_uuid: Variable UUID (from list_pipeline_variables)', suggesting this tool should be used after listing variables to get details for a specific one. However, it doesn't provide explicit guidance on when to use this versus alternatives (e.g., no comparison to 'list_pipeline_variables' for bulk details or other get_* tools for different resources), leaving some context to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the tool retrieves details but doesn't disclose behavioral traits like authentication needs, rate limits, error handling, or whether it's read-only. While 'Get details' implies a read operation, it lacks confirmation and additional context, leaving gaps in 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 appropriately sized and front-loaded, starting with the core purpose. The Args and Returns sections are structured clearly, but the 'Returns' part could be more concise by integrating it into the main sentence. Overall, it's efficient with minimal waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (2 parameters, no annotations, no output schema), the description is moderately complete. It covers the purpose and parameters but lacks details on return values (only mentions 'including URL, events, and status' without full structure) and behavioral aspects. For a tool with no structured support, it should provide more comprehensive guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaningful semantics beyond the input schema, which has 0% description coverage. It explains that 'repo_slug' is a 'Repository slug' and 'webhook_uuid' is a 'Webhook UUID (from list_webhooks)', providing context and source for the UUID. This compensates well for the low schema coverage, though it could detail format constraints.
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: 'Get details about a specific webhook.' It specifies the verb ('Get details') and resource ('a specific webhook'), making it easy to understand. However, it doesn't explicitly differentiate from sibling tools like 'list_webhooks' beyond mentioning the UUID source, missing full sibling distinction.
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 noting that the 'webhook_uuid' comes from 'list_webhooks', suggesting a workflow. However, it doesn't provide explicit guidance on when to use this tool versus alternatives (e.g., 'list_webhooks' for multiple webhooks or other get_* tools), leaving some ambiguity.
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 states the tool retrieves data ('Get'), implying a read-only operation, but doesn't clarify permissions, rate limits, pagination (beyond the 'limit' parameter), or error conditions. The return format is briefly described but lacks details on structure or potential edge cases, leaving significant gaps for a tool with no annotation coverage.
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 appropriately sized, with a clear purpose statement followed by parameter and return sections. Every sentence adds value, and there's no redundant information. However, it could be slightly more front-loaded by integrating key parameter details into the opening sentence for faster scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (3 parameters, no annotations, no output schema), the description is adequate but incomplete. It covers the purpose and parameters reasonably well but lacks behavioral context (e.g., safety, performance) and detailed return format. Without annotations or output schema, more guidance on error handling or result interpretation would improve completeness for a read operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaningful semantics beyond the input schema, which has 0% description coverage. It explains that 'repo_slug' is a repository slug, 'environment_uuid' comes from 'list_environments', and 'limit' defaults to 20 and controls result count. This compensates well for the schema's lack of descriptions, though it doesn't detail format constraints (e.g., UUID structure) or validation rules.
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: 'Get deployment history for a specific environment.' It specifies the verb ('Get') and resource ('deployment history'), and distinguishes it from siblings like 'list_environments' by focusing on deployment history rather than environments themselves. However, it doesn't explicitly differentiate from other list tools like 'list_pipelines' or 'list_commits' beyond the resource name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides implied usage context by mentioning that 'environment_uuid' comes from 'list_environments', suggesting a workflow dependency. However, it lacks explicit guidance on when to use this tool versus alternatives (e.g., 'list_pipelines' for pipeline history or 'get_commit' for commit details), and doesn't specify prerequisites or exclusions beyond the parameter hints.
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. While it mentions that the repository will be created and returns clone URLs, it doesn't address important behavioral aspects like required authentication, potential rate limits, whether the operation is idempotent, or what happens if a repository with the same slug already exists. This leaves significant gaps for an agent to understand the tool's behavior.
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 and Returns, making it easy to parse. It's appropriately sized with no redundant information, though the formatting with quotes around the entire description is slightly awkward. Every sentence serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a creation tool with 4 parameters and no annotations or output schema, the description provides basic parameter semantics and return information but lacks important contextual details. It doesn't explain error conditions, authentication requirements, or how the tool fits into broader workflows. The absence of an output schema means the description should ideally provide more detail about the return structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides meaningful semantic information for all parameters beyond what the schema offers (0% coverage). It explains that 'repo_slug' must be lowercase with no spaces, 'project_key' is optional, 'is_private' defaults to True, and 'description' is for repository description. This adds substantial value over the bare schema field names.
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 specific action ('Create a new Bitbucket repository') with the resource type, distinguishing it from sibling tools like 'update_repository' or 'delete_repository'. It uses precise language that leaves no ambiguity about the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'update_repository' or 'get_repository', nor does it mention prerequisites such as required permissions or project existence. It lacks context about when this operation is appropriate versus other repository-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?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions 'Confirmation of deletion' as a return, which hints at output, but lacks critical details: whether this is destructive (likely yes, but not stated), permission requirements, error conditions, or side effects. For a deletion tool, this is a significant gap in safety and operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured with a clear purpose statement followed by Args and Returns sections. Every sentence adds value: the first states the action, the second and third explain parameters, and the fourth describes output. No wasted words, and it's front-loaded with the core functionality.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (a deletion operation with 2 parameters), no annotations, and no output schema, the description is minimally adequate. It covers parameters well and hints at output, but lacks details on behavioral aspects like permissions, errors, or confirmation format. For a destructive tool, this leaves gaps that could hinder safe agent 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 description coverage is 0%, so the description must compensate. It adds meaningful context for both parameters: repo_slug is documented as 'Repository slug' and restriction_id is explained with 'from list_branch_restrictions', clarifying its source. This goes beyond the bare schema (which only has titles) and provides practical guidance, though it could detail formats or constraints further.
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 action ('Delete') and resource ('a branch restriction'), making the purpose immediately understandable. However, it doesn't differentiate this tool from other deletion tools like delete_group_permission or delete_repository, which would require mentioning the specific domain (branch management in version control).
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 referencing 'restriction_id (from list_branch_restrictions)', suggesting this tool should be used after listing restrictions. However, it doesn't explicitly state when to use this versus alternatives (e.g., update operations) or provide context about prerequisites beyond the ID reference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action ('Remove') but doesn't disclose critical traits: whether this is destructive (likely yes, but not confirmed), authentication requirements, error conditions (e.g., if permission doesn't exist), or side effects. The mention of 'Returns: Confirmation of removal' hints at output but lacks detail on format or success/failure indicators.
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 appropriately sized and front-loaded: the first sentence states the core purpose, followed by structured 'Args' and 'Returns' sections. Every sentence earns its place, though the 'Returns' line could be more informative (e.g., specifying response format). No redundant or verbose content is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (a destructive operation with 2 parameters), no annotations, and no output schema, the description is minimally adequate but has clear gaps. It covers the basic action and parameters but lacks behavioral context (e.g., permissions needed, idempotency) and detailed output information. For a deletion tool, this leaves the agent under-informed about risks and results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds semantic meaning by explaining that 'repo_slug' refers to a 'Repository slug' and 'group_slug' to a 'Group slug', clarifying these are identifiers rather than display names. However, it doesn't specify format constraints (e.g., alphanumeric) or provide examples, leaving some 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 clearly states the specific action ('Remove') and target ('a group's explicit permission from a repository'), distinguishing it from sibling tools like 'delete_user_permission' (which removes user permissions) and 'update_group_permission' (which modifies rather than removes). It precisely defines the verb+resource combination without being tautological.
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 doesn't mention prerequisites (e.g., needing admin access), when not to use it (e.g., for inherited permissions), or direct alternatives like 'update_group_permission' for modifying permissions instead of removing them. Usage is implied only by the action described.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states the basic action. It doesn't disclose behavioral traits like whether this is destructive (implied by 'delete' but not explicit), what permissions are required, if changes are reversible, or error conditions (e.g., if permission doesn't exist).
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 and Returns. It's front-loaded with the core purpose, though the return statement could be more specific (e.g., what format the confirmation takes).
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 destructive operation with no annotations and no output schema, the description is minimally adequate but lacks important context. It explains parameters well but doesn't cover behavioral aspects like permissions needed, side effects, or error handling, leaving gaps for safe usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaningful context for both parameters beyond the schema (which has 0% coverage). It clarifies that 'repo_slug' identifies the repository and 'selected_user' can be either an 'account_id' or 'UUID', which is crucial for correct usage.
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 ('Remove') and target ('user's explicit permission from a repository'), distinguishing it from sibling tools like 'delete_group_permission' or 'update_user_permission'. It specifies the exact resource being manipulated.
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 'update_user_permission' or 'delete_group_permission'. The description doesn't mention prerequisites, such as needing admin access or confirming the permission exists first.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions the tool lists comments with author, content, and timestamps, but lacks details on permissions, rate limits, pagination (beyond the limit parameter), error handling, or whether it's read-only. For a tool with no annotations, this leaves significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the core purpose, followed by parameter and return details. It uses minimal sentences efficiently, though the 'Args' and 'Returns' sections could be integrated more seamlessly into prose.
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 no annotations and no output schema, the description covers the basic purpose and parameters adequately but lacks behavioral context like safety, performance, or error details. It's complete enough for a simple read operation but misses nuances that would help an agent use it effectively in complex scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains all three parameters: 'repo_slug' (Repository slug), 'pr_id' (Pull request ID), and 'limit' (Maximum number of results with default). This adds clear meaning beyond the bare schema, though it could specify format details like slug structure.
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 specific action ('List comments') and resource ('on a pull request'), distinguishing it from sibling tools like 'get_pull_request' or 'add_pr_comment' which have different purposes. It precisely identifies what the tool does without being vague or tautological.
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 doesn't mention sibling tools like 'get_pull_request' (which might include comments) or 'list_pull_requests', nor does it specify prerequisites or contextual constraints. Usage is implied but not explicitly stated.
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. While it states this is a creation operation (implying mutation), it doesn't mention permission requirements, whether the operation is idempotent, what happens on conflicts, or any rate limits. The description provides basic functional information but lacks critical 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 well-structured with clear sections (Args, Returns) and uses bullet points effectively for the 'kind' parameter. While comprehensive, it maintains efficiency - every sentence adds value. The front-loaded purpose statement is clear, though the parameter explanations are necessarily detailed given the complexity.
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 6-parameter mutation tool with no annotations and no output schema, the description provides good parameter semantics but lacks behavioral context and usage guidance. The return statement is minimal ('Created restriction info with ID'), leaving the agent uncertain about the response format. While parameters are well-documented, other aspects remain incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates excellently by explaining all 6 parameters in detail. It provides semantic meaning for 'kind' with common values and examples, clarifies 'pattern' usage with examples, explains the relationship between 'branch_match_kind' and 'branch_type', and specifies when 'value' is needed. This adds substantial value beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Create a branch restriction/protection rule') and resource ('branch restriction'), distinguishing it from sibling tools like 'delete_branch_restriction' or 'list_branch_restrictions'. It provides a precise verb+resource combination that leaves no ambiguity about the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. While it's clear this creates restrictions (unlike 'delete_branch_restriction' which removes them), there's no mention of prerequisites, when this should be applied, or how it relates to other repository management tools in the sibling list. The agent receives no contextual usage 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?
No annotations are provided, so the description carries full burden. It states it 'Returns: List of CI/CD statuses' but lacks behavioral details such as whether this is a read-only operation (implied by 'Get'), rate limits, authentication requirements, error conditions, or pagination behavior (only mentions a default limit). This leaves significant gaps for safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the core purpose, followed by Args and Returns sections. Every sentence adds value without redundancy, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description provides basic purpose and parameter info but lacks behavioral context (e.g., safety, errors) and detailed return format. It's minimally adequate for a read operation but incomplete for reliable use, as it doesn't address key invocation aspects like authentication or rate limits.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explicitly lists all three parameters (repo_slug, commit, limit) with brief explanations, adding meaning beyond the schema's titles. However, it doesn't specify format details (e.g., commit hash length, repo_slug structure) or constraints, leaving some 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 clearly states the specific action ('Get build/CI statuses') and resource ('for a commit'), distinguishing it from siblings like get_commit (which retrieves commit details) or get_pipeline (which retrieves pipeline information). The verb 'Get' is precise and the scope is well-defined.
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. While the purpose is clear, there's no mention of prerequisites (e.g., needing repository access), exclusions, or comparisons to similar tools like get_pipeline (which might provide related CI/CD data).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states this is a creation operation but doesn't mention permission requirements, whether tags are immutable once created, rate limits, or what happens if a tag with the same name already exists. For a mutation tool with zero annotation coverage, this represents significant gaps in behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly structured and concise. It begins with a clear purpose statement, then provides organized parameter documentation with helpful examples, and ends with a brief returns statement. Every sentence earns its place with no wasted words or 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?
For a creation tool with 4 parameters, no annotations, and no output schema, the description provides good parameter documentation but lacks behavioral context. The 'Returns: Created tag info' is minimal but acknowledges output. However, without annotations covering safety, permissions, or side effects, and with no output schema, the description doesn't fully compensate for these structural gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides excellent parameter semantics despite 0% schema description coverage. It clearly explains each parameter's purpose: 'repo_slug: Repository slug', 'name: Tag name (e.g., "v1.0.0")', 'target: Commit hash or branch name to tag', and 'message: Optional tag message (for annotated tags)'. The examples and clarifications add substantial value beyond what the bare schema provides.
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 specific action ('Create a new tag') and resource ('in a repository'), distinguishing it from sibling tools like 'delete_tag' or 'list_tags'. It provides a complete verb+resource+scope statement that leaves no ambiguity about the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'create_branch_restriction' or 'create_commit_status', nor does it mention prerequisites or exclusions. While the purpose is clear, there's no contextual usage information to help an agent choose between similar creation tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly indicates this is a creation/mutation operation and mentions the default behavior for 'close_source_branch', but doesn't cover authentication requirements, error conditions, rate limits, or what happens if the source branch doesn't exist. It provides basic behavioral context but lacks completeness.
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 (Args, Returns) and uses bullet-like formatting for parameters. It's appropriately sized for a 6-parameter tool, though the 'Returns' section could be more detailed given the lack of output schema. Every sentence adds value with no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 6 parameters, no annotations, and no output schema, the description provides adequate parameter documentation but lacks important contextual information about authentication, error handling, and the full structure of returned data. The 'Returns' section mentions only 'id, url, and state' without specifying data types or additional fields that might be included.
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 value beyond the input schema, which has 0% description coverage. It explains each parameter's purpose with examples (e.g., 'repo_slug: Repository slug (e.g., "anzsic_classifier")') and clarifies default values and formats (e.g., 'description: PR description in markdown'), fully compensating for the schema's lack of documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Create a pull request') and target resource ('in a Bitbucket repository'), distinguishing it from sibling tools like 'merge_pull_request' or 'get_pull_request' that perform different operations on pull requests. It provides a complete verb+resource+scope specification.
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 'create_branch_restriction' or 'create_commit_status', nor does it mention prerequisites or conditions for successful use. It simply states what the tool does without contextual usage 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, so the description carries the full burden. It mentions the action ('Decline') which implies a mutation, but does not disclose behavioral traits such as required permissions, whether the action is reversible, or any side effects. This is a significant gap for a mutation tool with zero annotation coverage.
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 the core purpose in the first sentence, followed by structured sections for Args and Returns. Every sentence earns its place with no wasted words, making it highly efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description is adequate but has clear gaps. It covers the purpose and parameters well, but lacks details on behavioral aspects like permissions, side effects, or return value structure, which are important for safe usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description explicitly lists and names both parameters ('repo_slug', 'pr_id') in the Args section, adding meaning beyond the bare schema. It compensates well for the low coverage, though it could provide more context on parameter formats or examples.
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 specific action ('Decline (close without merging)') and resource ('a pull request'), distinguishing it from sibling tools like 'merge_pull_request' and 'approve_pr'. It uses precise terminology that conveys the exact operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for closing pull requests without merging, but does not explicitly state when to use this versus alternatives like 'merge_pull_request' or 'request_changes_pr'. It provides basic context but lacks explicit guidance on exclusions 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 full burden of behavioral disclosure. It adds useful context like fuzzy matching for 'search', advanced query syntax examples for 'query', and default/max values for 'limit'. However, it doesn't cover important aspects like pagination behavior, rate limits, authentication requirements, or error handling, leaving gaps for a tool with search/list functionality.
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 and Returns, and each sentence adds value. It's appropriately sized for a tool with 4 parameters and search functionality, though the 'query' examples could be slightly more concise. The purpose statement is front-loaded, making it easy to understand quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (search/list with 4 parameters), no annotations, and no output schema, the description is moderately complete. It covers parameter semantics well but lacks details on behavioral aspects like pagination, rate limits, or authentication. The return value description ('List of repositories with basic info') is vague without an output schema, leaving uncertainty about what 'basic info' includes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides extensive parameter semantics beyond the input schema, which has 0% description coverage. It explains optional filtering with 'project_key', details fuzzy matching for 'search', gives multiple examples for 'query' syntax, and specifies default and maximum values for 'limit'. This fully compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
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 as 'List and search repositories in the workspace,' which includes both listing and searching functionality. It distinguishes itself from siblings like 'get_repository' (singular) and 'list_projects' (different resource), but could be more explicit about how it differs from other list/search tools like 'list_pull_requests' or 'list_branches'.
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 parameter explanations (e.g., 'search' for fuzzy matching, 'query' for advanced syntax), but lacks explicit guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, such as needing workspace access, or compare it to similar tools like 'list_projects' or 'get_repository' for specific use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states the action ('Remove your approval') which implies a mutation operation, but doesn't mention authentication requirements, permission levels needed, rate limits, or whether the action is reversible. The description provides basic behavioral information but lacks important operational details.
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 perfectly structured and front-loaded: purpose statement first, then parameters, then return value. Every sentence earns its place with zero wasted words. The three-part structure (action, args, returns) is efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description provides basic purpose and parameter information but lacks details about authentication, permissions, error conditions, or the exact format of the return confirmation. It's minimally adequate but has clear gaps for operational use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by clearly explaining both parameters in the Args section: 'repo_slug: Repository slug' and 'pr_id: Pull request ID'. This adds meaningful context beyond the bare schema, though it doesn't provide format examples or validation rules.
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 specific action ('Remove your approval') and resource ('from a pull request'), distinguishing it from sibling tools like 'approve_pr' and 'decline_pr'. It uses precise language that directly communicates the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context (when you want to retract approval from a PR you previously approved) but doesn't explicitly state when to use this vs alternatives like 'decline_pr' or 'request_changes_pr'. No explicit exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively communicates that this is a write operation ('Create') and includes a critical behavioral note about secured variables ('cannot be read back from the API'). However, it omits other important details like authentication requirements, rate limits, error conditions, or whether the operation is idempotent.
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 efficiently structured with a clear purpose statement followed by organized sections for arguments and returns. Every sentence adds value: the first establishes the tool's function, the argument explanations provide necessary context, and the return statement clarifies output expectations. No wasted words or 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?
Given the tool's complexity (a write operation with 4 parameters), absence of annotations, and no output schema, the description does an adequate but incomplete job. It covers the basic creation functionality and parameter semantics well, but lacks information about authentication, error handling, permissions, or what the 'Created variable info with UUID' actually contains, leaving gaps for the agent.
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 significant semantic value beyond the input schema, which has 0% description coverage. It explains that 'key' represents variable names with concrete examples ('PYPI_TOKEN', 'AWS_SECRET_KEY'), clarifies that 'secured' determines encryption with a default value and important consequence ('cannot be read back'), and provides context for 'repo_slug' and 'value' parameters that the schema lacks entirely.
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 specific action ('Create a pipeline variable') and identifies the resource ('pipeline variable'), making the purpose immediately apparent. It distinguishes itself from siblings like 'update_pipeline_variable' and 'delete_pipeline_variable' by focusing on creation rather than modification or deletion.
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 'update_pipeline_variable' or 'get_pipeline_variable'. It lacks context about prerequisites (e.g., needing repository access) or typical use cases, offering only basic functional information without strategic direction.
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 discloses that the tool creates a webhook (implying a write operation) and returns created webhook info with UUID, which adds some behavioral context. However, it lacks details on permissions needed, rate limits, error conditions, or whether the operation is idempotent, leaving gaps 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 well-structured with a clear purpose statement followed by Args and Returns sections. It's appropriately sized with no redundant information. Minor deduction because the events list could be slightly more concise, but overall it's efficient and 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 no annotations and no output schema, the description does a good job explaining parameters and return value. It covers the core functionality adequately for a creation tool. However, it lacks some contextual details like authentication requirements or error handling, preventing a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It provides clear semantics for all 5 parameters: repo_slug, url, events (with examples), description (optional), and active (default). This adds significant value beyond the bare schema, explaining usage and common event types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'create' and resource 'webhook for a repository', making the purpose specific and unambiguous. It distinguishes from sibling tools like 'delete_webhook' and 'list_webhooks' by focusing on creation rather than deletion or listing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., repository access), compare with similar tools (e.g., 'update_user_permission' for other configurations), or specify when webhook creation is appropriate versus other notification methods.
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 indicates this is a creation/mutation operation ('Create'), but doesn't disclose permission requirements, rate limits, side effects, or what 'Created status info' contains. The description adds basic behavioral context but lacks important operational details for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and appropriately sized. It starts with the core purpose, provides usage context, then documents parameters clearly in a formatted section, and ends with return information. Every sentence earns its place without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 7 parameters, no annotations, and no output schema, the description provides good parameter documentation but lacks important behavioral context. The 'Returns' section is vague ('Created status info'), and there's no information about permissions, error conditions, or system constraints that would be important for a CI/CD integration tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by providing detailed parameter documentation in the Args section. It explains each parameter's purpose, provides enum values for 'state', notes optional parameters, and gives examples like 'my-ci-system' for the key parameter. This adds significant value beyond the bare 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 the tool's purpose as 'Create a build status for a commit' with the specific verb 'create' and resource 'build status', distinguishing it from sibling tools like get_commit_statuses (which retrieves rather than creates). However, it doesn't explicitly differentiate from all sibling tools beyond this basic distinction.
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 with 'Use this to report CI/CD status from external systems,' giving a specific use case. It doesn't mention when NOT to use it or name explicit alternatives, but the context is sufficient for understanding its primary application.
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 states the tool retrieves status information, which implies a read-only operation, but does not specify authentication needs, rate limits, error conditions, or whether it's idempotent. For a tool with zero annotation coverage, this leaves significant gaps in understanding its 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 front-loaded with the core purpose in the first sentence, followed by structured sections for Args and Returns. Each sentence earns its place by providing essential information without redundancy, making it efficient and well-organized.
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 no annotations and no output schema, the description does a decent job by explaining parameters and return values. However, it lacks details on behavioral aspects like error handling or authentication, and the return description ('Pipeline status including state, duration, and steps') is somewhat vague without an output schema. It's adequate but has clear gaps for a tool with 2 parameters and no structured support.
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 input schema, which has 0% description coverage. It explains that 'repo_slug' is a repository slug and 'pipeline_uuid' is a Pipeline UUID from 'trigger_pipeline', clarifying the source and purpose of both parameters. This compensates fully for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Get status') and resource ('pipeline run'), distinguishing it from sibling tools like 'list_pipelines' (which lists pipelines) and 'get_pipeline_logs' (which retrieves logs). It precisely defines the tool's function without being vague or tautological.
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 context by mentioning 'pipeline_uuid (from trigger_pipeline)', suggesting it should be used after triggering a pipeline. However, it does not explicitly state when to use this tool versus alternatives like 'list_pipelines' or 'stop_pipeline', nor does it provide exclusions or prerequisites beyond the implied UUID source.
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. It discloses the tool's conditional behavior (returns logs or steps list based on step_uuid), which is helpful. However, it lacks details on permissions, rate limits, error handling, or output format, leaving gaps for a mutation-like read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the core purpose, followed by clear sections for arguments and returns. Every sentence adds value without redundancy, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description does a decent job but has gaps. It explains the tool's conditional behavior and parameters well, but doesn't cover return formats, error cases, or system constraints. For a tool with 3 parameters and conditional outputs, more completeness would be beneficial.
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 significant meaning beyond the input schema, which has 0% description coverage. It explains each parameter's role: repo_slug and pipeline_uuid as required identifiers, and step_uuid as optional with guidance to 'get from steps list first.' This fully compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
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: 'Get logs for a pipeline run.' It specifies the resource (pipeline logs) and the action (get). However, it doesn't explicitly differentiate from sibling tools like 'get_pipeline' or 'list_pipelines', which reduces it from a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage guidance: 'If step_uuid is not provided, returns list of steps to choose from.' This explains when to use it with or without the optional parameter. It doesn't mention alternatives or exclusions, but the context is well-defined.
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 mentions the return format ('List of tags with name, target commit, and tagger info'), which adds value beyond the input schema. However, it lacks details on permissions, rate limits, or pagination behavior, leaving gaps for a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the core purpose, followed by clear sections for arguments and returns. Every sentence adds value without redundancy, making it efficient and easy 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?
Given no annotations and no output schema, the description provides a solid foundation by explaining the purpose, parameters, and return format. It covers the essentials for a simple list operation but could improve by addressing behavioral aspects like error handling or authentication needs, which are missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, so the description must compensate. It explains both parameters: 'repo_slug' as the repository identifier and 'limit' with its default value and purpose ('Maximum number of results'). This adds meaningful semantics beyond the bare schema, though it could include more details like format constraints for 'repo_slug'.
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 with a specific verb ('List') and resource ('tags in a repository'), distinguishing it from sibling tools like 'list_branches' or 'list_commits' that list different repository elements. It precisely defines what is being listed without ambiguity.
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 tags in a repository, but it does not explicitly state when to use this tool versus alternatives (e.g., 'list_branches' for branches or 'get_tag' for a specific tag). It provides basic context but lacks guidance on exclusions 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 full burden. It discloses the read-only nature through 'List' and specifies the return format (URL, events, status), but lacks details on permissions, rate limits, error handling, or pagination behavior. It adds some behavioral context but not comprehensively.
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 and front-loaded with the core purpose, followed by clear sections for arguments and returns. Every sentence adds value without redundancy, making it efficient and easy 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?
Given no annotations and no output schema, the description provides a solid foundation: purpose, parameters, and return format. However, it lacks details on authentication, error cases, or pagination for large result sets, which would enhance completeness for a list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains both parameters: 'repo_slug' as the repository slug and 'limit' as the maximum number of results with a default value. This adds meaningful semantics beyond the bare schema, though it could detail format constraints for 'repo_slug'.
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 specific action ('List webhooks') and resource ('configured for a repository'), distinguishing it from sibling tools like 'create_webhook', 'delete_webhook', and 'get_webhook'. It precisely defines the scope of the operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when needing to retrieve webhooks for a specific repository, but it does not explicitly state when to use this tool versus alternatives like 'get_webhook' (for a single webhook) or 'create_webhook'. No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It correctly implies this is a mutation tool (updating settings), but doesn't mention important behavioral aspects like required permissions, whether changes are reversible, rate limits, or what happens to existing settings not mentioned. The description adds basic context about what can be updated but lacks richer behavioral context needed for a mutation tool with zero annotation coverage.
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 purpose statement, usage guidance, and organized parameter documentation. It's appropriately sized for a tool with 5 parameters, though the 'Args:' and 'Returns:' sections could be more integrated with the natural language description rather than appearing as separate documentation blocks.
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 mutation tool with 5 parameters, no annotations, and no output schema, the description provides adequate coverage of what the tool does and what parameters mean. However, it lacks important context about behavioral aspects (permissions, side effects, error conditions) and doesn't describe the return value beyond 'Updated repository info' - a significant gap given the absence of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides excellent parameter semantics beyond the input schema, which has 0% description coverage. It explains what each parameter does with concrete examples (e.g., 'Repository slug (e.g., "anzsic_classifier")', 'Move to different project (optional, e.g., "DS")'), clarifies which parameters are optional, and maps them to specific update operations. This fully compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'update' and the resource 'repository settings', specifying the exact fields that can be modified (project, visibility, description, name). It distinguishes this tool from sibling tools like 'create_repository' and 'delete_repository' by focusing on modification rather than creation or deletion.
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 ('Use this to move a repository to a different project, change visibility, update description, or rename the repository'), which covers the main use cases. However, it doesn't explicitly mention when NOT to use it or name specific alternatives among the sibling tools (e.g., when to use 'update_repository' vs 'update_group_permission').
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 the tool's behavior by stating it 'see files changed' and returns 'Diff statistics,' indicating a read-only operation with specific output. However, it doesn't mention potential limitations like rate limits, authentication needs, or error conditions, leaving gaps for a mutation-free but potentially complex 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 and front-loaded with the core purpose, followed by clear 'Args' and 'Returns' sections. Every sentence earns its place by providing essential information without redundancy, making it efficient and easy 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?
Given no annotations, no output schema, and 3 parameters, the description is largely complete: it explains the purpose, parameters, and return value. However, it lacks details on output format (e.g., structure of diff statistics) and behavioral aspects like error handling, which could be useful for a tool with no structured output documentation.
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 schema description coverage is 0%, so the description must compensate. It provides detailed semantics for all three parameters: 'repo_slug: Repository slug,' 'base: Base commit hash or branch name,' and 'head: Head commit hash or branch name,' adding crucial meaning beyond the schema's basic titles. This fully addresses the coverage gap.
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: 'Compare two commits or branches and see files changed.' It specifies the verb ('compare'), resources ('commits or branches'), and output ('files changed'), distinguishing it from siblings like get_commit (single commit) or get_pr_diff (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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by specifying it compares 'two commits or branches,' but it doesn't explicitly state when to use this tool versus alternatives like get_pr_diff (for pull requests) or list_commits (for listing without comparison). It provides clear input requirements but lacks explicit when/when-not 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 provided, the description carries the full burden of behavioral disclosure. It effectively communicates the destructive nature ('irreversible') and the required parameter ('repo_slug'), though it lacks details on permissions, error conditions, or what 'Success status' entails. The warning adds critical context beyond basic function.
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 the core purpose, followed by a critical warning, and then structured sections for Args and Returns. Every sentence earns its place—no wasted words—making it highly efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's high complexity (destructive operation), lack of annotations, and no output schema, the description is somewhat incomplete. It covers the irreversible nature and parameter basics but omits details on permissions, error handling, or the structure of the return value ('Success status'), leaving gaps for safe agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning by specifying that 'repo_slug' is the 'Repository slug to delete', which clarifies the parameter's role beyond the schema's basic title ('Repo Slug'). With 0% schema description coverage and only one parameter, this compensates adequately, though more detail on format or examples would be beneficial.
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 specific action ('Delete') and resource ('a Bitbucket repository'), distinguishing it from sibling tools like 'create_repository' or 'update_repository'. It uses precise language that leaves no ambiguity about the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context with the 'WARNING: This action is irreversible!' statement, which implicitly guides when to use this tool (for permanent deletion) versus alternatives like 'update_repository' for modifications. However, it doesn't explicitly name alternatives or specify prerequisites beyond the warning.
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 discloses key behavioral traits: the read-only nature ('Get', 'Read'), the no-clone constraint, and error conditions for binary/not-found files. However, it lacks details on authentication requirements, rate limits, response formats beyond 'text', or handling of large files.
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 efficiently structured with a clear purpose statement followed by organized sections for Args and Returns. Every sentence adds value: the first establishes context, the second adds behavioral constraint, and the parameter/return details are essential for understanding. 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?
For a read operation with no annotations and no output schema, the description provides good coverage: purpose, usage context, parameter semantics, and return behavior. It lacks only minor details like authentication needs or exact error formats, but is largely 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.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant meaning beyond the 0% schema coverage. It explains all three parameters: repo_slug ('Repository slug'), path with examples ('File path (e.g., "src/main.py", "README.md")'), and ref with default and format ('Branch, tag, or commit hash (default: "main")'). This fully compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Get the content of a file') and resource ('from a repository'), distinguishing it from sibling tools like list_directory (which lists files) or get_commit (which retrieves commit data). It precisely defines the tool's scope as reading file contents without cloning.
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 ('Read file contents without cloning the repository'), which implicitly distinguishes it from operations that require repository cloning. However, it doesn't explicitly mention when NOT to use it or name specific alternatives like list_directory for browsing or get_commit for metadata.
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 for behavioral disclosure. It adequately describes the core behavior (listing directory contents) and mentions the 'without cloning' constraint, which is useful context. However, it doesn't disclose important behavioral traits like whether this is a read-only operation (implied but not stated), potential rate limits, authentication requirements, error conditions, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly structured and concise. It begins with the core purpose, adds important context in the second sentence, then provides well-organized parameter and return value documentation. Every sentence earns its place, with no wasted words or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (4 parameters, no output schema, no annotations), the description is quite complete. It covers purpose, usage context, all parameters with semantics, and return value format. The main gap is the lack of output schema, so the description must describe returns - which it does adequately but could benefit from more detail about the structure of the returned list.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides excellent parameter semantics despite 0% schema description coverage. It clearly explains all 4 parameters: 'repo_slug' (Repository slug), 'path' (Directory path with special case for root), 'ref' (Branch/tag/commit with default), and 'limit' (Maximum entries with default). This fully compensates for the lack of schema descriptions and adds meaningful context beyond just parameter names.
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 with specific verbs ('List contents', 'Browse repository structure') and resources ('directory in a repository'). It distinguishes itself from siblings like 'get_file_content' by focusing on directory listing rather than file content retrieval, and from 'list_repositories' by operating within a specific repository's directory structure.
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 about when to use this tool ('Browse repository structure without cloning'), which implicitly suggests it's for exploration rather than file operations. However, it doesn't explicitly state when NOT to use it or name specific alternatives among the many sibling tools (like 'get_file_content' for individual files or 'list_repositories' for repository-level listing).
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-server-bitbucket MCP server](https://glama.ai/mcp/servers/JaviMaligno/mcp-server-bitbucket/badges/card.svg)](https://glama.ai/mcp/servers/JaviMaligno/mcp-server-bitbucket)

Score Badge

Copy to your README.md:

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

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/JaviMaligno/mcp-server-bitbucket'

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