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

With no annotations provided, the description carries the full behavioral burden, yet it omits any mention of required permissions/token scopes, whether the comment is attributed to an authenticated user, rate limits, or what the response contains. For a write/mutation tool this is a significant gap beyond simply implying mutation.

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

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

A single front-loaded sentence with no wasted words. It is efficiently sized, though its brevity reflects under-specification rather than economy of rich content.

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

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

An output schema exists, so return values need not be explained. However, for a write tool with no annotations and no output-shape caveats, the description is thin on auth and behavioral context that an agent would want before commenting.

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

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

Schema description coverage is 100%, so all four parameters (body, repo, owner, issue_number) are already documented including the owner default. The description adds only the note that issue_number may refer to a PR, offering marginal value over the schema; baseline 3 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?

States a specific verb (Create) and resource (comment) with the target scope (GitHub issue or pull request). It is distinguishable from create_issue_tool and update_issue_tool, though it does not explicitly name how it differs from 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?

The description gives no when-to-use guidance, prerequisites, or alternatives. Nothing tells the agent when to reach for this over create_issue_tool or update_issue_tool.

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 behavioral burden. It never states that this is a mutating write, whether auth/permissions are required, or that labels/owner defaults apply; 'create' is the only behavioral signal given.

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

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

A single front-loaded sentence with zero waste. It is tight, though arguably too sparse for a mutation tool, which is a completeness issue rather than a conciseness one.

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 output schema covers return values and the schema fully documents all five parameters, so those burdens are lifted. What remains missing is any usage or behavioral context for a write operation, leaving the definition minimally viable.

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 every parameter (body, repo, owner, title, labels) is already documented in the schema, establishing the baseline of 3. The description adds no meaning beyond the schema, but nothing is missing either.

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 ('Create a new issue') plus the domain (GitHub repository), which distinguishes it from read siblings like get_issue_tool and list_issues_tool. It does not, however, explicitly differentiate from the closer siblings update_issue_tool and create_issue_comment_tool, 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?

The description offers no when-to-use context, no prerequisites, and no mention of alternatives such as create_issue_comment_tool for adding comments or update_issue_tool for edits. An agent must infer usage entirely from the name.

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 behavioral burden, yet it discloses nothing beyond the bare action. It does not state required authentication/scopes, whether the branch must already be pushed, or any side effects of creating a PR; only the implicit mutation is conveyed.

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 single sentence is clean and front-loaded with the core action, so it wastes no words. However, its brevity reflects under-specification rather than disciplined 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?

An output schema exists so return values need not be explained, but for a git-mutating tool with zero annotations and no guidance, the description is far too thin. It omits auth requirements, branch prerequisites, and how it relates to the update/merge 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 100%, so all 7 parameters (including head/base/owner semantics) are already documented in the schema. The description adds nothing on top of that, so the baseline 3 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 gives a specific verb ('Open') and resource ('GitHub pull request'), so an agent knows exactly what action is performed. It does not, however, differentiate itself from siblings like update_pull_request_tool or merge_pull_request_tool, which also act 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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as update_pull_request_tool or merge_pull_request_tool. The agent must infer usage purely from the name and sibling list.

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, and it delivers the two most important behavioral facts: the tag is created if missing, and publishing (draft=false) triggers the repository's on:release workflows. It omits auth/permission prerequisites and reversibility, but the side-effect disclosure is genuinely valuable.

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 core action, and the second sentence conveys a high-value consequence without waste. Every sentence earns its place.

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

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

An output schema exists so return values need no explanation, and the description covers the operation and its main side effect for a 9-param mutation tool with zero annotations. Slightly incomplete on permissions/auth context, but otherwise sufficient.

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

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

Schema description coverage is 100%, so the schema already documents all 9 parameters, and the default for draft is defined there. The description reinforces the draft=false semantics but adds no syntax or format detail beyond the structured fields, so the baseline 3 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?

States a specific verb (Create) and resource (GitHub release) and adds the key side effect that the tag is created when absent. No sibling tool covers releases, so there is no ambiguity to resolve, and the scope is unmistakable.

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

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

