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

With no annotations provided, the description fully discloses key behaviors: writes are rejected unless BBKT_API_ALLOW_WRITE is set, pagination is supported, and the tool returns raw HTTP status and JSON body. This covers safety and operational aspects adequately.

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

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

The description is concise, using three sentences that front-load the purpose, then provide usage guidance, and finally behavioral details. Every sentence adds essential information with no redundancy.

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

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

Given the tool's nature as a passthrough with moderate complexity (5 parameters, no output schema), the description covers all necessary aspects: purpose, usage context, pagination, auth restrictions, and return format. It is completely sufficient for an agent to understand and invoke the tool correctly.

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

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

The input schema already describes all 5 parameters (100% coverage). The description adds useful context beyond the schema, such as pagination defaults, method default, and read/write behavior. This enriches understanding without repeating schema info.

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

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

The description clearly states that the tool is an 'Authenticated passthrough to ANY Bitbucket Cloud REST API v2 endpoint', specifying the verb as passthrough and resource as API endpoints. It distinguishes itself from sibling typed manage_* tools by noting usage for endpoints not covered by them.

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

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: 'Prefer a typed manage_* tool when one fits; use this for the long tail instead of calling the API yourself.' It also explains that writes are rejected unless an environment variable is set, helping agents avoid errors.

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

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

With no annotations provided, the description carries full burden but only states what actions are available without disclosing behavioral traits. It doesn't mention whether operations are read-only or mutating, authentication requirements, rate limits, pagination behavior (though schema hints at it), error conditions, or what the outputs look like.

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

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

The description is a single, efficient sentence that directly states the tool's purpose. It's appropriately sized and front-loaded with the core information, though it could be slightly more specific about the resource context.

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

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

For a complex tool with 11 parameters, no annotations, and no output schema, the description is inadequate. It doesn't explain the relationships between actions and parameters, what results to expect, or important behavioral aspects. The schema handles parameter documentation, but the description fails to provide necessary context for proper tool selection and usage.

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

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 11 parameters thoroughly. The description adds no additional meaning about parameters beyond what's in the schema, so it meets the baseline of 3 where the schema does the heavy lifting.

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

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

The description states it's a 'unified tool for listing and getting commits, diffs, and diffstats' which provides a general purpose but lacks specificity about what resources it operates on (commits in a repository). It doesn't distinguish itself from sibling tools like 'manage_source' or 'manage_repositories' that might handle similar operations.

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

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 is provided. The description mentions multiple actions but doesn't explain when to choose one action over another or how this tool relates to sibling tools like 'manage_source' or 'manage_pull_requests' that might handle related operations.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure. It mentions the four action types but doesn't describe what each action does, what permissions are required, whether operations are idempotent, rate limits, or what happens on success/failure. 'Manage' is vague about mutation behaviors.

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

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

The description is a single, efficient sentence that states the unified nature and four action types. It's appropriately sized for a multi-action tool, though it could be more front-loaded with key behavioral context given the lack of annotations.

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

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

For a complex 13-parameter mutation tool with no annotations and no output schema, the description is inadequate. It doesn't explain what 'manage' entails for each action, what values are returned, error conditions, or how this tool fits with sibling tools. The agent lacks crucial context for proper invocation.

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

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 13 parameters thoroughly with descriptions and action mappings. The description adds no additional parameter semantics beyond what's in the schema, meeting the baseline for high schema coverage.

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

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

The description clearly states the tool's purpose as a 'unified tool for managing repository issues' with specific actions (list, get, create, update). It distinguishes itself from siblings like manage_commits or manage_pull_requests by focusing on issues, but doesn't explicitly differentiate from other issue-related tools that might exist.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, when to choose specific actions, or how it relates to sibling tools like manage_repositories or manage_workspaces. The agent must infer usage from the action parameter alone.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure. It lists actions but fails to describe critical behaviors: whether actions are read-only or destructive (e.g., 'stop' implies mutation), authentication needs, rate limits, error handling, or response formats. This is inadequate for a multi-action tool with potential write operations.

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

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

The description is a single, efficient sentence that front-loads the tool's unified nature and lists all actions without redundancy. Every word earns its place, making it highly concise and well-structured.

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

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

Given the tool's complexity (12 parameters, multiple actions including potential mutations like 'trigger' and 'stop'), no annotations, and no output schema, the description is insufficient. It lacks behavioral details, usage context, and output information, leaving significant gaps for an agent to operate effectively.

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

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

