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

With no annotations, the description carries full burden. It indicates a read-only browse operation and what it returns, but does not disclose any potential limitations such as recursion depth, hidden files, or permission requirements. It provides basic behavioral transparency but not deep 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 two sentences, front-loads the core purpose and result, and has no redundant or filler words. It earns every word.

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 browse tool with four parameters and no output schema, the description provides enough context: the action, result summary, and use case. It does not exhaustively explain edge cases but is sufficient for an agent to understand when and how to invoke it.

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

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

Schema description coverage is 100%, so all parameters are already documented. The description adds no extra parameter semantics beyond what the schema provides, which matches the baseline for high 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 (browse), the resource (directory in a repository), and the output (file/folder names, types, paths). It is distinguishable from siblings like get_file_content by focusing on directory exploration rather than file retrieval.

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 states the use case 'Use this to explore the repository structure,' which provides clear context. However, it does not mention when not to use it or name alternative tools, so it lacks exclusion 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?

No annotations are provided, so the description carries the full burden of disclosure. It does convey that the tool returns commit details (author, message, date, files), which is helpful, and the verb 'get' implies a read operation, so there is no suggestion of destructive side effects. However, it does not mention potential errors, authentication needs, or rate limits. Given the absence of annotations, the description adds some useful behavior but is not fully transparent, so a middle score is warranted.

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 is appropriately front-loaded. It states the core purpose and the primary output fields with no redundant phrasing, fully earning 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?

With 100% schema coverage and a clear output-feature description, the tool is callable correctly. However, with no output_schema and no mention of error handling or result shape nuances, the description is only minimally complete for context. The presence of multiple similar siblings also argues for a note about when to pick this one, which is missing. Therefore a 3 is appropriate.

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

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

Schema description coverage is 100%, meaning all three parameters (commit_id, repo_slug, workspace) are already explained in the schema, including the optionality of workspace when the environment variable is set. The description adds no new parameter-level detail, so it meets the baseline score of 3 rather than exceeding it.

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 names the resource ('a specific commit') with a detail list (author, message, date, files changed). This is sufficiently concrete and distinguishable from list_commits (listing) and get_commit_diff (comparing diffs), even though it does not explicitly name sibling alternatives. A score of 4 reflects that the purpose is clear but not perfectly differentiated from its 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 gives no guidance on when to prefer this tool over list_commits, get_commit_diff, or any other alternative. It states only what the tool does with no mention of context or exclusions. An agent has to infer from the description when this tool is the right choice among the eleven siblings.

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

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

With no annotations, the description carries the full burden. It does disclose the return format (unified diff) and that all changes are shown, which is useful. However, it does not mention authentication requirements, rate limits, potential for large payloads, or any side effects, which would help fully set 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?

The description is two short sentences with no filler. The key purpose is first, and the output format is second. 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 relatively simple read-only tool with a fully documented schema, the description provides the essential purpose and output format. It could be improved by explicitly noting that this complements get_commit (which likely returns metadata) or mentioning any output size limitations, but these are minor given the strong context signals.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no additional meaning for the parameters beyond what the schema already provides; it only states the tool's overall intention.

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'), a specific resource ('the diff/patch of a specific commit'), and states the output format ('unified diff'). It clearly distinguishes this tool from sibling tools like get_commit by specifying the diff/patch content rather than commit metadata.

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 tool should be used when a commit's diff is needed, but it does not explicitly state when to use it versus alternatives such as get_commit or list_commits. There are no exclusions or comparisons with sibling tools, leaving the routing decision 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?

With no annotations, the description carries the full burden of behavioral disclosure. It states that the tool returns raw file content as text, which is helpful, but it does not mention potential limitations like file size, binary files, or authentication requirements. The description adds some transparency but is not thorough.

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 three short, direct sentences with no redundant wording. The core action, return format, and use case are each given their own sentence, making it easy to parse quickly.

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

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

For a simple file-reading tool, the description covers the essential action and return format, and the schema documents parameters. However, the absence of annotations and the lack of guidance on when to prefer this over sibling tools (e.g., get_readme for README files) leaves some contextual gaps.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema. The description repeats that the tool reads files but adds no additional meaning about parameters such as branch defaults or workspace resolution. 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 verb 'Read' and the resource 'a file in a repository', and specifies the return type as raw text. It implies use for source code but does not explicitly distinguish itself from sibling tools like get_readme or browse_directory, so it falls short of a full 5.

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 'Use this to read source code files' provides an implied usage context, but there is no explicit guidance on when to choose this tool over alternatives such as get_readme or search_code. No exclusions or when-not-to-use conditions are given.

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

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