Usage is only implied: an agent infers you call this to publish a release. There is no explicit when-to-use, when-not-to-use, or alternative routing guidance across the 25 sibling tools, which is acceptable only because no sibling overlaps.

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

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

Annotations only declare readOnlyHint=true, and the description goes well beyond that: it discloses the 5-failed-job fetch cap, the 256 KiB aggregate log cap, timestamp/ANSI stripping, the 300-job examination ceiling, and the meaning of `truncated`, `failed_jobs_omitted`, and `jobs_truncated`. These are exactly the operational limits an agent needs before relying on the output being complete.

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 purpose sentence is front-loaded and the second paragraph packs dense but useful constraints. It is slightly verbose with backtick-heavy flag naming, but no sentence is 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?

With an output schema present, the description need not document return shape, yet it still explains the truncation flags and caps that govern what comes back. For a read-only diagnostic tool with four well-documented params, nothing an agent needs to call or trust it is missing.

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

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

Schema description coverage is 100%, so the schema already documents repo, owner default, run_id, and tail_lines (default 200, max 1000). The description adds no parameter syntax or format detail beyond restating tail_lines, so the baseline of 3 is appropriate.

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

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

Opens with a specific verb+resource: 'Get the end of the log of each failed job in a GitHub Actions run.' That is immediately distinguishable from siblings like get_workflow_run_tool (run metadata) or rerun_failed_jobs_tool (mutation), so an agent can route correctly 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?

Usage is implied by the resource ('failed jobs', 'end of the log') but there is no explicit when-to-use, when-not-to, or named alternative such as rerun_failed_jobs_tool for remediation versus this tool for diagnosis. Adequate but the routing guidance is left to inference.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered. The word 'decoded' hints at base64 decoding and 'text' hints that binary files may not be returned, which is some added context, but the description omits size limits, error behavior for missing paths, and truncation handling.

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

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

A single front-loaded sentence with no filler or redundancy. Every word earns its place.

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

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

With an output schema present, return values need not be described, and the annotations cover safety. What remains missing for a file-fetch tool is whether large or binary files are handled, which is relevant given the description's 'text content' phrasing.

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

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

Schema description coverage is 100%, so all four parameters (repo, path, ref, owner) are already documented in the schema, including the ref and owner defaults. The description adds no parameter syntax or format detail beyond that, making the baseline 3 appropriate.

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

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

States a specific verb (Get) and resource (decoded text content of a file in a GitHub repository), which is unambiguous. It does not, however, distinguish itself from siblings like search_code_tool or list_repo_tree_tool, so an agent must infer the boundary itself.

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

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

Usage is only implied: an agent infers it should be used when it needs the contents of a specific file. There is no explicit when-to-use, when-not-to-use, or named alternative (e.g. search_code_tool for locating content, list_repo_tree_tool for discovering paths).

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

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

The readOnlyHint annotation already declares this is a safe read, and the description adds essentially no behavioral context beyond restating the operation — no auth requirements, rate limits, error behavior for missing issues, or pagination. With annotations covering only the safety profile, the description leaves the rest of the behavior undisclosed.

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

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

A single front-loaded sentence with zero waste and no filler. Its brevity borders on under-specification rather than pure conciseness, which keeps it from a 5.

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?

An output schema exists, so return values need no explanation, and parameters are fully covered by the schema, making the description minimally sufficient. The remaining gap is the absence of any sibling routing or usage context, which leaves the definition adequate but thin for a tool in this crowded sibling set.

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 repo, owner (with its GITHUB_DEFAULT_ORG default), and issue_number are fully documented in the schema. The description adds no syntax or format meaning beyond that, so the baseline 3 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 states a specific verb (Get) and resource (GitHub issue) and scopes it with 'single' and 'by number', which distinguishes it from siblings like list_issues_tool and search_issues_tool. It stops short of naming those alternatives, so it does not reach 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 phrase 'by number' implies the tool is used when a specific issue number is known, which is a reasonable usage cue. However, it never states when to prefer this over search_issues_tool or get_pull_request_tool, and gives no 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?