Schema description coverage is 100%, so parameters are well-documented in the schema. The description adds no additional semantic context beyond listing action names, which are already in the 'action' parameter description. Baseline 3 is appropriate as the schema does the heavy lifting.

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

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

The description clearly states the tool's purpose as a 'unified tool for managing Bitbucket Pipelines' and lists six specific actions (list, get, trigger, stop, list-steps, get-step-log). It distinguishes itself from siblings by focusing on pipelines rather than commits, issues, PRs, etc., though it doesn't explicitly contrast with them.

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

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

The description provides no guidance on when to use this tool versus alternatives, nor does it specify prerequisites or appropriate contexts. It merely lists actions without indicating scenarios for each, leaving the agent to infer usage from parameter descriptions.

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

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

No annotations are provided, so the description carries full burden. It lists actions but doesn't disclose behavioral traits like authentication requirements, rate limits, side effects of destructive actions (delete), or what 'resolve/unresolve' means in context. For a multi-action tool with write operations, this leaves critical gaps in understanding how the tool behaves.

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

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

The description is a single, efficient sentence that front-loads the key information: it's a unified tool for managing PR comments and enumerates all actions. There's no wasted verbiage or redundancy, making it easy to parse quickly.

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

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

Given the tool's complexity (12 parameters, multiple actions including destructive ones), lack of annotations, and no output schema, the description is inadequate. It doesn't explain return values, error conditions, or behavioral nuances needed for safe and effective use. The agent would struggle to invoke this tool correctly without trial and error.

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

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

Schema description coverage is 100%, so parameters are well-documented in the schema itself. The description adds minimal value by mentioning the action types, which aligns with the 'action' parameter's description. However, it doesn't provide additional context about parameter interactions or semantics beyond what's already in the schema, meeting the baseline for high schema coverage.

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

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

The description clearly states the tool's purpose as a 'unified tool for managing pull request comments' and lists the specific actions (list, create, update, delete, resolve, unresolve). It distinguishes itself from siblings like 'manage_pull_requests' by focusing specifically on comments rather than pull requests themselves. However, it doesn't explicitly contrast with other comment-related tools if they exist.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, when certain actions are appropriate, or how it differs from other tools that might handle comments. The agent must infer usage from the action list alone, which is insufficient for informed tool selection.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. While it lists the available actions, it provides no information about authentication requirements, rate limits, side effects, error conditions, or what happens when operations succeed/fail. For a tool with 11 different mutation actions (create, update, merge, approve, etc.), this lack of behavioral context is a significant gap.

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

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

The description is a single, efficient sentence that packs substantial information by enumerating all 11 supported actions. It's appropriately front-loaded with the core concept ('unified tool covering all pull request operations') followed by the action list. While dense, every word earns its place by specifying scope.

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

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

For a complex tool with 11 different actions (many being mutations), no annotations, and no output schema, the description is incomplete. It doesn't address authentication needs, error handling, response formats, or the behavioral differences between actions like 'merge' versus 'decline'. The agent lacks crucial context to use this tool effectively across its varied operations.

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

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 16 parameters thoroughly. The description adds no additional parameter semantics beyond what's in the schema - it doesn't explain parameter relationships, constraints, or usage patterns. The baseline of 3 is appropriate when the schema does all the parameter documentation work.

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

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

The description clearly states the tool's purpose as a 'unified tool covering all pull request operations' and enumerates the 11 specific actions it supports (list, get, create, update, merge, approve, unapprove, decline, diff, diffstat, commits). This provides a comprehensive verb+resource scope and distinguishes it from sibling tools like manage_pr_comments which would handle only comments.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, explain why one would choose this unified tool over more specialized siblings, or indicate which actions require specific permissions or conditions. The agent must infer usage entirely from the action parameter.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the operations (list, create, delete) but doesn't specify permissions required, rate limits, side effects (e.g., if deletions are permanent), or response formats. This is inadequate for a tool with multiple actions including destructive ones like delete.

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

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

The description is a single, efficient sentence that front-loads the core purpose without unnecessary words. It directly states the unified nature and key actions, making it easy to parse quickly.

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

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

Given the tool's complexity (9 parameters, multiple actions including destructive ones), no annotations, and no output schema, the description is incomplete. It lacks behavioral details, usage context, and output information, leaving significant gaps for an agent to operate effectively.

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

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 9 parameters. The description adds no additional parameter semantics beyond implying that actions involve branches and tags, which is already covered by the schema's action descriptions. Baseline 3 is appropriate as the schema does the heavy lifting.

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

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

