RepoPilot

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

Annotations already declare readOnlyHint=false (write) and destructiveHint=false (non-destructive), so the description's job is to add context. It does: it mentions creating an 'external PR,' appending a 'git_reference evidence record,' and reassuring 'never merges it.' This adds useful behavioral details beyond the annotations without contradiction.

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 sentences with zero redundancy. The main action is front-loaded, the usage condition is placed early, and the side-effect clarification (never merges) is concise. Every sentence earns its place, making it easy to parse for an agent.

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 write tool with 6 required parameters and no output schema, the description covers the essential context: when to use, permission constraints, and post-conditions (creates PR, appends evidence). It omits a return format, but without an output schema that is not strictly required. Preconditions like allowed repositories are handled in the schema. Overall, it is sufficient for 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 coverage is 100%, so the baseline is 3. The description adds marginal context by linking 'repair branch' to the head parameter and 'maintenance run' to runId, but these are already implied by the schema descriptions. No significant additional semantic value is provided beyond what the schema offers.

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

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

The description clearly states the specific verb and resource: 'Create a GitHub pull request from an existing repair branch.' It also distinguishes itself from the sibling merge tool by explicitly saying 'never merges it,' making its role unambiguous in the toolset.

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

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

The description provides a clear when-to-use condition ('Use only after the patch and focused verification are complete') and sets expectations about the permission level ('highest automatic repository write allowed by pull_request_only'). It implicitly excludes merging by stating 'never merges it,' but it does not explicitly name the merge alternative as a separate tool, leaving a small gap in exclusions.

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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the authentication requirement ('requires GITHUB_TOKEN') and reiterates 'read-only GitHub API request', which reinforces the read-only nature but doesn't contradict annotations. The token requirement is useful context beyond what annotations 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?

The description is exactly two sentences with zero filler. The first sentence front-loads the concrete read action and fields, the second gives usage guidance and exclusions. Every word earns its place, and the most important operational detail (what it reads) is immediately clear.

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

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

Given the tool's simple nature, the description is largely complete: it specifies the data returned, the auth requirement, and the usage context. An output schema is not present, but the description enumerates the fields returned (title, body, labels, state, URL), which gives the agent a good idea of the response shape. It doesn't mention any rate limits or error handling, but those are likely covered by the annotations and general platform knowledge. The only minor gap is no explicit statement about what happens if the issue doesn't exist, but that is typical and not required for 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 coverage is 100% – both parameters have descriptive text in the schema (repository pattern and allowed repos, issueNumber positive integer). The description doesn't add any parameter-level semantics beyond what the schema already explains. Baseline 3 is appropriate because the schema does the heavy lifting and the description adds no extra 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?

The description states a specific verb ('Read') and resource ('one GitHub issue') and enumerates the exact fields returned (title, body, labels, state, URL). It explicitly says 'do not use it for pull requests', which distinguishes it from the sibling tool github_get_pull_request. This provides clear, unambiguous purpose and differentiates it from the tool family.

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 an explicit when-to-use guidance ('Use this to establish source requirements before triage') and a when-not-to-use exclusion ('do not use it for pull requests'). This is direct and leaves no ambiguity about selecting this tool over alternatives. Though it doesn't name the sibling explicitly, the exclusion is sufficient to route the agent correctly.

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, destructiveHint=false, and idempotentHint=true, so the safety profile is set. The description adds value by disclosing the failure condition ('call fails if the GitHub head changed') and specifying the content of the response (immutable head SHA and change totals). It also clarifies the binding requirement between run, repository, and pull request. No contradiction with annotations; it enriches them.

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 achieve everything: the first defines the action and key outputs, the second gives the usage context and a critical failure condition. It is front-loaded with the core purpose and contains zero filler. 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 simple read-only metadata GET with three parameters and no output schema, the description is fully sufficient. It explains what the tool does, when to call it, what it returns (head SHA and change totals), and the failure condition. There is no missing essential detail that an agent would need to invoke it correctly.

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 each parameter (runId, repository, pullNumber) already documented with formats and constraints. The tool description reinforces the relationship ('bound to a RepoPilot review run') and the 'must match' requirement, which adds slight semantic context to runId and repository. However, it does not add syntax or usage nuance beyond the schema, so the baseline 3 is appropriate.

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

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

