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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the agent knows this is a safe, non-mutating read operation, and the description ('List') is consistent with those. The description adds no additional behavioral context such as pagination, ordering, or output scope, but the annotated safety profile lowers the burden here.

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?

A single front-loaded sentence with no filler, repetition, or unnecessary words. Every word carries meaning and the core action is immediately visible.

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?

This is a minimum-viable description: it names the operation and relies on the schema for parameter semantics and on annotations for safety. It lacks guidance on pagination/limits, output shape, and when to use it relative to sibling list tools, which is a clear gap for a tool with no output schema.

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 coverage is 50%, with query and workspace already described in the input schema; repoSlug and maxItems have no description but are semantically obvious from their names and constraints. The description itself adds no parameter detail beyond tying the operation to 'a repository', so it does not materially improve on the schema.

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 uses a specific verb ('List') and resource ('branches in a repository'), clearly identifying what the tool does. It does not explicitly distinguish itself from sibling tools like bitbucket_tag_list or bitbucket_commit_list, but the resource is specific enough on its own.

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 choose this tool over alternatives such as tag_list or commit_list, and it does not mention prerequisites like requiring a workspace or repoSlug. Usage context is only implied by the tool name and schema.

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?

The read-only, idempotent, and open-world hints are already provided by the annotations, so the description does not need to repeat them. It adds a useful scoping phrase ('across a workspace's repositories'), but does not disclose result shape, pagination, or anything beyond the annotation truth.

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 one efficient, front-loaded sentence with no filler or repetition. It is appropriately concise for a straightforward read-only search tool, though it does not carry extra structural richness.

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 small read-only search tool, the purpose, required parameter, workspace default, and maxItems constraint are reasonably discoverable from the schema and annotations. The description is missing output/result-format guidance and does not mention sibling routes, but the overall definition is still adequate for basic 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 moderate at 67%, and the searchQuery and workspace parameters already have useful descriptions in the schema. The tool description itself adds no parameter-level meaning, but the existing schema covers the majority of what an agent needs.

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 uses a specific verb ('search') and a specific resource ('code across a workspace's repositories'). It clearly identifies the tool as a code search rather than a repository/source-fetch tool, though it does not explicitly contrast it with a sibling tool.

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

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

There is no guidance on when to use this tool versus alternatives like bitbucket_source_get or bitbucket_repository_list. No exclusions or conditions are given, so the agent must infer the use case from the tool name and short description.

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?

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is clear. The description adds useful behavioral context by stating the output is a full unified diff and that it can be scoped to one file, which is meaningful because no output schema exists. It does not mention potential size/pagination or access prerequisites, but it adds value 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.

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

The description is two short sentences with zero filler. The core operation is front-loaded, and 'Prefer diffstat first' packs meaningful guidance into four words. Every sentence earns its place.

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 low schema coverage and absent output schema, the description is adequate but incomplete. It correctly identifies the response type and scope, but leaves out the spec format, explicit alternatives like diffstat or pull-request diff, and any limit on commit-range length. An agent can likely proceed, but some inference is required.

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 only 25%, so the description must compensate. It does add meaning for 'spec' ('commit or commit range') and 'path' ('optionally scoped to one file'), but it does not specify the exact format expected for the commit range or for repoSlug, and workspace is only handled by the schema. This is helpful but not fully compensating for the low 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 uses a specific verb ('Get') and a specific resource ('full unified diff for a commit or commit range'), and adds scope ('optionally scoped to one file'). It is clearly distinct from the diffstat sibling by emphasizing 'full unified diff', so an agent can separate it from bitbucket_commit_diffstat.

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 instruction 'Prefer diffstat first' provides clear ordering guidance and implies this tool is for the full diff after consulting the summary diffstat. It does not explicitly name the diffstat sibling or contrast with pull_request_diff, but the commit/commit-range scope and the preference instruction give enough context to route correctly.

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?

Annotations already declare readOnlyHint=true and idempotentHint=true, covering safety and idempotency. The description adds that the tool returns a summary per file rather than content, which is useful behavioral context. It does not contradict annotations and adequately communicates the operation's nature for a read-only tool.

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 two sentences with zero wasted words. The core purpose is front-loaded, followed immediately by the usage guidance. Every sentence earns its place and the structure is optimal for quick agent parsing.

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 simple read-only tool with annotations covering safety, the description provides the essential purpose and usage guidance. It omits details about the exact contents of the summary (e.g., lines added/deleted) and there is no output schema, but this is minor given the tool's simplicity and the sibling context. The description is adequate for an agent to call it 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?

Schema coverage is 67% (spec and workspace have descriptions; repoSlug lacks one). The description provides an example for the spec parameter ('base..head'), which adds a bit beyond the schema's 'A commit hash, or base..head range'. However, it does not clarify repoSlug, leaving a gap that the description could have addressed. Given moderate coverage, a score of 3 is appropriate.

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 function: 'Get the per-file change summary for a commit or commit range'. It specifies the resource (commit) and the result type (per-file summary), and gives a concrete example of the range format. This distinguishes it from siblings like bitbucket_commit_diff, which returns the full diff.

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 explicitly says 'Prefer over the full diff unless file contents are actually needed.' This is a direct when-to-use vs. alternative instruction, pointing the agent to bitbucket_commit_diff when file contents are required. No other exclusions are necessary given the tool's specific scope.

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?

Annotations already declare readOnlyHint and idempotentHint, but the description adds no behavioral context beyond those. It does not clarify what 'details' includes, whether the commit parameter accepts a hash or ref, or what the response contains.

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 concise sentence with no filler, which is good. But it is under-specified rather than well-structured, providing little beyond the tool name's obvious meaning.

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?

With no output schema, minimal parameter descriptions, and many closely related commit siblings, the description does not give an agent enough information to know exactly what data is returned or how this tool differs from commit_diff or source_get. It is minimally viable but incomplete.

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 only 33%, with only workspace described, and the tool description does not explain repoSlug or commit. The phrase 'one commit's details' weakly implies the commit parameter identifies the target, but it fails to compensate for the two undocumented required parameters.

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 a specific verb ('Get') and resource ('one commit's details'), and the word 'one' distinguishes it from bitbucket_commit_list. However, 'details' is vague and it doesn't explicitly differentiate from commit_diff, diffstat, or statuses siblings.

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?

There is no guidance on when to use this tool versus alternatives like bitbucket_commit_list, bitbucket_commit_diff, or bitbucket_source_get. No prerequisites or exclusion conditions are mentioned, so the agent must infer usage from the tool name alone.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds minimal behavioral context beyond the schema, such as the fact that it lists from a ref, but doesn't disclose details like pagination behavior, default ordering, or whether it includes merge commits. With annotations covering the read-only nature, a 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.

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

The description is a single concise sentence that front-loads the core action and resource. It earns its place with no wasted words, though it could arguably add a bit more context without becoming verbose.

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 read-only list operation with annotations covering safety, the description is adequate but not complete. It doesn't mention return format, pagination, or how it differs from related commit tools. Given the tool's moderate complexity (4 params, no output schema), a bit more context would help an agent select and invoke it 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?

Schema description coverage is 50%, with 'revision' and 'workspace' having descriptions. The tool description itself adds no parameter-level meaning beyond what the schema provides. The 'maxItems' and 'repoSlug' parameters lack descriptions in the schema, and the description doesn't compensate for those gaps, so the baseline 3 is appropriate.

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 'List commits on a branch/ref' uses a specific verb and resource, clearly identifying the tool's function. It distinguishes itself from sibling tools like bitbucket_commit_get (which fetches a single commit) and bitbucket_branch_list (which lists branches), though it doesn't explicitly name those alternatives.

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 implies usage context by mentioning 'branch/ref', and the schema's revision parameter description clarifies that it can be a branch, tag, or commit. However, there is no explicit guidance on when to use this tool versus alternatives like bitbucket_commit_get or bitbucket_commit_list_statuses, and no mention of exclusions or prerequisites.

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?

The annotations already declare readOnlyHint and idempotentHint, covering the safety profile. But the description adds no additional behavioral context such as pagination, the exact status types returned, or whether an invalid commit fails silently, so it does not go beyond the structured hints.

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, compact sentence that states the action and the resource without filler. It is appropriately sized for a simple list operation and remains front-loaded with the essential purpose.

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?

The tool takes 3 parameters, has no output schema, and has low schema description coverage. A one-line description does not sufficiently explain the exact parameters, response shape, or behavior for an agent to invoke it confidently, especially given the sibling tools that command similar actions.

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?

With schema description coverage at only 33%, the description should compensate by clarifying the meaning of commit and repoSlug, but it only says 'build/CI statuses attached to a commit.' The workspace parameter is already documented in the schema, but the other two essential parameters remain ambiguously named and unexplained.

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 verb 'List' and the resource 'build/CI statuses attached to a commit,' so an agent can understand the core function. However, it does not explicitly differentiate from sibling tools like bitbucket_pull_request_list_statuses, leaving the distinction entirely to the tool name.

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 cues about when to use this tool over siblings such as pull_request_list_statuses or commit_get. It also omits any prerequisites (e.g., existing CI integrations) or exclusions, leaving the agent without routing guidance.

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?

Annotations are all false (readOnlyHint, idempotentHint, destructiveHint), so they provide no behavioral insight. The description compensates by disclosing the pending/invisible state and the condition for visibility (submitting a review). This is a key behavioral trait beyond what annotations offer, though it does not cover other aspects like reversibility or authentication requirements. Given the annotation void, the description adds substantial transparency.

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, focused sentence that front-loads the core action and its key behavior. There is no fluff or redundant information, making it efficient for an agent to parse.

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

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

The tool has 6 parameters, no output schema, and the description is minimal. It does not explain the workflow (e.g., that a review must be submitted for the comment to appear), does not clarify ambiguous parameters, and provides no insight into return values or side effects. For a create operation with several undocumented parameters, this is insufficient for reliable 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?

The description provides no parameter-level guidance. Schema coverage is only 33% (repoSlug and workspace have descriptions; id, body, inlineLine, inlinePath do not). The description fails to compensate for the missing meanings of id (presumably the pull request ID), inlineLine/inlinePath (for inline comments), or how body is used. With low schema coverage, the description should have clarified these, but it does not.

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 action (add a comment), the resource (pull request), and a distinguishing trait (pending, invisible to others until review submission). This differentiates it from sibling tools like bitbucket_pull_request_comment_list and other PR operations, making the purpose unambiguous.

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

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

The description provides clear context: it's for adding a pending comment that becomes visible only after the user submits a review in Bitbucket's UI. However, it does not explicitly mention alternatives or exclusions (e.g., if a visible comment is needed, use a different tool). Since no direct alternative exists among siblings, the lack of explicit routing is acceptable, but the guidance is still somewhat implied rather than stated.

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?

Annotations already declare readOnlyHint=true and idempotentHint=true, and 'List comments' is consistent with those, so there is no contradiction. However, the description adds no behavioral context beyond the annotations — nothing about pagination, ordering, or what the response contains — so it contributes minimal value.

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?

A single clear, front-loaded sentence with zero wasted words. It conveys the essential action efficiently.

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 list tool with no output schema and a non-obvious maxItems parameter, the description is too thin. It fails to mention pagination, default result limits, or return semantics, and gives an agent no help distinguishing comments from tasks via the sibling task_list tool.

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 only 50%; id and maxItems have no schema descriptions, and the tool description adds nothing about any parameter. In particular, maxItems (default 50, max 100) is non-obvious and could benefit from explanation, but the description provides no compensation for the coverage gap.

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 a specific verb (List) and resource (comments on a pull request), so the core action is clear. However, it does not distinguish itself from nearby siblings like bitbucket_pull_request_task_list (tasks vs. comments) or bitbucket_pull_request_comment_create, so an agent must infer the boundary from names alone.

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?

There is no guidance on when to use this tool versus alternatives. With siblings such as bitbucket_pull_request_comment_create, bitbucket_pull_request_task_list, and bitbucket_pull_request_get, no context or exclusions are given to help an agent choose correctly.

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?

The annotations provide only negative hints, so the description carries the behavioral burden. It clearly discloses the draft state, visibility to teammates, and that the PR remains not-ready until marked ready in Bitbucket. It does not cover authorization or error behavior, but the core state transition is transparent.

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?

A single sentence front-loads the primary action and then adds the essential draft-state nuance. 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.

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

This is a 7-parameter mutation with no output schema and only minimal annotation value. The description covers high-level selection but leaves required parameter behavior, defaults for the workflow, and invocation details under-explained, forcing the schema and the agent to do the heavy lifting.

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-level meaning; it never mentions repoSlug, title, sourceBranch, reviewers, workspace, description, or destinationBranch. With schema description coverage at only 57% and the required title and sourceBranch properties lacking descriptions, this is a meaningful gap.

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 explicitly identifies the exact action and resource ('Create a new pull request') and adds the unique draft state ('as a draft'). This differentiates it from the sibling list/get/read tools without requiring schema inspection.

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 draft and 'not-yet-ready-for-review' language imply the intended use case, but there is no explicit when-to-use or when-not-to-use guidance, and no alternative tool is mentioned. The agent must infer that this is for work-in-progress pull requests.

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?

Annotations already declare readOnlyHint=true and idempotentHint=true, covering the safety profile. The description adds that this returns a full unified diff and implicitly signals a heavier payload via 'only when file contents are actually needed,' which is useful cost context. 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.

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

Two sentences with zero waste; the core purpose is front-loaded and the routing guidance follows naturally. Every clause earns its place.

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 read-only fetch tool with no output schema, the description covers what is returned (full unified diff, optional file scoping) and when to use it. Combined with the rich schema and safety annotations, nothing essential an agent needs to invoke it correctly is missing.

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 coverage is 75%, with path, repoSlug, and workspace already described in the schema. The description reinforces the path intent ('optionally scoped to one file') but adds no new parameter detail. The 'id' parameter remains undocumented in both schema and description, but it is self-evident. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

States a specific verb and resource ('Get the full unified diff for a pull request') plus an optional scoping mode ('scoped to one file'). It explicitly differentiates from the sibling by declaring the diffstat distinction, so an agent can tell this apart from bitbucket_pull_request_diffstat without opening either schema.

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?

Provides explicit routing guidance: 'Prefer diffstat first; use this only when file contents are actually needed.' This names the alternative tool and the exact condition that should trigger selection, leaving nothing to inference.

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?

Annotations already declare readOnlyHint and idempotentHint, so no safety disclosure is needed. The description adds useful behavioral context beyond that: it returns only a per-file summary rather than file contents, and it is the cheapest way to see what changed, which informs latency and cost expectations.

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?

Two sentences with no filler: the first states what the tool returns, and the second gives the routing guidance. Every sentence earns its place and the key usage direction is front-loaded.

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 simple read-only list-like tool with annotations already covering safety, the description covers the output ('files touched, lines +/-'), the purpose ('what changed'), and the decision boundary versus the diff tool. Nothing an agent needs to invoke it correctly is missing.

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 coverage is 67%: repoSlug and workspace are described in the schema, but the required 'id' parameter is not. The description adds that the tool is 'for a pull request,' which mildly clarifies the role of id, but it does not fully compensate for the undocumented id parameter.

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 names a specific verb ('Get'), a concrete resource ('per-file change summary for a pull request'), and the returned content ('files touched, lines +/-'). It also distinguishes itself from the full diff tool by positioning itself as the cheaper option, so an agent can tell it apart from bitbucket_pull_request_diff without opening schemas.

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?

It explicitly says when to prefer this tool over the full diff ('prefer this over the full diff unless file contents are actually needed'), giving the agent a clear decision rule. This directly addresses the alternative and the condition that selects between them.

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?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds the 'full details' scope but no further behavioral context such as absent-parameter behavior, error conditions, or relation to default workspace; this is adequate but not enriching 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.

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

The description is a single front-loaded sentence with no filler. It conveys the essential action and object immediately and earns its place.

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?

The required parameters and read-only annotations are sufficient for basic invocation, but with no output schema and many PR-related siblings, 'full details' is vague about the response boundary. The description could clarify what full details include or confirm that separate diff/comment/status tools are not included.

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 coverage is 67%, with repoSlug and workspace already described in the input schema. The description adds little beyond implying that `id` refers to the pull request being fetched, and `id` remains undocumented, but the missing semantics are relatively self-evident.

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?

Description uses a specific verb ('Get') and resource ('full details of one pull request'), and the singular 'one' clearly separates it from list-oriented siblings like bitbucket_pull_request_list. The phrase 'full details' also distinguishes it from focused tools like pull_request_diff or merge_status.

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 states what the tool does but gives no guidance on when to pick it over siblings such as bitbucket_pull_request_list, diff, or comment tools. There are no explicit conditions, exclusions, or alternative tool mentions.

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?

The description only restates a read-only listing action, which the readOnlyHint and idempotentHint already communicate. It adds no extra context about pagination behavior, default filtering, return contents, or other effects, so the annotation's safety profile is the main source of transparency.

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 consists of one sentence with only 12 words and fronts the essential action and scope. It contains no padding or redundant material.

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 simple read-only list tool, the description communicates the primary task, but it does not explain the default state behavior, maximum result count, or return shape in the absence of an output schema. The annotations handle safety, yet a bit more context about pagination or defaults would make it complete.

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 50%, and the description adds meaning to 'state' by calling it an optional filter, which the schema expresses only through an enum. However, maxItems is not explained and workspace is only described in the schema, so the description does not fully compensate for the missing parameter-level documentation.

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 identifies a specific verb ('List'), resource ('pull requests'), and scope ('in a repository') and notes the optional state filter. It is clear and distinguishes from single-PR tools like bitbucket_pull_request_get, though it does not explicitly contrast with bitbucket_pull_request_list_by_user.

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 says what the tool does but gives no guidance on when to choose it over alternatives such as bitbucket_pull_request_get or bitbucket_pull_request_list_by_user. It does not state any conditions, prerequisites, or exclusion rules.

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?

Annotations already declare readOnlyHint and idempotentHint, so the safe read-only profile is covered. The description adds the cross-repository scope and the whoami prerequisite, but does not disclose pagination/limits or result shape; this gap is modest given 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.

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

Single sentence with the core action front-loaded and the useful whoami tip separated by an em dash. Every phrase earns its place; there is no filler or repetition.

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 read-only cross-repo listing tool, the description plus schema cover the required user parameter, workspace default, state filter, and result limit. No output schema exists, but the operation is simple enough that a standard list response can be inferred; the only notable gap is not explicitly contrasting with repository-scoped PR listers.

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 selectedUser and workspace parameters are already documented in the schema, and state is self-explanatory through its enum while maxItems has default/min/max constraints. The description only adds 'user's' and 'workspace' context, so at 50% schema coverage it only partially compensates for the undocumented parameters.

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?

Description uses a specific verb 'List' and a precise scope: 'a user's pull requests across every repository in a workspace.' This clearly identifies the operation and differentiates it from repository-scoped siblings like bitbucket_pull_request_list. The 'use bitbucket_whoami first' clause adds orientation without obscuring the action.

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 states a concrete prerequisite for the common case: run bitbucket_whoami first to list your own PRs. It does not explicitly name alternatives or say when not to use this tool, but 'across every repository' strongly implies the distinction from repository-specific PR listers.

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?

Annotations already establish read-only and idempotent behavior. The description adds meaningful behavioral scoping by specifying that statuses are read for the 'current head commit' of the pull request, which clarifies the exact object being inspected and warns about scope in a way the schema alone does not.

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?

A single, well-constructed sentence that front-loads the action and resource, then states the practical use case. No filler or redundant restatement of schema fields.

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 simple read-only list operation, the description sufficiently covers what is retrieved, on which resource, and for what purpose. The lack of an output schema and pagination notes is acceptable given the tool's simplicity, though a brief note on interpreting status results would improve completeness.

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 only 67%, with the required 'id' parameter undocumented. The description compensates by clarifying that the object is a pull request and that statuses are on its current head commit, giving agents enough context to infer that 'id' is the pull request identifier.

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?

States a specific verb ('List'), resource ('build/CI statuses'), and precise scope ('on a pull request's current head commit'). The added usage cue 'check whether a PR is safe to merge' makes the tool's role clear and distinguishes it from generic commit-status listing.

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?

Provides an explicit use case: checking whether a PR is safe to merge based on build/CI statuses. It does not explicitly mention alternatives like bitbucket_pull_request_merge_status or bitbucket_commit_list_statuses, so exclusions are absent, but the intended context is clear.

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?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the agent knows this is a safe read operation. The description adds the context that this is a follow-up status check for an in-progress merge, which is useful. However, it doesn't disclose what the response looks like or whether the status check consumes the task (e.g., one-time vs pollable). With annotations covering safety, a 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.

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

One sentence, zero waste, and the key context (follow-up to a merge reported in progress) is front-loaded. Every word earns its place.

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 simple status-check tool with readOnly and idempotent annotations, the description is nearly complete. It tells the agent when to call it (after a merge reported in progress) and what it checks. The only minor gap is not describing the return format, but with no output schema and a simple status check, this is acceptable.

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 50%, with repoSlug and workspace documented. The description doesn't add meaning for id or taskId beyond what the schema provides, but the tool name and description imply taskId is the merge task identifier. The description doesn't compensate for the undocumented parameters, but the schema covers half and the context is fairly inferable. Baseline 3 is appropriate.

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 checks the status of a merge that was previously reported as in progress, referencing the sibling tool bitbucket_pull_request_merge. It identifies the specific resource (merge status) and the context (a prior merge operation). It doesn't explicitly name the sibling tool in the description, but the reference is clear enough to distinguish it from other pull request tools.

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 implies when to use this tool: after bitbucket_pull_request_merge reports a merge still in progress. This is a clear context signal, though it doesn't explicitly state when not to use it or name alternatives. The reference to the merge tool provides enough guidance for an agent to select this tool appropriately.

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?

Annotations mark the operation as read/write and non-idempotent, and the description goes further by disclosing that the created task remains pending and invisible to everyone else until the user's review is submitted. This is material behavioral context not covered by the 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.

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

A single, front-loaded sentence that conveys the core action and the key behavioral caveat without fluff. The dash construction is efficient and immediately communicates the most important constraint.

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?

Provides useful behavioral context and is short, but the unlinked parameter semantics (notably id) remain an obstacle to correct invocation. For a tool with 50% schema coverage and no output schema, this is a meaningful gap, though the rest of the context is present.

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?

Only repoSlug and workspace have schema descriptions; id and content are undocumented. The description adds no explicit meaning for these parameters, leaving ambiguity about whether id is the pull request ID or a task ID and what format content should take.

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?

States a specific verb ('Add'), resource ('checklist task to a pull request'), and a unique behavioral constraint ('pending - invisible to everyone but you until you submit your review'). This clearly distinguishes the tool from sibling task listing tools and leaves no doubt about the action.

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?

Gives a clear context for when the task is useful (before review submission), but never explicitly says when to choose this over alternatives such as bitbucket_pull_request_task_list or when not to use it. The usage is implied by the verb and subject rather than stated directly.

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?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the agent knows this is a safe read-only operation. The description adds minimal behavioral context by linking to task_count, but it does not disclose return format, pagination, or ordering. It is not contradictory, and the annotations lower the burden, but the description could still add more behavioral detail.

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

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

The description is a single, front-loaded sentence with zero filler. It leads with the verb and resource, adds a clarifying parenthetical, and concludes with a useful distinction. Every word earns its place.

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 simple list tool with read-only annotations and no output schema, the description is nearly complete. It clearly identifies what is returned (checklist tasks) and distinguishes from comments. It does not mention pagination or response structure, but given the tool's simplicity and the annotations covering safety, this is a minor gap.

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 67%, which is above the 50% threshold, so the baseline is 3. The description does not add any parameter-specific meaning beyond what the schema already provides (e.g., it does not explain that 'id' refers to the pull request ID, though the context implies it). It does not compensate for the undocumented 'id' parameter.

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 a specific verb ('List') and resource ('a pull request's checklist tasks'), and clarifies that these tasks are what PullRequestSchema.task_count counts. It also explicitly distinguishes from comments, making it easy to differentiate from sibling tools like bitbucket_pull_request_comment_list.

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 a contextual clue by stating the tool is 'distinct from comments,' implying it should not be used when comments are needed. However, it does not explicitly name the alternative tool or provide when-to-use/when-not-to-use guidance beyond that single contrast. The intent is clear but not fully explicit.

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?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safe read-only behavior is covered structurally. The description 'Get details' is consistent with those annotations and adds no additional behavioral context, but it also does not contradict them.

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?

A single, front-loaded sentence with no filler. Every word contributes to identifying the operation and the resource.

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 simple read-only get operation with named parameters and one described parameter in the schema, the description is reasonably complete. It does not explain return contents, but no output schema exists and 'details' is acceptable shorthand for a repository fetch.

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 50%; the workspace parameter is described in the schema, while repoSlug is not. The description adds minimal semantic value beyond the tool name, though 'one repository' helps connect repoSlug to the target resource. This is adequate but not compensating.

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 a clear verb and resource: 'Get details of one repository.' The word 'one' differentiates it from sibling tool bitbucket_repository_list, but 'details' is not elaborated, so the exact nature of the return value is left somewhat vague.

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 is provided about when to use this tool versus alternatives such as bitbucket_repository_list or bitbucket_source_get. The name implies a singular fetch, but the description does not explicitly state selection criteria or exclusions.

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?

Annotations already declare readOnlyHint and idempotentHint, so the main side-effect profile is covered and there is no contradiction. The description itself adds little behavioral context beyond the workspace scope; it does not mention pagination, result limits, or how the query parameter affects the returned list.

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, clear sentence with no filler or redundant content. It fronts the core operation and object type and earns every word that is present.

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?

The schema and read-only annotations make the tool callable correctly, but the description itself is thin in this Respect: it does not mention response shape, query flexibility, or the optional nature of the parameters beyond what the schema already states. For such a simple list tool this is acceptable but not guiding.

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 does not add parameter-level meaning; it does not discuss the query filter, workspace default, or maxItems. However, schema descriptions already cover query and workspace and constrain maxItems with default/min/max values, so the 67% schema coverage keeps this at a baseline rather than a failure.

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 uses a specific verb ('List') and a distinct resource ('repositories') scoped to 'a workspace.' This makes the tool's purpose clear and separates it from resource-specific get/retrieve tools, though it does not explicitly name or contrast sibling tools.

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 choose this tool over alternatives such as bitbucket_repository_get, bitbucket_code_search, or other list tools. It relies on the agent to infer the use case from the name and the operation, providing no exclusions or alternative conditions.

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?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral context: the dual file/directory behavior, the root path convention, and the metaOnly optimization for large files. It doesn't mention rate limits or error cases, but for a read-only tool with annotations, this is solid.

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

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

Three sentences with zero waste. The core action is front-loaded, the root path behavior is stated compactly, and the metaOnly tip is actionable. Every sentence earns its place.

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 read-only tool with annotations covering safety and an 80% schema coverage, the description is nearly complete. It explains the dual behavior, the root path convention, and the large-file optimization. It doesn't describe the return format, but there is no output schema and the description's mention of 'contents' and 'metadata' gives enough context for an agent to proceed.

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 80%, so the schema already documents most parameters. The description adds meaning beyond the schema by explaining the path omission behavior (root) and the metaOnly use case (checking size/type before fetching large contents). It doesn't add detail for repoSlug or workspace, but those are self-explanatory and the schema covers them.

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 a specific verb ('Read') and resource ('a file's contents or list a directory at a given revision'), which clearly distinguishes it from sibling tools like bitbucket_commit_get or bitbucket_repository_get. It also clarifies the dual behavior (file read vs directory listing) and the root path behavior, making the tool's purpose unambiguous.

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 gives clear context for when to use the tool (reading files or listing directories at a revision) and provides a specific usage tip: use metaOnly:true first for anything that might be large. It doesn't explicitly name alternatives or exclusions, but the sibling list is broad and the description's context is sufficient for an agent to select this tool over others.

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?

The description discloses no behavioral traits beyond the readOnlyHint and idempotentHint annotations. It does not mention pagination, ordering, response shape, or any operational details, leaving the annotations to carry the entire behavioral burden.

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, front-loaded sentence with no wasted words. It is maximally concise and easy to parse, even if the brevity reflects under-specification.

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 simple read-only list operation with schema-documented parameters, the description is minimally sufficient but leaves the agent to infer return format and pagination behavior. Since there is no output schema, some completeness is missing.

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 only 33%, yet the description does not clarify maxItems or workspace semantics. The word 'repository' only loosely maps to repoSlug, so the description fails to compensate for the poorly documented parameters.

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 action 'List' and the resource 'tags in a repository', which is specific enough to distinguish it from sibling tools like bitbucket_branch_list or bitbucket_commit_list. It does not add much beyond the tool name, but it is unambiguous.

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?

There is no guidance about when to use this tool versus alternatives, and no sibling tool is referenced. The only usage signal is the implied context of needing repository tags, which is not explicit.

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?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds useful behavioral detail by specifying the output fields (display name, uuid), which is especially valuable since no output schema is provided.

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 sentence that immediately states the action, the target, and the expected result. There is no wasted wording or redundant information.

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 zero-parameter, read-only, idempotent identity tool with no output schema, this description is fully complete. An agent knows what the tool does, what it returns, and when to call it; no additional context is necessary.

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 tool has zero parametersaimanah, and the input schema is empty, so the baseline is 4. The description needs no parameter-related explanation because there is nothing to configure or clarify.

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 a specific verb ('Get'), a clear resource ('the identity of the currently authenticated Bitbucket account'), and the exact returned fields ('display name, uuid'). It is immediately distinguishable from sibling tools like bitbucket_workspace_list or bitbucket_repository_list, which target different resources.

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

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

The phrase 'currently authenticated Bitbucket account' provides clear context for when this tool should be used: when an agent needs the caller's own identity. There is no ambiguity about alternatives because no sibling tool performs this function, and no exclusions are needed.

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?

Annotations already declare readOnlyHint and idempotentHint, covering safety. The description adds the 'authenticated account' scope and the concept of a 'configured default', which are useful behavioral details beyond annotations. No contradictions and no need to restate read-only nature.

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?

Two sentences: the first states the main action, the second gives usage guidance. Front-loaded, concise, and every sentence earns its place 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?

For a simple list tool with one optional param and no output schema, the description covers purpose, usage timing, and the default workspace nuance. Nothing an agent needs to invoke it correctly is missing.

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 0% for the single parameter maxItems, and the description doesn't mention it at all. The parameter is optional with default/min/max in the schema, so the schema itself is clear, but the description fails to compensate for the low coverage as required. It adds no meaning beyond the schema.

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?

States 'List every Bitbucket workspace the authenticated account can access' with a specific verb (list) and resource (workspaces). It also distinguishes itself from siblings by explaining its role in discovering slugs before other tools and finding non-default workspaces, making it clear which tool to pick.

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?

Provides explicit context: 'Use this to discover a workspace slug before calling any other tool, or to find one other than the configured default.' This tells the agent when to invoke it, though it doesn't explicitly mention when not to use it or name alternatives. Clear context without exclusions.

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

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

The annotations already declare readOnlyHint and idempotentHint, so the description doesn't need to repeat safety. It adds value by mentioning the uuid output and that it's used for resolution, which helps the agent understand the expected output format without an output schema. 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.

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

Two sentences with no fluff. The purpose is front-loaded, and the cross-reference to the pull request create tool is immediately useful. Every word earns its place.

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?

The tool has only 2 simple parameters/styles, no output schema, but the description tells the key purpose and return value (uuid). The annotations cover safety. Missing details like pagination or sorting are minor for a listing tool with defaults; the description is sufficient for an agent to call it 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?

Schema description coverage is 50% (workspace is described, maxItems is not). The description doesn't add parameter details beyond the schema, but with only one undocumented parameter and a default of 25, the agent can infer its meaning. The description's focus on uuid resolution adds context but not parameter-level semantics. Since schema covers half, a 4 is generous; the baseline is 3 but the description's clarity about the uuid output partially compensates.

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?

Clearly states the tool lists workspace members with their account uuid, and explains its specific purpose of resolving names to uuids for bitbucket_pull_request_create's reviewers argument. This differentiates it from sibling tools like bitbucket_workspace_list.

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?

Explicitly tells when to use it: to resolve a teammate's name to uuid for the pull request create reviewers argument, and notes that plain names are not accepted there. This gives clear guidance on the use case and the prerequisite for another tool.

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