Annotations only declare readOnlyHint=true, so the description carries the burden for behavioral disclosure and does so well. It explains classification categories, that skipped checks are not failures, the semantics of ready_to_merge, and the important token-scope limitation where check-run access may fall back to Actions jobs with checks_source indicating the source.

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 and then adds only high-value behavioral details: classification rules, skipped handling, ready_to_merge semantics, and token fallback. It is dense but appropriately sized for a tool with meaningful auth and output nuances.

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 output schema, readOnly annotation, and fully described parameters, the description supplies the remaining critical context an agent needs. It covers the return signal, skipped-check semantics, and token-related visibility limitations, making the definition complete for correct invocation and interpretation.

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 repo, owner, and pull_number are already documented in the schema. The description does not add parameter-level syntax or meaning beyond what the schema provides, which is acceptable given complete schema coverage but does not exceed the baseline.

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: get a CI verdict for a PR, with classification of check-runs and commit-status contexts. It is clearly distinct from sibling PR tools and workflow-run tools because it focuses on merge-readiness checks, including the skipped-vs-failed 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 tells the agent to use ready_to_merge as the signal for whether a PR is clear to merge, and explains the token-scope fallback to Actions jobs. It provides clear usage context but does not explicitly name alternatives such as get_pull_request_tool or list_workflow_runs, so it stops short of full when-to-use/when-not guidance.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description usefully adds the output format ('unified diff'), but it says nothing about a critical trait for diff tools — whether large diffs are truncated, capped, or paginated — nor about auth requirements.

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

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

A single front-loaded sentence with zero filler and no redundancy. It is efficient, though its brevity comes at the cost of the usage and behavioral context an agent would benefit from.

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?

An output schema exists, so return values need not be explained, and readOnlyHint covers the safety side. However, for a tool whose output can be enormous, the absence of any note on diff size limits or truncation leaves a real gap.

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

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

Schema description coverage is 100%, so repo, owner, pull_number are all documented in the schema and the description adds no parameter-level detail. Baseline 3 applies when the schema does the heavy lifting.

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

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

The description states a specific verb ('Get') and resource ('the unified diff for a GitHub pull request'), which clearly distinguishes it from metadata siblings like get_pull_request_tool. It stops short of explicitly naming or contrasting with any sibling, so the differentiation is inferred rather than stated.

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

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

There is no guidance on when to choose this over get_pull_request_tool, get_file_content_tool, or list_pull_request_comments_tool, nor any mention of prerequisites. The agent must infer that 'I want the diff' maps to this tool from the 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?

readOnlyHint=true already tells the agent this is a safe read, and the description is consistent with that. However, it adds no behavioral context beyond the annotation — nothing about error behavior for a nonexistent PR number or any rate/auth considerations — so it only meets the lowered bar.

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

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

A single sentence, front-loaded with the verb and resource, with zero filler. Nothing in it is redundant or padded.

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 single-resource read with an output schema (which removes any need to explain return values), the definition covers what is needed. It loses a point only for not clarifying relationship to the PR-diff/checks/comments siblings an agent might confuse it with.

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 repo, owner (with GITHUB_DEFAULT_ORG fallback), and pull_number are fully documented in the schema. The description's phrase 'by number' loosely maps to pull_number but adds no format or defaulting detail, so the baseline 3 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 states a specific verb (Get) and resource (a single GitHub pull request) plus the keying dimension (by number), which separates it from list_pull_requests_tool and the diff/checks siblings. It does not explicitly name any sibling, so it falls 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?

There is no when-to-use guidance and no mention of alternatives such as get_pull_request_diff_tool, get_pull_request_checks_tool, or list_pull_request_comments_tool for adjacent PR data. The agent must infer routing purely from the tool name.

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?

