Skip to main content
Glama

add_vcs_link

Links a task to a pull request, commit, or branch, creating the task↔PR join that PR-driven status automation and shipped-work reports rely on. Only a task ID and GitHub or GitLab URL are required.

Instructions

Link a task to a pull request, commit, or branch. The link is the task↔PR join that PR-driven status automation and 'what shipped for this task?' reports read. Only task_id and url are needed — provider, link_type and external_id are inferred from a GitHub or GitLab URL. The optional status parameter ('merged' or 'closed') records a PR that was already merged or closed before it was linked. Without it the link starts as 'open', and the done-evidence gate blocks move→done on it, since no GitHub webhook fires for a merge that happened before the link existed.

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": {
      "task_id": "<task_id>",
      "url": "<url>"
    },
    "name": "add_vcs_link"
  }
}

Input Schema

NameRequiredDescriptionDefault
urlYesLink URL, e.g. https://github.com/owner/repo/pull/123.
roleNo'review' (the only value) marks the PR as the subject this task reviews or signs off, not the task's own work: its being unmerged no longer blocks move→done. Never set it on the PR that implements the task. To mark a link that already exists, call again with status='open' (or its current status) and role='review'.
titleNoHuman-readable label, e.g. the PR title.
ci_shaNoCommit the CI verdict ran on, 40 hex.
statusNoPR status, if you already know it: open, merged, closed. Pass 'merged' when linking a PR that was merged before this call — that is the one case a webhook can never backfill. Omit it to let the link start as 'open' (the safe default when the PR is still active). Calling add_vcs_link again on the same PR with a status update is safe — it corrects the existing link rather than failing.
task_idYesTask ID.
providerNoVCS provider: github, gitlab. Inferred from the URL host; defaults to github.
ci_statusNoDelivery state: CI verdict status (pending, running, success, failed, canceled, skipped, manual). Use ci_pipeline_id and ci_sha for the pipeline and commit it ran on.
link_typeNoWhat the URL points at: pr (alias: pull_request), commit, branch. Inferred from the URL path; defaults to pr.
merged_shaNoDelivery state: the commit the MR merged as on the target branch, 40 hex.
deployed_atNoRFC3339 deploy time; defaults to now.
environmentNoEnvironment of deployed_sha, e.g. prod or staging.
external_idNoPR number, commit SHA, or branch name. Inferred from the URL; only needed when the URL is not a recognised PR/commit/branch link.
deployed_shaNoDelivery state: the commit now running in `environment`, 40 hex. Requires environment. The link counts as shipped only when this equals merged_sha on environment=prod. Reporting the same sha and environment again keeps the first deployed_at.
acceptance_byNoWho accepted.
acceptance_shaNoCommit the acceptance covered, 40 hex.
ci_pipeline_idNoPipeline id of the CI verdict.
acceptance_resultNoDelivery state: live acceptance result, passed or failed — separate from CI and deploy. Add acceptance_by, acceptance_evidence_url and acceptance_sha for who, proof and the commit it covered.
implementation_shaNoDelivery state (pr links): the commit the change was implemented at, 40 hex.
acceptance_evidence_urlNoLink to the acceptance proof.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.1.7
    • addedInput schema / properties / role
      Added value: +{
      +  "description": "'review' (the only value) marks the PR as the subject this task reviews or signs off, not the task's own work: its being unmerged no longer blocks move→done. Never set it on the PR that implements the task. To mark a link that already exists, call again with status='open' (or its current status) and role='review'.",
      +  "type": "string"
      +}
  2. Changed12 schema fields changedv0.1.6
    • addedInput schema / properties / acceptance_by
      Added value: +{
      +  "description": "Who accepted.",
      +  "type": "string"
      +}
    • addedInput schema / properties / acceptance_evidence_url
      Added value: +{
      +  "description": "Link to the acceptance proof.",
      +  "type": "string"
      +}
    • addedInput schema / properties / acceptance_result
      Added value: +{
      +  "description": "Delivery state: live acceptance result, passed or failed — separate from CI and deploy. Add acceptance_by, acceptance_evidence_url and acceptance_sha for who, proof and the commit it covered.",
      +  "type": "string"
      +}
    • addedInput schema / properties / acceptance_sha
      Added value: +{
      +  "description": "Commit the acceptance covered, 40 hex.",
      +  "type": "string"
      +}
    • addedInput schema / properties / ci_pipeline_id
      Added value: +{
      +  "description": "Pipeline id of the CI verdict.",
      +  "type": "number"
      +}
    • addedInput schema / properties / ci_sha
      Added value: +{
      +  "description": "Commit the CI verdict ran on, 40 hex.",
      +  "type": "string"
      +}
    • addedInput schema / properties / ci_status
      Added value: +{
      +  "description": "Delivery state: CI verdict status (pending, running, success, failed, canceled, skipped, manual). Use ci_pipeline_id and ci_sha for the pipeline and commit it ran on.",
      +  "type": "string"
      +}
    • addedInput schema / properties / deployed_at
      Added value: +{
      +  "description": "RFC3339 deploy time; defaults to now.",
      +  "type": "string"
      +}
    • addedInput schema / properties / deployed_sha
      Added value: +{
      +  "description": "Delivery state: the commit now running in `environment`, 40 hex. Requires environment. The link counts as shipped only when this equals merged_sha on environment=prod. Reporting the same sha and environment again keeps the first deployed_at.",
      +  "type": "string"
      +}
    • addedInput schema / properties / environment
      Added value: +{
      +  "description": "Environment of deployed_sha, e.g. prod or staging.",
      +  "type": "string"
      +}
    • addedInput schema / properties / implementation_sha
      Added value: +{
      +  "description": "Delivery state (pr links): the commit the change was implemented at, 40 hex.",
      +  "type": "string"
      +}
    • addedInput schema / properties / merged_sha
      Added value: +{
      +  "description": "Delivery state: the commit the MR merged as on the target branch, 40 hex.",
      +  "type": "string"
      +}
  3. First observedv0.1.1

