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 states the tool 'adds' a comment, implying a write operation, but doesn't cover critical aspects like required permissions, whether comments are editable/deletable, rate limits, or error conditions. The mention of markdown support is useful, but overall behavioral context is insufficient for a mutation tool.

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

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

The description is well-structured and appropriately sized. It starts with a clear purpose statement, followed by a brief feature note, then detailed parameter explanations, and ends with return info. Every sentence earns its place, though the 'Returns' line is vague ('Created comment info') and could be slightly more informative.

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

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

Given the tool's moderate complexity (5 parameters, mutation operation) and lack of annotations or output schema, the description is partially complete. It thoroughly documents parameters but lacks behavioral context (e.g., permissions, side effects) and output details. It's adequate for basic use but leaves gaps for robust agent 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?

The description excels in parameter semantics. With 0% schema description coverage, it fully compensates by detailing all 5 parameters in the 'Args' section, explaining their purposes, optionality, and interdependencies (e.g., 'line' requires 'file_path'). This adds significant value beyond the bare schema, making parameter usage clear and actionable.

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: 'Add a comment to a pull request' with the additional detail that it can add 'general comments or inline comments on specific lines.' This is a specific verb+resource combination. However, it doesn't explicitly differentiate from sibling tools like 'list_pr_comments' or 'request_changes_pr,' which keeps it from a perfect score.

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

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

The description provides minimal usage guidance. It mentions the tool can add general or inline comments, but offers no explicit advice on when to use this tool versus alternatives like 'request_changes_pr' or 'approve_pr.' There's no mention of prerequisites, permissions, or typical use cases, leaving the agent with little contextual direction.

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 states the action ('Approve') but doesn't describe what approval entails (e.g., whether it's reversible, if it requires specific permissions, what happens to the PR status, or any side effects). This is a significant gap for a mutation tool.

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

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

The description is efficiently structured with clear sections (purpose, Args, Returns) in just three sentences. Every element serves a purpose with no wasted words, though the 'Returns' section could be slightly more informative.

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 mutation tool with no annotations and no output schema, the description adequately covers the basic purpose and parameters. However, it lacks important context about behavioral aspects (permissions, side effects, return format) and usage guidelines relative to sibling tools, leaving gaps for an AI agent.

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

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

The description explicitly documents both parameters ('repo_slug' and 'pr_id') in the Args section, providing clear semantic meaning. Since schema description coverage is 0%, this documentation fully compensates for the schema's lack of descriptions, making parameters well-understood.

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 ('Approve') and resource ('a pull request'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'unapprove_pr' or 'merge_pull_request' which are related approval/merge operations on pull requests.

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

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

No guidance is provided about when to use this tool versus alternatives like 'unapprove_pr', 'decline_pr', or 'merge_pull_request'. The description lacks any context about prerequisites, permissions needed, or typical workflow scenarios.

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 present, the description carries the behavioral disclosure burden and does a solid job: it states the return is a complete page of file statistics and explains that next_cursor paginates remaining files while preserving issued filters and page size. It does not mention permissions, rate limits, or other operational constraints, but the core read/list behavior and pagination semantics are clear.

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 four short sentences, front-loads the core operation, and then adds revision semantics, pagination behavior, and the sibling alternative. Every sentence adds useful information without repetition.

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

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

For a read-only list operation with no output schema, the description supplies the essential comparison semantics, return-shape hint, pagination instruction, and line-diff alternative. The main gap is that path and limit are not explained, so an agent must infer their behavior from the schema alone.

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 for undocumented parameters. It explains base/head as branches, tags, or hashes and clarifies cursor pagination behavior, but it leaves path, limit, and repo_slug without semantic detail. This is adequate but incomplete for a six-parameter tool.

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: list changed files from base to head, with explicit git diff base/head semantics. It also distinguishes the tool from get_commit_diff by saying that sibling returns actual changed lines, while this returns file statistics.

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 names an alternative, get_commit_diff, and clarifies that this tool is for file-level comparisons rather than line-level diffs. It also explains that revisions may be branches, tags, or hashes. However, it does not contrast with list_commits or get_commit, so it stops short of full when-to-use 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. While it states this is a creation operation (implying mutation), it doesn't mention permission requirements, whether the operation is idempotent, what happens on conflicts, or any rate limits. The description provides basic functional information but lacks critical behavioral context for a mutation tool.

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

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

The description is well-structured with clear sections (Args, Returns) and uses bullet points effectively for the 'kind' parameter. While comprehensive, it maintains efficiency - every sentence adds value. The front-loaded purpose statement is clear, though the parameter explanations are necessarily detailed given the complexity.

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 6-parameter mutation tool with no annotations and no output schema, the description provides good parameter semantics but lacks behavioral context and usage guidance. The return statement is minimal ('Created restriction info with ID'), leaving the agent uncertain about the response format. While parameters are well-documented, other aspects remain incomplete.

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

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

With 0% schema description coverage, the description compensates excellently by explaining all 6 parameters in detail. It provides semantic meaning for 'kind' with common values and examples, clarifies 'pattern' usage with examples, explains the relationship between 'branch_match_kind' and 'branch_type', and specifies when 'value' is needed. This adds substantial value beyond the bare 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 clearly states the specific action ('Create a branch restriction/protection rule') and resource ('branch restriction'), distinguishing it from sibling tools like 'delete_branch_restriction' or 'list_branch_restrictions'. It provides a precise verb+resource combination that leaves no ambiguity about the tool's function.

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. While it's clear this creates restrictions (unlike 'delete_branch_restriction' which removes them), there's no mention of prerequisites, when this should be applied, or how it relates to other repository management tools in the sibling list. The agent receives no contextual usage advice.

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

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

With no annotations provided, the description carries full burden. It indicates this is a creation/mutation operation ('Create'), but doesn't disclose permission requirements, rate limits, side effects, or what 'Created status info' contains. The description adds basic behavioral context but lacks important operational details for a mutation tool.

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

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

The description is well-structured and appropriately sized. It starts with the core purpose, provides usage context, then documents parameters clearly in a formatted section, and ends with return information. Every sentence earns its place without 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 mutation tool with 7 parameters, no annotations, and no output schema, the description provides good parameter documentation but lacks important behavioral context. The 'Returns' section is vague ('Created status info'), and there's no information about permissions, error conditions, or system constraints that would be important for a CI/CD integration 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?

With 0% schema description coverage, the description fully compensates by providing detailed parameter documentation in the Args section. It explains each parameter's purpose, provides enum values for 'state', notes optional parameters, and gives examples like 'my-ci-system' for the key parameter. This adds significant value beyond the bare 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 clearly states the tool's purpose as 'Create a build status for a commit' with the specific verb 'create' and resource 'build status', distinguishing it from sibling tools like get_commit_statuses (which retrieves rather than creates). However, it doesn't explicitly differentiate from all sibling tools beyond this basic distinction.

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

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

The description provides clear context with 'Use this to report CI/CD status from external systems,' giving a specific use case. It doesn't mention when NOT to use it or name explicit alternatives, but the context is sufficient for understanding its primary application.

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 effectively communicates that this is a write operation ('Create') and includes a critical behavioral note about secured variables ('cannot be read back from the API'). However, it omits other important details like authentication requirements, rate limits, error conditions, or whether the operation is idempotent.

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 efficiently structured with a clear purpose statement followed by organized sections for arguments and returns. Every sentence adds value: the first establishes the tool's function, the argument explanations provide necessary context, and the return statement clarifies output expectations. No wasted words or redundant information.

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

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

Given the tool's complexity (a write operation with 4 parameters), absence of annotations, and no output schema, the description does an adequate but incomplete job. It covers the basic creation functionality and parameter semantics well, but lacks information about authentication, error handling, permissions, or what the 'Created variable info with UUID' actually contains, leaving gaps for the agent.

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

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

The description adds significant semantic value beyond the input schema, which has 0% description coverage. It explains that 'key' represents variable names with concrete examples ('PYPI_TOKEN', 'AWS_SECRET_KEY'), clarifies that 'secured' determines encryption with a default value and important consequence ('cannot be read back'), and provides context for 'repo_slug' and 'value' parameters that the schema lacks entirely.

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 specific action ('Create a pipeline variable') and identifies the resource ('pipeline variable'), making the purpose immediately apparent. It distinguishes itself from siblings like 'update_pipeline_variable' and 'delete_pipeline_variable' by focusing on creation rather than modification or deletion.

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 like 'update_pipeline_variable' or 'get_pipeline_variable'. It lacks context about prerequisites (e.g., needing repository access) or typical use cases, offering only basic functional information without strategic direction.

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 clearly indicates this is a creation/mutation operation and mentions the default behavior for 'close_source_branch', but doesn't cover authentication requirements, error conditions, rate limits, or what happens if the source branch doesn't exist. It provides basic behavioral context but lacks completeness.

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 well-structured with clear sections (Args, Returns) and uses bullet-like formatting for parameters. It's appropriately sized for a 6-parameter tool, though the 'Returns' section could be more detailed given the lack of output schema. Every sentence adds value with no redundant information.

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

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

For a mutation tool with 6 parameters, no annotations, and no output schema, the description provides adequate parameter documentation but lacks important contextual information about authentication, error handling, and the full structure of returned data. The 'Returns' section mentions only 'id, url, and state' without specifying data types or additional fields that might be included.

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

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

The description adds substantial value beyond the input schema, which has 0% description coverage. It explains each parameter's purpose with examples (e.g., 'repo_slug: Repository slug (e.g., "anzsic_classifier")') and clarifies default values and formats (e.g., 'description: PR description in markdown'), fully compensating for the schema's lack of documentation.

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

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

The description clearly states the specific action ('Create a pull request') and target resource ('in a Bitbucket repository'), distinguishing it from sibling tools like 'merge_pull_request' or 'get_pull_request' that perform different operations on pull requests. It provides a complete verb+resource+scope specification.

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 like 'create_branch_restriction' or 'create_commit_status', nor does it mention prerequisites or conditions for successful use. It simply states what the tool does without contextual usage information.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. While it mentions that the repository will be created and returns clone URLs, it doesn't address important behavioral aspects like required authentication, potential rate limits, whether the operation is idempotent, or what happens if a repository with the same slug already exists. This leaves significant gaps for an agent to understand the tool's behavior.

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

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

The description is well-structured with clear sections for Args and Returns, making it easy to parse. It's appropriately sized with no redundant information, though the formatting with quotes around the entire description is slightly awkward. Every sentence serves a purpose.

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

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

For a creation tool with 4 parameters and no annotations or output schema, the description provides basic parameter semantics and return information but lacks important contextual details. It doesn't explain error conditions, authentication requirements, or how the tool fits into broader workflows. The absence of an output schema means the description should ideally provide more detail about the return structure.

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

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

The description provides meaningful semantic information for all parameters beyond what the schema offers (0% coverage). It explains that 'repo_slug' must be lowercase with no spaces, 'project_key' is optional, 'is_private' defaults to True, and 'description' is for repository description. This adds substantial value over the bare schema field names.

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 specific action ('Create a new Bitbucket repository') with the resource type, distinguishing it from sibling tools like 'update_repository' or 'delete_repository'. It uses precise language that leaves no ambiguity about the tool's function.

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 like 'update_repository' or 'get_repository', nor does it mention prerequisites such as required permissions or project existence. It lacks context about when this operation is appropriate versus other repository-related 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?

With no annotations provided, the description carries full burden for behavioral disclosure. It states this is a creation operation but doesn't mention permission requirements, whether tags are immutable once created, rate limits, or what happens if a tag with the same name already exists. For a mutation tool with zero annotation coverage, this represents significant gaps in behavioral transparency.

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

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

The description is perfectly structured and concise. It begins with a clear purpose statement, then provides organized parameter documentation with helpful examples, and ends with a brief returns statement. Every sentence earns its place with no wasted words or redundant information.

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

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

For a creation tool with 4 parameters, no annotations, and no output schema, the description provides good parameter documentation but lacks behavioral context. The 'Returns: Created tag info' is minimal but acknowledges output. However, without annotations covering safety, permissions, or side effects, and with no output schema, the description doesn't fully compensate for these structural 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?

The description provides excellent parameter semantics despite 0% schema description coverage. It clearly explains each parameter's purpose: 'repo_slug: Repository slug', 'name: Tag name (e.g., "v1.0.0")', 'target: Commit hash or branch name to tag', and 'message: Optional tag message (for annotated tags)'. The examples and clarifications add substantial value beyond what the bare schema provides.

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 specific action ('Create a new tag') and resource ('in a repository'), distinguishing it from sibling tools like 'delete_tag' or 'list_tags'. It provides a complete verb+resource+scope statement that leaves no ambiguity about the tool's function.

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 like 'create_branch_restriction' or 'create_commit_status', nor does it mention prerequisites or exclusions. While the purpose is clear, there's no contextual usage information to help an agent choose between similar creation 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?

With no annotations provided, the description carries full burden. It discloses that the tool creates a webhook (implying a write operation) and returns created webhook info with UUID, which adds some behavioral context. However, it lacks details on permissions needed, rate limits, error conditions, or whether the operation is idempotent, leaving gaps for a mutation tool.

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

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

The description is well-structured with a clear purpose statement followed by Args and Returns sections. It's appropriately sized with no redundant information. Minor deduction because the events list could be slightly more concise, but overall it's efficient and 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?

Given no annotations and no output schema, the description does a good job explaining parameters and return value. It covers the core functionality adequately for a creation tool. However, it lacks some contextual details like authentication requirements or error handling, preventing a perfect score.

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 provides clear semantics for all 5 parameters: repo_slug, url, events (with examples), description (optional), and active (default). This adds significant value beyond the bare schema, explaining usage and common event types.

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 'create' and resource 'webhook for a repository', making the purpose specific and unambiguous. It distinguishes from sibling tools like 'delete_webhook' and 'list_webhooks' by focusing on creation rather than deletion or listing.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., repository access), compare with similar tools (e.g., 'update_user_permission' for other configurations), or specify when webhook creation is appropriate versus other notification methods.

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. It mentions the action ('Decline') which implies a mutation, but does not disclose behavioral traits such as required permissions, whether the action is reversible, or any side effects. This is a significant gap for a mutation 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?