readOnlyHint=true already establishes this is a safe read. The '(no logs)' note adds genuinely useful scope context—telling the agent logs are excluded and must come from a logs-specific tool—but nothing else about auth, pagination, or result shape is disclosed.

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

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

A single front-loaded sentence with zero waste; the most useful qualifier ('no logs') lands immediately after the core action.

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?

An output schema exists, so return values (including jobs) need not be described, and annotations cover the safety profile. The definition is essentially complete, with only minor room for explicit sibling routing.

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 100%, so repo, owner, and run_id are all documented in the schema, including the owner default. The description adds no format or syntax detail beyond what the schema already provides, making the 3 baseline correct.

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 (get), resource (a GitHub Actions workflow run and its jobs), and scope ('one'), which implicitly contrasts with list_workflow_runs_tool. It does not explicitly name any sibling, so it falls short of the top band.

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

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

Usage is only implied: 'one' suggests fetching a known run_id versus listing, and '(no logs)' hints that log retrieval belongs to a different tool. No explicit when/when-not or named alternative is given, so routing is left 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?

Beyond readOnlyHint=true, the description discloses result ordering (oldest first) and the precise content boundary on PRs (conversation comments only, excluding diff comments and reviews), which the annotations do not convey. It stops short of describing pagination behavior or result shape, though the output schema and page/per_page params partly cover that.

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, each doing distinct work: scope and ordering, the plain-issue case, and the PR caveat. The routing information is front-loaded with zero filler.

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

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

For a read-only list tool with full schema coverage, an output schema, and clear sibling routing, nothing an agent needs in order to call it correctly is missing. Pagination and return shape are handled by structured fields rather than the description.

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 100%, so repo, owner, issue_number, page and per_page are all documented in the schema already. The description adds only the implicit point that issue_number accepts a PR number, which the schema itself states. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('List the comments on a GitHub issue or pull request conversation') plus the ordering ('oldest first'). It explicitly contrasts itself with list_pull_request_comments_tool, so an agent can distinguish the two without inspecting either schema.

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

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

Gives an explicit routing rule: use this for plain issues, because list_pull_request_comments_tool does not handle them. It also states the when-not caveat for pull requests — diff comments and reviews must come from the sibling tool — leaving nothing to inference.

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

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

The readOnlyHint annotation already establishes this is a safe read operation, so the description is not the sole carrier of the safety profile. It adds one behavioral fact beyond annotations and schema: the result set excludes pull requests. It says nothing about pagination behavior, default result ordering, or authentication requirements, so it adds modest value.

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

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

A single front-loaded sentence with zero filler; the scope constraint is placed immediately after the action. It is efficient, though arguably too terse to serve as a standalone definition given the missing usage distinctions.

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?

An output schema exists, the annotations cover the safety profile, and the schema fully documents all six parameters, so the description does not need to explain return values or inputs. What remains missing is disambiguation from search_issues_tool and get_issue_tool, which a list tool sharing this namespace should ideally provide.

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 every parameter (page, repo, owner, state, labels, per_page) documented including defaults and bounds. The description adds no parameter-level meaning beyond that, so the baseline of 3 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?

States a specific verb and resource ('List issues for a GitHub repository') and explicitly carves out the scope ('pull requests excluded'), which distinguishes it from the sibling list_pull_requests_tool. It stops short of naming or contrasting with search_issues_tool or get_issue_tool, but the core purpose is unambiguous.

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

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

There is no explicit when-to-use guidance. The parenthetical exclusion of pull requests hints at scope, but the description never says when to pick this over search_issues_tool (filtered search) or get_issue_tool (single issue fetch), so the agent must infer the choice from tool names alone.

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

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

Annotations only declare readOnlyHint=true, and the description goes well beyond that: it discloses per-kind ordering (oldest first), a hard cap of 300 items per kind, and the truncated/truncated_kinds fields that signal omissions. It does not cover auth/rate-limit behavior, but the truncation semantics are exactly the kind of operational detail annotations cannot express.

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 the one-line summary, then a compact paragraph on what is merged and the item shape, then a short note on truncation. No sentence is filler and the ordering follows what an agent needs first.

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?

