bitbucket-mcp

by lawp09

Overview Schema Related Servers Score Discussions

Python

Remote

Server Quality Checklist

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

Latest release: v1.25.0
Disambiguation4/5
Most tools have clearly distinct purposes (e.g., get vs list vs create for PRs, comments, tasks, issues). The main ambiguity is between approving/requesting changes on a PR vs the similar unapprove/unrequest pairs, but descriptions clarify well. One minor overlap: `create_pull_request` and `create_draft_pull_request` could be a single tool with a draft flag, but they are still distinguishable.
Naming Consistency3/5
The server mostly uses verb_noun pattern (e.g., list_repositories, get_pull_request), but there are deviations like 'submit_pull_request_batch_review' (verb_adj_noun_noun), 'suggest_pull_request_reviewers' (verb_noun_noun), and 'get_effective_default_reviewers' (verb_adj_adj_noun). Most names are readable, but the inconsistency in adjective and compound noun placement prevents a higher score.
Tool Count2/5
With 74 tools, the server is significantly over-scoped for a single MCP. Bitbucket is a large platform, but 74 tools cover many distinct sub-domains (PRs, issues, pipelines, commits, deployments, permissions, etc.) that could be split into multiple servers. While each tool has a specific purpose, the sheer count will likely confuse agents navigating the list.
Completeness3/5
The server covers PR lifecycle well (create, update, approve, decline, review, comments, tasks), issues (CRUD + comments), and pipelines (list, get, run, steps, logs). However, there are notable gaps: no tool for creating/updating/deleting deployment variables, no webhook management, and no branch management (create/delete branches). The breadth without full depth for each sub-domain leaves some dead ends.
Average 4.1/5 across 73 of 74 tools scored. Lowest: 3/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 22 commits in the last 12 weeks
- Last stable release on August 12, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

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

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

How is the quality score calculated?

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

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

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

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