The description is front-loaded with the core purpose in the first sentence, followed by structured sections for Args and Returns. Every sentence earns its place with no wasted words, making it highly efficient 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 mutation tool with no annotations and no output schema, the description is adequate but has clear gaps. It covers the purpose and parameters well, but lacks details on behavioral aspects like permissions, side effects, or return value structure, which are important for safe usage.

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

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

Schema description coverage is 0%, but the description explicitly lists and names both parameters ('repo_slug', 'pr_id') in the Args section, adding meaning beyond the bare schema. It compensates well for the low coverage, though it could provide more context on parameter formats or examples.

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

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

The description clearly states the specific action ('Decline (close without merging)') and resource ('a pull request'), distinguishing it from sibling tools like 'merge_pull_request' and 'approve_pr'. It uses precise terminology that conveys the exact 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?

The description implies usage for closing pull requests without merging, but does not explicitly state when to use this versus alternatives like 'merge_pull_request' or 'request_changes_pr'. It provides basic context but lacks explicit guidance on exclusions or prerequisites.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure. It mentions 'Confirmation of deletion' as a return, which hints at output, but lacks critical details: whether this is destructive (likely yes, but not stated), permission requirements, error conditions, or side effects. For a deletion tool, this is a significant gap in safety and operational context.

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

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

The description is efficiently structured with a clear purpose statement followed by Args and Returns sections. Every sentence adds value: the first states the action, the second and third explain parameters, and the fourth describes output. No wasted words, and it's front-loaded with the core functionality.

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

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

Given the tool's complexity (a deletion operation with 2 parameters), no annotations, and no output schema, the description is minimally adequate. It covers parameters well and hints at output, but lacks details on behavioral aspects like permissions, errors, or confirmation format. For a destructive tool, this leaves gaps that could hinder safe agent invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It adds meaningful context for both parameters: repo_slug is documented as 'Repository slug' and restriction_id is explained with 'from list_branch_restrictions', clarifying its source. This goes beyond the bare schema (which only has titles) and provides practical guidance, though it could detail formats or constraints further.

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 ('Delete') and resource ('a branch restriction'), making the purpose immediately understandable. However, it doesn't differentiate this tool from other deletion tools like delete_group_permission or delete_repository, which would require mentioning the specific domain (branch management in version control).

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 by referencing 'restriction_id (from list_branch_restrictions)', suggesting this tool should be used after listing restrictions. However, it doesn't explicitly state when to use this versus alternatives (e.g., update operations) or provide context about prerequisites beyond the ID reference.

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 states the action ('Remove') but doesn't disclose critical traits: whether this is destructive (likely yes, but not confirmed), authentication requirements, error conditions (e.g., if permission doesn't exist), or side effects. The mention of 'Returns: Confirmation of removal' hints at output but lacks detail on format or success/failure indicators.

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 appropriately sized and front-loaded: the first sentence states the core purpose, followed by structured 'Args' and 'Returns' sections. Every sentence earns its place, though the 'Returns' line could be more informative (e.g., specifying response format). No redundant or verbose content is present.

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

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

Given the tool's complexity (a destructive operation with 2 parameters), no annotations, and no output schema, the description is minimally adequate but has clear gaps. It covers the basic action and parameters but lacks behavioral context (e.g., permissions needed, idempotency) and detailed output information. For a deletion tool, this leaves the agent under-informed about risks and results.

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 adds semantic meaning by explaining that 'repo_slug' refers to a 'Repository slug' and 'group_slug' to a 'Group slug', clarifying these are identifiers rather than display names. However, it doesn't specify format constraints (e.g., alphanumeric) or provide examples, 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?

