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

Annotations indicate non-read-only, non-destructive, and non-open-world. The description adds that it is idempotent and purely local, never calling Bitbucket, providing useful behavioral context beyond annotations. No contradiction with annotations.

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

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

Two concise sentences with no redundant words. The action is stated first, followed by two key qualifiers (idempotent, local). 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 tool with one optional parameter and no output schema, the description covers the action, the parameter semantics, and key behavioral traits. No critical information 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?

The schema provides only the profile parameter with no description. The description clarifies that it targets the active profile unless a profile is explicitly named, giving the parameter semantic meaning. This fully compensates for the 0% 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 action (removes), the target (default workspace), and the scope (active or explicitly named profile). It implicitly distinguishes itself from the sibling set_default_workspace by being the inverse operation.

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?

Usage context is implied: it clears the default workspace, but there is no explicit guidance on when to use it vs alternatives or any exclusions. The description does not reference the sibling set_default_workspace or provide conditions for use.

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=false, so the description's 'WRITE tool' reinforces but does not add new information. However, it adds a useful behavioral detail: 'Requires non-empty content — validated before any Bitbucket call.' This discloses the validation step and pre-call behavior, which is beyond what annotations provide. No contradictions.

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

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

The description is two sentences with no fluff. It leads with the primary action, then states the validation requirement, and finally labels the tool's nature. Every word earns its place, making it highly efficient.

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 write tool with 4 parameters and no output schema, the description is inadequate. It does not explain what the tool returns (e.g., the created comment object), error conditions, or the roles of the other parameters. While the schema covers required fields, the lack of descriptions and output details leaves the agent under-informed for a successful call.

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%, so the description must explain each parameter. It only mentions 'content' (non-empty requirement) and does not clarify the purpose or format of repo, pr_id, or workspace. The property names give some hint, but the description fails to compensate for the lack of schema descriptions, leaving the agent guessing on the other three 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: 'Posts a new comment on a pull request.' It uses a specific verb and resource, and the name itself distinguishes it from listing comments (list_pr_comments) or other PR operations. It also labels itself as a WRITE tool, which further clarifies its role.

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 it (to add a comment) but provides no explicit guidance on alternatives or exclusions. It does not mention that listing comments should be done with list_pr_comments, nor does it describe any prerequisites beyond non-empty content. The usage context is inferred from the name and action, not explicitly 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?

The description adds meaningful behavioral context beyond annotations: it verifies branch existence before creation and guarantees no partial PR is left behind. This is useful for an agent to understand side effects and failure behavior. The "WRITE tool" label is redundant with readOnlyHint=false but not misleading.

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 tight: two sentences that front-load the core action, state essential parameters, and add a behavior guarantee. Every sentence contributes value without padding.

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 9 parameters, no output schema, and zero schema-level descriptions, this definition is incomplete. It does not explain what the tool returns, how workspace and repo relate, whether draft or closeSourceBranch have defaults, or how reviewers should be formatted. This is a sizable gap for an agent invoking 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?

Schema description coverage is 0%, so the description bears the full burden of explaining parameters. It clarifies title, sourceBranch, and destinationBranch, but omits the required repo parameter and gives no meaning for draft, reviewers, description, closeSourceBranch, or workspace. This leaves agents guessing about most of the tool's surface.

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 opening phrase "Opens a new pull request" names a specific verb and resource, making the tool's purpose immediately clear. It is distinguishable from the sibling update_pull_request because it states creation rather than modification, and from list_pull_requests because it performs an action rather than a query.

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 the correct use case: creating a new pull request. It also gives a prerequisite by naming required fields. However, it does not explicitly say when to prefer this over update_pull_request or other sibling tools, and it omits the repo parameter that the schema marks as required.

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 destructiveHint=false, so the safety profile is clear. The description adds that the tool returns resolved defaults when present, but does not disclose edge cases, failure behavior, or what 'resolved defaults' means exactly.

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, direct sentence that front-loads the core purpose and adds no filler. Every word contributes 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 zero parameters, a read-only annotation set, and no output schema, the description gives enough information for an agent to invoke the tool correctly. No additional invocation details are 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?