The description opens with an explicit action ('Read current metadata') and a clearly defined resource ('the pull request bound to a RepoPilot review run'), and immediately names the key outputs (head SHA and change totals). This specific verb+resource pairing distinguishes it from siblings like github_get_pull_request_checks, which focuses on check runs, and github_list_pull_request_files, which lists files. An agent can tell them apart without opening schemas.

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 point-in-workflow instruction ('Use before reviewing files or publishing a review') and warns about preconditions (run/repo/PR must match, fails if head changed). However, it does not explicitly mention alternative tools or when *not* to use it. The siblings are functionally distinct, so the omission is minor, but explicit exclusions would push this to 5.

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 indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=false. The description adds valuable context by explicitly stating that it appends evidence (a write side-effect) and requires the PR number and head SHA to match for review runs. This goes beyond the annotation flags and explains real behavioral constraints. No contradiction with annotations.

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

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

The description is two sentences with no redundant words. It front-loads the primary action and side-effect, then gives usage context and a critical condition. Every sentence earns its place—concise without sacrificing essential guidance.

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 tool with 3 required parameters and no output schema, the description provides sufficient context: what it does, when to use it, and a key prerequisite. It doesn't cover error handling or response format, but these are not required when the action and constraints are clear. The detail about the head SHA matching is especially valuable for correctness.

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 three parameters are well-documented in the schema itself. The description does not add new parameter-level detail, but it does reinforce that pullNumber must correspond to a live PR ('the PR number and current head SHA must still match the run'). This aligns with the schema's exclusiveMinimum and maximum. Baseline 3 is appropriate given full schema coverage.

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

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

The description states a specific action ('Read GitHub combined commit statuses and Actions check runs for a pull request') and its side-effect ('then append the result as ci_result evidence'). This clearly identifies the tool's purpose and distinguishes it from siblings like github_get_pull_request (fetches PR metadata) and github_list_pull_request_files (lists changed files).

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

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

The description provides clear usage context: 'Use during verification or read-only review after a PR exists.' It also includes a precondition: 'For review runs, the PR number and current head SHA must still match the run.' Though it doesn't explicitly name alternatives, the timing and conditions are unambiguous. A small deduction for not explicitly saying 'when not to use'.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description reveals two behaviors: it verifies the head SHA before and after reading, and it returns null patch values for binary or unavailable diffs. These add meaningful context about reliability and edge cases, fully satisfying the transparency requirement given the existing annotations.

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 pack the core purpose, the pagination rule, the SHA verification, and the null-patch behavior with zero redundancy. The most important information (what the tool reads) is front-loaded, and 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?

For a paginated read tool with no output schema, the description covers the key aspects: the content returned (metadata and patches), the pagination signal (hasNextPage), and a common edge case (binary/unavailable diffs). It does not spell out the exact response shape (e.g., field names like 'files' or 'hasNextPage'), but the essential information is present.

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

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

The input schema already fully documents all four parameters (100% coverage), so the baseline is 3. The description adds value by explaining the pagination loop (use consecutive page values) and that the page is tied to a review run, giving the page parameter practical usage context beyond its schema description. This lifts it to a 4.

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 ('Read'), a precise resource ('one 100-file page of changed-file metadata and GitHub-provided text patches'), and the binding condition ('bound to a review run'). This clearly distinguishes it from sibling tools like github_get_pull_request or github_get_pull_request_checks without naming 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 explicit pagination guidance ('Use consecutive page values until hasNextPage is false') and clarifies the review-run binding, which provides clear context for when to use this tool. However, it does not explicitly contrast itself with alternatives or state when not to use it, so it stops short of the full 5.

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 indicate destructiveHint=true and readOnlyHint=false, and the description adds valuable context beyond this: the approval is atomically consumed before the external merge, meaning it cannot authorize another action. This is a critical behavioral trait that an agent must know. However, the description could have elaborated on what happens if the merge fails (e.g., whether the approval is still consumed), leaving a minor 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?

The description is two sentences with zero waste. It front-loads the most critical constraint (merge only after human approval) and then explains the consumption behavior. Every sentence contributes to safe and correct usage.

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

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