The description clearly states the specific action ('Remove') and target ('a group's explicit permission from a repository'), distinguishing it from sibling tools like 'delete_user_permission' (which removes user permissions) and 'update_group_permission' (which modifies rather than removes). It precisely defines the verb+resource combination without being tautological.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing admin access), when not to use it (e.g., for inherited permissions), or direct alternatives like 'update_group_permission' for modifying permissions instead of removing them. Usage is implied only by the action described.

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 states the tool deletes a pipeline variable and returns a confirmation, which covers the basic action and output. However, it lacks critical details such as whether this operation is destructive/permanent, what permissions are required, if there are rate limits, or how errors are handled. For a deletion tool with zero annotation coverage, this is insufficient.

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 well-structured and concise, using a brief purpose statement followed by clear sections for Args and Returns. Each sentence adds value without redundancy. However, the 'Returns' section is vague ('Confirmation of deletion'), which slightly reduces efficiency by not specifying the confirmation format.

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

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

Given the tool's complexity (a destructive operation with 2 parameters), no annotations, and no output schema, the description is incomplete. It covers the basic action and parameters but misses critical behavioral details like permanence, error handling, and authentication needs. The lack of output schema means the description should explain return values more thoroughly, which it doesn't do.

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

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

The description adds meaningful context for both parameters beyond the input schema, which has 0% coverage. It explains that 'repo_slug' identifies the repository and 'variable_uuid' is the UUID from 'list_pipeline_variables', clarifying their roles and relationships. This compensates well for the lack of schema descriptions, though it doesn't detail format constraints (e.g., UUID format).

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 ('Delete') and target resource ('a pipeline variable'), making the purpose immediately understandable. It distinguishes itself from sibling tools like 'create_pipeline_variable' and 'update_pipeline_variable' by specifying the destructive operation. However, it doesn't explicitly mention the repository context, which is implied but could be more specific.

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 minimal guidance on when to use this tool. It mentions that 'variable_uuid' should come from 'list_pipeline_variables', which hints at a prerequisite but doesn't explicitly state when to choose this over alternatives like 'update_pipeline_variable' or warn about irreversible deletion. No context on permissions or constraints is provided.

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 effectively communicates the destructive nature ('irreversible') and the required parameter ('repo_slug'), though it lacks details on permissions, error conditions, or what 'Success status' entails. The warning adds critical context beyond basic function.

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 front-loaded with the core purpose, followed by a critical warning, and then structured sections for Args and Returns. Every sentence earns its place—no wasted words—making it highly efficient 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?

Given the tool's high complexity (destructive operation), lack of annotations, and no output schema, the description is somewhat incomplete. It covers the irreversible nature and parameter basics but omits details on permissions, error handling, or the structure of the return value ('Success status'), leaving gaps for safe agent use.

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

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

The description adds meaning by specifying that 'repo_slug' is the 'Repository slug to delete', which clarifies the parameter's role beyond the schema's basic title ('Repo Slug'). With 0% schema description coverage and only one parameter, this compensates adequately, though more detail on format or examples would be beneficial.

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 specific action ('Delete') and resource ('a Bitbucket repository'), distinguishing it from sibling tools like 'create_repository' or 'update_repository'. It uses precise language that leaves no ambiguity about the tool's function.

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

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

The description provides clear context with the 'WARNING: This action is irreversible!' statement, which implicitly guides when to use this tool (for permanent deletion) versus alternatives like 'update_repository' for modifications. However, it doesn't explicitly name alternatives or specify prerequisites beyond the warning.

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. It mentions 'Confirmation of deletion' in the Returns section, which hints at output, but fails to disclose critical behavioral traits like whether this is a destructive operation, permission requirements, or error handling. This is inadequate for a deletion tool with no annotation coverage.

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

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

The description is well-structured with clear sections for Args and Returns, and each sentence is essential. It is front-loaded with the main purpose and avoids unnecessary details, making it efficient 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?

Given the complexity of a deletion tool with no annotations and no output schema, the description is incomplete. It lacks information on behavioral aspects like safety, permissions, and error cases, which are crucial for proper tool invocation in this context.

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

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

Schema description coverage is 0%, but the description lists both parameters ('repo_slug' and 'tag_name') with brief explanations, adding meaning beyond the bare schema. However, it does not provide details on format, constraints, or examples, so it only partially compensates for the low coverage.

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

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

The description clearly states the action ('Delete') and target resource ('a tag from a repository'), which is specific and unambiguous. However, it does not differentiate from sibling tools like 'delete_repository' or 'delete_webhook' beyond the resource type, so it's not fully distinguished.

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

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

No guidance is provided on when to use this tool versus alternatives, such as when to delete a tag versus other deletion tools like 'delete_repository'. The description lacks context about prerequisites or scenarios 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?

With no annotations provided, the description carries full burden but only states the basic action. It doesn't disclose behavioral traits like whether this is destructive (implied by 'delete' but not explicit), what permissions are required, if changes are reversible, or error conditions (e.g., if permission doesn't exist).

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 well-structured with clear sections for Args and Returns. It's front-loaded with the core purpose, though the return statement could be more specific (e.g., what format the confirmation takes).

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 destructive operation with no annotations and no output schema, the description is minimally adequate but lacks important context. It explains parameters well but doesn't cover behavioral aspects like permissions needed, side effects, or error handling, leaving gaps for safe usage.

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

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