No annotations are provided, so the description must carry the full burden of behavioral transparency. The description only says 'List pull requests' and lists result fields, but it does not disclose any behavioral traits such as read-only nature, pagination limits, authentication needs, or how filtering works (though the schema covers state). It does not contradict annotations (none exist), but it provides minimal additional behavioral context beyond declaring it lists. Thus it is significantly under-specified.

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 captures the core action and the returned fields. It is front-loaded with the action 'List' and the resource, and it avoids any unnecessary fluff. Every part earns its place, making it effective in communicating the essential purpose with no waste.

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 complexity (only 3 parameters, no output schema, no nested objects) and the presence of a complete schema, the description covers the main functional scope: it lists pull requests and indicates the return contents. It does not mention pagination, rate limits, or other edge behaviors, but for a simple list operation this is not a fatal gap. It is appropriately complete for a tool with this complexity, though it could benefit from a note about filtering defaults or pagination, so it earns a 4 rather than 5.

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

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

The input schema has 100% description coverage: every parameter (state, repo_slug, workspace) has its own description. The tool description adds no extra information about these parameters. According to scoring guidance, when schema_description_coverage is high (>80%), the baseline is 3, and indeed the description does little to enhance parameter understanding. Therefore, the score is 3.

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: 'List pull requests in a repository'. It also lists the returned fields (titles, authors, states, descriptions). It does not explicitly differentiate from sibling tools, but the noun phrase 'pull requests' is specific enough to distinguish it from list_workspaces, list_branches, etc. Since it is clear but lacks explicit sibling differentiation, it fits a 4.

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 does not mention any exclusions or conditions that would help an agent choose it over similar list tools. There is only an implicit understanding that it lists pull requests, but no explicit use cases or when-not-to-use. Given the absence of usage guidance, this scores a 2.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It does disclose a key behavior: automatically searching for README.md, README.txt, and readme.rst. But it does not mention what happens when no README is found, how the content is returned (raw text vs. structured object), or any permission requirements.

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 that immediately states what the tool does, followed by a concrete list of supported extensions. Every word contributes value 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?

The tool is simple and the schema rich enough for invocation, but no output schema exists and the description does not explicitly explain the return type or format. For an AI agent, it is clear a README is fetched, but ambiguity remains about what 'read' returns (raw content, parsed text, etc.) and edge-case behavior when multiple or no README versions exist.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no parameter-specific meaning beyond the schema; it neither explains repo_slug/workspace semantics nor the branch defaulting behavior, but the schema fields already carry detailed 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 clearly states the action ('Fetch and read the README file') and identifies the resource ('of a repository'). It also lists the specific file names that are auto-detected, distinguishing this tool from generic file access tools like get_file_content and browse_directory.

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 a clear context for when to use the tool: when you need the README file and don't know or want to specify the exact filename. However, it does not explicitly mention alternatives or exclusion cases, so it misses the top bar for explicitness.

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

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

No annotations are provided, so the description must carry the burden of behavioral disclosure. It only says what information is returned, but does not indicate whether this is a read-only operation, any permission requirements, rate limits, or how the response is structured. This is a notable gap for a tool with zero annotation coverage.

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

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

A single sentence that is direct and informative, providing the core purpose and key return fields without any filler. 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 is simple, and the description names the main return fields, partially compensating for the missing output schema. However, there is no mention of when to use this tool, no behavioral details, and no clarification on how the workspace parameter is resolved. Given the lack of annotations, the description is adequate but not 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 100%, so the parameters are already documented. The description does not add extra meaning about parameter formats or usage beyond what the schema provides; it merely restates the kind of data returned.

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 'Get' and the resource 'detailed information about a specific repository', listing concrete attributes (description, language, size, URLs). This distinguishes it from listing siblings like list_repositories, which cover multiple repos.

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 'specific repository' implies use when a single repo is needed, contrasting with list_repositories. However, no explicit guidance is given about when to choose this over siblings or when the workspace parameter matters, so usage context is only implied.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It accurately indicates a read-only listing action and states the returned data shape (branch names and latest commit hashes). However, it does not disclose pagination, potential size limits, or any authentication requirements. Since the action is benign and the return type is summarized, this is adequate but not thorough.

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 concise sentence that directly states the action and the output. Every word earns its place; there is no fluff or redundancy. The core purpose 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 list tool with two parameters and no output schema, the description is reasonable but not complete. It lacks usage guidelines, alternative routing, and any caveats about empty results or error conditions. The presence of sibling tools makes the missing differentiation more noticeable.

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 description coverage is 100%, so the input schema already documents both parameters (repo_slug and workspace) sufficiently. The description adds no parameter-specific meaning beyond restating the repository context. By rule, baseline 3 applies when the schema covers all 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 uses a specific verb and resource: 'List all branches in a repository.' It clearly distinguishes this tool from sibling tools like list_repositories and list_commits by naming the object type (branches) and scope (repository). The added detail about returning branch names and latest commit hashes further clarifies its purpose.

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 does not provide any guidance on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or conditions that would lead an agent to prefer another tool such as list_commits or get_repository. Usage context is entirely absent.

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

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