TDQS

A4.3/5.0
Behavior4/5

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

Annotations only declare it is a non-read-only, non-destructive, non-idempotent write. The description adds genuinely behavioral context the annotations cannot: the default 'open' status, the done-evidence gate that blocks move→done on an unmerged link, and the fact that no webhook can backfill a pre-existing merge. It does not discuss permissions or failure modes beyond that.

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

Conciseness4/5

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

Front-loaded with the action, then the purpose, then the minimal call shape, then the one non-obvious edge case. Every sentence carries information, though the merged-before-linking rationale is stated here and again in the status schema entry, which is slightly redundant.

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

Completeness4/5

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

For a 20-parameter mutation the description covers the critical decision points (required fields, status default, the done-gate consequence) while the schema documents the delivery-state fields in detail, and no output schema exists to explain. Coverage of the deploy/acceptance parameter family is left entirely to the schema, which is acceptable given 100% coverage but means the description alone would not orient an agent to that half of the tool.

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% and the per-parameter text is unusually rich, so the baseline is 3; the description earns an extra point by framing the call shape for a 20-parameter tool — only two fields are needed and the rest are inferred from the URL. The status default/override semantics are reinforced here in plain language.

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?

States a specific verb and resource ("Link a task to a pull request, commit, or branch") and then clarifies what the link actually is — the task↔PR join consumed by PR-driven automation and shipped-work reports. That distinguishes it from a generic comment/note tool and tells an agent exactly what artifact is being created.

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 concrete when-to-use guidance: only task_id and url are required because provider, link_type and external_id are inferred, and it explains the one case where the optional status must be supplied (a PR merged/closed before the link existed). It stops short of naming an alternative tool for post-link delivery-state updates, so the boundary for CI/deploy/acceptance fields is left implicit.

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