The description adds meaningful context for both parameters beyond the schema (which has 0% coverage). It clarifies that 'repo_slug' identifies the repository and 'selected_user' can be either an 'account_id' or 'UUID', which is crucial for correct usage.

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 ('Remove') and target ('user's explicit permission from a repository'), distinguishing it from sibling tools like 'delete_group_permission' or 'update_user_permission'. It specifies the exact resource being manipulated.

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

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

No guidance is provided on when to use this tool versus alternatives like 'update_user_permission' or 'delete_group_permission'. The description doesn't mention prerequisites, such as needing admin access or confirming the permission exists first.

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

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

No annotations are provided, so the description carries full burden. It states 'Delete a webhook' and 'Returns: Confirmation of deletion', which implies a destructive mutation but lacks details on permissions required, whether deletion is permanent, error conditions, or side effects. This is inadequate for a destructive 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?

The description is appropriately sized with three brief sections: purpose, args, and returns. It's front-loaded with the core action. However, the 'Args:' and 'Returns:' headings add minor structural overhead without enhancing clarity significantly.

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 this is a destructive mutation tool with no annotations, no output schema, and 2 parameters, the description is incomplete. It lacks critical behavioral details like authentication needs, irreversible effects, or error handling. The return value mention is vague ('Confirmation of deletion'), failing to specify format or content.

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 adds meaning by explaining 'repo_slug: Repository slug' and 'webhook_uuid: Webhook UUID (from list_webhooks)', clarifying the source of the UUID. This provides useful context beyond the bare schema, though it doesn't detail format constraints for repo_slug.

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 'Delete' and resource 'a webhook', making the purpose unambiguous. It distinguishes from siblings like 'create_webhook' and 'list_webhooks' by specifying deletion, though it doesn't explicitly contrast with other deletion tools like 'delete_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 description provides no guidance on when to use this tool versus alternatives. It mentions 'webhook_uuid: Webhook UUID (from list_webhooks)' which hints at prerequisite data, but offers no explicit when/when-not instructions or comparisons with sibling tools like 'delete_repository' or 'update_webhook' (if it existed).

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 behavioral disclosure. It states it 'Get information' and returns 'Branch info with latest commit details,' which implies a read-only operation, but doesn't cover aspects like error handling, authentication needs, rate limits, or what specific information is included in the return. This leaves significant gaps for a tool with no annotation coverage.

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

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

The description is well-structured and front-loaded with the main purpose, followed by clear sections for 'Args' and 'Returns.' Every sentence earns its place without redundancy, making it efficient 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?

Given the tool's low complexity (2 parameters, no output schema, no annotations), the description is somewhat complete but has gaps. It covers the basic purpose and parameters but lacks usage guidelines and detailed behavioral context. For a simple read tool, this is minimally adequate but could be improved with more context.

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

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

The description lists the parameters ('repo_slug' and 'branch_name') and their purposes, but the schema description coverage is 0%, so the schema provides no additional details. The description adds basic semantics by explaining what each parameter represents, but it doesn't provide format examples, constraints, or deeper context beyond naming them.

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

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

The description clearly states the tool's purpose with 'Get information about a specific branch,' which includes a specific verb ('Get') and resource ('branch'). It distinguishes from siblings like 'list_branches' (which lists multiple branches) by focusing on a single branch, though it doesn't explicitly name this distinction.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when to use 'get_branch' over 'list_branches' or 'get_commit' for related information, nor does it specify any prerequisites or exclusions for usage.

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 states this is a read operation ('get'), which implies it's non-destructive, but doesn't mention authentication requirements, rate limits, error conditions, or what happens if the commit doesn't exist. The description adds minimal behavioral context beyond the basic operation.

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 well-structured and appropriately sized. It starts with a clear purpose statement, then lists parameters and return values in separate sections. Every sentence adds value, though the 'Args' and 'Returns' labels could be more integrated with the main text.

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

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

For a simple read tool with 2 parameters and no output schema, the description is minimally complete. It covers the basic operation and parameters but lacks behavioral details (like error handling) and doesn't fully explain the return format beyond listing fields. Given the low complexity, it's adequate but has clear gaps.

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

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

The description provides parameter semantics in the 'Args' section, explaining what 'repo_slug' and 'commit' represent. Since schema description coverage is 0%, this adds valuable meaning beyond the bare schema. However, it doesn't specify format details (e.g., what constitutes a valid repo_slug or commit hash format), keeping it at a baseline level.

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: 'Get detailed information about a specific commit.' It uses a specific verb ('get') and resource ('commit'), but doesn't explicitly differentiate it from sibling tools like 'list_commits' or 'compare_commits' beyond the singular vs. plural distinction.

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

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

No guidance is provided on when to use this tool versus alternatives. The description doesn't mention sibling tools like 'list_commits' (for multiple commits) or 'compare_commits' (for comparing commits), nor does it specify prerequisites or contextual constraints for usage.

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 behavioral burden and does a good job: it discloses explicit clipping of large responses, the 555 rejection from Bitbucket, the max_chars clamp range (1-100000), the possibility of a binary diff having no text patch, and the consistency hazard of chunking against moving branches. It omits auth/permission requirements and how the agent knows chunking has ended (empty next chunk?), which keeps it below 5.

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?

Purpose is front-loaded in the first clause, followed by short, independently useful operational notes with zero filler. Every sentence (clipping, chunking, hashing, clamping, 555, binary) carries distinct information an agent would otherwise have to discover by trial.

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?

No output schema and no annotations means the description must stand alone, and it covers the risky edges (clipping, oversized-diff errors, binary files, revision drift). What's missing is the shape of a successful return (raw patch text? headers?) and an explicit end-of-chunking signal, which matter for a tool designed to be called repeatedly.

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, and it partially does: base/head are framed as git revisions, path narrows the diff, max_chars has a stated clamp. But it refers to the chunking parameter as "next_offset" while the schema names it "offset" — an agent could look for a nonexistent parameter — and repo_slug is never explained. Useful but not fully reliable 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 opens with a specific verb and resource: "Read the raw diff from base to head, optionally restricted to a file." An agent immediately knows this returns diff content between two revisions. It does not distinguish itself from close siblings like compare_commits or get_pr_diff, which also return revision-to-revision differences, so it stops short of a 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?

Operational guidance is present for the hard cases: chunk large diffs with the offset, pin revisions to hashes so moving branches don't change results, narrow with path if Bitbucket returns 555. However, there is no guidance on when to choose this tool over compare_commits or get_pr_diff, which is the selection decision an agent actually has to make. Usage is implied by mechanics rather than by explicit alternatives.

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

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

No annotations are provided, so the description carries full burden. It states it 'Returns: List of CI/CD statuses' but lacks behavioral details such as whether this is a read-only operation (implied by 'Get'), rate limits, authentication requirements, error conditions, or pagination behavior (only mentions a default limit). This leaves significant gaps for safe invocation.

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 well-structured and front-loaded with the core purpose, followed by Args and Returns sections. Every sentence adds value without redundancy, making it efficient 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?

Given no annotations and no output schema, the description provides basic purpose and parameter info but lacks behavioral context (e.g., safety, errors) and detailed return format. It's minimally adequate for a read operation but incomplete for reliable use, as it doesn't address key invocation aspects like authentication or rate limits.

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 explicitly lists all three parameters (repo_slug, commit, limit) with brief explanations, adding meaning beyond the schema's titles. However, it doesn't specify format details (e.g., commit hash length, repo_slug structure) or constraints, 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?

The description clearly states the specific action ('Get build/CI statuses') and resource ('for a commit'), distinguishing it from siblings like get_commit (which retrieves commit details) or get_pipeline (which retrieves pipeline information). The verb 'Get' is precise and the scope is well-defined.

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

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

No guidance is provided on when to use this tool versus alternatives. While the purpose is clear, there's no mention of prerequisites (e.g., needing repository access), exclusions, or comparisons to similar tools like get_pipeline (which might provide related CI/CD data).

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

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

With no annotations provided, the description carries full burden for behavioral disclosure. It states this is a 'Get' operation, implying read-only behavior, but doesn't explicitly confirm it's non-destructive or safe. It mentions returns 'details including restrictions and variables,' giving some output context, but lacks information about authentication needs, rate limits, error conditions, or pagination. For a tool with zero annotation coverage, this leaves significant behavioral gaps.

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 well-structured and appropriately sized at four sentences. It front-loads the core purpose, then details Args and Returns in clear sections. There's minimal waste, though the 'Args' and 'Returns' labels are slightly redundant given the schema context. Overall, it's efficient 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?

Given the tool's moderate complexity (2 required parameters, no output schema, no annotations), the description is partially complete. It covers the purpose and parameters well but lacks output details beyond a high-level mention ('Environment details including restrictions and variables'). Without an output schema, more specifics on return structure would be helpful. It's adequate but has clear gaps in behavioral and output context.

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

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

The description adds meaningful context for both parameters in the Args section: 'repo_slug: Repository slug' and 'environment_uuid: Environment UUID (from list_environments).' This clarifies what these parameters represent and where to obtain the UUID. However, with 0% schema description coverage, the schema provides only titles ('Repo Slug', 'Environment Uuid') without descriptions. The description compensates adequately but doesn't fully detail format constraints or examples, keeping it at baseline 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 clearly states the tool's purpose as 'Get details about a specific deployment environment,' which is a specific verb ('Get') and resource ('deployment environment'). It distinguishes from siblings like 'list_environments' (which lists multiple) and 'get_repository' (different resource). However, it doesn't explicitly contrast with all siblings, so it's not a perfect 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 description provides no explicit guidance on when to use this tool versus alternatives. While it mentions 'environment_uuid (from list_environments)' in the Args section, this is parameter documentation rather than usage guidance. There's no discussion of prerequisites, when-not-to-use scenarios, or comparisons to similar tools like 'get_repository' or 'get_project'.

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

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

With no annotations provided, the description carries full burden. It discloses key behavioral traits: the read-only nature ('Get', 'Read'), the no-clone constraint, and error conditions for binary/not-found files. However, it lacks details on authentication requirements, rate limits, response formats beyond 'text', or handling of large files.

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 efficiently structured with a clear purpose statement followed by organized sections for Args and Returns. Every sentence adds value: the first establishes context, the second adds behavioral constraint, and the parameter/return details are essential for understanding. No wasted words.

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 operation with no annotations and no output schema, the description provides good coverage: purpose, usage context, parameter semantics, and return behavior. It lacks only minor details like authentication needs or exact error formats, but is largely complete for the tool's complexity.

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

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

The description adds significant meaning beyond the 0% schema coverage. It explains all three parameters: repo_slug ('Repository slug'), path with examples ('File path (e.g., "src/main.py", "README.md")'), and ref with default and format ('Branch, tag, or commit hash (default: "main")'). This fully compensates for the schema's lack of 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 specific action ('Get the content of a file') and resource ('from a repository'), distinguishing it from sibling tools like list_directory (which lists files) or get_commit (which retrieves commit data). It precisely defines the tool's scope as reading file contents without cloning.

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

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

The description provides clear context for when to use this tool ('Read file contents without cloning the repository'), which implicitly distinguishes it from operations that require repository cloning. However, it doesn't explicitly mention when NOT to use it or name specific alternatives like list_directory for browsing or get_commit for metadata.

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 zero annotations the description carries the full load, and it delivers: rename-preserving paths, full rather than abbreviated hashes, and a non-obvious pagination quirk ('cursor keeps its issued page size; limit only applies to the first page'). It stops short of stating auth/scoping requirements or error behavior, so not a 5.

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?

Four short sentences, front-loaded with what the tool returns, then the sibling redirect, then pagination. No sentence is filler and each adds a distinct fact.

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 5-parameter, no-output-schema, no-annotation tool this is close to sufficient: it describes the returned fields, the delta versus get_commit, and how to page. Missing only repo_slug semantics and any note on default ref resolution.

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, and it does for the hard parts: ref is characterized as branch/tag/commit, and the cursor/limit interaction is explained in a way the bare schema cannot convey. It leaves repo_slug and the 'main'/20 defaults unaddressed, keeping it off a 5.

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

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

States a specific verb and resource ('List a file's history') plus the scoping qualifier ('at a branch, tag or commit without cloning'), which distinguishes it from get_commit and get_file_content. An agent knows immediately what it would get back and at what granularity.

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 routes the agent away from this tool for author/message/date metadata by naming get_commit and explaining why ('Bitbucket omits those from filehistory'). It also gives a concrete continuation procedure ('Follow next_cursor until has_more is false'), so both selection and usage are covered.

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 behavioral disclosure. It states the tool retrieves permission data, implying it's a read-only operation, but doesn't clarify authentication needs, rate limits, error conditions, or what happens if the group or repository doesn't exist. For a tool with zero annotation coverage, this leaves significant gaps in understanding its behavior.

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

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

The description is well-structured and concise, with three clear sections: purpose, arguments, and returns. Each sentence earns its place by providing essential information without redundancy. It could be slightly improved by integrating the sections more fluidly, but it's efficiently front-loaded with the core purpose.

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

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

Given the tool's moderate complexity (2 parameters, no output schema, no annotations), the description is somewhat complete but has gaps. It covers the purpose and parameters adequately but lacks behavioral details (e.g., error handling) and doesn't fully explain the return value ('Group's permission level' is vague without examples). For a read operation with simple inputs, it's minimally viable but could be more informative.

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

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

The description lists the parameters ('repo_slug' and 'group_slug') and their roles, but schema description coverage is 0%, meaning the schema provides no descriptions. The description adds basic meaning by specifying what each slug represents, but it doesn't explain format (e.g., string patterns), examples, or constraints. With 2 parameters and low schema coverage, this is adequate but minimal.

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: 'Get a specific group's permission for a repository.' It specifies the verb ('Get'), resource ('group's permission'), and target ('repository'), making it easy to understand. However, it doesn't explicitly differentiate from sibling tools like 'list_group_permissions' or 'get_user_permission', which would be needed for a perfect score.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'list_group_permissions' (for listing all permissions) or 'get_user_permission' (for user-specific permissions), nor does it specify prerequisites or exclusions. Usage is implied by the purpose but 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?

With no annotations, the description carries the full behavioral burden. It valuably discloses that Bitbucket returns a single best ancestor even when several exist, but it omits permission requirements, error behavior when no common ancestor exists, and does not explicitly frame this as a safe read operation.

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 short sentences with the core purpose front-loaded and no wasted text. The final sentence adds a non-obvious behavioral nuance and earns its place.

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

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

For a simple three-parameter read tool with no output schema, the description covers purpose, usage, and the key return behavior. It could still say more about repo_slug and the no-common-ancestor case, but it is largely 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 coverage is 0%, so the description must compensate. It does partially by explaining that base/head accept branches, tags, or hashes, but repo_slug is left unexplained and no format details or examples are provided for any parameter.

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

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

States a specific verb and resource: returns Bitbucket's best common ancestor of two refs. The concept of a merge-base is distinct from sibling tools like compare_commits or get_commit, so an agent can identify it without opening the schema.

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

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

Gives a clear usage scenario ('Useful for ancestry checks: compare the returned hash with a resolved commit') but does not name alternatives or say when not to use it. That is clear context without exclusions, matching a 4.

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 behavioral disclosure. It states the tool retrieves status information, which implies a read-only operation, but does not specify authentication needs, rate limits, error conditions, or whether it's idempotent. For a tool with zero annotation coverage, this leaves significant gaps in understanding its behavior.

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

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

The description is front-loaded with the core purpose in the first sentence, followed by structured sections for Args and Returns. Each sentence earns its place by providing essential information without redundancy, making it efficient and well-organized.

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 no annotations and no output schema, the description does a decent job by explaining parameters and return values. However, it lacks details on behavioral aspects like error handling or authentication, and the return description ('Pipeline status including state, duration, and steps') is somewhat vague without an output schema. It's adequate but has clear gaps for a tool with 2 parameters and no structured support.

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

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

The description adds substantial meaning beyond the input schema, which has 0% description coverage. It explains that 'repo_slug' is a repository slug and 'pipeline_uuid' is a Pipeline UUID from 'trigger_pipeline', clarifying the source and purpose of both parameters. This compensates fully for the lack of 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 clearly states the specific action ('Get status') and resource ('pipeline run'), distinguishing it from sibling tools like 'list_pipelines' (which lists pipelines) and 'get_pipeline_logs' (which retrieves logs). It precisely defines the tool's function without being vague or tautological.

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

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

The description implies usage context by mentioning 'pipeline_uuid (from trigger_pipeline)', suggesting it should be used after triggering a pipeline. However, it does not explicitly state when to use this tool versus alternatives like 'list_pipelines' or 'stop_pipeline', nor does it provide exclusions or prerequisites beyond the implied UUID source.

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. It discloses the tool's conditional behavior (returns logs or steps list based on step_uuid), which is helpful. However, it lacks details on permissions, rate limits, error handling, or output format, leaving gaps for a mutation-like read operation.

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 well-structured and front-loaded with the core purpose, followed by clear sections for arguments and returns. Every sentence adds value without redundancy, making it efficient 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?

Given no annotations and no output schema, the description does a decent job but has gaps. It explains the tool's conditional behavior and parameters well, but doesn't cover return formats, error cases, or system constraints. For a tool with 3 parameters and conditional outputs, more completeness would be beneficial.

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

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

The description adds significant meaning beyond the input schema, which has 0% description coverage. It explains each parameter's role: repo_slug and pipeline_uuid as required identifiers, and step_uuid as optional with guidance to 'get from steps list first.' This fully compensates for the schema's lack of 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 tool's purpose: 'Get logs for a pipeline run.' It specifies the resource (pipeline logs) and the action (get). However, it doesn't explicitly differentiate from sibling tools like 'get_pipeline' or 'list_pipelines', which reduces it from a perfect score.

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

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

The description provides clear usage guidance: 'If step_uuid is not provided, returns list of steps to choose from.' This explains when to use it with or without the optional parameter. It doesn't mention alternatives or exclusions, but the context is well-defined.

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. It discloses that it returns 'Variable details including key, secured status, and value (if not secured)', which adds some behavioral context about the output. However, it lacks details on permissions required, error conditions, rate limits, or whether it's a read-only operation (implied by 'Get' but not explicit). For a tool with no annotations, this is a significant gap in transparency.

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

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

The description is appropriately sized and front-loaded: the first sentence states the purpose clearly, followed by structured 'Args' and 'Returns' sections. Every sentence earns its place by adding necessary information, though the structure could be slightly more streamlined (e.g., integrating the explanation into a single paragraph).

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 no annotations and no output schema, the description provides basic purpose, parameter semantics, and return value details. However, for a tool with 2 parameters and no structured safety or output information, it lacks completeness in areas like error handling, authentication needs, or behavioral nuances. It's adequate but has clear gaps for a read operation in a complex system.

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 adds meaning by explaining 'repo_slug' as 'Repository slug' and 'variable_uuid' as 'Variable UUID (from list_pipeline_variables)', clarifying the source and purpose of parameters beyond the schema's basic titles. This effectively documents both parameters, though it could provide more context on format or constraints.

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: 'Get details about a specific pipeline variable.' It specifies the verb 'Get' and resource 'pipeline variable', making it distinct from siblings like 'list_pipeline_variables' (which lists multiple) or 'create_pipeline_variable' (which creates). However, it doesn't explicitly differentiate from siblings like 'update_pipeline_variable' or 'delete_pipeline_variable' in terms of action specificity.

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 by referencing 'variable_uuid: Variable UUID (from list_pipeline_variables)', suggesting this tool should be used after listing variables to get details for a specific one. However, it doesn't provide explicit guidance on when to use this versus alternatives (e.g., no comparison to 'list_pipeline_variables' for bulk details or other get_* tools for different resources), leaving some context 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?

No annotations are provided, so the description carries full burden. It states the tool returns 'Diff content as text' which adds some behavioral context about output format. However, it doesn't disclose important traits like whether this is a read-only operation, authentication requirements, rate limits, error conditions, or pagination behavior for large diffs.

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 appropriately sized with three sentences that each serve a purpose: stating the tool's purpose, listing parameters, and describing the return value. It's front-loaded with the core functionality. Minor improvement could be made by combining the parameter documentation into a more structured format.

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 2 parameters with 0% schema coverage and no output schema, the description provides basic parameter documentation and return format. However, for a tool that fetches potentially complex diff data, it lacks details about diff format specifics, size limitations, error handling, and authentication requirements that would be needed for robust usage.

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

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

Schema description coverage is 0%, so the description must compensate. It documents both parameters ('repo_slug' and 'pr_id') with brief explanations, adding meaning beyond the bare schema. However, it doesn't provide format details (e.g., what constitutes a valid repo_slug), examples, or constraints, leaving gaps in parameter understanding.

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

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

The description clearly states the tool's purpose with a specific verb ('Get') and resource ('diff of a pull request'). It distinguishes from siblings like 'get_pull_request' by focusing on the diff content rather than general PR information. However, it doesn't explicitly contrast with 'compare_commits' which might also provide diff-like functionality.

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

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

No guidance is provided about when to use this tool versus alternatives. The description doesn't mention prerequisites, appropriate contexts, or comparisons to sibling tools like 'get_pull_request' (for general PR info) or 'compare_commits' (for commit diffs). Usage is implied but 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?

No annotations are provided, so the description carries the full burden. It states it 'Get[s] information,' implying a read-only operation, but does not disclose behavioral traits such as authentication requirements, rate limits, error handling, or what happens if the project does not exist. This is inadequate 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?

The description is appropriately sized and front-loaded with the core purpose. The 'Args' and 'Returns' sections are structured clearly, though the 'Returns' section could be more concise by omitting redundant phrasing like 'Project info including'.

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

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

Given the tool's low complexity (1 parameter, no output schema, no annotations), the description is minimally adequate. It covers the purpose and parameter semantics but lacks usage guidelines and behavioral details, making it incomplete for optimal agent use.

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

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

The description adds meaningful context for the single parameter: it explains that 'project_key' is a key like 'DS' or 'PROJ,' which is not covered in the schema (0% coverage). This compensates well for the lack of schema descriptions, though it could specify format constraints more explicitly.

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: 'Get information about a specific project.' It specifies the verb ('Get') and resource ('project'), but does not explicitly differentiate it from sibling tools like 'list_projects' or 'get_repository', which would require a 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 description provides no guidance on when to use this tool versus alternatives. It does not mention sibling tools like 'list_projects' for listing all projects or 'get_repository' for repository-specific details, leaving the agent without context for 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?

No annotations are provided, so the description carries the full burden. It states it 'Get[s] information' and returns 'PR info', implying a read-only operation, but doesn't disclose behavioral traits like authentication needs, rate limits, error handling, or pagination. For a tool with no annotations, this is a significant gap in transparency about how it behaves beyond basic functionality.

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 appropriately sized and front-loaded: the first sentence states the purpose clearly, followed by structured sections for args and returns. There's no wasted text, and each sentence adds value. However, the structure could be more integrated (e.g., combining purpose with usage) for optimal flow.

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 no annotations, no output schema, and low schema coverage, the description is minimally complete. It covers the basic purpose and parameters but lacks behavioral context, usage guidelines, and detailed return values (only high-level info like 'state, author, reviewers, and merge status'). For a simple read tool, it's adequate but has clear gaps in providing a full picture for an AI agent.

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 schema provides no parameter details. The description adds minimal semantics by listing args ('repo_slug', 'pr_id') and their purpose ('Repository slug', 'Pull request ID'), but doesn't explain format (e.g., string patterns for repo_slug) or constraints. It compensates slightly but not fully for the low coverage, aligning with the baseline for partial compensation.

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

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

The description clearly states the tool's purpose as 'Get information about a pull request' with a specific verb ('Get') and resource ('pull request'). It distinguishes itself from siblings like 'list_pull_requests' (which lists multiple) and 'get_pr_diff' (which gets diff content), though not explicitly. However, it doesn't fully differentiate from 'get_commit' or 'get_branch' in terms of resource type, which slightly limits clarity.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention siblings like 'list_pull_requests' for multiple PRs or 'get_pr_diff' for diff details, nor does it specify prerequisites or contexts (e.g., after listing PRs). Usage is implied by the name but not explicitly stated, leaving gaps for an AI agent.

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. It states this is a 'Get' operation, implying read-only behavior, but doesn't disclose any behavioral traits like authentication requirements, rate limits, error conditions, or response format details. For a tool with no annotation coverage, this leaves significant gaps in understanding how it behaves.

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

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

The description is well-structured and front-loaded, starting with the core purpose, followed by clear sections for Args and Returns. Every sentence adds value without redundancy, making it efficient 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?

Given the tool's low complexity (1 parameter, no nested objects) and lack of annotations or output schema, the description is minimally adequate. It covers the purpose and parameter semantics but lacks behavioral details and usage guidelines, leaving room for improvement in completeness.

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

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

The description adds meaningful context for the single parameter 'repo_slug' by explaining it's a 'Repository slug' and providing an example ('anzsic_classifier'). With schema description coverage at 0%, this compensates well by clarifying what the parameter represents, though it doesn't detail constraints like format or length.

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: 'Get information about a Bitbucket repository.' It specifies the verb ('Get') and resource ('Bitbucket repository'), making it easy to understand what the tool does. However, it doesn't explicitly differentiate from sibling tools like 'get_project' or 'list_repositories', which would require a 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 description provides no guidance on when to use this tool versus alternatives. It doesn't mention when to choose 'get_repository' over 'list_repositories' for a single repo, or 'get_project' for project-level info. Without such context, the agent lacks clear usage instructions.

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 discloses the return value ('full target hash') and that it avoids page scanning, but says nothing about authentication, behavior when the tag is missing, or whether the hash is a commit or annotated tag object.

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 tightly written sentence with the key differentiator ('without scanning pages') and the return value front-loaded. No wasted words.

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?

Return value is covered despite no output schema, and the exact-match semantics of tag_name are stated. Missing are error behavior for nonexistent tags and any explanation of repo_slug, which leaves a two-parameter tool under-documented.

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 for both parameters. It adds only that tag_name must be an exact name; repo_slug is left completely unexplained, as is whether the slug is owner/repo or a numeric ID.

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

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

States a specific verb and resource: resolves an exact tag name and returns the full target hash. This implicitly distinguishes it from list_tags (which scans pages) and from create_tag/delete_tag, but it does not explicitly name any sibling.

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?

'Without scanning pages' implies you should use this when you already know the exact tag name, as an alternative to paginating list_tags. However, it never states the condition explicitly or names the alternative, so the agent must infer it.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the return value ('User's permission level') but doesn't specify what that level entails (e.g., read, write, admin), whether it's a read-only operation, or any error conditions. This leaves significant gaps for a tool that retrieves permission data.

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 efficiently structured with a clear purpose statement followed by bullet points for arguments and returns. Every sentence adds value without redundancy, making it easy to scan and understand quickly.

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

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

Given the tool's moderate complexity (2 parameters, no output schema, no annotations), the description covers the basics but lacks depth. It explains parameters well and states the return type, but doesn't detail the permission level format or potential errors, leaving room for improvement in behavioral context.

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

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

The description adds meaningful context for both parameters beyond the schema's 0% coverage: 'repo_slug' is explained as 'Repository slug' and 'selected_user' as 'User's account_id or UUID'. This clarifies the expected format and purpose of each parameter, compensating well for the lack of 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 clearly states the tool's purpose with a specific verb ('Get') and resource ('user's permission for a repository'), making it easy to understand what it does. However, it doesn't explicitly differentiate from its sibling 'list_user_permissions' or 'get_group_permission', which would be needed for a perfect score.

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

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

The description provides no guidance on when to use this tool versus alternatives like 'list_user_permissions' or 'get_group_permission'. It simply states what the tool does without context about appropriate use cases or prerequisites.

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

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

No annotations are provided, so the description carries the full burden. It states the tool retrieves details but doesn't disclose behavioral traits like authentication needs, rate limits, error handling, or whether it's read-only. While 'Get details' implies a read operation, it lacks confirmation and additional context, leaving gaps in transparency.

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

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

The description is appropriately sized and front-loaded, starting with the core purpose. The Args and Returns sections are structured clearly, but the 'Returns' part could be more concise by integrating it into the main sentence. Overall, it's efficient with minimal 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 complexity (2 parameters, no annotations, no output schema), the description is moderately complete. It covers the purpose and parameters but lacks details on return values (only mentions 'including URL, events, and status' without full structure) and behavioral aspects. For a tool with no structured support, it should provide more comprehensive guidance.

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

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

The description adds meaningful semantics beyond the input schema, which has 0% description coverage. It explains that 'repo_slug' is a 'Repository slug' and 'webhook_uuid' is a 'Webhook UUID (from list_webhooks)', providing context and source for the UUID. This compensates well for the low schema coverage, though it could detail format constraints.

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: 'Get details about a specific webhook.' It specifies the verb ('Get details') and resource ('a specific webhook'), making it easy to understand. However, it doesn't explicitly differentiate from sibling tools like 'list_webhooks' beyond mentioning the UUID source, missing full sibling distinction.

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 by noting that the 'webhook_uuid' comes from 'list_webhooks', suggesting a workflow. However, it doesn't provide explicit guidance on when to use this tool versus alternatives (e.g., 'list_webhooks' for multiple webhooks or other get_* tools), leaving some ambiguity.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the return format ('List of branches with commit info'), which is helpful, but lacks critical details like pagination behavior (beyond the limit parameter), authentication requirements, rate limits, error conditions, or whether results are sorted/filtered.

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 efficiently structured with clear sections (Args, Returns) and uses minimal, purposeful sentences. Every line adds value—no redundant or verbose phrasing—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 read-only list tool with 2 parameters and no output schema, the description covers the basics (purpose, parameters, return format) but lacks depth. Without annotations, it should ideally include more behavioral context (e.g., pagination, auth). The return format hint is helpful, but overall completeness is adequate yet minimal.

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

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

The description explicitly documents both parameters ('repo_slug' and 'limit') with brief explanations, including the default value for 'limit'. Since schema description coverage is 0%, this adds significant value beyond the bare schema, though it doesn't elaborate on format details (e.g., what a 'repository slug' entails).

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

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

The description clearly states the verb ('List') and resource ('branches in a repository'), making the purpose immediately understandable. However, it doesn't differentiate from similar sibling tools like 'list_repositories' or 'list_tags', which follow the same pattern for different resources.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'get_branch' (for single branch details) or 'list_commits' (for commits within branches), leaving the agent to infer usage context from the tool name alone.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the return format ('List of branch restrictions with kind, pattern, and settings'), which adds some context, but fails to address critical aspects like pagination (implied by 'limit'), authentication needs, error conditions, or rate limits. For a read operation with zero annotation coverage, this is insufficient.

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 well-structured and front-loaded, with a clear purpose statement followed by concise sections for arguments and returns. Every sentence earns its place by providing essential information without redundancy, making it efficient 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?

Given the tool's moderate complexity (2 parameters, no output schema, no annotations), the description is partially complete. It covers the purpose, parameters, and return structure adequately, but lacks behavioral details (e.g., authentication, errors) and usage guidelines. Without annotations or output schema, it should do more to compensate, resulting in an average score.

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

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

The description adds meaningful semantics beyond the input schema, which has 0% description coverage. It explains that 'repo_slug' identifies the repository and 'limit' controls the maximum number of results with a default of 50, clarifying their roles. However, it doesn't detail format constraints (e.g., slug syntax) or the effect of 'limit' on pagination, leaving minor 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 clearly states the verb ('List') and resource ('branch restrictions (protection rules) in a repository'), making the purpose specific and understandable. It distinguishes from siblings like 'create_branch_restriction' and 'delete_branch_restriction' by focusing on listing rather than modifying. However, it doesn't explicitly differentiate from other list tools (e.g., 'list_branches'), which prevents a perfect score.

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

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

No guidance is provided on when to use this tool versus alternatives. The description lacks context about prerequisites (e.g., repository access), exclusions, or comparisons with similar tools like 'list_branches' or 'get_branch'. This omission leaves the agent without clear usage direction.

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 present, the description carries the full load and does it well: it discloses ordering, pagination rules (cursor preserves filters and page size; limit and filters apply only to the first page), and an important caution that absence from one page is not absence from repository history. It doesn't state auth/permission requirements, which keeps it from a 5.

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?

Front-loaded with purpose and the most surprising semantics (reachability filtering) early, and every sentence adds information. It is dense to the point that pagination rules read as a run-on, but no sentence is expendable.

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 7-parameter read tool with no annotations and no output schema, the description covers filtering semantics, ordering, and pagination behavior, and incidentally reveals the next_cursor/has_more response fields. It stops short of describing commit record contents, but nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 0%, so the description must compensate and largely does: it defines include, exclude, branch (as an include alias), path, cursor, and limit with a valid range of 1-100, plus the next_cursor/has_more loop. Only repo_slug is left implicit, which is a reasonable omission given it is required and self-named.

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

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

States a specific verb and resource ("List a page of commits"), plus ordering ("newest first") and a distinguishing trait ("without cloning"). This clearly separates it from get_commit (single commit) and compare_commits (diff between revisions) without needing to name them.

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

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

Explains the include/exclude reachability model with a concrete worked example (include=["v2"], exclude=["v1"]) and clarifies that branch is an alias for include and path scopes to a file/directory. It does not say when to prefer compare_commits or get_commit_diff instead, but the usage context for this tool is clear.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool retrieves data ('Get'), implying a read-only operation, but doesn't clarify permissions, rate limits, pagination (beyond the 'limit' parameter), or error conditions. The return format is briefly described but lacks details on structure or potential edge cases, leaving significant gaps for a tool with no annotation coverage.

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

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

The description is well-structured and appropriately sized, with a clear purpose statement followed by parameter and return sections. Every sentence adds value, and there's no redundant information. However, it could be slightly more front-loaded by integrating key parameter details into the opening sentence for faster scanning.

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

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

Given the tool's moderate complexity (3 parameters, no annotations, no output schema), the description is adequate but incomplete. It covers the purpose and parameters reasonably well but lacks behavioral context (e.g., safety, performance) and detailed return format. Without annotations or output schema, more guidance on error handling or result interpretation would improve completeness for a read 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?

The description adds meaningful semantics beyond the input schema, which has 0% description coverage. It explains that 'repo_slug' is a repository slug, 'environment_uuid' comes from 'list_environments', and 'limit' defaults to 20 and controls result count. This compensates well for the schema's lack of descriptions, though it doesn't detail format constraints (e.g., UUID structure) or validation rules.

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: 'Get deployment history for a specific environment.' It specifies the verb ('Get') and resource ('deployment history'), and distinguishes it from siblings like 'list_environments' by focusing on deployment history rather than environments themselves. However, it doesn't explicitly differentiate from other list tools like 'list_pipelines' or 'list_commits' beyond the resource name.

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

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

The description provides implied usage context by mentioning that 'environment_uuid' comes from 'list_environments', suggesting a workflow dependency. However, it lacks explicit guidance on when to use this tool versus alternatives (e.g., 'list_pipelines' for pipeline history or 'get_commit' for commit details), and doesn't specify prerequisites or exclusions beyond the parameter hints.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure. It adequately describes the core behavior (listing directory contents) and mentions the 'without cloning' constraint, which is useful context. However, it doesn't disclose important behavioral traits like whether this is a read-only operation (implied but not stated), potential rate limits, authentication requirements, error conditions, or pagination behavior beyond the 'limit' parameter.

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 perfectly structured and concise. It begins with the core purpose, adds important context in the second sentence, then provides well-organized parameter and return value documentation. Every sentence earns its place, with no wasted words or redundant information.

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

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

Given the tool's moderate complexity (4 parameters, no output schema, no annotations), the description is quite complete. It covers purpose, usage context, all parameters with semantics, and return value format. The main gap is the lack of output schema, so the description must describe returns - which it does adequately but could benefit from more detail about the structure of the returned list.

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

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

The description provides excellent parameter semantics despite 0% schema description coverage. It clearly explains all 4 parameters: 'repo_slug' (Repository slug), 'path' (Directory path with special case for root), 'ref' (Branch/tag/commit with default), and 'limit' (Maximum entries with default). This fully compensates for the lack of schema descriptions and adds meaningful context beyond just parameter names.

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 with specific verbs ('List contents', 'Browse repository structure') and resources ('directory in a repository'). It distinguishes itself from siblings like 'get_file_content' by focusing on directory listing rather than file content retrieval, and from 'list_repositories' by operating within a specific repository's directory structure.

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

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

The description provides clear context about when to use this tool ('Browse repository structure without cloning'), which implicitly suggests it's for exploration rather than file operations. However, it doesn't explicitly state when NOT to use it or name specific alternatives among the many sibling tools (like 'get_file_content' for individual files or 'list_repositories' for repository-level listing).

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. It mentions the tool lists environments but doesn't disclose behavioral traits such as whether it's read-only (implied by 'List' but not explicit), pagination behavior, rate limits, authentication needs, or error handling. The description is minimal and lacks crucial operational context.

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

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

The description is appropriately sized and front-loaded, starting with the core purpose followed by parameter and return details in a structured format. Every sentence adds value, with no wasted words, though it could be slightly more detailed without losing conciseness.

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 complexity (a simple list operation with 2 parameters), no annotations, and no output schema, the description is minimally complete. It covers the purpose, parameters, and return type, but lacks behavioral context and usage guidelines, making it adequate but with clear gaps for effective tool selection.

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 0%, so the description must compensate. It adds meaning by explaining 'repo_slug' as 'Repository slug' and 'limit' with its default value, which clarifies beyond the bare schema. However, it doesn't detail parameter formats (e.g., what a 'repo_slug' looks like) or constraints, 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?

The description clearly states the verb ('List') and resource ('deployment environments for a repository'), making the purpose specific and understandable. However, it doesn't explicitly differentiate from sibling tools like 'get_environment' (singular) or 'list_deployment_history', which might be related but 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?

No guidance is provided on when to use this tool versus alternatives. For example, it doesn't mention when to choose 'list_environments' over 'get_environment' (which fetches a single environment) or 'list_deployment_history' (which might include environment-related data). The description only states what it does, not when it's appropriate.

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 states it's a list operation, implying read-only behavior, but doesn't mention critical details like pagination (only a limit parameter), authentication requirements, rate limits, or error conditions. This leaves significant gaps for an AI agent to understand how to use it effectively.

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 well-structured and front-loaded with the core purpose, followed by clear sections for Args and Returns. Every sentence earns its place by providing essential information without redundancy, making it easy to parse quickly.

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

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

Given the tool's moderate complexity (2 parameters, no output schema, no annotations), the description is adequate but incomplete. It covers the basic purpose and parameters but lacks behavioral details (e.g., pagination, auth) and usage guidelines. Without annotations or output schema, it should do more to compensate, but it meets a minimum viable standard.

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

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

The description adds meaningful context beyond the input schema, which has 0% description coverage. It explains that 'repo_slug' identifies the repository and 'limit' controls the maximum results with a default of 50, clarifying their roles. However, it doesn't detail format constraints (e.g., slug syntax) or that 'limit' is optional due to the default, though the schema indicates this.

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 with a specific verb ('List') and resource ('group permissions for a repository'), making it immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'list_user_permissions' or 'get_group_permission', which would require mentioning it's specifically for groups (not users) and listing (not getting a single permission).

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'list_user_permissions' for user permissions or 'get_group_permission' for a specific group's permission, nor does it specify prerequisites or exclusions (e.g., requires repository access).

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 behavioral disclosure. It mentions the tool lists 'recent' pipeline runs, implying a time-based filter, but does not specify what 'recent' means (e.g., time range, ordering). It also lacks details on permissions, rate limits, pagination, or error handling, which are important for a read operation with no annotation coverage.

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

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

The description is well-structured and concise, with a clear purpose statement followed by Args and Returns sections. Each sentence earns its place by providing essential information without redundancy. It is appropriately sized for a simple list 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?

Given the tool's low complexity (2 parameters, no output schema, no annotations), the description is minimally adequate. It covers the basic purpose and parameters but lacks behavioral details like ordering, time range for 'recent', or error cases. Without annotations or output schema, more context would improve completeness for safe agent use.

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

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

The description adds meaningful semantics beyond the input schema, which has 0% description coverage. It explains that 'repo_slug' is a 'Repository slug' and 'limit' is the 'Maximum number of results (default: 10)', clarifying purpose and default values. However, it does not detail format constraints (e.g., slug syntax) or behavioral effects (e.g., how limit affects ordering), preventing a score of 5.

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: 'List recent pipeline runs for a repository.' It specifies the verb ('List'), resource ('pipeline runs'), and scope ('for a repository'). However, it does not explicitly differentiate from sibling tools like 'get_pipeline' or 'list_pipeline_variables', which reduces the score from a 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 description provides no guidance on when to use this tool versus alternatives. It does not mention sibling tools like 'get_pipeline' (for a specific pipeline) or 'list_pipeline_variables', nor does it specify prerequisites or exclusions. Usage is implied by the purpose but 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the return format ('List of pipeline variables with key, secured status, and value'), which adds some context. However, it lacks critical details like whether this is a read-only operation, if it requires authentication, pagination behavior beyond the 'limit' parameter, or error conditions. For a list operation with zero annotation coverage, this is insufficient.

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 well-structured and front-loaded with the core purpose, followed by parameter and return details. Every sentence earns its place: the first states the action, the 'Args' section clarifies inputs, and the 'Returns' section explains outputs. It's appropriately sized with zero 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 tool's moderate complexity (2 parameters, no annotations, no output schema), the description covers the basics: purpose, parameters, and return format. However, it lacks behavioral context (e.g., safety, pagination) and doesn't reference sibling tools. For a list operation, this is adequate but leaves gaps that could hinder agent effectiveness.

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

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

The description includes an 'Args' section that documents both parameters ('repo_slug' and 'limit') with brief explanations, adding meaning beyond the input schema (which has 0% description coverage). However, it doesn't elaborate on format (e.g., what a 'repository slug' is) or constraints (e.g., 'limit' range). With schema coverage low, the description compensates partially but not fully.

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: 'List pipeline variables for a repository.' It specifies the verb ('List') and resource ('pipeline variables') with scope ('for a repository'), making it unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'get_pipeline_variable' (singular) or 'create_pipeline_variable', though the plural vs. singular naming provides implicit distinction.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'get_pipeline_variable' (for a single variable) or 'create_pipeline_variable', nor does it specify prerequisites or contextual constraints. The agent must infer usage from the name and description alone.

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

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

No annotations are provided, so the description carries the full burden. It mentions the tool lists comments with author, content, and timestamps, but lacks details on permissions, rate limits, pagination (beyond the limit parameter), error handling, or whether it's read-only. For a tool with no annotations, this leaves significant behavioral gaps.

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 well-structured and front-loaded with the core purpose, followed by parameter and return details. It uses minimal sentences efficiently, though the 'Args' and 'Returns' sections could be integrated more seamlessly into prose.

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 no annotations and no output schema, the description covers the basic purpose and parameters adequately but lacks behavioral context like safety, performance, or error details. It's complete enough for a simple read operation but misses nuances that would help an agent use it effectively in complex scenarios.

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 all three parameters: 'repo_slug' (Repository slug), 'pr_id' (Pull request ID), and 'limit' (Maximum number of results with default). This adds clear meaning beyond the bare schema, though it could specify format details like slug structure.

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 specific action ('List comments') and resource ('on a pull request'), distinguishing it from sibling tools like 'get_pull_request' or 'add_pr_comment' which have different purposes. It precisely identifies what the tool does without being vague or tautological.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'get_pull_request' (which might include comments) or 'list_pull_requests', nor does it specify prerequisites or contextual constraints. Usage is implied but 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?

No annotations are provided, so the description carries full burden. It mentions a default limit and return format, but lacks details on pagination, error handling, permissions, rate limits, or whether it's read-only. For a list tool with zero annotation coverage, this is insufficient behavioral disclosure.

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 well-structured with clear sections (Args, Returns) and uses only three sentences with zero waste. It's front-loaded with the core purpose and efficiently covers key details without redundancy.

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

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

Given no annotations, no output schema, and low schema coverage, the description is minimally adequate. It covers purpose, parameter, and return format, but lacks behavioral context (e.g., pagination, errors) and usage guidelines, leaving gaps for a list operation in a complex API with many siblings.

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 documents the single parameter 'limit' with its default value, adding meaning beyond the bare schema. However, it doesn't explain constraints (e.g., min/max values) or usage context, keeping it from a perfect score.

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

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

The description clearly states the verb 'List' and resource 'projects in the workspace', making the purpose explicit. However, it doesn't differentiate from sibling tools like 'list_repositories' or 'list_pull_requests', which follow the same pattern, so it lacks sibling distinction for a perfect score.

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

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

The description provides no guidance on when to use this tool versus alternatives. There are many sibling list tools (e.g., list_repositories, list_pull_requests), but no indication of context, prerequisites, or exclusions for selecting this specific 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions filtering by state and pagination via 'limit', but doesn't describe the return format (e.g., what 'basic info' includes), whether results are sorted, authentication requirements, rate limits, or error conditions. For a list tool with no annotation coverage, this leaves significant gaps in understanding its behavior.

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

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

The description is appropriately sized and front-loaded: the first sentence states the purpose clearly, followed by a structured breakdown of args and returns. Every sentence adds value without redundancy, making it efficient 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?

Given the tool's moderate complexity (3 parameters, no output schema, no annotations), the description is partially complete. It covers parameters well but lacks details on return values (e.g., structure of 'basic info'), behavioral aspects like sorting or pagination, and context for usage among siblings. This leaves room for improvement in guiding an AI agent effectively.

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

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

The description adds meaningful semantics beyond the input schema, which has 0% description coverage. It explains 'repo_slug' as 'Repository slug', 'state' with allowed values and default, and 'limit' with default and max values. This compensates well for the schema's lack of descriptions, though it doesn't detail 'repo_slug' format (e.g., 'owner/repo') or 'limit' constraints beyond max.

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: 'List pull requests in a repository.' It specifies the verb ('List') and resource ('pull requests'), and distinguishes it from siblings like 'get_pull_request' (singular) and 'list_pr_comments' (comments only). However, it doesn't explicitly differentiate from 'list_repositories' or other list tools beyond 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 provides no guidance on when to use this tool versus alternatives. It doesn't mention siblings like 'get_pull_request' (for a single PR), 'list_pr_comments' (for PR comments), or 'list_repositories' (for repositories instead of PRs). There's no context about prerequisites, such as needing repository access, or when filtering by state is appropriate.

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 adds useful context like fuzzy matching for 'search', advanced query syntax examples for 'query', and default/max values for 'limit'. However, it doesn't cover important aspects like pagination behavior, rate limits, authentication requirements, or error handling, leaving gaps for a tool with search/list functionality.

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 well-structured with clear sections for Args and Returns, and each sentence adds value. It's appropriately sized for a tool with 4 parameters and search functionality, though the 'query' examples could be slightly more concise. The purpose statement is front-loaded, making it easy to understand quickly.

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

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

Given the tool's complexity (search/list with 4 parameters), no annotations, and no output schema, the description is moderately complete. It covers parameter semantics well but lacks details on behavioral aspects like pagination, rate limits, or authentication. The return value description ('List of repositories with basic info') is vague without an output schema, leaving uncertainty about what 'basic info' 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?

The description provides extensive parameter semantics beyond the input schema, which has 0% description coverage. It explains optional filtering with 'project_key', details fuzzy matching for 'search', gives multiple examples for 'query' syntax, and specifies default and maximum values for 'limit'. This fully compensates for the schema's lack of 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 tool's purpose as 'List and search repositories in the workspace,' which includes both listing and searching functionality. It distinguishes itself from siblings like 'get_repository' (singular) and 'list_projects' (different resource), but could be more explicit about how it differs from other list/search tools like 'list_pull_requests' or 'list_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 through parameter explanations (e.g., 'search' for fuzzy matching, 'query' for advanced syntax), but lacks explicit guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, such as needing workspace access, or compare it to similar tools like 'list_projects' or 'get_repository' for specific use cases.

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

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

With no annotations, the description carries the full burden and does well: it discloses pagination behavior (follow next_cursor until has_more is false), cursor semantics (retains filters and page size), and a non-obvious caveat that target date is not tag creation date or ancestry proof. It omits auth requirements or rate-limit behavior, but the core behavioral traits are well covered.

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