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

No annotations are provided, so the description must disclose behavioral traits. It does reveal that the tool uses AI and returns probable cause, suggested fixes, severity, and a diagnostic report. However, it omits potential side effects like cost, latency, or token usage, and does not state whether the operation is read-only. The disclosure is partial, not comprehensive.

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

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

The description is a single, well-structured sentence that front-loads the core function and lists the expected outputs. Every word contributes value, with no unnecessary repetition or filler. It is appropriately sized for the tool's complexity.

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

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

Given there is no output schema, the description adequately summarizes the return values (probable cause, fixes, severity, report). It covers the essential purpose and outputs. However, it lacks detail on the diagnostic report's structure or any constraints (e.g., run must be completed, API limits), which would make it more complete for an AI-driven 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 input schema already fully documents all three parameters (owner, repo, runId) with descriptions, achieving 100% coverage. The tool description adds no extra parameter semantics beyond what the schema provides, so the baseline score 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 clearly states the tool's function: 'Automatically analyze a failed GitHub Actions workflow run using AI.' It names the specific verb 'analyze', the resource 'failed GitHub Actions workflow run', and the approach 'using AI'. This distinguishes it from sibling tools like github_get_workflow_run (retrieval) and github_rerun_workflow (action).

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

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

The description implies usage for failed workflow runs when AI-driven diagnosis is desired, differentiating from simple retrieval or rerun tools. However, it does not explicitly state when not to use it or mention alternatives (e.g., github_get_workflow_logs for raw logs). The context is clear but exclusions are absent.

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 destructive action ('cancel') and the precondition of run state, but lacks details on permissions, error conditions, or reversibility, leaving some behavioral ambiguity.

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

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

The description is a single, front-loaded sentence with no wasted words. It clearly and efficiently communicates the action and its precondition.

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

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

The tool is simple, but with no output schema and no annotations, the description must provide more context. It covers the essential purpose and precondition but does not mention expected responses, failure modes, or permission requirements. Adequate for basic use, but with clear gaps.

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

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

Schema descriptions cover 100% of parameters, so the baseline is 3. The description does not add extra meaning beyond the schema, though it does highlight that the runId must refer to a queued/in-progress run, which is a slight contextual addition.

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 'cancel' and the resource 'workflow run', and adds a scope condition ('queued or in progress'). This distinguishes it from sibling tools like rerun_workflow or watch_workflow, making the purpose 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 implies the tool should be used when a workflow run is queued or in progress, but it does not explicitly state when not to use it or mention alternative tools. The state constraint provides some guidance, but there is no direct comparison to siblings.

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, leaving the description to carry the full transparency burden. It usefully discloses return values (artifact names, sizes, pre-signed download URLs) and hints at the read-only nature of the operation, but it does not explain URL expiration, permission requirements, or potential rate limits. This is adequate but not rich.

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

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

The description is a single concise sentence that front-loads the action and includes return value information. Every word contributes value, with no redundancy or filler.

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

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

For a simple list/get tool with four well-documented parameters and no output schema, the description adequately covers purpose and return values. It does not mention pagination or limits, but these are unlikely to be critical given the tool's narrow scope and sibling context.

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

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

Schema description coverage is 100%, so the schema already documents all parameters clearly. The description adds minimal parameter-specific context beyond what the schema provides, effectively meeting the baseline but not exceeding it.

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

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

The description clearly states the tool's function: 'List and get download URLs for artifacts produced by a workflow run.' It uses a specific verb and resource, and the focus on artifacts distinguishes it from sibling tools that handle repositories, workflows, runs, and deployments.

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

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

The description provides clear context: use this tool when you need to list artifacts from a workflow run or obtain their download URLs. It does not explicitly mention when not to use it or name alternatives, but among the siblings no other tool handles artifacts, so the intended usage 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?

With no annotations provided, the description carries the full burden of disclosing behavior. It adds value beyond the schema by stating that the tool returns deployment ID, environment, status, ref, and creator, and that the environment filter is optional. It does not mention pagination or rate limits, but for a simple listing operation this is adequate disclosure.

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

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