An output schema exists, so return values needn't be restated, and the description still names the kinds and truncation signals the agent will see. The only gap is routing guidance versus the diff/review-specific siblings, which is a usage concern rather than a completeness one.

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% for all three parameters (repo, owner, pull_number), so the schema already carries the parameter documentation. The description adds nothing about parameter meaning or format, which is acceptable but is the baseline rather than added value.

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

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

States a specific verb (list) and resource (comments on a GitHub pull request) and immediately clarifies scope: it aggregates conversation comments, diff comments, and submitted reviews into one list. That aggregation distinguishes it from siblings like get_pull_request_diff_tool and reply_to_review_comment_tool without the agent needing to open any 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?

The description implies when it is useful (you want all comment activity on a PR in one call), but it never states when to prefer it over alternatives such as get_pull_request_diff_tool or get_pull_request_tool, nor any exclusions or prerequisites. Usage is inferable but not guided.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered, but the description adds nothing on top of that — no mention of default filtering to open PRs, pagination behavior, or ordering. With annotations present the bar is lower, yet this text contributes zero behavioral context beyond what the title already implies.

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

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

A single front-loaded sentence with no filler or repetition. It is appropriately sized for the tool, though the length also reflects how little it attempts to say.

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?

An output schema exists and the input schema fully documents all five parameters, so return values and parameter meaning need not be repeated. What is still missing is any routing guidance among the many sibling PR/issue list tools, which leaves the definition only minimally 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 page, repo, owner, state, and per_page are each documented in the schema and the baseline of 3 applies. The description adds no extra meaning such as default org resolution or max per_page behavior, but it does not need to.

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

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

States a specific verb ('List') and resource ('pull requests for a GitHub repository'), so an agent can tell it apart from get_pull_request_tool or create_pull_request_tool on the resource alone. However, it does nothing to distinguish itself from list_pull_request_comments_tool or to note that it returns a collection rather than a single object, so sibling differentiation is implicit at best.

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

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

There is no when-to-use guidance and no alternatives named. The description never says to use get_pull_request_tool for a single PR, nor does it explain what the state/page/per_page knobs are for in practice, leaving the agent to infer routing from the tool name alone.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds nothing further — no mention of pagination, result size limits, or how recursion affects output — leaving the behavioral burden largely on structured fields.

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

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

A single front-loaded sentence with no filler; the purpose is stated immediately. It is arguably thin for a four-parameter tool, but nothing is wasted.

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

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

With an output schema present and full parameter coverage, the description need not explain return values. However, for a tool sitting among several code-access siblings, it lacks any routing context, leaving a modest gap.

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

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

Schema description coverage is 100% and all four parameters (repo, owner, tree_sha, recursive) are documented in the schema. The description adds no additional meaning about SHA formats, owner defaults, or recursion depth, so the baseline 3 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?

States a specific verb ('List') and resource ('git tree ... of a GitHub repository'), and the parenthetical clarifies the tree contains files and directories. It does not explicitly distinguish itself from siblings like get_file_content_tool or search_code_tool, 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?

There is no guidance on when to use this tool versus alternatives such as get_file_content_tool (fetch a single file) or search_code_tool (find code by pattern). The agent must infer usage entirely from the name and description.

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

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

The readOnlyHint=true annotation already tells the agent this is a safe read, so the description only needs to add context — and it adds essentially none. It does not disclose pagination behavior, result ordering, filter semantics, or any rate-limit/auth notes beyond what the annotation and schema already convey.

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

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

A single front-loaded sentence with zero filler, which is efficient. It is arguably under-specified rather than padded, but nothing in it wastes space.

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

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

With a full output schema, annotations, and 100% schema coverage, much of the burden is carried elsewhere, so a short description is defensible. However, for a six-parameter filtered-list tool that sits alongside many workflow siblings, the absence of any routing or filtering guidance leaves a real gap.

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

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

