Skip to main content
Glama

mark_vcs_deployed

Idempotent

Record a PR/MR link's deployed commit, environment, and timestamp so dependent tasks waiting on deployment can be released.

Instructions

Record that the change behind a PR/MR link is deployed: sets deployed_sha, deployed_env and deployed_at (now) on the link and releases the dependents waiting on a deployed dependency edge of this card. Reporting the same sha and env again is safe: the first deployed_at stands. The link must be a pr link of task_id (link ids are in get_task vcs_links and in the add_vcs_link result).

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>",
      "link_id": "<link_id>",
      "sha": "<sha>",
      "env": "<env>"
    },
    "name": "mark_vcs_deployed"
  }
}

Input Schema

NameRequiredDescriptionDefault
envYesEnvironment, 1-32 chars of a-z, 0-9, _ or -, e.g. prod. Only prod releases a `deployed` edge by itself; other environments need verified evidence.
shaYesThe deployed commit, 40 lowercase hex.
link_idYesVCS link ID.
task_idYesTask ID.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.1.7
    • changedInput schema / properties / env / description
      Previous value: -"Environment, 1-32 chars of a-z, 0-9, _ or -, e.g. production."New value: +"Environment, 1-32 chars of a-z, 0-9, _ or -, e.g. prod. Only prod releases a `deployed` edge by itself; other environments need verified evidence."
  2. Addedv0.1.6

TDQS

A4.5/5.0
Behavior5/5

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

Goes well past the annotations: annotations say idempotent, and the description explains what that means concretely ('the first deployed_at stands'), which is real behavioral detail. It also discloses a side effect annotations cannot express — releasing dependents waiting on a `deployed` dependency edge — plus the precondition that the link must be a pr-type link.

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 core action and effects, then the idempotency guarantee, then the link-type precondition. Three dense sentences with no filler, though the parenthetical on link-id provenance could be tightened.

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 mutating tool with no output schema, it covers the mutation target, the side effect on dependents, idempotency, and the precondition. The only gap is that it does not indicate what is returned (e.g. which dependents were released), which would help an agent act on the result.

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; the description adds value by specifying that link_id must reference a pr link belonging to task_id and by telling the agent where link ids are found. The sha/env field semantics are left to the schema, which already documents them well, so this is above baseline but not exhaustive.

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 ('Record that the change behind a PR/MR link is deployed') and enumerates exactly what gets mutated: deployed_sha, deployed_env, deployed_at. It also names the cross-resource effect (releasing dependents on a `deployed` edge), which no sibling tool does, so the agent can distinguish it from add_vcs_link.

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 clear preconditions and routing: the link must be a pr link of task_id, and link ids come from get_task vcs_links or the add_vcs_link result. It also states the repeat-call case is safe. It stops short of naming explicit when-not-to-use cases or which sibling to pick for non-prod evidence, so it is not a full 5.

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