The description is a single sentence that is direct and free of unnecessary words. It front-loads the primary action and then provides concise supporting details about filtering and return fields. Every word contributes meaning.

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 list operation with 3 well-documented parameters and no output schema, the description is sufficiently complete. It names the return fields, which is important because there is no output schema. It does not explain ordering or pagination, but these are not critical for a basic listing tool given the context of sibling tools that handle more specific actions.

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 provides complete descriptions for all three parameters (repo, owner, environment), so the schema coverage is 100%. The description adds little extra parameter semantics, only echoing the optional nature of the environment filter. It does not go beyond what the schema already states, 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 starts with a clear action verb 'List' and a specific resource 'deployments for a repository', immediately distinguishing it from sibling tools that handle workflows or repositories. The optional environment filter adds precision without confusion.

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

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

The description implies when to use this tool (when listing deployments for a repo) but provides no explicit guidance on when not to use it or which alternative to prefer. Since there is a sibling 'rollback_deployment' that also involves deployments, a note about using this to inspect before rolling back would have been helpful, but the core usage is 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?

With no annotations, the description carries full burden. It discloses that logs are parsed and returned as structured per-job logs with error extraction, which is useful. However, it does not mention potential limitations, authentication requirements, or failure behavior, leaving gaps in transparency.

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

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

Two sentences, front-loaded with the core action, and no filler. Every word contributes to understanding the tool's purpose and output.

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 simple parameter set and lack of output schema, the description reasonably conveys that the return is structured per-job logs with error extraction. It could detail the structure further, but it is adequate for an agent to understand what to expect.

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 documents all three parameters (owner, repo, runId) with 100% coverage. The description adds no extra parameter-level meaning beyond restating that logs are retrieved for a specific run, so it meets the baseline without adding 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 uses specific verbs ('Retrieve and parse') and a clear resource ('execution logs for a specific workflow run'). It clearly distinguishes itself from siblings like github_get_workflow_run by focusing on logs rather than run metadata.

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 'for a specific workflow run' implies the need for a run ID and a scenario where logs are required. However, it does not provide explicit guidance on when to prefer this tool over alternatives like github_analyze_failure or github_get_workflow_run, leaving the choice somewhat implicit.

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

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

With no annotations provided, the description carries the full burden for behavioral disclosure. It correctly implies a read-only operation via 'Get' and adds useful context about jobs and statuses, but it does not mention prerequisites, error behavior, authentication needs, or rate limits. This is adequate but not thorough.

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

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

The description is a single clear sentence (16 words) that front-loads the main action ('Get detailed information') and states the key scope. Every word earns its place; there is no fluff.

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

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

For a simple read tool with three required parameters and no output schema, the description adequately covers the essential return value ('including its jobs and their statuses'). It is reasonably complete given the tool's low complexity, though it could hint at sibling distinctions more explicitly.

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 provides 100% coverage with descriptions for owner, repo, and runId, so the description adds no additional meaning about the parameters. According to the baseline for high schema coverage, this scores a 3.

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

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

The description uses a specific verb and resource ('Get detailed information about a specific workflow run') and adds unique scope by mentioning 'including its jobs and their statuses,' which distinguishes it from sibling tools like github_list_workflow_runs (listing) and github_get_workflow_logs (raw logs).

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

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

The description implies this tool is for fetching details of a single run (as opposed to listing runs or getting logs), but it does not explicitly state when to use it over alternatives or provide exclusions. It lacks direct guidance such as 'for logs, use github_get_workflow_logs.'

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

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

With no annotations, the description carries the burden. It discloses the accessible scope and the specific return fields, which gives useful behavioral context. It does not mention pagination, rate limits, or that it's a read-only operation explicitly, but 'List' implies no 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?

The description is two sentences with no wasted words. It front-loads the primary action and then lists the return fields, making it highly efficient and scannable.

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?