No annotations are provided, so the description carries the burden. It discloses that the tool returns commit messages, authors, dates, and hashes, but does not mention pagination, default limits, authentication requirements, or read-only behavior. The word 'List' implies a safe read, but more detail would improve 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?

A single, well-formed sentence that efficiently communicates the action, scope, optional filter, and return fields. Every word 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?

The description is adequate for a simple listing tool, but lacks information about result ordering, max number of commits returned, pagination, and any prerequisites. With no output schema and no annotations, the description alone should fill these gaps to be fully 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?

The input schema covers all three parameters with descriptions (100% coverage), so the baseline is 3. The tool description only adds the concept of 'recent' and optional branch filtering, which is already reflected in the schema's branch parameter. No additional semantic value 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?

The description states a clear verb ('List') and resource ('commits in a repository'), and notes the optional branch filter. It is easily distinguishable from sibling tools like get_commit (single commit) or list_branches (branches).

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 for retrieving commit history, but does not explicitly explain when to choose this tool over alternatives like get_commit or get_commit_diff. It mentions the branch filter as a condition, which is a light usage hint.

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?

There are no annotations, so the description must carry the behavioral burden. 'List' suggests a read-only operation, but the description does not disclose potential pagination behavior, whether it returns all results in a single call, or how workspace resolution works when not provided. It is not misleading, but it is thin on behavioral nuance.

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, efficient sentences. The first conveys the core action and scope, the second lists the return fields, with no wasted words or 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 one-parameter tool, the description and schema together provide enough context to call it: the workspace parameter is documented, and the return values (names, slugs, descriptions, links) are explicitly listed. A small gap is the lack of mention of pagination or any limits, but 'all repositories' implies the tool handles that.

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 description fully covers the single optional parameter, including its meaning and fallback environment variable, so the description does not need to add details. Baseline 3 is appropriate because the schema already provides 100% 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 a specific action ('List') on a specific resource ('repositories') scoped to 'a Bitbucket workspace,' and adds what it returns. It semantically differentiates from siblings such as get_repository by emphasizing 'all repositories.'

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

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

No guidance is given for when to use this tool over siblings such as get_repository or list_workspaces, nor are any exclusions or prerequisites mentioned. The description only states what it does, leaving the agent to infer context.

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

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

No annotations exist, so the description must carry behavioral transparency. It discloses the scope (accessible workspaces) and return fields, which is good, but it omits potential concerns like pagination, ordering, or authentication requirements. For a simple no-parameter list operation, this is acceptable but not rich.

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, each earning its place: the first states the action and scope, the second specifies the returned data. No filler or redundant wording.

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 absence of input parameters and an output schema, the description adequately covers what an agent needs to invoke the tool and understand its return. It could mention potential quirks like rate limits or pagination, but for a simple list endpoint, the information provided is sufficient.

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 the schema coverage is 100% (empty schema fully documents parameters). The description adds no parameter info because none exist, matching the baseline of 4 for zero-parameter tools.

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 all Bitbucket workspaces accessible by the authenticated user, with specific verb 'List' and resource 'workspaces'. It also specifies the return content (names, slugs, descriptions), making it unambiguous. It naturally differentiates from sibling tools like list_repositories and get_repository.

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 usage is implied: use this when you need the set of workspaces for the authenticated user. However, there is no explicit statement about when to use it versus alternatives, nor any conditional guidance. Since no sibling tool lists workspaces, this is a minor gap.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does state the result type (files and snippets), which is helpful, but it does not clarify read-only nature, authentication requirements, search limits, or any other behavioral traits. For a search tool, this is adequate but not thorough.

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 action and resource, then states the output. Every word earns its place, and it is appropriately concise for a straightforward search tool.

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 provides enough information for an agent to understand the tool's purpose and expected output. The input schema covers parameter details, and the description adds the return format. While it omits potential edge cases or restrictions, these are not critical for invoking this simple search 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 100%, so parameters are fully documented in the schema itself. The description adds no extra meaning about the parameters beyond what the schema already provides, so a baseline 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 action (search), the resource (code across a repository), and the specific mechanism (Bitbucket's code search), while also mentioning the return value (matching files and snippet previews). This distinguishes it from siblings like get_file_content or browse_directory, which serve different purposes.

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 no guidance on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or scenarios where another tool would be more appropriate. The context is implied but not articulated.

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