For a destructive tool with 6 parameters and no output schema, the description captures the essential preconditions (approval, run binding, not for review runs) and the atomic consumption. It does not describe the return value, but since no output schema exists, this is less critical. The sibling tool context (e.g., github_create_pull_request) clarifies the action's scope, and the description is sufficiently complete for an agent to invoke it correctly.

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 each parameter's purpose. The description adds semantic value by emphasizing that approvalId and approvalVersion must correspond to a single human approval and that they are consumed, which reinforces the optimistic-lock semantics. This goes slightly beyond the schema descriptions but is not a full replacement for them.

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

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

The description clearly states the verb 'squash-merge' and the resource 'GitHub pull request', and specifies the critical precondition of human approval for the same maintenance run. It also differentiates from sibling tools like github_create_pull_request and github_get_pull_request by focusing on the merge action and its approval requirement.

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

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

The description explicitly states when to use the tool ('only after a human approved this exact merge for the same maintenance run') and when not to ('Do not call for pull-request review runs or without the matching approval ID and version'). This provides clear, actionable guidance that distinguishes this tool from alternatives.

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

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

Annotations cover the four hints (readOnly=false, idempotent=false, etc.), and the description adds genuinely useful behavior beyond them: 'This is append-only and repeated calls create distinct evidence records' directly reinforces idempotentHint=false and clarifies the mutation semantics, while immutability and hash-chaining are disclosed nowhere else. This meaningfully augments the annotation profile without contradicting 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?

Three sentences with zero waste: purpose is front-loaded, usage and exclusions follow, and the append-only behavioral note closes it. Every sentence earns its place and no information is repeated from the schema or annotations.

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 4-param (3 required) append tool with no output schema, the definition covers purpose, usage context, security exclusions, behavioral traits, and enum routing. The only absence is a statement about the return value, but for an append-only record tool the response is trivially a confirmation, so this is a minor omission rather than a functional 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 the schema already documents all four parameters including payload's structure and the runId UUID pattern. The description contributes security guidance for payload ('never include credentials or raw secrets') and usage semantics for evidenceType, but the schema does the heavy lifting — baseline 3 is appropriate for a fully documented schema.

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

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

The description states a specific verb ('Append') and resource ('evidence record to an existing RepoPilot run'), and adds precise technical character (immutable, SHA-256 hash-chained). The enum note that proof_publication and review_publication are reserved for dedicated tools helps distinguish it from sibling publication tools, so an agent can pick it apart from alternatives 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?

The description gives explicit when-to-use guidance ('Use after each material decision, tool result, Git reference, CI result, or error') and an exclusion ('never include credentials or raw secrets'). It signals that certain evidenceType values belong to other tools, but stops short of explicitly naming a sibling to use instead in those cases — a minor gap since the enum description already carries that routing.

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 provide idempotentHint=true and readOnlyHint=false, and the description aligns with these by stating idempotent repeats and rejection of conflicting results. It adds behavioral context beyond annotations: it clarifies the state machine (only after Skill stopped), and notes conflict rejection. This exceeds the baseline annotation-only coverage.

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

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

The description is succinct and front-loaded with the main purpose, followed by usage constraints. Each sentence carries weight: purpose, conditionality, and idempotency/conflict behavior. It's not overly verbose, though it could slightly improve by mentioning the sibling alternatives for clarity.

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

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

Given the tool is a terminal action with three parameters and no output schema, the description covers the key context: it's a mutation (readOnlyHint=false), it has idempotency behavior, and it has a post-Skill-stop condition. It doesn't need to explain return values, but something about response or success indication could be added, yet it's not critical for a tool with clear behavior.

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 descriptions already document all three parameters. The description adds context like 'evidence-backed summary' and 'without credentials', but this adds only moderate value beyond the schema. It doesn't explain the impact of 'blocked' or 'skipped' statuses, but the schema already defines them as enums.

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

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

The description clearly states it finishes a RepoPilot Step with a terminal outcome and summary, and it's connected to the Step lifecycle. However, it doesn't explicitly distinguish it from the sibling tools beyond this role; while it references the start and evidence append tools indirectly, it doesn't name them or differentiate beyond 'finish' vs others.

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 provides explicit usage guidance: use only after the associated Skill has stopped, do not use for a running Step, and notes idempotency and rejection of conflicting terminal results. This is clear when-to-use and when-not-to-use guidance, though it doesn't name alternative tools for various scenarios, the guidance is sufficient for correct invocation.

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 idempotentHint: true and destructiveHint: false. The description adds valuable behavioral context: it says the call both creates and updates a marked comment, and it explicitly spells out the idempotency effect ('Repeating the call updates the same marked comment instead of posting duplicates'). It also mentions verification of the evidence chain and redaction, which are not in annotations. No contradiction with annotations.

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

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