This is a simple tool with one optional parameter and no output schema. The description lists the return fields, which is helpful, but it doesn't mention the default type behavior or pagination. Given its simplicity, it is nearly complete but could be more explicit about how the 'type' filter affects results.

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

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

The schema provides 100% coverage for the single 'type' parameter, including its enum values and default. The description adds no additional parameter-specific information, 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 clearly states the verb 'List' and the resource 'GitHub repositories', and adds the scope 'accessible with the current token'. It also lists the returned fields, making it distinct from sibling tools that focus on workflows and deployments.

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

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

The description implies the tool is for listing repositories available to the authenticated token, which is clear context. However, it does not explicitly mention when to prefer this over sibling tools or any exclusions, so it misses 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?

With no annotations provided, the description carries full burden. It accurately describes the read operation but does not disclose ordering, pagination behavior, or that logs are not returned (which github_get_workflow_logs covers). No contradictions with annotations since none exist.

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

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

A single, well-structured sentence with a leading verb and clear object. Every word earns its place; 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?

Given a moderate parameter set and no output schema, the description is sufficient: it names the purpose and optional filters. It could further describe return shape or ordering, but the schema covers parameters and the tool is straightforward. The combination is adequate for an AI agent to invoke 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 parameters are already documented. The description adds marginal value by mentioning status and branch filters, but does not enrich understanding of perPage, workflowId, or other parameters beyond what the schema provides.

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

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

The description uses a specific verb 'List' with a clear resource 'recent runs of a GitHub Actions workflow' and mentions optional filters. This clearly differentiates from sibling tools like github_list_workflows (which lists workflow definitions) and github_get_workflow_run (which gets a single run).

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 states what the tool does and that filters exist, but provides no explicit guidance on when to use it versus alternatives. No exclusions or alternative tool references are given, so usage context is only implied by the name and sibling list.

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

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

With no annotations provided, the description bears the full burden of behavioral disclosure. It adds the context that it lists 'all' workflows in a specific repository, but it does not mention potential pagination, authentication needs, or return format. This is some value but not comprehensive.

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

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

The description is a single, front-loaded sentence with no unnecessary filler. It is appropriately sized for the tool's simplicity.

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 straightforward list operation with a fully described schema, the description is adequate. It clearly states the action and scope, though it does not describe the return structure. Given that no output schema exists, a brief mention of return values could improve completeness, but it is not essential.

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?

Both parameters are fully described in the input schema (100% coverage), so the description adds no additional parameter semantics. The baseline of 3 is appropriate since the schema handles the parameter meaning.

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

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

The description clearly states the tool's function with a specific verb ('List'), resource ('GitHub Actions workflows'), and scope ('defined in a repository'). This distinguishes it from sibling tools like github_list_workflow_runs and github_list_repositories.

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

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

The description implies when to use the tool (when you need to list workflows in a repository) but provides no explicit guidance on when not to use it or what alternatives exist. No comparisons to sibling tools are mentioned.

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 must carry the full behavioral disclosure. It states the start/stop action and return value, but does not disclose side effects such as idempotency, whether resources are consumed, or what happens to existing monitors. It also omits permission requirements or rate limit implications.

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 concise sentences, front-loaded with the primary action and return behavior. There is no unnecessary wording or repetition.

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

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

The description provides the essential purpose and return value, which is adequate for a simple tool. However, it does not clarify how the 'list' action interacts with the return statement, nor does it elaborate on operational effects, leaving some gaps given the absence of an output schema and 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?

The schema already provides 100% coverage for all three parameters (owner, repo, action) with descriptions for each. The tool description does not add parameter-level detail beyond what the schema offers, so the baseline score 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 clearly states the tool starts or stops continuous monitoring of a repository's GitHub Actions, using specific verbs and a clear resource. It also mentions the return of the currently monitored repositories, which distinguishes it from sibling tools that list workflows or runs rather than managing monitoring.

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 explicit guidance is provided on when to use this tool versus alternatives like github_watch_workflow or the list tools. The description implies usage for managing monitoring but does not mention prerequisites, exclusions, or when to choose another 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?

