Server Quality Checklist

Tool Scores

• get_activitiesB
  3.2/5.0
  Behavior2/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  No annotations are provided, so the description carries full burden. It describes what the tool retrieves but doesn't disclose behavioral traits like whether this is a read-only operation (implied by 'retrieve'), potential rate limits, authentication requirements, pagination behavior, or what happens if parameters are invalid. For a tool with no annotation coverage, this leaves significant gaps in understanding how it behaves.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is two sentences that efficiently convey the purpose and usage without wasted words. It's front-loaded with the core functionality and follows with the intended use case. However, the second sentence could be slightly more concise by integrating with the first.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given no annotations and no output schema, the description provides basic purpose and usage but lacks details on behavioral aspects (e.g., safety, performance) and output format. For a tool with 3 parameters and sibling tools offering overlapping functionality, more context on differentiation and operational traits would improve completeness.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100%, so the schema already documents all three parameters thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema (e.g., it doesn't explain relationships between parameters or provide usage examples). Baseline 3 is appropriate when the schema does the heavy lifting.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the verb 'retrieve' and resource 'activities for a pull request' with specific examples of what's included (comments, reviews, commits, timeline events). It distinguishes from siblings like get_comments or get_reviews by mentioning it retrieves 'all activities' including those elements, but doesn't explicitly contrast with get_pull_request which might also provide some activity information.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description provides implied usage guidance by stating 'Use this to get the complete activity history and timeline,' suggesting this is for comprehensive historical data rather than specific subsets. However, it doesn't explicitly state when to use this versus alternatives like get_comments (for just comments) or get_pull_request (which might include some activity data), nor does it mention any prerequisites or exclusions.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• list_repositoriesB
  3.2/5.0
  Behavior2/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions what the tool returns ('repository names, slugs, clone URLs, and project associations'), which is helpful. However, it doesn't disclose important behavioral traits such as whether this is a read-only operation (implied but not stated), pagination behavior (hinted at by 'limit' and 'start' parameters but not explained in description), authentication requirements, rate limits, or error conditions. For a tool with no annotations, this leaves significant gaps.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is appropriately sized with three sentences that are front-loaded with the core purpose. Each sentence adds value: the first states what the tool does, the second provides usage context, and the third describes the return values. There's minimal waste, though it could be slightly more structured (e.g., separating purpose from usage more clearly).

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the tool's moderate complexity (3 parameters, no output schema, no annotations), the description is partially complete. It covers the purpose, usage hints, and return values, but lacks details on behavioral aspects like pagination, authentication, or error handling. With no output schema, the description's mention of return values is helpful, but it doesn't fully compensate for the missing annotations and behavioral context. It's adequate but has clear gaps.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The input schema has 100% description coverage, providing clear documentation for all three parameters ('project', 'limit', 'start'). The description adds no additional parameter-specific information beyond what's in the schema. According to the rules, when schema_description_coverage is high (>80%), the baseline score is 3 even with no param info in the description, which applies here.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool's purpose: 'Browse and discover repositories within a specific project or across all accessible projects.' It specifies the verb ('browse and discover') and resource ('repositories'), and mentions the scope ('specific project or across all accessible projects'). However, it doesn't explicitly differentiate from sibling tools like 'browse_repository' or 'list_projects', which would be needed for a score of 5.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description implies usage context by stating 'Use this to find repository slugs, explore codebases, or understand the repository structure,' which suggests when this tool might be appropriate. However, it doesn't provide explicit guidance on when to use this versus alternatives like 'browse_repository' or 'list_projects', nor does it mention any exclusions or prerequisites. The guidance is present but not comprehensive.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• browse_repositoryA
  3.7/5.0
  Behavior2/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  No annotations are provided, so the description carries the full burden of behavioral disclosure. While it mentions the tool's purpose, it lacks details on behavioral traits such as pagination behavior (implied by the 'limit' parameter but not explained), error handling, authentication requirements, or rate limits. This is a significant gap for a tool with multiple parameters and no 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 appropriately sized and front-loaded, with two concise sentences that directly state the tool's purpose and usage context. Every sentence earns its place without redundancy or unnecessary elaboration.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the tool's moderate complexity (5 parameters, no output schema, no annotations), the description is adequate but incomplete. It covers the basic purpose and usage but lacks behavioral details (e.g., output format, error cases) that would help an agent use it effectively. Without annotations or an output schema, more context is needed for full completeness.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description does not add any additional meaning or context beyond what the schema provides (e.g., it doesn't explain parameter interactions or default values beyond the schema). Baseline 3 is appropriate when the schema does the heavy lifting.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool's purpose with specific verbs ('browse and list') and resources ('files and directories in a Bitbucket repository'). It distinguishes this from sibling tools like 'get_file_content' (which retrieves content) or 'search' (which searches across repositories) by focusing on structural exploration.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description provides clear context for when to use this tool ('to explore repository structure, find files, or navigate directories'), but it does not explicitly state when not to use it or name specific alternatives. For example, it doesn't clarify that 'get_file_content' should be used for reading file contents instead of this tool.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• create_pull_requestA
  3.8/5.0
  Behavior3/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  With no annotations provided, the description carries the full burden of behavioral disclosure. It adds useful context about automatically setting up branch references and assigning reviewers, but lacks details on permissions required, error conditions, rate limits, or what happens on success/failure. For a mutation tool with zero annotation coverage, this leaves significant gaps.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is efficiently structured in two sentences that front-load the core purpose and usage context. Every sentence adds value, though it could be slightly more concise by combining some clauses without losing clarity.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a mutation tool with 7 parameters, no annotations, and no output schema, the description is moderately complete. It covers purpose and basic usage but lacks details on behavioral outcomes, error handling, or return values. Given the complexity and absence of structured safety/behavioral data, it should provide more guidance on what to expect after invocation.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100%, so the schema already documents all 7 parameters thoroughly. The description does not add any parameter-specific information beyond what's in the schema, such as formatting examples or constraints not captured in schema descriptions. Baseline 3 is appropriate when schema does the heavy lifting.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool's purpose with specific verbs ('create a new pull request') and resources ('code changes', 'feature branches'), distinguishing it from siblings like 'merge_pull_request' or 'decline_pull_request' by focusing on creation rather than modification or review actions.

  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 the tool ('when you want to submit code for review, merge a feature branch, or contribute changes'), but does not explicitly state when NOT to use it or name specific alternatives among siblings like 'merge_pull_request' for merging without creation.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• searchA
  3.8/5.0
  Behavior3/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  With no annotations provided, the description carries the full burden of behavioral disclosure. It describes what the tool does (searching code/files across repositories) and mentions filtering capabilities, but doesn't address important behavioral aspects like authentication requirements, rate limits, error conditions, or what the response format looks like. The description provides basic operational context but misses key behavioral details.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is appropriately sized with three sentences that each add value. It's front-loaded with the core purpose, followed by usage context and capabilities. While efficient, the third sentence could be slightly more structured by separating the filtering and optimization aspects more clearly.

  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 search tool with 6 parameters, no annotations, and no output schema, the description provides adequate context about what the tool does but lacks important completeness elements. It doesn't describe the return format, result structure, pagination behavior, or error handling. The description covers the 'what' but misses the 'what comes back' and operational constraints.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100%, so the schema already documents all 6 parameters thoroughly. The description mentions 'filtering by project, repository, and query optimization' which aligns with parameters but doesn't add significant meaning beyond what the schema provides. The baseline of 3 is appropriate when the schema does the heavy lifting.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool's purpose with specific verbs ('search for code or files') and resources ('across repositories'), distinguishing it from sibling tools like browse_repository or get_file_content. It explicitly mentions searching both file contents and filenames, providing a comprehensive 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 provides clear context for when to use this tool ('to find specific code patterns, file names, or content within projects and repositories'), but doesn't explicitly mention when not to use it or name specific alternatives among the sibling tools. It implies usage for search tasks but lacks explicit exclusions.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• add_commentA
  3.9/5.0
  Behavior3/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  With no annotations provided, the description carries the full burden. It discloses that the tool supports 'threaded conversations' (via parentId) and Markdown formatting, which is useful behavioral context. However, it lacks details on permissions, rate limits, or response format that would be important for a mutation tool.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is front-loaded with the core purpose in the first sentence, followed by specific use cases and a key feature ('Supports threaded conversations'). Every sentence adds value with zero waste, making it efficient and well-structured.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given no annotations and no output schema, the description is moderately complete for a mutation tool. It covers the purpose and usage well but lacks details on behavioral aspects like authentication needs, error handling, or what the tool returns, which are gaps for a tool that modifies data.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds no additional parameter semantics beyond what's in the schema, such as explaining how 'parentId' enables threading or formatting details for 'text'. Baseline 3 is appropriate when the schema does the heavy lifting.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the specific action ('Add a comment') and resource ('to a pull request'), with explicit purposes like 'code review, feedback, questions, or discussion'. It distinguishes from sibling tools like 'get_comments' (which retrieves) and 'add_comment_inline' (which likely adds inline comments).

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description provides clear context for when to use this tool ('provide review feedback, ask questions about specific changes, suggest improvements, or participate in code review discussions'), but does not explicitly state when not to use it or name alternatives like 'add_comment_inline' for comparison.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• add_comment_inlineA
  3.9/5.0
  Behavior3/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions that the tool 'supports threaded conversations' and implies mutation ('Add'), but does not disclose other behavioral traits such as required permissions, rate limits, or what happens on success/failure. This leaves gaps for a mutation tool, though the purpose is clear.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is appropriately sized and front-loaded, with the first sentence covering the core purpose and the second adding usage context. Every sentence adds value without redundancy, making it efficient and well-structured.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the complexity of a mutation tool with 8 parameters and no annotations or output schema, the description is somewhat complete but lacks details on behavioral aspects like error handling or response format. It covers purpose and usage well but misses deeper contextual information needed for full agent understanding.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100%, so the input schema fully documents all 8 parameters. The description does not add any parameter-specific details beyond what the schema provides, such as examples or edge cases. This meets the baseline of 3, as the schema handles the heavy lifting.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the specific action ('Add an inline comment'), target resource ('to the diff of a pull request'), and purpose ('for code review, feedback, questions, or discussion'). It distinguishes from the sibling 'add_comment' by specifying 'inline comment (to specific lines)' and mentions threaded conversations, providing clear differentiation.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description explicitly states when to use this tool ('to provide review feedback, ask questions about specific changes, suggest improvements, or participate in code review discussions'), which gives clear context. However, it does not mention when not to use it or explicitly name alternatives like 'add_comment' for non-inline comments, which prevents a perfect score.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• get_diffA
  3.9/5.0
  Behavior3/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  With no annotations provided, the description carries the full burden of behavioral disclosure. It describes what the tool returns ('code differences showing what lines were added, removed, or modified') and the purpose of those differences. However, it doesn't mention important behavioral aspects like whether this is a read-only operation (implied but not stated), potential rate limits, authentication requirements, or what format the diff is returned in (unified diff, JSON, etc.).

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is efficiently structured with two sentences. The first sentence states the core purpose, and the second provides usage context. Every sentence earns its place by adding value - no redundant or vague language. It's appropriately sized for a tool with 5 parameters and good schema documentation.

  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 tool with 5 parameters, 100% schema coverage, but no annotations and no output schema, the description is adequate but has gaps. It explains the purpose and usage context well, but doesn't address the output format or behavioral constraints that would be important for an agent to use this tool effectively. The absence of output schema means the description should ideally mention what format the diff is returned in.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100%, so the schema already documents all 5 parameters thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema. It mentions 'diff' generally but doesn't explain how parameters like contextLines or maxLinesPerFile affect the output format. Baseline 3 is appropriate when the schema does the heavy lifting.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool's purpose with specific verbs ('retrieve', 'show') and resource ('code differences for a pull request'). It distinguishes this tool from siblings like get_pull_request (which likely returns metadata) or get_file_content (which retrieves file contents rather than diffs). The description explicitly mentions what the diff shows: 'lines were added, removed, or modified'.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description provides clear context for when to use this tool: 'to understand the scope of changes, review specific code modifications, or analyze the impact of proposed changes before merging.' This gives the agent specific scenarios for invocation. However, it doesn't explicitly state when NOT to use this tool or mention alternatives like get_pull_request for high-level information.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• get_file_contentA
  3.9/5.0
  Behavior3/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the core functionality (retrieving file content) and mentions pagination behavior for large files, which is useful context. However, it doesn't cover other important behavioral aspects like error conditions (e.g., file not found), authentication requirements, rate limits, or response format details.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is perfectly sized and front-loaded: the first sentence states the core purpose, the second provides usage context, and the third offers specific guidance for edge cases (large files). Every sentence earns its place with zero wasted words or redundancy.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a read operation with 6 parameters and no output schema, the description provides adequate but incomplete coverage. It explains the what and when-to-use well, but lacks details about return values, error handling, and authentication requirements that would be helpful given the tool's complexity and absence of both annotations and output schema.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The schema description coverage is 100%, so the schema already documents all 6 parameters thoroughly. The description adds minimal value beyond the schema by mentioning the 'start' parameter for pagination and implying text-based file usage, but doesn't provide additional syntax, format, or constraint details that aren't already in the schema descriptions.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the specific action ('Retrieve the content'), resource ('a specific file from a Bitbucket repository'), and scope ('with pagination support'). It distinguishes this tool from siblings like 'browse_repository' (which likely lists files) or 'get_diff' (which compares changes) by focusing on reading file contents directly.

  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 on when to use this tool ('to read source code, configuration files, documentation, or any text-based files') and includes an explicit alternative for large files ('use start parameter to paginate'). However, it doesn't explicitly state when NOT to use it or compare it to all sibling tools (e.g., vs. 'get_diff' for file comparisons).

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• get_pull_requestA
  3.9/5.0
  Behavior3/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  With no annotations provided, the description carries the full burden. It implies a read-only operation through verbs like 'retrieve' and 'check,' but doesn't explicitly state permission requirements, rate limits, or error behaviors. It adds some context about the scope of returned data but lacks details on pagination or response format.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is efficiently structured in two sentences: the first states the purpose and scope, the second provides usage guidelines. Every phrase adds value without redundancy, making it appropriately sized and front-loaded with essential information.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a read operation with 3 parameters, 100% schema coverage, and no output schema, the description provides adequate purpose and usage context. However, without annotations or output schema, it lacks details on return format, error handling, or authentication needs, leaving some gaps for the agent to infer.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100%, so the schema already documents all three parameters thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema, maintaining the baseline score of 3 for adequate but not enhanced parameter documentation.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the verb 'retrieve' and resource 'pull request' with specific details included ('comprehensive details about a specific pull request including status, reviewers, commits, and metadata'). It distinguishes from siblings like get_comments or get_diff by emphasizing comprehensive details rather than specific aspects.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description provides clear context for when to use this tool ('to check PR status, review progress, understand changes, or gather information before performing actions like merging or commenting'), which helps differentiate it from write-oriented siblings like merge_pull_request. However, it doesn't explicitly state when NOT to use it or name specific alternatives among siblings.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• get_reviewsA
  3.9/5.0
  Behavior3/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  No annotations are provided, so the description carries the full burden. It discloses the tool's purpose and what information it returns (review history, approval status, feedback, merge readiness), but lacks details on behavioral traits like error handling, rate limits, authentication needs, or response format. It's adequate but has gaps for a tool with no 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 front-loaded with the core purpose in the first sentence, followed by specific use cases. It uses two concise sentences with zero wasted words, efficiently covering key aspects without redundancy.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given no annotations and no output schema, the description adequately explains the tool's purpose and usage context. However, it lacks details on return values (e.g., format of review data), error conditions, or prerequisites, which would be helpful for completeness in this context.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100%, so the schema fully documents all three parameters. The description does not add any parameter-specific information beyond what the schema provides, such as examples or constraints. Baseline 3 is appropriate when the schema handles parameter documentation.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the specific action ('fetch') and resource ('review history and approval status of a pull request'), with explicit purposes like checking reviewers, approval status, feedback, and merge readiness. It distinguishes from siblings like get_pull_request (general PR info) or get_comments (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 Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description provides clear context for when to use this tool ('to check who has reviewed... see approval status... determine if ready for merging'), but does not explicitly state when not to use it or name alternatives. It implies usage for review-related queries rather than general PR info.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• decline_pull_requestA
  4.1/5.0
  Behavior3/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  No annotations are provided, so the description carries the full burden. It discloses that the action 'declines or rejects' and 'closes the PR without merging,' which implies a destructive mutation. However, it lacks details on permissions required, whether the action is reversible, or any rate limits. It adds some behavioral context but is incomplete for a mutation tool.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is front-loaded with the core action and usage guidelines in two concise sentences. Every sentence earns its place by clarifying purpose, when to use, and the outcome, with no wasted words. 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?

  Given no annotations and no output schema, the description is moderately complete. It covers purpose and usage well but lacks details on behavioral aspects like permissions or reversibility. For a mutation tool with 4 parameters and no structured safety hints, it should provide more context on risks or requirements, leaving some gaps.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100%, so the schema already documents all parameters. The description does not add any additional meaning or syntax details beyond what the schema provides. It mentions a 'reason for declining' which aligns with the 'message' parameter but doesn't elaborate further. Baseline 3 is appropriate when the schema handles parameter documentation.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the specific action ('decline or reject a pull request') and resource ('pull request'), distinguishing it from siblings like 'merge_pull_request' by specifying it 'closes the PR without merging.' It avoids tautology by explaining the outcome rather than just restating the name.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description explicitly states when to use this tool: 'when changes are not acceptable, conflicts with project direction, or when the PR needs significant rework.' It also distinguishes from alternatives by noting it 'closes the PR without merging,' contrasting with 'merge_pull_request.' This provides clear context and exclusions.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• get_commentsA
  4.1/5.0
  Behavior3/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  With no annotations provided, the description carries the full burden of behavioral disclosure. It correctly indicates this is a read operation ('retrieve'), but doesn't mention authentication requirements, rate limits, pagination behavior, or error conditions. The description is accurate but lacks comprehensive behavioral context needed for a read-only tool with no annotation coverage.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is perfectly concise with two sentences that each earn their place. The first sentence states the core purpose, and the second provides essential usage guidance. There's zero waste or redundancy, and it's front-loaded with the most important information.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a read-only tool with 3 parameters, 100% schema coverage, but no output schema or annotations, the description provides adequate purpose and usage guidance but lacks information about return values, error handling, or authentication. The agent knows what the tool does and when to use it, but not what to expect from the operation or potential constraints.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100%, so all parameters are documented in the schema. The description doesn't add any parameter-specific information beyond what the schema provides about project, repository, and prId. It correctly implies these parameters are needed but doesn't elaborate on their semantics, format, or relationships.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the specific verb ('retrieve') and resource ('comments from a pull request'), and distinguishes it from siblings by specifying 'only the comments' and contrasting with 'other activities like reviews or commits'. This provides precise differentiation from tools like get_activities or get_reviews.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description explicitly states when to use this tool ('when you specifically want to read the discussion and feedback comments') and when not to use it ('without other activities like reviews or commits'), providing clear alternatives. This gives the agent perfect guidance on tool selection among siblings.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• merge_pull_requestA
  4.1/5.0
  Behavior3/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  With no annotations provided, the description carries the full burden. It clearly indicates this is a write/mutation operation ('merge'), but doesn't disclose permissions needed, whether the merge is reversible, rate limits, or what happens on failure. It mentions strategy selection but doesn't explain default behavior if strategy is omitted.

  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 well-structured sentences with zero waste. First sentence states purpose and prerequisites, second provides strategic guidance. Every word earns its place, and the most critical information (what it does and when to use it) is front-loaded.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a mutation tool with no annotations and no output schema, the description does well on purpose and guidelines but lacks behavioral details about permissions, reversibility, error conditions, or return values. Given the complexity of merging code changes, more transparency about what happens during execution would be beneficial.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100%, so the schema already documents all 5 parameters thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema, but doesn't need to since schema coverage is complete. Baseline 3 is appropriate when schema does the heavy lifting.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the specific action ('merge'), the resource ('an approved pull request'), and the outcome ('into the target branch'). It distinguishes this tool from siblings like 'decline_pull_request' or 'create_pull_request' by focusing on the final integration step after approval.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  Explicitly states when to use this tool: 'when a PR has been reviewed, approved, and is ready to be integrated.' It also provides guidance on choosing the merge strategy based on team workflow and repository history, offering contextual decision-making criteria.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• list_projectsA
  4.2/5.0
  Behavior3/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  With no annotations provided, the description carries the full burden of behavioral disclosure. It describes the return format ('Returns project keys, names, descriptions and visibility settings') which is valuable, but doesn't mention authentication requirements, rate limits, error conditions, or pagination behavior beyond what's implied by the parameters. It adequately covers the core behavior but lacks comprehensive operational details.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is efficiently structured with two sentences that each serve distinct purposes: the first states the core functionality, the second provides usage guidance and return format. There's no wasted language, and key information is front-loaded appropriately.

  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 operation with 2 parameters, 100% schema coverage, and no output schema, the description provides good context about purpose, usage scenarios, and return format. However, without annotations or output schema, it could benefit from more detail about authentication, error handling, or pagination behavior to be 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?

  Schema description coverage is 100%, so the schema already fully documents both parameters (limit and start). The description doesn't add any parameter-specific information beyond what's in the schema. This meets the baseline expectation when schema coverage is complete.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the specific action ('Discover and list'), resource ('all Bitbucket projects'), and scope ('you have access to'), distinguishing it from sibling tools like list_repositories or search. It provides a comprehensive purpose statement that goes beyond a simple tautology.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description explicitly states when to use this tool: 'Use this first to explore available projects, find project keys, or when you need to work with a specific project but don't know its exact key.' It provides clear context for usage scenarios, though it doesn't explicitly mention when NOT to use it or name specific alternatives.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.