The tool has zero parameters and schema coverage is 100%, so no parameter documentation is needed. The description's mention of what is returned sufficiently covers the relevant semantics.

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 ('Returns') and identifies a precise resource: the currently active profile's name and resolved defaults. This clearly distinguishes the tool from siblings like set_active_profile (a write) and list_profiles (a read of all profiles).

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 intended use is implied by the name and description: retrieve the current profile state. However, there is no explicit guidance about when to prefer this over list_profiles or how it relates to set_active_profile.

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 destructiveHint=false, so the description need not restate safety. It adds one useful behavioral note about resolving workspace via standard precedence, which is beyond the schema, but no additional context about error behavior, response format, or side effects.

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

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

A single, front-loaded sentence with zero filler: purpose first, then requirements, then a scoping rule. It is efficient and easy to parse, earning its place without unnecessary detail.

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, the phrase 'returns details' is vague and does not specify what is returned. The read-only annotations and simple nature of the operation mitigate this, but an agent would still benefit from knowing the response shape or potential failure modes.

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%, so the description carries the burden. It states that repo and branch are required and explains how workspace is resolved, but it does not elaborate on the semantic meaning of each parameter beyond their names. This is partial compensation for the missing schema descriptions.

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 ('Returns') and a specific resource ('details for a specific branch'), clearly differentiating it from list_branches by emphasizing the singular target. It also signals that a branch identifier is required, so an agent can select this tool when needing a single branch's details.

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 clear precondition by saying 'Requires repo and branch' and mentions workspace resolution, but it does not explicitly contrast with alternative tools such as list_branches or get_repository. When-not-to-use guidance is missing, so usage is implied rather than 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 destructiveHint=false, so the tool is known to be safe. The description adds the behavioral detail that results are 'fully paginated,' which is not in the annotations. However, it does not describe return format, ordering, or potential edge cases (e.g., empty PRs). This adds some value beyond annotations but is minimal.

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 no fluff. It front-loads the core purpose ('Lists every commit...') and then states a key requirement. Every word earns its place, and the structure is clear and efficient.

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 3 parameters, no output schema, and minimal annotations, the description is severely under-specified. It does not explain the meaning of 'pr_id', does not clarify that 'repo' likely refers to a workspace identifier, and provides no information about return format or potential errors. An agent calling this tool would lack critical context to use 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 0%, meaning no parameter descriptions exist in the schema. The description only mentions 'repo' and that it is required, but does not explain what 'repo' represents (it references 'workspace' in the schema, but the description doesn't clarify this). The 'pr_id' parameter is completely unaddressed. With no descriptions in the schema, the tool description fails to compensate, leaving agents without semantic understanding of the 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 tool's purpose: 'Lists every commit belonging to a pull request.' The verb 'Lists' and resource 'commits belonging to a pull request' are specific and unambiguous. It differentiates from sibling tools like get_pr_diff (diff) and list_pr_comments (comments) by focusing solely on commits. The mention of 'fully paginated' adds a key detail about behavior, making the purpose even clearer.

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 only states a requirement ('Requires an explicit `repo` argument') but does not explain when an agent should choose this over, say, get_pr_diff or list_pull_requests. There is no mention of exclusions or alternative tools, so an agent must infer usage solely from the tool's name and purpose.

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?

Beyond the readOnlyHint and destructiveHint annotations, the description discloses critical runtime behavior: truncation at 100k chars (hard cap 400k), line-boundary truncation, and the response always reporting truncated/returnedChars so truncated output is never mistaken for complete. It also surfaces the Bitbucket timeout behavior. This is substantial added 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?

Three sentences with no filler. The first sentence states the primary function, the second covers truncation behavior, and the third gives an actionable alternative. Each sentence earns its place and the most important information 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?

The description covers the return format (plain text), truncation reporting, and timeout handling, which is strong given there is no output schema. It does not clarify the relationship between repo and workspace or the exact meaning of pr_id, but those are inferable from sibling tools and the schema constraints. The only notable gap is the ambiguous repo/workspace schema reference.

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 0% schema description coverage, the description must compensate. It does add meaning for maxChars (default 100k, hard cap 400k) beyond the schema's bare maximum. However, it does not explain repo, pr_id, or workspace, leaving their semantics to inference from names. The unusual '$ref' for repo to workspace is also unaddressed. Partial compensation, but with clear gaps.

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 and resource: 'Returns the unified diff for a pull request as plain text.' This clearly distinguishes it from siblings like get_pr_commits (commit list) and get_pull_request (PR metadata). The purpose is immediately identifiable and not a tautology.

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 an explicit when-not scenario: on very large diffs that time out (HTTP 555), it tells the agent to prefer get_pr_commits or a smaller maxChars instead of retrying. This names an alternative and the condition that selects it, satisfying the highest bar for usage 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 already cover read-only and non-destructive behavior. The description adds useful context about workspace resolution via "standard precedence," but that phrase is not explained. 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 no filler. The core purpose is front-loaded and the required-argument/workspace behavior is stated compactly. Each sentence contributes useful 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?

The tool is simple and annotations cover safety, but with no output schema the phrase "full metadata" is not elaborated. The undefined "standard precedence" is also a gap that could leave an agent unsure how workspace is resolved.

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%, so the description must carry the parameter-semantics burden. It names repo and pr_id as required and mentions workspace resolution, but it does not clarify the meaning or format of repo, what "standard precedence" means, or how workspace behaves when omitted. This is insufficient given the empty schema descriptions.

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 and resource: "Returns full metadata for a single pull request." This clearly distinguishes it from list-level tools like list_pull_requests and from related sub-resource tools like get_pr_commits or get_pr_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 implies this tool is for fetching one pull request's metadata, and it mentions required arguments, but it does not explicitly state when to prefer this over siblings or when not to use it. There are no stated exclusions or alternative routing cues.

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, openWorldHint, and destructiveHint, so the safety profile is covered. The description adds one behavioral detail—workspace is resolved via 'standard precedence'—but leaves that precedence undefined and offers no further behavior or side-effect 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?

One compact sentence conveys the core action, the required parameter, and the workspace-resolution behavior with no filler or repetition of annotation values. The information is well 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 annotated read-only getter, this is mostly adequate, but the undefined 'standard precedence' is a genuine gap for an AI agent choosing and invoking the tool. With no output schema and no return-format guidance, the description could usefully clarify what 'details' includes.

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%, so the description must carry the parameter-explanation burden. It clarifies that 'repo' is required and 'workspace' is resolved, but it does not define valid formats, the meaning of 'standard precedence', or how the two parameters interact. This is insufficient compensation for an undocumented 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 ('Returns') and identifies the resource ('details for a specific repository'), clearly distinguishing it from sibling list_repositories. The scope is unambiguous: this is a single-repository read operation.

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 states a prerequisite ('Requires repo') and hints at workspace resolution, but it never explicitly says when to prefer this tool over list_repositories or how the precedence relates to other workspace-related siblings. Usage context is implied rather than made 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 destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: full pagination, workspace resolution precedence, requirement for explicit repo, and the name filter semantics (partial match via Bitbucket's query language). This goes beyond what annotations provide, though it doesn't detail pagination size or error behavior, which is a minor 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?

Three sentences, each carrying distinct information: what the tool does, how workspace resolution works, and what parameters are required/optional. No fluff, no repetition of schema details. The most important information (lists every branch, fully paginated) 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 read-only list tool with no output schema, the description covers the essential aspects: purpose, pagination, parameter requirements, and filter behavior. It doesn't describe the return format, but since there's no output schema and the tool is a simple list operation, this is a minor gap. The workspace resolution precedence is a nice touch that prevents common errors.

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%, so the description must compensate. It does: it explains that `repo` is required, `workspace` is resolved via standard precedence if not provided, and `name` is an optional partial-match filter using Bitbucket's query language. This adds meaning beyond the bare schema properties. However, it doesn't explain the exact format of the `name` filter (e.g., query language syntax), which is a minor 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 clearly states the tool lists every branch in a repository, with full pagination. It distinguishes itself from siblings like get_branch (which fetches a single branch) and list_repositories (which lists repos, not branches). The verb 'lists' plus the resource 'branches in a repository' is specific and 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 explicitly states when to use this tool: to list all branches in a repository. It also provides clear usage constraints: requires an explicit `repo` argument, resolves `workspace` via standard precedence if not provided, and accepts an optional `name` filter. While it doesn't explicitly name alternatives, the sibling list makes the distinction clear (e.g., get_branch for a single branch), and the usage conditions are precise enough for an agent to select this tool 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 destructiveHint=false, covering the safety profile. The description adds behavioral context by specifying 'fully paginated' and clarifying the scope ('every comment (inline and general)'), which goes beyond the annotations. This is useful and not contradictory.

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 waste. It states the action, scope, and a key requirement 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?

With no output schema and 0% parameter coverage, the description is incomplete. It does not describe the return format, the exact meaning of `repo`, or the required `pr_id`. An agent would need to infer parameter semantics from the schema alone, and the description lacks enough context for a complex list operation.

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%, so the description must compensate. It mentions the `repo` argument but does not explain what it represents (though the schema shows it references `workspace`). The `pr_id` parameter is not described at all. The description adds minimal semantic value beyond the schema, failing to clarify parameter formats or meaning.

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 (Lists), the resource (every comment on a pull request), and the scope (inline and general, fully paginated). It distinguishes itself from sibling tools like create_pr_comment (write) and get_pull_request (overview) by focusing on listing 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 mentions a requirement ('Requires an explicit `repo` argument') but does not explicitly state when to use this tool versus alternatives. It implies a listing scenario but lacks explicit when/when-not guidance or references to sibling tools. The purpose is clear enough that an agent can infer usage, but explicit guidance is missing.

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 destructiveHint=false, covering the safety profile. The description adds a useful behavioral trait—'Never contacts Bitbucket'—which is not covered by annotations. This adds context about the tool's execution characteristics without contradicting 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 a single sentence, concise and front-loaded with the primary action and scope. The additional clause about Bitbucket is short and valuable, adding no waste. It is exemplary in brevity.

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 parameterless list tool with no output schema, the description fully conveys what the tool does and its key behavioral constraint. There is no missing information an agent would need to 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?

The tool has zero parameters, so the description does not need to explain any. The schema is empty and fully covered. Per the guideline, 0 params gets a baseline of 4, and the description adds no parameter-related information, which 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 states a specific action ('Lists') with a clear resource ('every configured local profile') and its scope ('and its defaults'). It also explicitly distinguishes itself from remote operations by saying 'Never contacts Bitbucket', which differentiates it from siblings that might access Bitbucket.

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 clear context for when to use this tool: when you need local profile information and want to avoid network calls. It implicitly excludes alternatives by the 'Never contacts Bitbucket' clause, but it does not explicitly name alternative tools or conditions for choosing them, so it falls short of a 5.

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 destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: 'fully paginated' and the default state filter of 'OPEN', which are not visible in annotations. It doesn't mention rate limits or response shape, but for a read-only list tool this is adequate.

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, each carrying distinct information: what it lists, pagination, required argument, workspace resolution, and state filtering with default. No filler or repetition of schema 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?

For a read-only list tool with annotations covering safety and no output schema, the description covers the essential call semantics: required argument, filtering, pagination, and default behavior. It could be more complete by explaining the workspace precedence order and repo format, but nothing critical is missing for an agent to 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 0%, so the description must compensate. It explains `repo` (explicit argument), `workspace` (resolved via precedence), and `state` (enum values and default). This adds meaning beyond the raw schema, but it doesn't detail the precedence order or the exact format of `repo` (e.g., 'workspace/repo-slug'), leaving some ambiguity.

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 ('Lists'), resource ('pull requests in a repository'), and key constraints ('fully paginated', requires explicit repo). It is clearly distinguishable from siblings like get_pull_request (single PR) and list_repositories (repos, not PRs).

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 says it requires an explicit `repo` argument and resolves `workspace` via standard precedence, which tells the agent when this tool is appropriate. It doesn't explicitly name alternatives or exclusions, but the context is clear enough for a list operation.

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 destructiveHint=false, and the description extends this by disclosing two important behaviors: the result is fully paginated, and workspace resolution follows a precise precedence chain ending in an error. This gives the agent useful behavioral context beyond what the schema or annotations provide.

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

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

Two sentences with no filler: the first states the core function, the second explains workspace resolution. The most important information is front-loaded, and nothing in the description merely repeats the annotations or schema.

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 simple single-parameter read-only list tool, and the description covers the key invocation details: full pagination, optional workspace, and resolution/error behavior. Given the annotations and the low complexity, nothing material is missing for an agent to select and call 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?

Schema description coverage is 0%, but the description compensates by explaining that `workspace` is optional and resolved through a defined precedence chain. This gives meaningful semantics to the parameter beyond the bare string schema, even though it does not enumerate accepted workspace identifiers.

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 ('Lists'), a specific resource ('repository'), and a clear scope ('in a workspace'). The phrase 'every repository' combined with 'fully paginated' also makes the exhaustive nature explicit, which helps distinguish it from sibling tools like get_repository and list_workspaces.

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 this tool: when you want the complete set of repositories in a workspace, with pagination handled. It does not explicitly name alternatives or exclusion conditions, but the 'every repository' phrasing and the workspace resolution details make the intended usage obvious without needing to inspect other tools.

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, openWorldHint, and destructiveHint, so the safety profile is known. The description adds meaningful behavioral detail beyond annotations by stating that results are 'fully paginated' and that the tool returns every accessible workspace, plus it explicitly notes it takes no arguments.

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 short sentences, no filler. The purpose and scope are front-loaded, and the no-argument note is valuable because it directly prevents invocation mistakes.

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 parameterless, read-only listing tool with safety annotations, the description covers the essential behavioral facts: scope, pagination, and lack of arguments. No output schema exists, but the description clearly communicates what the tool returns conceptually, so an agent can 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?

With zero parameters, the baseline is 4. The description reinforces this by stating 'Takes no arguments,' which removes any ambiguity an agent might have about whether hidden or optional parameters are expected.

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 ('Lists') and a specific resource ('every Bitbucket workspace') with an explicit access scope ('the authenticated credentials can access'). It also clearly distinguishes this from sibling tools like list_repositories and list_profiles by naming the resource type.

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

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

The description makes the use case clear: call this when you need all workspaces accessible to the authenticated credentials. It does not explicitly mention alternatives or exclusions, but no sibling tool duplicates this exact purpose, so the context is sufficient.

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 provide only basic read/write and destructive hints. The description adds meaningful behavioral context: the operation is purely local and never calls Bitbucket, and the target profile must already exist. This goes beyond the structured metadata without contradicting it.

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 short sentence plus a compact clarifying clause. The core action and the 'existing profile' constraint are front-loaded, and every word contributes meaning with no filler.

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 single-parameter local state mutation with no output schema, the description is largely sufficient: it states the action, the precondition, and the network boundary. Minor omissions such as error behavior when the profile does not exist or whether the change persists are acceptable for such a simple 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 coverage is 0%, so the description must compensate for the undocumented parameter. It adds the key semantic constraint that 'profile' must be an existing profile, rather than any arbitrary string. However, it does not specify the expected identifier format or where valid values come from (e.g., list_profiles), leaving the parameter partially underspecified.

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?

Uses a specific action verb ('Switches') and a precise resource ('the active profile') with a clear binding constraint ('to an existing profile'). This strongly distinguishes it from siblings like get_active_profile and list_profiles, which are read-oriented, and from set_default_workspace, which targets a different setting.

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 clearly implies when to use the tool: when the agent needs to change the locally active profile, and explicitly notes that no Bitbucket call will be made. It does not name sibling alternatives or explicit exclusion conditions, but the context is unambiguous enough for correct 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?

The description adds meaningful behavioral context beyond the annotations: it discloses that the operation is a purely local persistence action and never makes a network call to Bitbucket. It also clarifies that the profile is either active or explicitly named. This does not contradict the readOnlyHint=false, destructiveHint=false 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, focused sentence with the key verb and scope at the front. Every clause earns its place: the active/named profile behavior and the 'purely local' constraint are both valuable and clearly stated.

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 two-parameter local mutation, the description covers the behavioral context well, but it leaves the meaning of the workspace parameter and the exact return behavior unstated. Since there is no output schema and no parameter documentation, an agent still has to infer some details about how to supply the workspace value.

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%, so the description must compensate, but it does not explain the required 'workspace' parameter at all. It only hints at the optional 'profile' parameter via 'or explicitly named profile.' The schema's 'profile' property is also an unusual $ref, and no meaningful parameter guidance is given.

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 ('Persists') and clearly names the resource ('a default workspace') and the scope ('on the active (or explicitly named) profile'). It also distinguishes this from siblings like set_active_profile and clear_default_workspace by emphasizing it stores the default workspace locally.

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 local-only context: 'Purely local — never calls Bitbucket' tells an agent this is the right tool when no remote interaction is desired. It does not explicitly name alternative tools or list when-not-to-use conditions, but the local/remote contrast is a strong usage signal.

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 indicate it is a write operation (readOnlyHint false) and not destructive (destructiveHint false). The description adds valuable behavioral detail beyond annotations by explicitly rejecting a 'state' parameter and listing unsupported operations. It also labels the tool as 'WRITE' for emphasis. It could disclose more about side effects or error behavior, but the additional context is meaningful.

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 and front-loaded with the core purpose in the first sentence. The second sentence delivers key constraints, and the final 'WRITE tool' reinforces the nature. It is efficient with no redundancy, though the 'WRITE tool' is arguably redundant with annotations; still, the structure is clean and easy 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?

For a tool with 8 parameters and no output schema, the description is incomplete. It fails to explain required parameters like 'repo' and 'pr_id', nor does it mention what the function returns on success or failure, or any side effects beyond the rejected state. Given the lack of schema descriptions and output schema, an agent would lack crucial details to use the tool reliably. More context about required inputs and expected results is needed.

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%, so the description must carry the burden of explaining parameters. It names four updatable fields (title, description, destination branch, reviewers) that map to schema properties, but it does not explain the required parameters 'repo' and 'pr_id', nor does it clarify 'workspace' or the rejected 'state' beyond noting rejection. Since the schema itself provides no descriptions and the description only partially compensates, the parameter semantics are insufficient for an agent to confidently construct a correct call.

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 'Updates' with a specific resource ('pull request') and enumerates the exact fields it modifies (title, description, destination branch, reviewers). It also explicitly disclaims unsupported operations (merge, approve, decline), distinguishing it from sibling tools like create_pull_request or get_pull_request. The purpose is unambiguous and well differentiated.

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: this tool is for updating an existing pull request, not for merging, approving, or declining. It explicitly states that passing a 'state' is rejected, providing a clear when-not condition. However, it does not name specific alternative tools to use for those unsupported actions, so it stops short of the full when/alternatives guidance.

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