Schema description coverage is 100% across all six parameters (repo, owner, branch, status, page, per_page), so the schema carries the parameter semantics. The description adds no syntax or filtering guidance beyond that, which lands it at the baseline for fully documented schemas.

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

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

States a specific verb ('List'), resource ('GitHub Actions workflow runs'), and scope ('for a repository'), which cleanly separates it from the singular get_workflow_run_tool and the mutating trigger_workflow_run_tool/rerun_workflow_run_tool siblings. It stops short of explicitly naming those siblings, so it is clear but not maximally differentiated.

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

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

There is no when-to-use or when-not-to-use guidance, no mention that this is the collection-level counterpart to get_workflow_run_tool, and no indication of when filters like branch or status should be applied. Usage is only implied by the tool name.

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 at all, the description carries the full burden and meets it: it discloses the refusal cases by name, the bypass-token hazard it guards against, the pinned-head-SHA guarantee, which conclusions count as passing (success/skipped/neutral), and the fine-grained-token fallback to Actions jobs. That is exactly the mutation-safety context an agent needs before calling a destructive, irreversible 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 core action and its gating condition are front-loaded in the first sentence, and the remaining detail is genuinely load-bearing rather than filler. It is dense and long for a single paragraph, but no sentence is redundant.

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, irreversible write tool with no annotations, the description supplies the safety profile, the failure modes, and the token caveats; an output schema exists so return values need not be explained. Nothing an agent needs in order to call this 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 100%, so the baseline is 3; the description earns above that by explaining the semantics behind sha (a mismatch aborts the merge) and allow_no_required_checks (default refuse when the base branch requires nothing), which the schema states only tersely. merge_method and owner are left to the schema.

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

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

Opens with a specific verb+resource ("Merge a GitHub pull request") plus the gating condition ("only once its required checks are green"). This clearly separates it from sibling read tools like get_pull_request_checks_tool and from update_pull_request_tool, which cannot merge.

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 rich conditional picture of when the tool will proceed versus refuse (missing/pending/failed checks, sha mismatch, unreadable protection, no required checks unless allow_no_required_checks). It does not explicitly route the agent to siblings such as get_pull_request_checks_tool for a pre-flight check, so it stops short of the top band.

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 usefully discloses the 'no reply-to-reply' rejection behavior, but says nothing about authentication/scope requirements, rate limits, or what happens on success (partially covered by the output schema). Disclosed behavior is genuine but narrow.

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, zero filler, and the thread-reply constraint is front-loaded before the operand detail. Every clause earns its place.

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

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

For a mutation tool with no annotations, the description covers the critical input constraint and the return shape is handled by the output schema. It still leaves permission/scope requirements and failure modes other than the reply-to-reply rejection unstated.

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 100%, so the baseline is 3, and the description genuinely adds meaning beyond the schema by defining what comment_id must be (a thread-starting review_comment from list_pull_request_comments_tool). It does not, however, clarify owner/repo resolution or body formatting beyond the schema's own 'Markdown' note.

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 ('Reply in the thread of a pull request review comment') and explicitly names the sibling tool that supplies the required id (list_pull_request_comments_tool), so the agent can distinguish this from generic comment-creation siblings without opening any 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?

It gives a concrete selection rule: comment_id must come from a review_comment item whose in_reply_to_id is empty, and explains why (GitHub rejects a reply to a reply). That is strong context, though it never contrasts this tool against other comment-writing siblings like create_issue_comment_tool.

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 behavioral burden, and it discloses only scope. It says nothing about required write permissions, what happens if there are no failed jobs, whether the run must be in a completed/failed state, or whether this is rate-limited. For a state-mutating tool with zero annotation coverage, that is a significant gap.

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

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

A single front-loaded sentence with no filler; the scope constraint ('only the failed jobs') is stated immediately. Nothing is redundant or padding.

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

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

An output schema exists, so return values need not be described, and parameters are fully covered by the schema. However, with no annotations, the mutation semantics (permissions, preconditions, no-op behavior) remain undisclosed, leaving the definition adequate but incomplete for a write operation.

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

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