Tool Scores

Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true (destructive action) and idempotentHint=true (safe to retry). The description adds no further behavioral context, such as permanence or required permissions. While there is no contradiction, the description misses the opportunity to elaborate on effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and front-loaded, with a clear first sentence. However, it is overly minimal, sacrificing necessary detail for brevity.
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 destructive nature (desctructiveHint=true) and the existence of an output schema, the description lacks important context such as what happens after deletion, required permissions, error conditions, and the effect on the pull request. It is incomplete for safe usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% with no parameter descriptions in the schema. The description lists parameter names but provides no additional meaning, examples, formats, or constraints. It fails to compensate for the lack of schema 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 action (delete) and the resource (a task on a pull request). This distinguishes it from siblings like create_pull_request_task and update_pull_request_task.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor are there any prerequisites, when-not-to-use conditions, or exclusions mentioned. The agent has no context for appropriate 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?
Annotations already indicate this is non-destructive and idempotent. The description adds no behavioral context such as permissions, side effects, or that resolving collapses comments. It does not contradict annotations but provides no extra value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and to the point, listing arguments and return type without extraneous text. However, more detail could be included without sacrificing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description meets basic needs but lacks context about what resolving means (e.g., marks comment as resolved, hides it). The output schema exists, so return details are not necessary, but the overall completeness is minimal.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description merely repeats parameter names without defining their purpose or format. For example, 'comment_id' is ambiguous—could be a numeric ID or a UUID. No added semantics.
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 explicitly states 'Resolve a comment on a pull request.' The name and title are clear, and the sibling tools include 'reopen_pull_request_comment' and 'delete_pull_request_comment', distinguishing this action as resolution.
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. No context about prerequisites or typical scenarios. The description only lists parameters without any usage 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?
Annotations indicate a mutation (readOnlyHint=false) but the description lacks details on side effects (e.g., triggering CI, handling duplicates) or error conditions beyond the action of creating.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and lists parameters cleanly, though the docstring format adds minor 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?
Output schema exists so return details are covered; however, behavioral context (e.g., assumed permissions, branch state) is missing, leaving the description moderately complete for a complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds meaning for parameters like draft default and workspace fallback, but leaves source_branch and target_branch with only names, lacking format or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Create') and resource ('pull request'), distinguishing it from siblings like create_draft_pull_request and approve_pull_request.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., create_draft_pull_request) or prerequisites like branch existence or repository permissions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, and the description confirms a mutation action. However, it adds no further behavioral context (e.g., whether the PR can be reopened, impact on comments, or required permissions). The description is minimal beyond stating the action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: four sentences covering the action, all parameters, and return value. No redundant information, efficiently structured with Args and Returns sections.
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 destructive nature and four parameters, the description covers the basic use case but omits important details like what happens if the PR is already declined, and how 'decline' differs from 'close' or 'reject'. The output schema exists but is not elaborated in the description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains each parameter: repo_slug, pull_request_id, workspace (optional, defaults to configured workspace), and message (optional reason). This adds meaningful context beyond the schema's type definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Decline a pull request,' which is a clear verb+resource pairing. It distinguishes from sibling tools like approve_pull_request and unapprove_pull_request, but does not elaborate on what 'decline' means (e.g., closing without merging).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as request_changes_pull_request or unapprove_pull_request. The description does not mention appropriate contexts, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and idempotentHint=true. Description adds no further behavioral traits (e.g., irreversibility, permissions, side effects).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise with bullet points for args and a return statement. No unnecessary words, front-loaded with the action. Could be more structured but is effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete mutation with 4 params and annotations, the description is adequate but lacks details like prerequisites or effects. Output schema exists but return is only 'Success message'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It provides basic explanations for all 4 parameters (e.g., 'Repository slug'), but these are minimal and lack detail beyond the parameter name.
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 the resource 'comment on a pull request'. It distinguishes from sibling tools by the verb, but does not explicitly differentiate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like update_pull_request_comment or resolve_pull_request_comment. Does not mention when not to use or provide context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true and destructiveHint=false, and the description adds minimal context ('reopen/unresolve'). It does not disclose auth requirements, rate limits, or side effects beyond the operation. With annotations, the bar is lowered, but the description adds limited value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a single paragraph followed by Args and Returns sections. Every sentence is necessary, though no structured breakdown beyond that.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the tool is simple and annotations plus output schema exist, the description fails to provide sufficient parameter semantics, which is critical given 0% schema coverage. The return value is vague ('Success message').
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must fully explain parameters. It only lists parameter names without any additional meaning or syntax. The schema also lacks descriptions, making the parameters ambiguous.
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 'reopen( unresolve) a comment on a pull request,' using a specific verb and resource. It distinguishes itself from sibling tools like resolve_pull_request_comment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit guidance on when to use this tool versus alternatives. The context of being the inverse of resolve is implied but not stated. No when-not or alternative naming is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no behavioral annotations beyond readOnlyHint=false, the description carries the burden but only adds the error case for disabled issue trackers. It fails to disclose idempotency, permission requirements, or consequences of invalid inputs, leaving 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is somewhat verbose, listing all parameters in an Args section that largely duplicates the input schema. While structured with Args and Returns sections, it could be trimmed to more succinctly convey essential info 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 the output schema exists, the description appropriately mentions a specific error case. However, it lacks broader context such as authentication requirements, rate limits, or how this tool fits among siblings (e.g., vs. pull request creation). It is minimally complete for a resource creation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, requiring the description to compensate. The description provides basic parameter types and optional status but adds minimal insight beyond the schema (e.g., 'markdown' for content, examples for kind/priority, default for workspace). It does not fully compensate 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 'Create a new issue in a repository's issue tracker.' This uses a specific verb ('Create') and resource ('issue') and effectively distinguishes from siblings like update_issue, get_issue, and list_issues.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides parameter details but does not explicitly guide when to use this tool versus alternatives (e.g., create_pull_request, update_issue). Usage context is implied through the purpose statement, but no when-not-to-use or alternative references are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint, idempotentHint, and non-destructive behavior. The description adds a required OAuth scope, which is a behavioral constraint. However, it does not disclose potential errors or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: purpose first, then OAuth requirement, followed by parameter list in a clear docstring format. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool and presence of annotations and output schema, the description covers basic needs. However, it omits guidance on differentiating from the sibling get_deployment, which is a notable gap for agent decision-making.
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?
With 0% schema description coverage, the description provides basic meanings for each parameter (e.g., 'repository slug', 'environment UUID', and 'workspace name (optional, defaults to configured workspace)'). This adds value but lacks format constraints or relational context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a single deployment environment. While it distinguishes from list_environments, it does not differentiate from the sibling get_deployment, leaving ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like list_environments or get_deployment. Only an OAuth scope requirement is mentioned, which is minimal 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?
Annotations (all false) provide no behavioral hints, and the description only states 'Create' without elaborating on idempotency, side effects, or required permissions. No additional 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 brief with a one-sentence summary followed by a structured Args/Returns list. It is efficient, though the Args section could be more compact; still, no unnecessary content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description covers parameter meanings and return type, it lacks context on error conditions, required permissions, or behavior when the PR or comment does not exist. The output schema exists but the description's 'Created task details' is vague. Adequate but with gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema coverage, the description's Args section adds meaningful descriptions for each parameter (e.g., 'Task content in markdown format' for content). All 5 parameters are explained, compensating 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 action ('Create') and the resource ('a task on a pull request'), with the optional linkage to a comment. It distinguishes from sibling tools like delete_pull_request_task or update_pull_request_task by focusing on creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., update_pull_request_task for modifications). No mention of prerequisites like write access or that the PR must exist.
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?
Annotations already convey idempotence and non-destructive nature. The description adds the error case for missing issue tracker, but does not disclose other potential behaviors like permissions required or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with 'Args' and 'Returns' sections, and each line serves a purpose. It is appropriately sized for the tool's 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?
Parameters are explained, and an error case is noted. However, it lacks information about what happens when the comment doesn't exist, and could benefit from examples or more detail on the return structure.
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 each parameter with a brief explanation, such as 'content: New comment content in markdown'. Given the schema has 0% parameter descriptions, this basic explanation is helpful but lacks deeper details like format constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update a comment on an issue', using a specific verb and resource. This distinguishes it from siblings like add_issue_comment (add vs update) and get_issue_comment (read vs update).
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. It does not mention when not to use it or provide any context about prerequisites or conditions.
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?
Annotations indicate non-read-only and non-destructive (create). The description adds that draft PRs are not for review, but no additional behavior like authorization or side effects. Contradiction is false.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is very concise: one-sentence summary, then an Args block with all parameters, and a Returns line. Front-loaded, no unnecessary text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema (not shown but noted as present), the return value is covered structurally. The description covers the tool's action and parameters adequately, though it omits error conditions and branch existence assumptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description carries full burden. It lists each parameter with a brief label (e.g., 'Source branch name') and some extras (default for workspace, list of UUIDs for reviewers). This adds meaning beyond the schema property titles.
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 creates a draft pull request and distinguishes it from a regular PR by noting draft PRs are not ready for review. However, it does not explicitly contrast with the sibling tool 'create_pull_request'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., create_pull_request). No when-not-to-use or prerequisite info. The description only states the function.
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?
Annotations (readOnlyHint, idempotentHint, destructiveHint) already declare the tool's safety and idempotence. The description adds 'Returns: Repository information' but no additional behavioral context (e.g., rate limits, required permissions). With annotations covering the main traits, a score of 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a one-line purpose, followed by clear Args and Returns sections. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with two parameters and an existing output schema, the description covers the essential information. It explains parameters and return type. However, it could briefly mention the scope (e.g., 'for a specified repository') to improve clarity.
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 explains both parameters: 'repo_slug: Repository slug' and 'workspace: Workspace name (optional, defaults to configured workspace)'. This adds meaning beyond the schema's bare types and names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get repository details', identifying the verb and resource. However, it does not distinguish this tool from many other sibling 'get_*' tools (e.g., get_commit, get_issue), making it less specific for the agent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like get_commit or list_repositories. There is no mention of prerequisites, contexts, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate idempotent and non-destructive. Description adds the state transition from DRAFT to OPEN, which is useful beyond annotations. However, it doesn't mention potential side effects like notifications or required permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise—one line for purpose, then clear Args/Returns. Front-loaded with the core action. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple state-change tool, the description covers the basic functionality. Output schema is mentioned but not detailed. Parameter descriptions are lacking, but overall adequate for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and description only lists parameter names with brief defaults. No additional meaning or validation details are provided beyond what the schema already has.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Publish a draft pull request (convert DRAFT to OPEN)' with a specific verb and resource. Distinguishes from sibling tools like create_pull_request and decline_pull_request.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use vs alternatives. The description implies use when a draft PR is ready to be opened, but lacks context such as prerequisites or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true. The description adds the behavioral fact that it removes a specific status and returns a success message. No contradictions, but limited additional context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and structured with Args and Returns sections. However, the Args list repeats schema info without adding value. Could be more informative without being verbose.
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 mutation tool, the description covers the basic action and required parameters. However, given low schema coverage and no output schema details in description, it lacks completeness in explaining the exact outcome or conditions (e.g., PR must have 'request changes' status).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It lists parameter names but adds only minimal extra meaning (workspace defaults to configured workspace). No details on format, constraints, or usage beyond 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 action ('Remove 'request changes' status') and the resource ('a pull request'). It distinctly differentiates from sibling tools like request_changes_pull_request (adds status) and approve_pull_request.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context (after requesting changes) but does not explicitly state when to use, when not, or provide alternatives. No guidance on prerequisites or conditions.
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?
Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds no additional behavioral context (e.g., permissions, rate limits). Aligns with annotations but adds no extra value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Short and includes Args/Returns sections. However, Returns section is vague ('Pipeline run details') and doesn't add value since output schema exists. Could be more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get tool with output schema, description covers parameter semantics adequately. Lacks usage context or prerequisites, but overall complete for basic functionality.
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?
Input schema has 0% description coverage. Description provides one-line explanations for all three parameters, including default behavior for optional workspace. Adds significant meaning beyond 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?
Clearly states 'Get details for a specific pipeline run', which specifies verb (get), resource (pipeline run), and specificity (specific). Distinguishes from sibling 'list_pipeline_runs'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance. No mention of alternatives among many sibling tools. Only provides parameter descriptions.
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?
Annotations indicate read-only and idempotent. Description adds 'Returns: Comment details with resolution status,' providing more context on what the tool outputs. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise: one sentence for purpose, then Args list, then Returns. No fluff. Front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters with no schema descriptions, the description should compensate more. It lists them but adds no further detail. Output schema exists, so return values need less explanation, but still incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Description lists parameters but only restates names (e.g., 'repo_slug: Repository slug') without additional meaning. Schema coverage is 0%, and description provides no extra constraints, 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?
Clearly states 'Get a specific comment on a pull request,' specifying verb and resource. Distinguishes from sibling tools like get_issue_comment or get_commit_comment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. Does not mention context or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and destructiveHint=false. The description aligns with these, adding that the operation triggers a new run and returns details. However, it does not disclose potential failures, prerequisites (e.g., pipeline config must exist), or side effects such as rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact with a one-line purpose followed by a clear args/returns list. Every sentence is necessary, and the structure is well-organized for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While an output schema exists, the description lacks critical context for a mutation tool: it does not mention prerequisites (e.g., repository existing, branch having pipeline config), error scenarios, or the scope of impact. This leaves 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?
Despite 0% schema description coverage, the description provides meaningful explanations for each parameter: repo_slug as 'Repository slug', branch as 'Branch name', and workspace as optional with a default. This adds clarity beyond the property 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 triggers a new pipeline run on a branch. The verb 'trigger' and resource 'pipeline run' are specific, and the context 'on a branch' distinguishes it from list or get pipeline tools among siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like list_pipeline_runs or get_pipeline_config. The description simply states what it does without advising on appropriate conditions or excluding other scenarios.
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?
Annotations already indicate idempotency and non-destructiveness. The description adds that it returns 'Approval details' but does not elaborate on side effects (e.g., notifications, state changes) or behavior on duplicate approvals, which is acceptable given 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?
Extremely concise: one-sentence purpose followed by a clear arg list. No unnecessary words, front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having output schema, the description only says 'Approval details' without specifics. It omits operational context like required permissions or workflow steps (e.g., review submission). Annotations cover safety, but completeness for a mutation tool could be improved.
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 listing and explaining each parameter (e.g., 'repo_slug: Repository slug', 'workspace: Workspace name (optional, defaults to configured workspace)'). It adds meaning beyond schema titles but lacks format hints or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Approve a pull request.' clearly states the action and resource. It distinguishes from sibling tools like 'decline_pull_request', 'unapprove_pull_request', and 'request_changes_pull_request'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage 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. No prerequisites (e.g., user must be a reviewer, PR must be open) or exclusions are mentioned, leaving the agent to infer 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, indicating a safe read operation. The description does not contradict these and adds minimal behavioral context (e.g., it mentions the comment is on a commit, but no additional traits like caching or rate limits). With rich annotations, the bar is lower, and the description adds some value by clarifying the scope.
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 8 lines, with the main purpose in the first line. The Args section is structured and clear. However, the 'Returns: Commit comment details' line is redundant because an output schema exists, adding unnecessary verbiage. Overall, it is well-organized 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 the moderate complexity (4 params, 3 required) and the presence of an output schema and rich annotations, the description is largely complete. It explains all parameters and their optionality. It does not explain how to obtain the comment ID or hash, but that is external knowledge. With output schema handling the return value, the description adequately covers the tool's interface.
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 add meaning. It lists all parameters in the Args section with brief explanations (e.g., 'commit: Commit hash', 'workspace: Workspace name (optional, defaults to configured workspace)'). While basic, this provides essential context missing from the schema titles. However, it lacks format details (e.g., hash length, comment ID format), so it is adequate but not comprehensive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get a specific comment on a commit.' It uses a specific verb ('Get') and resource ('comment on a commit'), which is unambiguous. This distinguishes it from sibling tools like get_commit_comments (which lists comments) and get_pull_request_comment (which retrieves a comment on a pull request).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit guidance on when to use this tool versus alternatives like get_commit_comments or get_pull_request_comment. It implies usage by stating its purpose, but lacks when-to-use or when-not-to-use context. The sibling list includes many similar retrieval tools, so more guidance would help.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds no additional behavioral traits (e.g., rate limits, auth requirements, error behavior) beyond these annotations.
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?
Description is concise (5 lines) and front-loaded with purpose. The 'Returns' line is slightly redundant given the output schema, but not harmful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists, so return values are covered. Parameter meanings are explained. Missing context about prerequisites or error scenarios, but acceptable for a simple read tool with annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, but the description explains each parameter (repo_slug, schedule_uuid, workspace) with meaning and optionality. This compensates for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Get a single pipeline schedule', which is a specific verb-resource pair. It distinguishes from sibling tools like 'list_pipeline_schedules' by specifying a single entity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives (e.g., list_pipeline_schedules for multiple schedules). Usage is implied by the name and description but lacks explicit context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description aligns with annotations (readOnlyHint, idempotentHint, destructiveHint), indicating a safe read operation. It adds minimal behavioral context beyond the structured data, only noting the paginated return type.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph with a clear bullet-style list of arguments. It is front-loaded with the main action and contains no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the annotations (safe, idempotent) and presence of an output schema, the description covers the key aspects. It mentions pagination limits but could be more explicit about pagination iteration behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description effectively explains each parameter (e.g., workspace optional, max_pages limit recommended 10). However, defaults like page_size=20 are already in schema, so the description adds value but not maximal detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'List' and the resource 'executions of a pipeline schedule', making it distinct from sibling tools like 'list_pipeline_schedules' (lists schedules) and 'get_pipeline_schedule' (single schedule).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool vs alternatives. The description does not mention prerequisites, conditions, or refer to related 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?
Annotations already provide idempotentHint=true and destructiveHint=false. The description adds no further behavioral context (e.g., error handling, permission needs, or side effects). Minimal added value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: one action sentence followed by a clear bullet list of parameters. Every sentence is necessary; 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 simple mutation tool with an output schema, the description covers purpose and parameters adequately. It does not mention error scenarios or required permissions, but overall complete for this complexity level.
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 lists each parameter with a brief explanation (e.g., 'workspace: Workspace name (optional, defaults to configured workspace)'). This adds meaning, though details are minimal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Remove approval from a pull request,' defining the action and resource. This distinguishes it from sibling tools like 'approve_pull_request' (opposite) and 'decline_pull_request' (different action).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives. It does not mention prerequisites, when to unapprove vs. approve/decline, or any context for usage.
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?
Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, providing a safety profile. The description adds minimal behavioral context beyond stating that it updates a comment. It does not disclose permission requirements, error handling, or side effects, but does not contradict annotations either.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with a one-line summary followed by an Args section and Returns line. It is concise and front-loaded, but could be slightly tighter by removing the redundant 'Args:' label. Overall, it covers essential information without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters (4 required) and an output schema, the description explains all parameters and return type. However, it lacks context about validation (e.g., comment existence), error conditions, or permission requirements. For a mutation tool with idempotentHint, some additional behavior details would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description must compensate. It explicitly defines each parameter: repo_slug, pull_request_id, comment_id, content (with 'markdown format' clarification), and workspace (with optionality and default). This adds meaning beyond the schema's plain titles and types, enabling 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 'Update a comment on a pull request,' specifying the verb and resource. Among sibling tools like add_pull_request_comment, delete_pull_request_comment, and reopen_pull_request_comment, it is uniquely identified as the update operation, distinguishing itself well.
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 lists required parameters but provides no explicit guidance on when to use this tool versus alternatives. For example, it does not mention that the comment must already exist, nor does it contrast with add or delete operations. The usage context is implied by the resource type but lacks clarity on prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable context: it returns an error if the issue tracker is disabled, which is a behavioral trait beyond annotations. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a single sentence for purpose, followed by structured Args and Returns sections. Every part is necessary and efficiently communicates key 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 simplicity and the presence of annotations and output schema, the description covers essential aspects: purpose, required arguments, return value, and an error condition. Slight lack of alternative suggestions is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description lists all three parameters with brief explanations: repo_slug (Repository slug), issue_id (Issue ID), and workspace (optional with default). This adds semantic meaning beyond the schema titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get details for a specific issue.' It specifies the verb 'Get' and the resource 'issue,' making the purpose unmistakable. However, it does not differentiate from sibling 'get_*' tools like get_issue_comment, relying on the name for 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 when a single issue's details are needed, but it does not explicitly state when to use this tool over alternatives like list_issues. There is no guidance on when not to use it or prerequisites.
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?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds context that the returned pipeline variable's value is null if secured, which is useful beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a clear main sentence, an args list, and a return note. The args list duplicates schema information but is not excessive. Overall, it is efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool, rich annotations (readOnlyHint, destructiveHint, idempotentHint), and presence of an output schema, the description is complete. It adds the important detail about null value for secured variables, which fills the only gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 3 parameters with 0% description coverage. The description lists parameter names but adds no additional meaning or format details beyond what the schema already provides (e.g., repo_slug, variable_uuid, workspace). The names are self-explanatory, but the description does not compensate 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 'Get a single repository-level pipeline variable', specifying the verb 'Get', the resource 'pipeline variable', and the scope 'single repository-level'. This distinguishes it from sibling tools like list_pipeline_variables.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives like list_pipeline_variables. While it is implied that this is for a single variable, no explicit when-not or alternative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that the tool returns a paginated list with configurable page size and max pages. No additional behavioral traits or warnings beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: one sentence describing purpose, a bullet list of parameters with defaults, and a return type line. No unnecessary words, front-loaded, easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with an output schema, the description covers the action, all parameters with defaults, and the return type. It does not detail sorting or filtering, but the output schema likely covers that. Adequate for selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, but the description adds meaningful semantics for all parameters: repo_slug (repository slug), workspace (optional, defaults to configured), page_size (default 20), max_pages (default 1, max recommended 10). This significantly compensates for missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists pipeline schedules for a repository, using specific verb 'list' and resource 'pipeline schedules'. It distinguishes from siblings like 'get_pipeline_schedule' (singular) and 'list_pipeline_schedule_executions'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., get_pipeline_schedule for a single schedule, or list_pipeline_schedule_executions for executions). The description does not mention prerequisites or conditions.
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?
Annotations already indicate read-only and idempotent. The description adds valuable context: pagination defaults (page_size=30, max_pages=1) and a warning for over 10 pages, which exceeds annotation scope.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear initial statement, organized Args section, Returns, and a Note. No filler; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description appropriately focuses on input and behavior. It covers pagination limits, optional filters, and warning conditions. Could mention that it lists only repositories the user has access to, but overall is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully compensates with clear, specific docstrings for each parameter: workspace defaults, name partial matching, page_size default, max_pages default and limit. This adds meaning beyond the schema's type/default.
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 (list) and resource (repositories), with scope (in workspace) and pagination. It is specific but does not explicitly distinguish from sibling tools that also list different resources, though the resource type is distinct enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or alternatives are mentioned. The description only describes its own behavior, not when to choose this over other list tools or other approaches.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds value beyond annotations by stating the effect ('sets reviewer status to 'needs work'') and the return type ('Participant details with updated state'). Annotations indicate idempotency and non-destructiveness, and the description neither contradicts nor repeats this, providing complementary behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise: one sentence for purpose, an Args block, and a Returns line. It front-loads the core action and uses a clean structure, with no extraneous information. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, parameters, and return value adequately for a simple tool. However, it lacks prerequisites (e.g., required permissions, pull request state) and does not contrast with similar siblings. Given the tool's simplicity and existing annotations, it is minimally viable but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% coverage (no descriptions), so the description fills the gap by listing parameters with brief explanations like 'Repository slug' and 'Workspace name (optional, defaults to configured workspace).' While these add basic meaning, they are minimal and could be more detailed (e.g., format or constraints).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Request changes on a pull request (sets reviewer status to 'needs work').' It uses a specific verb and resource, and among siblings like approve_pull_request and decline_pull_request, it distinctly identifies its function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for requesting changes but does not explicitly guide when to use this tool versus alternatives like approve or decline. No exclusion criteria or contextual hints are provided, so the agent must infer from the tool's name and siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate it is not read-only (readOnlyHint=false) and not destructive (destructiveHint=false), which aligns with adding a comment. The description adds the specific error scenario for missing issue tracker but does not detail other behavioral aspects like notification side effects or idempotency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loads the purpose, and structures args and returns in an easily scannable format. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity and presence of an output schema, the description covers the essential behavior: creating a comment and handling the no-issue-tracker error. It is complete for the tool's simplicity, though could mention idempotency implications.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by explaining each parameter: repo_slug, issue_id, content (noted as markdown), and workspace (optional with a default). This provides meaningful context beyond the schema's type-only definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'add' and the resource 'comment to an issue', making the purpose immediately clear. It distinguishes itself from sibling tools like 'get_issue_comment' and 'update_issue_comment'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives, but the purpose is self-explanatory. It mentions an error case for repositories without an issue tracker, providing some context, but lacks prerequisites like issue existence or permissions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly, idempotent, non-destructive. Description adds 'Returns branch restriction details' but doesn't go beyond annotations. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise, no wasted words. Uses clear arg format and a returns line. Efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature of the tool and presence of output schema, the description is complete. Required parameters are identified. Good for a read operation among many sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but description explains each parameter: 'Repository slug', 'Numeric restriction id', 'Workspace name (optional, defaults to configured workspace)'. Provides meaning beyond bare schema titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Get a single branch restriction' with a specific verb and resource. It distinguishes from sibling 'list_branch_restrictions' which retrieves multiple.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this vs alternatives. Usage is implied (to fetch one restriction), but no exclusions or when-not-to-use info.
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?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds pagination behavior (default page_size=20, max_pages default=1, max recommended 10) and return type, providing useful context beyond what annotations alone offer.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (8 lines), front-loaded with purpose, and every sentence adds value. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all parameters with defaults and a return statement. With output schema present, it's sufficiently complete. Minor missing detail on workspace fallback behavior, but overall adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description explains all four parameters: repo_slug, workspace (optional, defaults to configured), page_size (default 20), max_pages (default 1, max recommended 10). This adds meaning beyond the schema's titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List pipeline caches for a repository,' with a specific verb and resource. This distinguishes it from sibling tools like list_pipeline_runs or get_pipeline_config.
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 only lists parameters without explaining contexts like caching vs. active runs, leaving the agent to infer purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate readOnlyHint, idempotentHint, and destructiveHint. The description adds that it returns a paginated list of permissions with user info, which is useful context. However, it does not disclose additional behavioral traits like rate limits or authentication details beyond the scope requirement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: first sentence states purpose, followed by scope requirement, parameter list, and return type. No unnecessary words, and information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters and an existing output schema, the description covers purpose, scope, all parameters, and return type. It could be improved by mentioning possible permission values (e.g., read, write, admin) but overall provides sufficient context for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema coverage is 0%, so the description fully compensates by explaining each parameter: repo_slug, workspace (optional, defaults to configured), page_size (default 30), and max_pages (default 1, max recommended 10). This adds meaningful context beyond the schema's type and default values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List the user permissions for a specific repository in the workplace,' which uses a specific verb and resource. It distinguishes itself from sibling tools like list_workspace_permissions by focusing on repository-level permissions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions the required scope ('account') but provides no guidance on when to use this tool instead of alternatives such as list_workspace_permissions. The context is implied by the resource type, but no explicit when-not or alternative recommendations are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the method (combining default reviewers and recent PR history) and what it returns (scores, reasons, already-assigned reviewers, data sources). Annotations already indicate read-only and idempotent, so no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with a summary paragraph and a list, but the Args section largely repeats schema information, making it slightly longer than necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of annotations and output schema, the description adds sufficient context about the tool's behavior and return values, though it could specify sorting or limit behavior more explicitly.
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 Args section explains each parameter's purpose beyond the schema, including defaults and optionality, compensating for the 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'suggest' and the resource 'pull request reviewers', and it distinguishes from sibling tools as no other tool suggests reviewers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that it combines default reviewers with frequent approvers, providing context for when to use it, but it lacks explicit guidance on when not to use it or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the description adds value by detailing the return structure, including comment_stats object with total, resolved, unresolved. This goes beyond annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured as a docstring with Args and Returns sections. It is reasonably concise, though the Args list with indentation is slightly verbose. Every sentence adds value; no filler. Well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity and presence of an output schema (implied by 'has output schema: true'), the description covers the operation, parameters, and key output detail (comment_stats). It does not mention prerequisites or edge cases, but for a simple retrieval, it is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description adds brief explanations for each parameter: 'Repository slug', 'Pull request ID', and 'Workspace name (optional, defaults to configured workspace)'. This adds meaning beyond the schema, especially the default for workspace. Could be more detailed but is adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get details for a specific pull request,' identifying the verb (Get) and resource (pull request). It distinguishes from siblings like get_pull_request_activity or get_pull_request_comment by implying 'details' includes basic info and comment stats, which is specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use versus alternatives. It is implied that for getting a specific PR's details, use this tool, but there are many sibling tools for specific aspects (e.g., get_pull_request_commits, get_pull_request_diff) without differentiation. The description does not provide when-not-to-use conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only and idempotent. The description adds behavioral context: pagination limits, enriched comment resolution status, and a warning for large fetches. This goes beyond annotations, but could detail more about the response structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded. The main purpose is in the first line, followed by a list of arguments, return info, and a note. Every sentence adds value without repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (which documents return values), the description thoroughly covers input parameters, pagination behavior, and limits. It is complete for the tool's complexity level.
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 listing each parameter, its purpose, defaults, and recommended max values. This adds meaning beyond the schema's type definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get activity log for a pull request' with pagination support. It uses a specific verb and resource, and the tool's purpose is distinct from sibling tools like get_pull_request_comments, which focus on comments only.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide guidance on when to use this tool versus alternatives. It lacks explicit context for when to choose this over similar tools like get_pull_request_activity itself or other activity-related tools. No 'when to use' or 'when not to use' clauses.
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?
Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds important behavioral details: required authentication scopes and pagination behavior (page_size default 30, max_pages default 1, max recommended 10). No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear purpose sentence, auth requirement, and an Args section listing parameters. It is concise and front-loaded, though the Args formatting uses non-standard parentheses and line breaks, which is slightly less readable than a table.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists, the description does not need to detail return values. It covers all required aspects: purpose, auth, parameter explanations, and pagination behavior. However, it does not mention the sibling tool to retrieve a single restriction.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% parameter description coverage, so the description compensates by explaining each parameter: repo_slug, kind (with examples like 'push'), workspace, page_size, max_pages. This adds meaningful usage context beyond the schema's type/default information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('List') and resource ('branch restrictions (branch protection rules)') for a repository. This distinguishes it from siblings like get_branch_restriction (singular) and other list tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides useful context about required OAuth scopes and parameter defaults, but does not explicitly state when to use this tool versus alternatives (e.g., get_branch_restriction for a single restriction). No when-not or exclusion guidance is given.
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?
Annotations already show this is a write operation (readOnlyHint=false) and not destructive. The description adds useful behavioral context: support for inline comments with line references, pending drafts, and threaded replies. This goes beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, using a single paragraph followed by a bullet list of arguments. It avoids fluff but could be slightly more structured (e.g., separating general vs inline comment use cases).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (9 parameters) and presence of an output schema (returns created comment details), the description covers the main aspects: purpose, parameters, and general behavior. Missing prerequisites or error conditions, but adequate for most use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully compensates by explaining each parameter's purpose in a clear docstring format (e.g., 'repo_slug: Repository slug', 'inline_path: Path to the file for inline comments'). All nine parameters are semantically described.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add a comment') and resource ('pull request'), specifying 'general or inline'. It distinguishes from sibling tools like add_issue_comment (different resource) and update_pull_request_comment (different action).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for adding comments but does not provide explicit guidance on when to use this tool versus alternatives like approve_pull_request or update_pull_request_comment. No when-not-to-use or prerequisite information is given.
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?
Annotations indicate read-only, non-destructive, and idempotent behavior, and the description's 'Get details' aligns. The description adds a valuable behavioral nuance: the 'commit' parameter accepts branch/tag names in addition to hashes, which the schema does not convey.
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 four short sentences: purpose, Args, Returns. Every sentence adds value, no redundancy. Front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the description covers the essential: purpose, parameters, and return value. The presence of an output schema reduces the need to detail return format. The description is complete enough for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description provides concise explanations for all three parameters: repo_slug, commit (with note on branch/tag acceptance), and workspace (optional with default). This meaningfully supplements the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get details') and resource ('a single commit'). It distinguishes itself from sibling tools like 'list_commits' (which retrieves multiple commits) and 'get_commit_comment' (which retrieves a comment on a commit).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives, such as 'list_commits' for multiple commits. The usage is implied but lacks direct guidance, which is adequate but not proactive.
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?
Annotations already indicate readOnlyHint, idempotentHint, and non-destructive nature. The description adds behavioral context by documenting that if the issue tracker is disabled, it returns an error object, and notes that workspace defaults to configured workspace.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two short paragraphs using an Args/Returns structure. Every line provides necessary information without redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple parameter set (4 string parameters, 3 required) and the presence of an output schema, the description covers the essential behavior. It mentions a key edge case (issue tracker disabled) and default workspace behavior. Could be slightly more thorough about return format, but adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds value by naming each parameter with a brief explanation (e.g., 'Repository slug', 'Issue ID'). It also clarifies that workspace is optional and defaults to the configured workspace, which is not in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get a specific comment on an issue,' using a specific verb and resource. It distinguishes itself from siblings like 'get_issue_comments' (plural) and 'get_pull_request_comment' (different context).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool over alternatives, nor does it provide exclusion or prerequisite information. Usage is implied by the name and parameter structure, but no direct guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds substantial behavioral context beyond annotations: pagination details (page_size, max_pages), default values, recommended limits, and a warning for excessive fetching. This helps the agent understand system constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences for purpose, five bullet points for args, one line for returns, and a note. Every part is essential and front-loaded. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is an output schema, the description need not detail return fields. It covers input parameters thoroughly, including behavior warnings. However, it could mention ordering or the fact that steps are returned in chronological order, which would be slightly more complete. Still, very close to complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by explaining each parameter's meaning, defaults, and recommended maximums. For example, it clarifies that workspace is optional and defaults to configured workspace, and provides specific recommendations for page_size and max_pages. This is far beyond the schema's bare type/default information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'List steps for a pipeline run', which combines a specific verb ('List') with a clear resource ('pipeline steps') and context. This clearly distinguishes it from sibling tools that deal with other aspects of pipelines (e.g., get_pipeline_run, get_pipeline_config).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing pipeline steps but does not explicitly state when to use this tool over alternatives. It lacks guidance on exclusions or when not to use it, such as comparing with get_pipeline_run for retrieving the pipeline itself. Usage is clear but not differentiated from siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the base safety profile is known. The description adds behavioral details: pagination support, return enriched with resolution status, and a warning for large fetches. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (Args, Returns, Note), uses bullet points for parameters, and is concise without any fluff. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers pagination, limits, warnings, return fields, and defaults. It lacks mention of error cases or status codes, but given the presence of an output schema, the return fields are well documented. A minor gap but overall 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?
With 0% schema description coverage, the description fully compensates by explaining each parameter's purpose, defaults, and constraints. For example, 'unresolved_only: If true, returns only unresolved comments (default: False)' and 'workspace: Workspace name (optional, defaults to configured workspace)'. This adds significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List comments on a pull request with pagination support.' It uses a specific verb and resource, and distinguishes from siblings like 'get_pull_request_comment' (single comment) and 'get_pull_request_tasks'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by stating it lists comments with pagination, but does not explicitly tell when to use this tool vs alternatives like 'get_pull_request_comment' for a single comment. The context from sibling tools provides some differentiation, but no explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds pagination details, defaults, and a warning threshold, providing useful behavioral context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with a purpose sentence, Args list, Returns, and Note. Front-loaded with the main action. Could be slightly more concise but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists, the description adequately covers input parameters, pagination behavior, and a warning. It explains the optional workspace and default behavior, making it complete for this paginated list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, but the description explains all parameters: required ones, optional workspace, defaults for page_size and max_pages, and recommended limits. This adds significant value over 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 explicitly states 'Get commits on a pull request' with clear verb and resource. It distinguishes from sibling tools like list_commits (repo-wide) and get_pull_request (PR details) by focusing on commits.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear usage with pagination parameters and a note about warnings for large fetches. Does not explicitly mention alternatives like list_commits, but context is sufficient for most use cases.
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?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral context: pagination limits (max 10 pages or 300 items triggers warning) and default values, which goes beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear 'Args' and 'Returns' sections. Every sentence is necessary: purpose, parameter list, and note about warnings. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists (so returns are covered) and the tool has 5 parameters with 1 required, the description covers all aspects: pagination, state filtering, workspace handling, and a warning about excessive pages. It is complete for a listing tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by explaining each parameter: repo_slug as required, workspace as optional with default, state with possible values, page_size and max_pages with defaults. However, it doesn't clarify what 'configured workspace' means.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get pull requests for a repository with pagination support', using a specific verb and resource. It effectively distinguishes from sibling tools like 'get_pull_request' (singular) which would fetch a single pull request.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing pull requests with pagination, but does not explicitly state when to use this tool versus alternatives such as 'get_pull_requests_pending_review' or 'get_pull_request'. No when-not or exclusion criteria are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds minimal behavioral context beyond stating it returns a paginated list, which is consistent but not additional insight.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences plus a well-formatted argument list. Front-loaded with the primary purpose. Every sentence is necessary and no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists, the description appropriately summarizes return type without superfluous detail. All parameters are documented, annotations cover safety, and the description fully scopes the tool's function.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description's Args section adds necessary meaning for all four parameters, including types, defaults, and optionality. Provides clear explanations beyond schema titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves open pull requests where the current user is a reviewer, using a specific verb and resource. It distinguishes from the sibling 'get_pull_requests' which likely returns all PRs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use this to find PRs needing review attention, providing clear context. It implicitly excludes other actions like commenting or merging, but does not explicitly state 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and idempotent. The description adds pagination behavior (defaults, max recommendations) and the warning, which is useful beyond annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections for args, returns, and note. Front-loaded with purpose. Could be slightly more concise, but overall effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists, so return structure is not required but still described. Covers pagination limits and default behavior. Lacks error cases or prerequisites, but adequate for a read tool with annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must add value. It adds defaults and max recommendations for page_size and max_pages, and notes workspace optionality. However, repo_slug and pull_request_id are not elaborated beyond titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves build/CI statuses for a pull request with pagination. The verb 'get' and resource 'pull request statuses' are specific and distinguish it from siblings like get_commit_statuses or get_pull_request.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides pagination defaults and a warning about limits (10 pages/300 items). However, it does not explicitly contrast with alternatives like get_commit_statuses or when to use this over get_pull_request.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds pagination behavior (defaults, max recommendations) and return structure (state, content, creator info). This enriches transparency beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with 7 lines: a one-line summary, a 5-line Args section, and a 1-line Returns section. Every sentence is useful and front-loaded, with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 parameters, output schema exists), the description adequately covers parameters and return fields. It could be slightly more complete by explaining how pagination works across page_size and max_pages, but overall it provides sufficient context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates by providing detailed explanations for all 5 parameters, including defaults and recommended limits (e.g., 'page_size: default 10, max recommended 100' and 'workspace: optional, defaults to configured workspace').
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List tasks on a pull request with pagination support.' It uses a specific verb ('list') and resource ('tasks on a pull request'), distinguishing it from sibling tools like get_pull_request_task (single task) and create/update/delete tasks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing all tasks with pagination via parameters like page_size and max_pages. However, it does not explicitly state when to use this tool over alternatives (e.g., get_pull_request_task) or provide conditions for when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, destructiveHint, and idempotentHint. The description adds the 'account' scope requirement but doesn't discuss error handling, rate limits, or what happens if the member is not found. Behavior is adequately but not richly described.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: a single sentence for purpose, one line for scope, and bulleted args. Every sentence earns its place with no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params, one required) and the presence of an output schema, the description covers all essential context: scope requirement, parameter formats, and default behavior. It is complete for agent decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It does so by explaining member_id format ('account_id or brace-wrapped uuid, not a username') and workspace defaulting behavior. 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get a single workspace member,' which is a specific verb+resource. It distinguishes itself from sibling 'list_workspace_members' by indicating it retrieves a single member.
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 mentions the required 'account' scope and gives guidance on member_id format and workspace default. However, it doesn't explicitly state when to use this tool over alternatives like list_workspace_members, though it's implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false. Description adds value by detailing that the tool returns a paginated listing with path, type, size, and mimetype, and explains pagination behavior (defaults and max pages). This goes beyond annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise and well-structured with an Args section and a Returns summary. No unnecessary information; every sentence adds value. It efficiently conveys purpose, parameters, and return format in a few lines.
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?
Description is complete for a read-only list operation: it explains all parameters, defaults, pagination, and return fields. It does not cover error scenarios or prerequisites (e.g., repository access), but given the presence of an output schema and annotations, the description adequately supports agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description must fully explain parameters. It does so by listing all 6 parameters with brief descriptions, including default values and constraints (e.g., path defaults to root, workspace defaults to configured, pagination limits). This compensates completely for missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it lists entries (files and sub-directories) of a directory at a commit/branch. The verb 'list' and resource 'directory entries' are specific, and the context is well-defined, distinguishing it from sibling tools like get_file_content or list_commits.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description does not explicitly state when to use this tool versus alternatives or provide exclusions. It gives usage context (e.g., defaults, pagination) but lacks guidance on when not to use or which sibling tool might be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey read-only, idempotent, non-destructive behavior. The description adds value by specifying pagination behavior (page_size, max_pages), a warning for fetching >10 pages, and default workspace behavior. This goes beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: a one-line summary, a well-organized parameter list, a returns line, and a note. Every sentence adds necessary information without redundancy. It is front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description's brief return statement suffices. It covers pagination limits and filters. However, it could mention error handling or behavior when workspace is unconfigured. Overall, it is mostly complete for a typical use case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, but the tool description fully documents each parameter in the 'Args' section, including allowed values for status and defaults for page_size/max_pages. This compensates completely for the schema gap, adding clear meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List pipeline runs for a repository with pagination support', specifying the verb (list) and resource (pipeline runs). It distinguishes from sibling tools like get_pipeline_run (single run) and list_pipeline_caches (different resource) by focusing on runs with filtering and pagination.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly suggests usage for listing runs with filters, but it lacks explicit when-to-use or when-not-to-use guidance. For example, it does not mention that get_pipeline_run is for individual runs. No alternatives or exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses that secured variables return null and explains pagination behavior with default and max values, adding valuable context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with a short introductory sentence followed by a bulleted list of arguments. No redundant or unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema explaining return values, the description adequately covers behavior (secured variables, pagination). Completeness is high for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description provides meaningful explanations for all four parameters, including defaults and optionality, which compensates for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List'), the resource ('pipeline variables'), and the scope ('repository-level'), making the purpose unambiguous and distinct from siblings like get_pipeline_variable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives (e.g., get_pipeline_variable), but the straightforward nature of listing vs. fetching a single variable provides implicit context.
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?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds pagination behavior (page_size, max_pages, default values) and return type, which is valuable beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description uses a clean docstring format with a one-liner summary, Args section, and Returns section. No wasted words, and all information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description appropriately summarizes returns as 'paginated list of commit comments.' It covers pagination, parameter defaults, and optionality, making it complete for a list 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?
With 0% schema description coverage, the description fully explains all 5 parameters: repo_slug, commit, workspace (optional, defaults), page_size (default 10), max_pages (default 1, max 10). This adds meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists comments on a commit with pagination. It specifies the resource (commit comments) and action (list), distinguishing it from sibling comment tools for issues and 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides pagination details but lacks explicit guidance on when to use this tool versus alternatives (e.g., get_issue_comments, get_pull_request_comments). No when-not-to-use or exclusion criteria are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering safety profile. The description adds behavioral context: optional path filtering to reduce token usage and that the return is a unified diff string. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with purpose, followed by arguments and return. Every sentence is necessary and informative, with no extraneous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the presence of an output schema, the description fully covers purpose, all parameters, and return type. It provides sufficient context for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries full burden. It explains all 4 parameters: repo_slug, pull_request_id, workspace (with default), and path (with example). This adds significant meaning beyond the schema's type-only properties.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get diff for a pull request,' using a specific verb and resource. It distinguishes itself from sibling tools like 'get_pull_request_commits' or 'get_pull_request_activity' by focusing on the diff.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a usage tip for the optional 'path' parameter to reduce token usage, but it does not explicitly state when to use this tool versus alternatives or any exclusions. The guidance is implied but not comprehensive.
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?
Annotations already indicate the tool is read-only and non-destructive. The description adds valuable behavioral context: pagination limits with warnings (e.g., >10 pages or 300 items), and the possibility of returning an error if the issue tracker is disabled. This goes beyond the annotations.
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 separate sections for Args, Returns, and Note. It is concise and each sentence adds value. There is no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the tool (11 parameters, pagination, error cases) and the presence of an output schema (so the description doesn't need to detail return structure), the description covers all necessary aspects: parameters, usage notes, and edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, meaning the schema only provides names and types. The description compensates fully by explaining each parameter, including valid values (e.g., state: new, open), default values, and a detailed example for the 'q' parameter with BBQL syntax.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists issues in a repository's issue tracker with filtering and pagination. The verb 'List' and resource 'issues' are specific, and among the many sibling tools focused on pull requests and issue comments, this tool's purpose is distinct.
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 a clear overview of the tool's functionality and its parameters, but it lacks explicit guidance on when to use this tool versus alternatives like 'get_issue' for a single issue. The usage is implied but not contrasted.
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?
Annotations already declare read-only, idempotent, non-destructive behavior. The description adds valuable context: scope requirement, pagination details (defaults, max pages), and return structure. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: a one-line purpose, one-line prerequisite, then a clear bullet-like list of parameters and return type. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (list with pagination) and 0% schema coverage, the description provides all necessary information: purpose, scope requirement, parameter semantics, and return format. The output schema exists but the description still summarizes the return structure sufficiently.
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 fully explains all three parameters: workspace (optional, default behavior), page_size (default 30), max_pages (default 1, max recommended 10), adding meaning beyond the schema's property names and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('user permissions (roles) of a workspace'), clearly distinguishing this tool from siblings like 'list_workspace_members' (members) and 'list_repository_permissions' (repo-level).
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 states a prerequisite ('Requires the `account` scope') but does not explicitly contrast with alternative tools or provide when-not-to-use guidance. The usage context is implied by the tool's purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context by noting that Bitbucket API does not support pending/draft comments in batch and that each comment is posted immediately. This goes beyond the annotations, which lack any behavioral hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, with a clear purpose statement, a behavioral note, and a neatly formatted parameter list. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all parameters, returns a summary, and includes a behavioral note. With an output schema present, it does not need to detail return values, but it still provides a concise overview, making the tool fully understandable.
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 coverage, the description fully explains the parameters: comments structure (content, inline), review_action enum values, and optional fields. This adds essential meaning that the schema alone does not provide.
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: submitting a batch review on a pull request with multiple comments and optional approval/request changes. This differentiates it from sibling tools like add_pull_request_comment (single comment) or approve_pull_request (only approval).
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 batch operations but does not explicitly state when to use this tool over alternatives like multiple single-comment calls. Guidance is implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate idempotentHint=true, readOnlyHint=false. The description adds that only provided fields are changed (partial update), and specifies an error return when the issue tracker is disabled. This goes beyond annotations, though it could mention persistence or rollback 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 very concise: a lead sentence followed by a bullet-like list of parameters. Returns clause is provided. No redundant filler; every line adds value. For nine parameters and error handling, it's optimally structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 9 parameters (2 required), presence of output schema, and complexity of a partial update tool, the description covers update behavior, parameter semantics, and error condition. It leaves no major gaps for an agent to misinterpret.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, meaning the description must fully explain parameters. It provides allowed values for 'state', 'kind', 'priority' enums, and clarifies optionality for all fields except required 'repo_slug' and 'issue_id'. This is excellent compensation for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update an issue (only the provided fields are changed).' The verb 'Update' paired with 'issue' makes the action and resource unambiguous. It distinguishes from sibling tools like 'create_issue' (creation) and 'get_issue' (reading).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives like 'update_issue_comment' or 'update_pull_request'. While the purpose is clear, there is no guidance on context-specific selection or exclusions. The sibling list provides implicit differentiation but the description itself lacks such 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?
Annotations indicate mutation (readOnlyHint=false) and idempotence (idempotentHint=true). The description adds the critical behavioral detail that the reviewers parameter replaces the entire reviewer list, a non-obvious side effect. This goes beyond annotations, though no further behavioral traits are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured as a docstring with an Args list, making it easy to scan. It is appropriately sized, with no superfluous sentences. The mandatory warning for reviewers adds necessary detail without bloat. Slightly more conciseness could be achieved, but it is well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given six parameters, two required, and an output schema present, the description adequately covers input parameter meanings and usage. It does not detail return values, but the output schema fulfills that role. No coverage of error conditions or permissions, which are acceptable omissions for this tool's scope.
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 explaining all six parameters. It clarifies that workspace defaults to the configured workspace and provides a crucial warning for reviewers (replacement behavior, retrieval advice, clearing). This is essential for correct tool invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update a pull request' with a specific verb and resource. Among siblings like create_pull_request, approve_pull_request, and decline_pull_request, this tool is distinctively about updating an existing PR, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance for the reviewers parameter, including a warning that it replaces the list and instructions to retrieve current reviewers via get_pull_request. However, it does not offer broader context on when to use this tool versus alternatives, which prevents a higher score.
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?
Annotations already provide idempotentHint (true) and destructiveHint (false). The description adds that it can update either content or state (or both) and returns updated details. No contradictions, but could mention permissions or constraints (e.g., task must be unresolved).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (9 lines) and well-structured with Args and Returns sections. Minor redundancy in 'Args:' and parameter listing, but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 6 parameters and output schema exists, the description covers all input details and return type. Lacks mention of error handling or prerequisites (e.g., valid task ID), but sufficient for basic usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description fully compensates by listing all 6 parameters with clear explanations: repo_slug, pull_request_id, task_id (required), content (markdown format, optional), state (UNRESOLVED/RESOLVED, optional), and workspace (optional with default). Adds meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Update a pull request task (content and/or state)', clearly identifying the verb (update) and resource (pull request task), distinguishing it from sibling tools like create, delete, or get.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for modifying an existing pull request task, but lacks explicit guidance on when not to use it (e.g., for creation or deletion) or alternatives. However, the context from sibling names provides implicit differentiation.
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?
Annotations already declare read-only and idempotent hints. The description adds valuable behavioral details: the metadata pre-check (rejecting directories, oversized/binary files) and the ambiguity warning for branch names. This extends beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with an overview, a behavioral note, and a parameter list. It is slightly verbose but every sentence adds value. Could be trimmed, but overall good.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters, no enums, and an output schema (so return docs not needed), the description is complete: it covers functionality, pre-checks, parameter details, and return type. All essential information is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, so the description carries full burden. It clearly explains each parameter: repo_slug, commit (with nuance about branch/tag ambiguity), path, workspace (optional), and max_bytes (with default and unit). This is thorough.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it gets raw text content of a file at a given commit or branch, using a specific verb and resource. It distinguishes itself from sibling 'get_*' tools which focus on other entities like commits, issues, or 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it pre-checks for directories, oversized files, and binary files, and warns about ambiguous branch names. It implicitly tells when to use this tool (for file content), but does not explicitly mention alternatives 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds value by disclosing pagination limits, warning thresholds, and error case for disabled issue tracker, providing behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well structured with title, parameter list, return info, and note. Front-loaded with main purpose. Slightly verbose in parameter details but acceptable. Could be more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given annotations and presence of output schema, description covers all necessary aspects: purpose, parameters, returns, error case, and pagination limits. No gaps identified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, but description explains all 6 parameters with defaults and max recommendations. Adds meaning such as optional workspace and pagination constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states 'List comments on an issue with pagination support' with specific verb and resource. Clearly distinguishes from siblings like get_issue_comment (single comment) and add_issue_comment.
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?
Clear context for using the tool: listing comments on an issue with pagination parameters. Includes warning about large fetches and error case. Does not explicitly mention when not to use or alternatives, but purpose is self-evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds significant behavioral details: 'Fetches PR details first, then aggregates diffstat, unresolved comments, and CI statuses in parallel.' It also describes the return structure and the review_readiness enum, which goes beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with clear sections (Args, Returns). Every sentence adds value, and it is well-structured for quick parsing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (3 parameters, output schema present, annotations), the description is complete. It covers return values with a structured summary and review_readiness enum, explains parallel fetching behavior, and provides parameter defaults. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the text description explains each parameter: repo_slug, pull_request_id, and workspace (optional, defaults to configured workspace). This adds meaning beyond the schema, especially clarifying the optionality and default of workspace.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get a comprehensive review summary for a pull request' and lists specific components (PR details, diffstat, unresolved comments, CI statuses). It distinguishes from sibling tools like get_pull_request (just PR details) and get_pull_request_diffstat (only diffstat) by aggregating multiple data sources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions 'for efficient AI-assisted code review' but does not explicitly say when to use this tool versus alternatives like get_pull_request or get_pull_request_diffstat. It provides implied usage context but lacks exclusions or alternative recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by summarizing the return fields (state, content, creator, resolution info) beyond what annotations provide. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, structured with Args and Returns sections, and no filler content. Every sentence is necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and existence of output schema (though not shown), the description adequately covers the purpose, parameters, and return structure. Could mention error handling, but not essential for a basic get 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?
Schema coverage is 0%, so the description carries full burden. It lists all 4 parameters with clear roles and notes workspace is optional with default. This compensates fully for missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get a specific task on a pull request', using a specific verb and resource. It distinguishes from siblings like get_pull_request_tasks (plural) and create/delete/update task tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
While no explicit when/when-not guidance is given, the description implies usage: use when you need a single task by ID. The tool name and context among siblings make selection straightforward.
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?
Annotations already indicate read-only and non-destructive behavior. The description adds valuable transparency: secured variables return null, and it details pagination parameters. This goes beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a summary sentence, a security note, an Args section with bullet-point parameters, and a Returns line. Every part adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool, the description covers all necessary aspects: purpose, parameters with defaults, pagination, security (OAuth scope and null for secure variables), and return type. An output schema exists, so return details are not missed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema coverage in context signals, the description provides clear parameter meanings (e.g., 'repo_slug: Repository slug') and default values (page_size: 20, max_pages: 1). This compensates for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'List the variables of a deployment environment.' It uses a specific verb ('list') and resource ('variables of a deployment environment'), distinguishing it from sibling tools like list_deployments and list_environments.
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 specifies the required OAuth scope ('deployment') and provides parameter defaults. While it does not explicitly state when not to use it, the sibling tool list_pipeline_variables exists for a different variable type, allowing inference of appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds value beyond annotations by stating the required OAuth scope, which is not captured in the annotations. The annotations already indicate the tool is read-only, idempotent, and non-destructive, so the description complements them well. It does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (6 lines) and front-loaded with the core purpose. Every sentence serves a purpose: stating the action, listing requirements, defining parameters, and indicating return type. No extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists (not shown but indicated in context signals), the description appropriately covers the essential behavioral and parameter information. It mentions the required scope, explains all parameters, and notes the return type. The annotations cover safety and idempotency, making the description complete for effective 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?
Despite 0% schema description coverage, the description effectively explains each parameter: repo_slug (required), workspace (optional with default), page_size (default 20), and max_pages (default 1, max recommended 10). This adds meaningful context beyond the schema's type and title information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: listing deployment environments for a repository. It uses a specific verb ('List') and resource ('deployment environments'), and the scope ('for a repository') distinguishes it from siblings like 'get_environment' (single environment) and 'list_deployments' (list deployments, not environments).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly mentions the required OAuth scope ('deployment'), which is helpful for knowing prerequisites. However, it does not provide explicit guidance on when to use this tool versus alternatives like 'get_environment' or 'list_deployments', though the context is clear enough for a knowledgeable user.
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?
Annotations already declare readOnlyHint and destructiveHint, so the description adds value by specifying the required 'account' scope and pagination behavior (max_pages default and recommended limit). This goes beyond the annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, with a brief overview, a sentence of additional context, and a clean Args/Returns block. Every sentence adds value, and the information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (list operation, 3 parameters, output schema present), the description covers all necessary aspects: purpose, usage, parameters, return type, and a key constraint (scope). No gaps are apparent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, but the description's Args section fully explains each parameter: workspace (optional, default), page_size (default 30), max_pages (default 1, max recommended 10). 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists workspace members, with a specific verb and resource. It explicitly distinguishes from 'list_workspace_permissions' by noting that endpoint handles roles, and 'get_workspace_member' is a sibling for a single member. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance on when not to use this tool (for permissions, use list_workspace_permissions) and mentions a prerequisite scope. It does not explicitly compare to get_workspace_member, but the context is sufficient for selecting the tool correctly.
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?
Annotations already cover safety (readOnly, idempotent). Description adds OAuth scope requirement and parameter list. No hidden behaviors mentioned, but annotations reduce burden.
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?
Front-loaded with purpose, then scope, arguments, returns. No unnecessary words; each sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given output schema exists, description covers purpose, required scope, parameters, and return fields. Complete for a simple read 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?
Schema has 0% description coverage, but description lists all three parameters with purpose and default for workspace, adding meaning beyond 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?
Clearly states 'Get a single deployment' with specific attributes (state, environment, deployed commit). Distinguishes from siblings like list_deployments.
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?
Includes OAuth scope requirement and optional workspace parameter. Implicitly indicates use when UUID is known, but no explicit alternative comparison.
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?
Annotations already indicate readOnly, idempotent, and non-destructive. The description adds behavioral details about sorting by target date and pagination (page_size, max_pages), which go beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise: a few sentences plus a clean parameter list. Front-loaded with purpose. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple list tool with pagination, the description covers purpose, sorting nuance, all parameters with defaults, and returns paginated list. Output schema exists, so return values need no further description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, but the description fully explains each parameter: repo_slug, workspace (optional with default), page_size (default 10), max_pages (default 1, max recommended 10). This compensates completely.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'List repository tags ordered by most recent target date.' The verb 'list' and resource 'repository tags' are clear. The ordering detail distinguishes it from other list tools among siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context via the note about target date vs creation date, helping agents understand when results may differ from expectations. However, no explicit 'when to use' or alternatives are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations confirm read-only and idempotent behavior. The description adds details on pagination (page_size, max_pages), a warning for excessive fetching, and the required plugin, providing full behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with paragraphs for usage, arguments, returns, and notes. It is slightly verbose but all sentences contribute meaningful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters, no enums, and existing output schema, the description covers all necessary aspects: purpose, arguments, return format, and a prerequisite note. Annotations provide safety profile. Complete for effective selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, but the description compensates by explaining each parameter's purpose, defaults, and maximums (e.g., max_pages default 1, max recommended 10). This adds significant value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool retrieves build/CI statuses for a specific commit, differentiating it from PR-level status tools by mentioning 'without needing to create a Pull Request first.' This provides a clear verb+resource scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear use case ('check the Jenkins build status for any branch commit') and prerequisites ('Requires Jenkins Bitbucket Build Status Notifier plugin'). However, it does not explicitly state when not to use it or mention alternatives like get_pull_request_statuses.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds that fetching more than 10 pages or 300 items triggers a warning, providing extra behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise and well-structured: header, parameters with defaults, return type, and a note. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only retrieval tool with an output schema, the description covers parameters, pagination behavior, and a warning. It is sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description compensates by listing all parameters with defaults, optional notes, and a max recommended value. This adds significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'effective default reviewers for a repository.' It distinguishes from sibling tools like get_pull_request or get_issue by specifically targeting default reviewers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides default values and a warning about pagination limits, but does not explicitly state when to use this tool versus alternatives. However, the context signals and sibling names indicate its specific purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds auth requirement and error behavior beyond what annotations (readOnly, idempotent) convey. Full burden addressed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four focused sentences: purpose, auth note, parameter listing, return description. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, parameters, auth, and return values. Output schema exists and description summarizes return. Complete for a simple config retrieval.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Description explains both parameters (repo_slug as slug, workspace as optional name) despite 0% schema coverage, compensating well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it retrieves repository pipeline configuration (enabled flag, next build number). Specific verb and resource distinguish it from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly notes required admin scope and behavior for read-only tokens (403). Provides clear context but no direct comparison to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by detailing pagination (page_size, max_pages), default values, maximum recommendations, and a warning for large fetches. It also describes the return format (status, lines_added/removed, new.path). No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with Args, Returns, and Note sections. Every sentence is informative, no fluff. It front-loads the purpose and provides details in a logical order. Length is appropriate for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema (mentioned), the description covers return fields adequately. Parameters are fully described with sensible defaults and limits. The note about warning thresholds provides important context. No gaps remain for an AI agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the full burden. It explains all 5 parameters: repo_slug, pull_request_id, workspace, page_size, and max_pages, including defaults and recommended limits. This compensates thoroughly for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get file modification statistics for a pull request with pagination support', specifying the verb ('Get'), resource ('pull request diffstat'), and key feature (pagination). The name and title align, and it is distinct from sibling tools like get_pull_request_diff which focuses on diff content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving diff statistics and provides pagination parameters. It mentions a warning for large fetches but does not explicitly contrast with alternatives like get_pull_request_commits or get_pull_request_diff. However, the context is clear enough for selecting this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds pagination behavior (defaults, max recommended pages), revision defaulting, and a caveat about ambiguous branch names. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the main action, and uses a clear structured format with Args and Returns. Every sentence provides value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description does not need to detail return values. It covers all necessary context: purpose, all parameters with defaults and caveats, and pagination. No 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?
Despite 0% schema description coverage, the Args section thoroughly documents each parameter's purpose, defaults, and special notes (e.g., ambiguous branch names). This adds significant meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists commits for a repository, with specific verb 'list' and resource 'commits'. It distinguishes from sibling 'get_commit' by implying multiple vs single. No ambiguity.
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 (list commits) and includes a caveat about ambiguous branch names needing resolution. However, it does not explicitly mention alternatives like 'get_commit' for single commits, which would fully clarify usage boundaries.
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?
Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds ordering ('most recent first'), pagination details, and the filtering limitation, which are useful beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: first line purpose, then limitation, then OAuth scope, then Args list with defaults, then Returns. Every sentence adds value, no repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with pagination and an output schema, the description covers all essential aspects: purpose, parameters, ordering, limitation, authentication, and return type. It is complete and no 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?
Schema coverage is 0%, but the description documents all parameters: repo_slug (required), workspace (optional default), page_size (default 20), max_pages (default 1, max recommended 10). This fully compensates for missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List deployments for a repository (deployment history, most recent first).' This is a specific verb+resource combination that distinguishes it from sibling tools like get_deployment, list_environments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly mentions the API limitation on server-side filtering and advises client-side filtering by environment. It also requires the 'deployment' OAuth scope. No explicit alternatives, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description goes beyond these by detailing the truncation behavior (only returning last max_bytes by default), the truncated flag in the response, the absolute byte window semantics of start/end, and the null behavior for total_bytes. This adds significant behavioral context not present in annotations.
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 separate sections for Args and Returns, but it could be slightly more concise. The first paragraph clearly explains truncation and pagination, and each parameter gets a brief explanation. Minor redundancy exists (e.g., 'start/end are an absolute byte window' repeats the description in parameter docs), which trims the score from 5 to 4.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the high complexity (8 parameters, 3 required), zero schema coverage, and presence of an output schema that likely documents return fields, the description covers all necessary aspects: parameter semantics, truncation/pagination behavior, UUID resolution guidance, and response fields. The output schema handles the return format, so the description need not repeat it. Complete for a complex log retrieval 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?
Schema description coverage is 0%, so the description must fully document all 8 parameters. It does so thoroughly: explains repo_slug, pipeline_uuid (with UUID vs build number distinction), step_uuid (from get_pipeline_steps), workspace (optional, defaults to configured), log_uuid (omit for main, pass service container UUID), start and end (absolute byte window, not 'last N'), and max_bytes (trailing slice default 100 KiB, pass null for whole log). No parameter is left undocumented.
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 explicitly states the tool retrieves logs for a specific pipeline step, using the verb 'Get' and the resource 'logs for a specific pipeline step'. It clearly distinguishes from sibling tools like get_pipeline_run or get_pipeline_steps by mentioning UUID resolution and step lookup. The resource and scope are precise.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool (after resolving pipeline UUID and step UUID), and when not to (does not accept build numbers; recommends using get_pipeline_run for that). It also explains pagination behavior with start/end parameters and references sibling tools for UUID resolution, fulfilling the criteria for explicit when/when-not/alternatives.
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:

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

Score Badge

Copy to your README.md:

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

Latest Blog Posts

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

MCP directory API

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

curl -X GET 'https://glama.ai/api/mcp/v1/servers/lawp09/bitbucket-mcp'

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