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?

With no annotations, the description carries the full behavioral burden, and it discloses only one trait implicitly: that content is decoded (i.e. base64 handling is done for you, so binary files are likely unsupported). It says nothing about authentication requirements, truncation of large files, or what happens on a missing path.

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 action and target are stated immediately with nothing 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?

An output schema exists, so return-value explanation is unnecessary, and the operation is a simple read. Still, with no annotations and no usage context, the definition leaves gaps around large/binary files and when to prefer sibling search tools.

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, including defaults for 'ref' and 'owner', are documented in the schema itself. The description adds no syntax, format, or constraint detail 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?

The description states a specific verb and resource ('Get the decoded text content of a file'), which is clear and unambiguous. It does not, however, differentiate itself from adjacent read tools such as search_code_tool or list_repo_tree_tool, so an agent must infer the distinction 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?

There is no when-to-use guidance, no statement of prerequisites, and no reference to alternative tools like search_code_tool when the file path is unknown. The agent gets a purpose but no routing logic.

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. 'Get' implies a read operation, but it says nothing about authentication requirements, behavior for a missing/nonexistent issue number, or rate limits. An output schema exists, so return values need not be explained, but the behavioral gaps remain significant for a tool with zero annotation coverage.

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

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

A single front-loaded sentence with no wasted words. The core action and scope lead the sentence.

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-item read with a full output schema and complete parameter documentation, the description covers the essential action. It is slightly thin on error/edge-case behavior, but nothing an agent needs to select or invoke the tool 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 description coverage is 100%, so the schema already documents repo, owner, and issue_number. The phrase 'by number' loosely reinforces issue_number but adds no syntax or format detail 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 (Get) and resource (GitHub issue) with clear scope (single, by number), which distinguishes it from list_issues_tool and search_issues_tool by implication. It stops short of explicitly naming those siblings, so differentiation is inferable 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?

Usage is only implied: 'single issue by number' suggests the lookup-one-item case, contrasted against the list/search siblings. There is no explicit when-to-use, when-not-to-use, or named alternative.

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

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

No annotations are provided, so the description must carry the behavioral load, and it does add real value: it discloses the classification scheme (passed/failing/pending/skipped), the critical semantic that SKIPPED is not a failure, and the exact truth conditions for ready_to_merge (including the known-unmergeable case). It stops short of stating auth requirements or rate-limit/read-only 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?

Four short sentences, front-loaded with the core verdict statement followed by classification and output semantics. Every sentence earns its place; the only minor redundancy is restating the ready_to_merge semantics alongside an existing output schema.

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

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

An output schema exists, so return values need not be described, yet the description usefully clarifies the one ambiguous field (ready_to_merge). Combined with full parameter coverage, an agent has enough to call it correctly; the only gap is the absence of any read-only/safety statement given there are 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 description coverage is 100% and all three parameters are documented in the schema (repo, owner with default, pull_number), so the baseline of 3 applies. The description adds no parameter-level detail such as accepted repo formats or owner defaulting behavior beyond what the schema already states.

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 (get a CI verdict for a PR) with a distinguishing scope: it separates skipped from failed and aggregates all check-runs plus commit-status contexts. This clearly differentiates it from siblings like get_pull_request_tool, which would not surface a CI verdict.

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 output-side guidance (use ready_to_merge as the merge-clearance signal), which implies the use case, but never states when to pick this over get_pull_request_tool or the workflow-run tools, and names no alternatives or exclusions. Usage is inferable but not explicit.

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

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

No annotations are provided, so the description carries the full burden. It discloses the return format (unified diff), which is useful, but says nothing about authentication requirements, whether large diffs are truncated or truncated-error, or rate-limit behavior for a GitHub-backed read.

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 efficient, though arguably too terse given the missing usage and behavioral context.

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 100%-covered input schema handles parameters. However, the absence of any when-to-use framing or behavioral notes leaves the definition only minimally complete for an agent choosing among several PR-related 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%, including the owner defaulting to GITHUB_DEFAULT_ORG, so the schema already documents all three parameters. The description adds no parameter meaning beyond what the schema provides, 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 and resource ("Get the unified diff for a GitHub pull request"), and the output format (unified diff) helps separate it from get_pull_request_tool and get_pull_request_checks_tool. It does not name a sibling explicitly, so it is clear but undifferentiated.

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

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