Two concise sentences front-load the core action (build, verify, create/update) and then add the critical usage constraint. No filler. Every word contributes to either purpose or condition.

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 no output schema, the description doesn't need to explain return values. It covers the operation, the evidence chain, the idempotency behavior, and the usage restriction. It omits details like required permissions or the exact format of the comment, but those are not essential for invocation given the high schema coverage and annotations. A small gap is the lack of guidance on what to do if the PR wasn't created by this run, though the usage condition implies rejection.

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 schema alone describes all three parameters. The description adds relational context by tying pullNumber to the run's create_pull_request evidence, clarifying that the caller must pass the PR created by that run. This goes beyond the schema's generic 'Pull request created by this run and recorded in its git_reference evidence.'

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

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

The description states a clear verb and resource: 'Build a redacted Proof Bundle... and create or update the run-scoped managed GitHub PR comment.' It distinguishes itself from siblings like repopilot_publish_review_comment and github_create_pull_request by specifically targeting the run-scoped proof comment, so an agent can tell which tool to use.

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 an explicit condition: 'Use only for the PR recorded in that run's create_pull_request evidence.' This tells the agent when this tool is appropriate and implies it should not be used for other PRs. It also notes the idempotent behavior (updates instead of duplicates), but does not name alternative tools as directly as the highest calibration example.

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?

While annotations already provide idempotentHint=true and destructiveHint=false, the description adds meaningful behavioral context beyond that: it is a single managed comment tied to a specific head SHA, it only publishes findings, and it explicitly states it never approves, requests changes, modifies code, or merges. This goes beyond the binary annotation flags and helps the agent anticipate side effects. There is no contradiction with annotations (readOnlyHint=false correctly reflects the write operation).

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

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

The description is two sentences with zero fluff. It front-loads the core action and scope, then provides usage timing and limitations in the same breath. Every sentence earns its place, and the structure is easy to parse.

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

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

For a tool with 7 required parameters, a detailed schema, and no output schema, the description covers everything an agent needs to decide when to call it and what to expect. It specifies prerequisites (after reading diffs/checks), operational context (active review run), and behavioral constraints. The description does not need to repeat schema details; it complements them perfectly.

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 all seven parameters have detailed descriptions. The description adds no additional parameter-specific meaning beyond what the schema already provides (e.g., headSha's SHA binding description matching the schema's note about rejection on head change). With full schema coverage, the baseline of 3 is appropriate; the description's value here is behavioral, not parameter-oriented.

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 action ('Create or update one managed GitHub review summary comment') with precise scope ('for the exact pull request head SHA bound to an active read-only review run'). It clearly differentiates from siblings by explicitly excluding approvals, change requests, code modification, and merging, and implies a specialized review-comment tool rather than generic GitHub comment/PR tools.

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

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

It gives explicit when-to-use guidance: 'Call after reading all relevant diff pages and checks, while the Reviewer Step is running.' It also provides strong exclusions ('never approves, requests changes, modifies code, or merges') that help an agent route to the correct sibling (e.g., github_merge_pull_request for merges, github_create_pull_request for PR creation). No alternative is named, but the conditions are clear enough.

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 the annotations (readOnlyHint=false, destructiveHint=false), the description discloses that the tool 'records the request and may pause the run, but it never executes the requested action.' This adds critical behavioral context about side effects and limitations, which annotations do not convey. It also states the constraint of one action per request.

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

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

Two concise sentences with high information density. The purpose is front-loaded, followed by usage scenarios and a key behavioral clarification. No redundant or verbose wording.

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

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

For a tool with 4 required parameters, two enums, and a nested object, the description covers purpose, usage, and side effects. The schema covers parameter details. No output schema exists, so return values are not expected. The description is sufficient for an agent to select and correctly invoke the 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?

