Skip to main content
Glama

review_story

Runs a code review on a dispatched story's tests-passed branch; on approval, opens a pull request and sets status to pr_open, otherwise records changes_requested. Never merges.

Instructions

Run the code-reviewer persona over a dispatched story's branch. On APPROVE, open a PR via gh and set status to pr_open; otherwise set status to changes_requested. Does not merge — merge is the overlord's decision.

Only reviewable when story["status"] == "tests_passed" - any other status (a stale/duplicate call, e.g. a second tick racing an already-merged story) is a no-op skip; see README.md's "Review & merge" section.

force (default false) is the explicit, audited way to re-run a review the unchanged-since-last-review skip would otherwise decline: it clears the story's last-reviewed markers (last_reviewed_sha, the reviewing-logic fingerprint and skip_notified_sha) so the review actually runs, and records one story:force_review audit entry. The first review after a force has no last_reviewed_sha and is therefore a first-style full-branch review of HEAD, not a since_sha rework diff. It refuses (changing nothing) while a detached review job holds the story, and for any status but tests_passed; it never merges anything, and it leaves review_verdict, review_feedback and the rework budget alone, so a forced review counts against that budget like any other.

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": {
      "plan_name": "<plan_name>",
      "story_key": "<story_key>"
    },
    "name": "review_story"
  }
}

Input Schema

NameRequiredDescriptionDefault
forceNo
plan_nameYes
story_keyYes

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.10.0
    • addedInput schema / properties / force
      Added value: +{
      +  "default": false,
      +  "title": "Force",
      +  "type": "boolean"
      +}
  2. First observedv0.1.0

TDQS

A4.5/5.0
Behavior4/5

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

With no annotations supplied, the description carries the full burden and does so well: it names side effects (gh PR creation, status write), the audit entry emitted, the specific markers cleared by force, and the refusal condition while a detached review job holds the story. It also discloses what force does NOT touch (review_verdict, review_feedback, rework budget), which is exactly the kind of detail an agent needs before mutating state.

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

Conciseness3/5

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

Front-loaded and logically ordered, but the force paragraph is dense and repeats ground already covered ("it never merges anything" restates "Does not merge" from the opening). The README cross-reference and the enum-of-cleared-markers list add bulk that could be tightened without losing meaning.

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?

For a stateful, multi-outcome mutation tool this covers preconditions, both branches, the force escape hatch, refusal cases, and side-effect scope. An output schema exists, so return values need no explanation, and nothing an agent needs in order to call it safely is missing.

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 0%, so the description must compensate, and it does so decisively for force: default false, what it clears, what audit record it writes, and that the first post-force review is a full-branch HEAD review rather than a since_sha diff. plan_name and story_key are left to their names alone, which is a gap for a 0%-coverage schema but a minor one given they are ordinary identifiers.

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?

Opens with a specific verb and resource ("Run the code-reviewer persona over a dispatched story's branch") and immediately states the two possible outcomes: PR opened plus status pr_open on APPROVE, status changes_requested otherwise. The explicit boundary "Does not merge — merge is the overlord's decision" separates it from approve_merge among the siblings.

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

Usage Guidelines5/5

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

Gives a hard precondition (story["status"] == "tests_passed"), explains that any other status is a deliberate no-op skip including the racing-tick case, and points to the README section for context. It also spells out exactly when force is the right mechanism versus letting the skip fire, and when force itself refuses.

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