No guidance on when to use this versus get_pull_request_tool, list_pull_requests_tool, or get_file_content_tool, and no preconditions (e.g., size limits, whether a PR must exist). Usage is left entirely to inference 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?

No annotations are provided, so the description carries the full behavioral burden. "Get" implies a read, but nothing is said about required permissions, behavior on a missing or closed PR, rate limits, or pagination/field selection.

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. It is efficient, though its brevity borders on under-specification rather than optimal density.

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 all three parameters are documented. However, with no annotations and no usage context, the description is only minimally adequate for guiding correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents repo, owner, and pull_number; the baseline is 3. The phrase "by number" loosely reinforces pull_number but adds no format or constraint detail beyond the schema.

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

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

The description gives a specific verb and resource ("Get a single GitHub pull request") and clarifies the lookup key ("by number"). It is clearly distinct from list_pull_requests_tool in spirit, but it never explicitly names or contrasts with the diff/checks/update siblings.

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 statement of when to use this tool versus list_pull_requests_tool, get_pull_request_diff_tool, or get_pull_request_checks_tool. Usage is only implied by the verb, with no exclusions or prerequisites such as authentication or the fact that the PR must already exist.

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 that pull requests are excluded, a behavioral trait beyond the schema, but omits read-only status, auth requirements, default state, and pagination 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?

A single front-loaded sentence with zero waste. It is appropriately sized for the tool and immediately states the resource and key exclusion.

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 all parameters are fully documented, so the description need not explain return values. It covers the core resource and PR exclusion, though it could better route the agent against search_issues_tool.

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

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

Schema description coverage is 100% and all six parameters are documented, so baseline is 3. The description adds no parameter 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?

States a specific verb+resource ('List issues for a GitHub repository') and adds an important scope exclusion ('pull requests excluded'), which distinguishes it from list_pull_requests_tool. It does not distinguish from search_issues_tool, 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?

No guidance on when to use this versus search_issues_tool or get_issue_tool; usage is only implied by the verb. The pull-request exclusion is a boundary, not an alternative-selection rule.

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 about pagination behavior, rate limits, auth requirements, or default filtering. The schema hints at pagination via page/per_page defaults, but the description itself adds no 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?

A single, front-loaded sentence with zero filler or redundancy. It is efficient, though the brevity reflects under-specification rather than tight editing of richer 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?

With an output schema present, return values need not be explained, and schema coverage is complete. But for a read tool with zero annotations, the description should still cover auth requirements and pagination semantics; it says nothing, leaving meaningful gaps.

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

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

Schema description coverage is 100%, so all five parameters (repo, owner, state, page, per_page) are already documented in the schema, including defaults and the state filter values. The description adds no syntax, format, or semantic detail beyond what the schema provides, which is the baseline 3 case.

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') scoped to a GitHub repository, which cleanly separates it from the singular get_pull_request_tool. However, it does not explicitly name or differentiate itself from related siblings such as search_issues_tool or list_issues_tool beyond the resource noun.

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 mention of alternatives (e.g., get_pull_request_tool for a single PR), and no stated prerequisites such as authentication or required org context. The agent must infer usage 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?

No annotations are provided, so the description carries the full behavioral burden, yet it only states what is listed. It does not confirm this is a read-only, non-mutating operation, does not mention authentication or rate-limit considerations, and does not hint at result size or truncation behavior when recursion is enabled.

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 tight sentence with no filler or redundancy, and the resource being listed is front-loaded. It is efficient, though arguably under-specified rather than maximally informative.

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

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