The schema provides 100% coverage for all parameters, including descriptions for runId, action, details, and riskLevel. The description adds no additional parameter-specific meaning beyond what the schema already documents. Per the rubric, with high schema coverage the baseline is 3, and there is no extra semantic value added.

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 ('Create'), resource ('a human approval request'), and scope ('one high-risk action on a maintenance run'). It distinguishes from execution tools by explicitly stating 'it never executes the requested action', making it clear this is a request-creation tool, not an action executor like github_merge_pull_request.

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 explicit use cases: 'Use before merge, branch deletion, rollback, permission changes, secret changes, or another explicitly gated action.' It also implies non-usage for execution, and notes the side effect of possibly pausing the run. This is strong guidance for an agent to know when to invoke this tool versus alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds 'ranked' output and 'verified historical' scope, which are not in annotations. The statement 'does not modify repository or run state' is redundant with annotations but harmless.

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 with no waste. The first sentence front-loads the primary action and resource; the second provides usage timing and a crucial caution. 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?

For a search tool with no output schema, the description sufficiently explains return value ('ranked stored runbooks'), its non-mutating nature, and when to use it. An agent has enough to call correctly without ambiguity.

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

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

Schema description coverage is 100%, so all parameters are already documented in the schema. The description mentions 'failure symptoms or repair terms' which aligns with the query parameter but adds no new information beyond the schema. 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 the verb 'Search' with a specific resource 'verified historical RepoPilot runbooks' and a target repository, using failure symptoms or repair terms. It clearly differentiates from sibling tools, as none of the other repopilot tools are search-focused.

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

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

Explicitly states when to call: 'during triage before selecting a repair strategy' and provides a negative constraint: 'do not use it as proof that a current defect is identical.' This gives clear context for selection.

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

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

Annotations already declare idempotentHint=true, readOnlyHint=false, and destructiveHint=false. The description adds value by explaining that reusing the idempotency key returns the existing Step instead of creating a duplicate, and notes the durable nature of the step. This goes beyond the annotations without contradicting them, providing context on side effects.

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 concise sentences, front-loaded with the primary purpose, then usage context, then idempotency detail. No superfluous words; every sentence earns its place. Well-structured for quick comprehension.

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 tool with 4 required parameters, two enums, and no output schema, the description covers the core workflow, idempotency, and return usage. It doesn't specify error conditions or prerequisites like runId validity, but these are implicit in the domain. The lack of an output schema is mitigated by the explicit mention of returning a Step ID. Adequately complete for an agent to call it correctly.

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 adds meaning by explaining the idempotencyKey's role (reusing it returns the existing Step) and implicitly that the tool returns a Step ID used by repopilot_finish_step. This enriches parameter understanding beyond schema descriptions, justifying a score above 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 clearly states the tool starts a durable Agent Skill execution Step for an existing RepoPilot run, with a specific verb and resource. It also explains the immediate usage context by saying to call it before executing the named Skill and pass the returned Step ID to repopilot_finish_step, distinguishing it from the finish step sibling.

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

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

Provides explicit when-to-use guidance: call immediately before executing the named Skill, and clarifies idempotency behavior for retries. It doesn't explicitly mention alternatives or when not to use it, but the workflow context and mention of the finish step make usage clear. Doesn't exclude other tools but the step-start role is unambiguous.

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 flag readOnlyHint=false and destructiveHint=false, so the description does not need to repeat that. It adds meaningful behavioral context by specifying 'This inserts a new runbook and appends runbook evidence,' which clarifies the side effect beyond the schema. It does not contradict annotations.

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

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

The description is two sentences with zero redundancy. The primary purpose and most critical constraint (verification requirement) are front-loaded, and the operational effect is stated efficiently.

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 write operation with all parameters already documented in the schema, the description provides the essential precondition (verification) and the effect (insert + append evidence). It does not explain what 'runbook evidence' means or what the response looks like, but these are not strictly required for the agent to call the tool correctly, given no output schema and the operation's simplicity.

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

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

Schema description coverage is 100%, meaning every parameter is fully documented in the schema. The description itself provides no additional parameter-level meaning, 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 ('Archive') and resource ('a verified maintenance outcome as a reusable repository runbook'). It clearly differentiates from siblings by explicitly excluding unverified hypotheses and pull-request review runs, making the tool's unique role evident.

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 explicitly states when to use ('only after independent verification for the source run') and when not to ('do not archive an unverified hypothesis or a pull-request review run'). However, it does not name alternative tools for those cases (e.g., repopilot_append_evidence or repopilot_request_approval), so it lacks explicit alternative names.

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