Skip to main content
Glama

Watch workflow run

watch_workflow_run
Read-only

After committing to a repo (github_commit_files returns commit_sha), register a watch on the CI run that commit triggers, then finish your turn — the platform wakes this conversation with the run's conclusion (or a timeout notice). Never busy-poll workflow runs while waiting. Identify the run by head_sha (the commit you just pushed) or an explicit run_id; branch disambiguates head_sha lookups.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "owner": "<owner>",
      "repo": "<repo>"
    },
    "name": "watch_workflow_run"
  }
}

Input Schema

NameRequiredDescriptionDefault
repoYesRepository name.
ownerYesRepository owner (organisation or user).
branchNoBranch name to disambiguate head_sha lookups.
run_idNoExplicit workflow run id to watch; alternative to head_sha.
head_shaNoCommit SHA whose workflow run to watch (e.g. the commit_sha returned by github_commit_files). One of head_sha/run_id is required.
timeout_minutesNoMinutes to keep watching before the platform reports a timeout instead (default 30, max 60).

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.5/5.0
Behavior4/5

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

Annotations only declare readOnlyHint=true, so the description carries the real burden and does well: it explains the async contract — the tool registers a watch, the agent ends its turn, and the platform wakes the conversation with the run conclusion or a timeout notice. It does not say what happens on an invalid head_sha/run_id or whether concurrent watches are limited, leaving failure behavior undisclosed.

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

Conciseness5/5

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

Three tight sentences: the action and its trigger first, the anti-pattern next, then the selector semantics. No restatement of the title or schema and no filler.

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

Completeness5/5

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

There is no output schema, and the description compensates by describing what the agent will receive (the run's conclusion or a timeout notice) and how the turn ends. Combined with the fully documented schema, an agent has everything needed to invoke it correctly.

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

Parameters4/5

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 cross-tool meaning: head_sha should be the commit_sha returned by github_commit_files, run_id is the alternative selector, and branch disambiguates head_sha lookups. That relationship between parameters is not derivable from the schema alone.

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

Purpose5/5

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

Specific verb+resource ('register a watch on the CI run that commit triggers') with an explicit scope statement and a named prerequisite tool (github_commit_files → commit_sha). It is clearly distinguishable from polling-style siblings such as github_list_workflow_runs or github_get_workflow_run_jobs.

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

Usage Guidelines4/5

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

Gives a concrete trigger ('after committing to a repo') and an explicit prohibition ('Never busy-poll workflow runs while waiting'), which is exactly the when-not guidance an agent needs. It stops short of naming the sibling alternatives it replaces (e.g. watch_pipeline_run, wait_for_execution), so the routing among watch-style tools is left to inference.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.