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

With no annotations, the description carries the transparency burden. It discloses that content is 'publicly visible' and requires explicit user approval, which is crucial behavioral context. It also explains the three comment modes. It lacks details about errors or auth, but the key public side-effect is clearly stated.

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

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

The description is three sentences, front-loaded with a critical warning, then a clear purpose, then the mode breakdown. Every sentence adds value with no redundancy or fluff.

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 8 parameters, 3 modes, and no output schema, the description covers all usage variants and the key approval constraint. It doesn't explain return values or error handling, but the schema covers parameter details and the mode explanations sufficiently address 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?

Although the schema already provides 100% parameter descriptions, the description adds meaningful semantic grouping: general mode (only content), inline mode (file_path + line with line_type), and reply mode (parent_id). This relational understanding goes beyond what the schema individually 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 tool's function: 'Post a comment on a pull request.' It specifies the resource (pull request comment) and the verb (post/create), and the three modes further clarify exactly what the tool does, distinguishing it from sibling list/get tools.

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

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

The description provides strong usage guidance: 'do NOT call this tool unless the user has explicitly approved the exact comment text' sets a critical precondition, and the three-mode explanation tells when to use different parameter combinations. However, it does not explicitly name sibling tools as alternatives for reading comments.

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

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

No annotations are provided, so the description must carry transparency. It discloses that the tool returns raw content and supports branch/tag/commit refs, but does not mention error handling, size limits, or whether binary content is encoded. The read-only nature is implied by 'get' but not explicitly stated.

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

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

Two short sentences—first defines the action, second gives a concrete use case. No wasted words; the front-loaded verb 'Get' makes it immediately clear.

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

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

The description covers the tool's purpose, ref types, and a practical review scenario. While there is no output schema, 'raw content' sufficiently implies the response body, though it does not specify encoding or error cases—minor gaps for a simple getter.

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

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

The input schema already describes all four parameters with 100% coverage, so the description adds little beyond the schema. It reaffirms 'raw content' and ref types, which are also in parameter 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 action ('Get the raw content of a file') and specifies the ref parameter (branch, tag, commit). This distinguishes it from sibling tools focused on pull request metadata, diffs, and comments.

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

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

The description explicitly notes it is useful for seeing full context beyond diff hunks during a review, guiding the agent to use this tool when a diff is insufficient. It does not list exclusions or alternative tools by name, but the context is clear.

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

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

With no annotations provided, the description must carry the behavioral transparency burden. It outlines the output scope (metadata fields) but does not disclose authentication needs, failure behavior, or explicitly confirm read-only semantics beyond the verb 'Get'. It is adequate but not rich.

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

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

The description is a single sentence that front-loads the purpose and lists the included metadata. Every word contributes to understanding the tool's function; there is no unnecessary filler.

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

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

The tool has only 3 parameters with full schema coverage and no output schema, so the description's listing of return fields compensates for missing output schema. It does not mention error cases or workspace usage, but for a straightforward GET operation, this is reasonably complete.

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

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

The input schema has 100% description coverage for all three parameters (repo, pr_id, workspace), so the baseline is 3. The description adds no parameter-specific meaning beyond what the schema already 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 uses a specific verb and resource ('Get full metadata of a pull request') and lists the exact fields returned (title, description, author, branches, state, reviewers). This distinguishes it clearly from sibling tools like get_pull_request_diff or list_pull_request_comments.

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

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

The description implies its use for retrieving pull request metadata, but it does not explicitly state when to use this tool versus alternatives or provide exclusions. Sibling tools are not referenced, leaving usage to be inferred from the purpose statement.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It mentions the output is a unified diff as plain text, which conveys a read-only, text-returning behavior. However, it does not disclose potential size limits, error behavior, or required permissions, leaving the agent with incomplete behavioral context.

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

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

The description is a single, front-loaded sentence. Every phrase earns its place: the verb-resource pair specifies the operation, 'as plain text' clarifies the return format, and the second sentence provides useful usage context without fluff.

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

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

For a simple, read-only diff-fetching tool, the description is largely complete: it names the tool's purpose, output format, and primary use case. It lacks details about pagination, diff size limits, or error scenarios, but these are not essential for basic invocation and the input schema fully covers parameters.

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

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

Schema description coverage is 100%, with all parameters documented in the input schema. The description adds no parameter-specific meaning beyond the schema, so the baseline score applies.

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

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

The description clearly states a specific action ('Get the unified diff') and resource ('pull request'), and notes the output is plain text. It is distinct from sibling tools like get_pull_request, which presumably returns metadata, and get_file_content, which targets a single file.

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

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

The phrase 'This is the primary input for a code review' provides clear context for when the tool is appropriate. It does not explicitly name alternatives or exclusions, but the intended use case is well implied.

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

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

With no annotations provided, the description carries the transparency burden. It adds useful behavioral details such as pagination ('Paginated; `next_page` is set when more results exist') and the inclusion of general and inline comments. However, it does not explicitly confirm that the operation is read-only, nor does it describe sorting or error 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 three sentences, all of which are relevant: main action, usage guidance, and pagination behavior. It is front-loaded with the purpose and contains no filler.

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

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

The description covers purpose, usage, and pagination for a list tool with 5 parameters (fully schema-documented) and no output schema. It could be more complete by describing the return structure, but the information provided is sufficient for basic invocation and understanding.

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

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

Schema description coverage is 100%, and the description adds no parameter-specific meaning beyond what the schema provides. The pagination mention relates to page/pagelen but does not add new syntax or format details.

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

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

The description clearly states the tool's function: 'List the comments of a pull request (general and inline)'. This is a specific verb and resource, and it distinguishes itself from sibling tools like list_pull_requests, get_pull_request_diff, and create_pull_request_comment.

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

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

The description provides a clear usage context: 'Use it before posting review comments to avoid repeating observations already made.' This tells the agent when to use the tool, but it does not explicitly name alternatives or state when not to use 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, the description carries the burden. It discloses pagination via `next_page`, the summary fields returned, and the default state behavior. It does not explicitly state it is read-only, but the 'List' and 'Returns a summary' wording implies a non-mutating 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?

Two sentences, front-loaded with the main purpose, followed by concrete details. No redundant or vague wording.

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

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

The description covers the core behavior, return summary, and pagination. It does not mention auth requirements or error behavior, but these are less critical for a list operation. The schema covers parameter details, so the description is adequate.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats the default OPEN state (already in schema) and mentions pagination but does not add new detail about page or pagelen beyond what the 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 verb 'List' and the resource 'pull requests of a repository', and includes the state filter. It is distinct from sibling tools like get_pull_request (singular) or list_pull_request_comments.

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

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

The description provides clear context for when to use this tool (listing PRs with optional state filtering) but does not explicitly mention alternatives or exclusions. The context is sufficient for an agent to distinguish it from siblings.

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