Schema description coverage is 100%, including the owner default (GITHUB_DEFAULT_ORG) and the repo/run_id definitions, so the schema does the heavy lifting. The description adds no extra meaning about parameter formats or constraints beyond it, making the baseline 3 appropriate.

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

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

States a specific verb (re-run) and resource (failed jobs in a GitHub Actions workflow run) with a clear scope qualifier ('only the failed jobs'). This implicitly separates it from rerun_workflow_run_tool, but it never names that sibling, so the differentiation relies on the agent noticing the overlap.

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 'only the failed jobs' implies the selection condition (use this when a run partially failed and you want to skip passing jobs), but there is no explicit when-to-use statement or routing against rerun_workflow_run_tool / trigger_workflow_tool. Usage is inferable rather than stated.

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

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

No annotations are provided, so the description carries the full behavioral burden for a mutation operation. It does not disclose permission/auth requirements, whether an existing run is cancelled or superseded, or what side effects occur; only the return shape is covered by the output schema.

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 efficient sentence with the action and scope front-loaded and no wasted words. It is arguably too terse for a mutation tool, but there is no padding.

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

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

For a simple three-parameter tool with a complete schema and an output schema, the core is adequate. The missing piece is behavioral context (permissions, effect on the in-progress run), which matters for a re-run mutation.

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 100%, documenting repo, owner (with default fallback to GITHUB_DEFAULT_ORG), and run_id. The description adds nothing beyond the schema, so the baseline 3 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?

States a specific verb (re-run), resource (workflow run), and scope (all jobs), which is enough to distinguish it from the sibling rerun_failed_jobs_tool by implication. It never names that sibling, so the differentiation is implicit rather than explicit.

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 'all jobs' hints at the alternative of re-running only failed jobs, but the description never states when to choose this tool over rerun_failed_jobs_tool or trigger_workflow_tool. Usage is only implied, not spelled out.

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?

readOnlyHint=true already tells the agent this is a safe read, so the description carries a lower burden. It adds the syntax hint but says nothing about the notoriously tight rate limits on GitHub code search, result caps, or pagination traversal behavior. Net: a modest value-add beyond annotations, with real gaps left.

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, purpose front-loaded, example immediately after. Nothing wasted, nothing pruned to the point of vagueness.

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?

An output schema exists, so return values need no explanation, and all three parameters are documented. The remaining gap is operational: no mention of rate limiting or how to page through large result sets for a search tool where both matter.

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 100%, so baseline is 3, but the description earns a bump by supplying a concrete query example ("addClass repo:jquery/jquery") that teaches the qualifier syntax the schema's terse "Search query string" does not. It does not address page/per_page, but those are self-documented.

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: "Search for code across GitHub." An agent can distinguish it from the issue-oriented siblings (search_issues_tool, list_issues_tool) and from read-only file tools (get_file_content_tool), though the description never explicitly names those alternatives.

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

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

Usage is implied by the pointer to GitHub code search syntax and the sample query, which tells the agent how to phrase a query but not when this tool beats list_repo_tree_tool or get_file_content_tool. No when-not or exclusion guidance is given.

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

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

readOnlyHint=true already tells the agent this is a safe read operation, so the safety profile is covered. The description adds the search-syntax flavor, but does not disclose result limits, pagination behavior, or rate-limit considerations beyond what the schema and output schema provide.

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

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

Two short sentences, front-loaded with the purpose and followed by the syntax hint; no wasted prose. It could arguably fold the example into a single tighter statement, but it is efficient as-is.

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?

An output schema exists so return values need not be explained, and the schema fully documents the three parameters. For a search tool the description is largely complete, though it omits how results are ordered or capped, which is minor given the structured fields.

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 query, page, and per_page are already documented in the schema. The inline GitHub search syntax example ("is:open is:pr author:octocat") adds genuine meaning about how the query parameter is constructed, keeping this just above the baseline rather than below it.

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

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