With no annotations, the description carries the behavioral disclosure burden. It communicates the key behavioral distinction between rerunning all jobs and only failed jobs, but does not mention side effects such as creating a new run, permission requirements, or any rate limits. This is adequate but not rich.

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

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

The description is two sentences, front-loaded with the core action, and immediately explains the only decision point (mode). Every word earns its place, with no redundant or tangential 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?

For a simple rerun operation with a fully described schema, the description covers the essential behavior and mode choice. It lacks preconditions such as the run needing to be in a completed state, but overall it is sufficiently complete for an agent to invoke the tool 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%, meaning every parameter already has a clear description. The tool description merely restates the mode enum, adding no new semantic detail beyond what is in the schema. This meets the baseline but does not exceed it.

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

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

The description uses the specific verb 'Rerun' and resource 'GitHub Actions workflow', making the tool's function unambiguous. It is clearly distinguished from sibling tools like github_cancel_workflow or github_list_workflow_runs.

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 explains the two operational modes ('all' vs 'failed') which is helpful for parameter selection, but it gives no explicit guidance on when to use this tool versus alternatives like github_cancel_workflow. The intended use case is implied rather than explicitly stated.

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

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

With no annotations provided, the description carries the full burden. It discloses the core behavior (creating a new deployment and marking the current one inactive), which is more than just stating 'rollback'. However, it does not explain side effects like whether the operation triggers workflows, requires special permissions, or is irreversible, and it leaves ambiguous whether marking inactive only happens when currentDeploymentId is supplied.

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

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

The description is a single, well-structured sentence that conveys the essential action without fluff. It earns its place completely, with no redundant information.

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

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

Despite full schema parameter descriptions and clear purpose, the description is incomplete for a mutation tool without annotations. It does not clarify the role of the optional currentDeploymentId (whether marking inactive is conditional), how to obtain that ID, what the API returns, or whether the action is asynchronous. More context is needed to safely invoke the tool effectively.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds minimal extra meaning beyond the schema, only referencing 'specific ref' and 'current deployment' which map to ref and currentDeploymentId. It does not enrich the parameter understanding beyond what the schema already provides.

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

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

The description clearly states the tool's function: rolling back a deployment by creating a new deployment to a specific ref and marking the current one inactive. This is a specific verb+resource combination that distinguishes it from sibling tools like github_get_deployments which only lists deployments.

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

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

The description implies the tool is used for rolling back deployments, but it does not provide explicit guidance on when to use it versus alternatives, nor does it mention prerequisites such as obtaining the current deployment ID via github_get_deployments. No exclusions or 'when not to use' are stated.

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

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

With no annotations provided, the description carries the full burden. It discloses specific behavioral details: polls every 10 seconds, times out after 5 minutes, and returns final status and conclusion. This goes beyond a simple 'watch' statement, though it doesn't specify timeout error behavior or whether it's read-only.

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 concise sentences with no wasted words. It front-loads the core purpose and includes essential operational details in a compact form.

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

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

Given no output schema, the description appropriately explains the return behavior (final status and conclusion) and the operational constraints (polling, timeout). It is slightly incomplete in not stating what happens on timeout, but is otherwise sufficient for a watch tool with well-documented parameters.

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

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

The input schema has 100% description coverage for all three parameters (owner, repo, runId), so the schema already explains them fully. The description adds no additional parameter-level meaning, warranting the baseline score of 3.

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

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

The description uses a specific verb 'Watch' with a clear resource ('workflow run') and scope ('until it completes'), distinguishing it from a single-fetch tool like github_get_workflow_run. It also mentions the timeout and polling behavior, which makes the purpose unmistakable.

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

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

The description clearly implies when to use this tool: when you need to wait for a workflow to finish and get the final status. It does not explicitly name alternatives or state when not to use it, but the polling/timeout context makes the usage scenario clear.

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