With a full output schema and 100% parameter documentation, the structured fields carry most of the load, so the terse description is nearly adequate. It still omits read-only confirmation and any comparison against sibling tools like get_file_content_tool, leaving a small but real completeness 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 each parameter (repo, owner, tree_sha, recursive) is already documented with defaults in the schema, so the baseline of 3 applies. The description adds no syntax, format, or interaction detail beyond what the schema supplies.

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 (list) and resource (git tree of files and directories in a GitHub repository), so an agent knows exactly what it retrieves. It does not explicitly distinguish itself from near-neighbors like get_file_content_tool or search_code_tool, which is the only gap.

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 mention of prerequisites (e.g., needing an owner/default org or a valid ref), and no routing to alternatives such as get_file_content_tool for a single file. The agent must infer usage entirely from the name and schema.

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 disclosure burden. It does not say the operation is read-only and non-mutating, does not describe pagination behavior, defaults, result ordering, or any auth/rate-limit considerations. For a list tool with six parameters and no annotation coverage, this is a substantial 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 wasted words. It is appropriately sized for the operation, though the brevity borders on under-specification for a tool with filtering and pagination.

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 parameters. However, given no annotations and a multi-filter listing tool, the description leaves behavioral context (read-only nature, pagination, filtering defaults) entirely to 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 all six parameters (repo, owner, branch, status, page, per_page) are already documented in the schema with defaults and filter semantics. The description adds nothing beyond this, 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?

The description states a specific verb and resource: 'List GitHub Actions workflow runs'. It is clear what the tool does, but it does nothing to distinguish it from siblings like trigger_workflow_tool or rerun_workflow_run_tool beyond implying a read-only listing.

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

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

There is no guidance on when to use this tool versus alternatives, no mention of the read-only listing context against the workflow mutation siblings, and no prerequisites or scope notes (e.g., single repo, paginated results). The agent must infer usage entirely.

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?

No annotations are provided, so the description carries the full behavioral burden, and it discloses almost nothing: no mention of authentication requirements, GitHub code-search rate limits, or result caps. The syntax hint is useful, but for a network search tool with zero annotation coverage this 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?

Two short sentences with the core action front-loaded and the syntax example immediately after; no filler or redundancy.

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

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

An output schema exists, so return values need not be explained, and the schema covers pagination defaults. What is missing is behavioral context an agent needs before calling: auth expectations and rate-limit behavior for GitHub code search.

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 adds real value by showing GitHub code-search qualifier syntax ('addClass repo:jquery/jquery') for the required query parameter, going beyond the schema's bare 'Search query string'.

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 ('Search for code across GitHub'), which cleanly separates it from siblings like search_issues_tool, get_file_content_tool, and list_repo_tree_tool. It does not explicitly name or contrast an alternative, but the resource 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?

The description gives syntax help but no when-to-use guidance: it never says when to prefer this over get_file_content_tool (known file) or list_repo_tree_tool (known repo), nor any prerequisite or exclusion. Usage context is left entirely to inference.

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

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

No annotations are provided, so the description carries the full behavioral burden and largely does not meet it. It discloses global scope ('across GitHub') but says nothing about GitHub search's strict rate limits, the ~1000-result result cap, or authentication requirements — all of which materially affect how an agent should call it.

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

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

Two short sentences, front-loaded with the verb and resource, then the query-syntax detail. Nothing is wasted and the reader gets the essential call pattern immediately.

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 all three parameters are documented. What is missing is the sibling differentiation (list_issues_tool vs this search tool) and the operational caveats — rate limits and result caps — that matter for a GitHub search endpoint.

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, and the description earns an upgrade by supplying the actual query dialect and a concrete example ('is:open is:pr author:octocat') that goes beyond the schema's bare 'Search query string'. Pagination params remain undocumented in prose, but the schema covers them adequately.

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 across GitHub'), and the 'across GitHub' scope hints that this is a global search rather than a repo-scoped listing. It does not explicitly name the sibling it competes with (list_issues_tool, search_code_tool), so an agent must infer the boundary from the scope wording alone.

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: the query-syntax example suggests this tool is for filtered/searched lookups rather than exhaustive listing, which indirectly points away from list_issues_tool. However, no alternative is named and no when-not-to-use condition (e.g., use list_issues_tool for a simple repo listing) 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?

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.