States a specific verb ("Search") and resource ("issues and pull requests") with the scope "across GitHub", which separates it from get_issue_tool and list_issues_tool. It does not explicitly contrast itself with the closely related search_code_tool or list_issues_tool, so sibling differentiation is only implied.

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

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

The description gives search syntax but offers no guidance on when to use this tool versus list_issues_tool, list_pull_requests_tool, or search_code_tool. There are no exclusions or conditions that select this search path over the filter-based list 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 present, the description carries the full behavioral burden, and it does disclose the key semantics: this creates a brand-new run rather than re-running an existing one, and it will fail if the target workflow lacks a workflow_dispatch trigger. It does not mention required token permissions/scopes or any rate-limit behavior, which is the remaining gap for a mutating trigger 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 tight sentences with zero filler; the core action is front-loaded and the sibling comparison plus precondition follow in priority order.

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?

An output schema exists, so return values need no explanation, and the description covers the action, the alternative, and the dispatch precondition. It is close to complete; only auth/permission requirements are unstated for this mutating call.

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

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

Schema description coverage is 100%, so repo, workflow_id, ref, owner and inputs are already documented, including defaults. The description adds no parameter-level detail beyond the schema (e.g. accepted input value types or ref format), so the baseline 3 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?

States a specific verb (trigger) and resource (a fresh GitHub Actions run) plus the exact mechanism (workflow_dispatch event). It explicitly contrasts itself with rerun_workflow_run_tool, so an agent can pick between them without opening either schema.

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

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

Gives an explicit when-to-use ("force a new build"), names the alternative (rerun_workflow_run_tool), and states the condition that selects this tool over that one (the 30-day rejection on re-runs). It also states the precondition that gates success: the workflow must declare an on: workflow_dispatch trigger.

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 usefully discloses the non-obvious state/state_reason coupling for reopening, but says nothing about required permissions, whether label changes are destructive/replacing, or reversibility of edits.

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, front-loaded with the purpose; the close/reopen mechanics follow immediately. The mid-sentence line breaks are a formatting blemish, not wasted content.

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

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

An output schema exists, so return values need no explanation, and the description covers the main reason an agent would pick this tool (state transitions). It is slightly thin on permission/ownership prerequisites for a mutation tool with no annotations.

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 100%, so the baseline is 3, but the description genuinely adds meaning the schema lacks: the schema only says state is "open" or "closed", while the description explains that reopening requires state="open" paired with state_reason="reopened".

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+resource ("Update a GitHub issue") and adds the lifecycle scope (closing/reopening). Distinguishable from update_pull_request_tool by resource name alone, but it never explicitly contrasts with siblings like create_issue_tool or get_issue_tool.

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

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

Gives concrete call recipes: state="closed" to close, state="open" with state_reason="reopened" to reopen. That is clear usage context, but there are no exclusions or guidance on when to prefer update_issue_tool over create_issue_comment_tool for adding commentary.

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 usefully discloses one key trait — this does not merge, and closing is done via state="closed" — but says nothing about permissions, reversibility, or side effects of overwriting title/body, leaving significant behavioral 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?

Two short sentences, front-loaded with the action and immediately followed by the most important constraint. No filler, no repetition of the title or schema fields.

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

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

An output schema exists so return values need not be explained. However, for a mutation tool with zero annotations, the description should say more about behavioral consequences (e.g., that closing is a state change on the PR, permission requirements); it is adequate but leaves real gaps.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters. The description adds only the semantic that state="closed" closes without merging; it adds no format or interaction detail (e.g., what happens if body is omitted vs null) beyond the schema, so baseline 3 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?

States a specific verb+resource ("Update a GitHub pull request") and adds scope detail (closing or reopening). It clearly reads as distinct from get_pull_request_tool and list_pull_requests_tool, but it never names an alternative, so differentiation rests on the tool name rather than explicit routing.

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 actionable usage context: use state="closed" to close a PR without merging, and explicitly warns that this is not the merge path. That is a clear when-to-use cue, though it offers no guidance on when to prefer it over other update paths or what happens on reopening.

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