The description clearly states the tool's purpose as a 'unified tool for listing, creating, and deleting branches and tags', which specifies the verb ('list, create, delete') and resource ('branches and tags'). However, it doesn't differentiate from sibling tools like 'manage_commits' or 'manage_repositories' that might handle related operations, so it doesn't reach the highest score.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention any prerequisites, exclusions, or compare it to sibling tools like 'manage_source' or 'manage_repositories', leaving the agent to infer usage from the action parameter alone.

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

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 but fails to do so adequately. It mentions actions like 'creating' and 'deleting' but doesn't clarify permissions needed, side effects, rate limits, or response formats. For a multi-action tool with potential mutations, this leaves critical gaps in understanding its behavior.

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

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

The description is extremely concise and front-loaded, consisting of a single sentence that directly states the tool's purpose without any unnecessary words. It efficiently communicates the core functionality, making it easy to grasp at a glance.

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

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

Given the tool's complexity with 12 parameters, multiple actions including mutations, and no annotations or output schema, the description is insufficient. It lacks details on behavioral traits, usage context, and output expectations, making it incomplete for safe and effective agent use.

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

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

The description adds no parameter-specific information beyond what the input schema already provides, as schema description coverage is 100%. The baseline score of 3 reflects that the schema adequately documents parameters, but the description doesn't enhance understanding with additional context or examples.

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

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

The description clearly states the tool's purpose as a 'unified tool for listing, getting, creating, and deleting repositories,' which specifies the actions and resource. However, it doesn't differentiate from sibling tools like 'manage_workspaces' or 'manage_source' that might handle related resources, preventing a perfect score.

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

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

The description provides no guidance on when to use this tool versus alternatives, such as when to choose 'manage_repositories' over 'manage_workspaces' for repository-related tasks. It lacks context about prerequisites, exclusions, or specific scenarios, offering only a basic functional overview.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure. It mentions the operations available but doesn't describe their behavior: what 'read' returns, what 'write' commits to, whether 'delete' is permanent, authentication requirements, rate limits, or error conditions. The description is essentially a feature list without 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.

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

The description is extremely concise - a single sentence listing the available actions. While efficient, it may be too terse given the tool's complexity. The structure is front-loaded with the unified nature of the tool, but could benefit from more context about what 'source code operations' means.

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

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

For a complex tool with 13 parameters, 6 different actions, no annotations, and no output schema, the description is inadequate. It doesn't explain what the tool actually does with source code, how actions differ, what resources they operate on, or what to expect as results. The description fails to compensate for the lack of structured metadata.

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

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 13 parameters thoroughly. The description doesn't add any parameter semantics beyond what's in the schema - it doesn't explain how parameters interact with different actions, which parameters are required for which actions, or provide examples. 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.

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

The description clearly states this is a 'unified tool for source code operations' and lists the specific actions available (read, list_directory, get_history, search, write, delete). It distinguishes itself from siblings by focusing on source code operations rather than commits, issues, pipelines, etc. However, it doesn't specify what resource it operates on (files/directories in repositories).

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

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

The description provides no guidance on when to use this tool versus the sibling tools. While it lists the available actions, it doesn't indicate when to choose this unified tool over more specialized ones like manage_commits or manage_repositories. There's no mention of prerequisites, constraints, or typical use cases.

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

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 'getting and listing' but fails to detail critical aspects like authentication requirements, rate limits, pagination behavior (beyond what the schema implies), or error handling. This leaves significant gaps for an agent to understand operational traits.

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

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

The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It is front-loaded and wastes no space, making it easy for an agent to parse quickly and understand the core functionality.

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

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

Given the tool's complexity (4 parameters, no output schema, and no annotations), the description is incomplete. It doesn't cover behavioral aspects like response format, error cases, or usage constraints, which are crucial for an agent to invoke the tool correctly in a Bitbucket context.

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

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 parameters. The description adds no additional meaning beyond what the schema provides, such as explaining the relationship between 'action' values and other parameters. This meets the baseline for high schema coverage but doesn't enhance parameter understanding.

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

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

The description clearly states the tool's purpose as a 'unified tool for getting and listing Bitbucket workspaces,' specifying both verbs ('getting' and 'listing') and the resource ('Bitbucket workspaces'). However, it doesn't explicitly differentiate from sibling tools like 'manage_repositories,' which might handle similar operations on different resources, leaving room for minor ambiguity.

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

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

The description provides no guidance on when to use this tool versus alternatives, such as other 'manage_' tools for different Bitbucket resources. It lacks context on prerequisites, exclusions, or specific scenarios where this tool is preferred, relying solely on the tool name and description for implied usage.

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