Skip to main content
Glama
Sign In

Damper

by com.usedamper
OverviewDiscussionsAdmin

Request Review

request_review

Lightweight hand-off into review: move an in_progress task to in_review as soon as a human could review it (a working slice, an opened PR, attached screenshots or API examples, or when you are about to stop for the session). Do not leave reviewable work in in_progress. No checklist, PR, or self-assessment is required, and no user confirmation is needed — it is reversible and does not commit or merge. complete_task still needs confirmation.

Requirements: the task must be in_progress and you must hold its lock (from start_task).

Effect: status becomes in_review, the lock is released (so reviewers can act on it), and your session is closed. A reviewer approves or sends it back with feedback; resume with start_task if it comes back.

Stage: complete (default) means the task is finished pending review. partial means a reviewable slice with more work to follow: approving it returns the task to in_progress instead of done.

complete_task on a task waiting for a stage review requested here is rejected until the reviewer decides.

Review evidence: the hand-off is checked against the project's review evidence policy for the change scope: checklistScope and touchedPaths passed here, unioned with what prepare_completion recorded; prepare_work's expected paths count per the project's plannedScope (default: only when nothing else is known). Each kind's level comes from its base level and the project's rules; preview it with get_completion_checklist and your scope. Missing required API examples, screenshots or diagrams block it with error code review_evidence_missing, naming each missing kind and the change kinds/surfaces that need it. Attach them (add_api_example, add_screenshot, add_diagram) or, when they genuinely do not apply, pass evidenceNotApplicable with the reason (recorded on the timeline). A partial stage only warns unless the project sets partialStageEvidence: "block"; projects with checkDirectDone also check moving a task straight to done. After a review decision, only artifacts attached since that decision count, so each round carries evidence for what it changed. Approving the review re-checks the same evidence. Call prepare_completion first to see what is missing.

Review instructions: optional steps for the reviewer. They are PUBLICLY VISIBLE on the roadmap while the item is in review — keep credentials, internal paths, and private URLs out of them.

Preview: pass previewUrl when the change is running somewhere the reviewer can open (e.g. a Tailscale URL); it is internal only and never shown publicly.

Waiting: if your Damper CLI is 0.13.0 or newer (damper --version), run damper review wait <taskId> as a background command (exit 10 = needs work, 0 = approved, 2 = timed out, 1 = error). Older CLIs don't have this command: poll get_task instead.

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": {
      "projectId": "<projectId>",
      "taskId": "<taskId>",
      "summary": "<summary>"
    },
    "name": "request_review"
  }
}

Input Schema

NameRequiredDescriptionDefault
stageNo"complete" (default): finished pending review. "partial": a reviewable slice, more work follows; approval returns the task to in_progress.
taskIdYes
summaryYesWhat is reviewable right now, written for the reviewer.
projectIdYesProject ID. Use list_projects to find available project IDs.
previewUrlNoOptional http(s) URL where the reviewer can open the running change, e.g. a Tailscale URL like http://laptop.tailnet.ts.net:5173. Private hosts are fine (it is never fetched by the server). INTERNAL: shown only to reviewers in the dashboard, never on public roadmaps. Pass null to clear.
touchedPathsNoRepository-relative paths this hand-off changed; their routed change kinds and surfaces join the scope.
checklistScopeNoScope of what this hand-off changed; decides which review evidence is required.
reviewInstructionsNoWhat the reviewer should test or verify (markdown). PUBLICLY VISIBLE while the item is in review — keep credentials, internal paths, and private URLs out of it.
evidenceNotApplicableNoWhy required review evidence does not apply to this hand-off (e.g. "copy-only change, no rendered page"). Recorded on the task timeline.

Output Schema

NameRequiredDescriptionDefault
idYes
stageYes
statusYes
messageNo
evidenceNo
dashboardUrlNoFull dashboard URL of the affected resource

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Adds substantial behavior beyond the annotations: it discloses that the lock is released and the session closed, that the operation is reversible and does not commit or merge, that no user confirmation is needed, and that approval may return the task to in_progress under a partial stage. It also names the failure mode and error code (review_evidence_missing) and the post-decision artifact-counting rule, which the destructiveHint/readOnlyHint hints do not convey.

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?

Long, but front-loaded and segmented with bold headers (Requirements, Effect, Stage, Review evidence, Review instructions, Preview, Waiting), so an agent can scan to the needed section. A few lines restate the same idea ('no checklist, PR... is required' and 'Do not leave reviewable work in in_progress' both push the same nudge), which keeps it just short of a 5.

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 9-parameter, mutation-flavored tool with nested objects and an evidence policy, the description covers prerequisites, effects, failure codes, sibling tool interactions, and the human-review loop end to end. Output schema exists, so return values need not be explained, and nothing an agent needs in order to call this correctly appears to be 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?

With 89% schema description coverage the schema already documents most parameters, but the description still adds real semantics: the behavioral consequence of the 'stage' enum (approval returning to in_progress, warning vs block under partialStageEvidence), how checklistScope and touchedPaths union with prepare_completion's recorded scope, what plannedScope does by default, and the public-visibility risk of reviewInstructions. Only previewUrl's null-clearing and a few minor precedence details are left to the schema.

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 precise verb and state transition ('move an in_progress task to in_review') rather than restating the name, and immediately distinguishes itself from sibling mutations by noting that 'complete_task' still needs confirmation and that 'complete_task' on a stage-review task is rejected. An agent can tell it apart from complete_task and review_task without opening any schema.

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 explicit trigger conditions ('as soon as a human could review it', 'when you are about to stop for the session'), an explicit prohibition ('Do not leave reviewable work in in_progress'), prerequisites (must be in_progress and hold the lock from start_task), a routing alternative ('Call prepare_completion first to see what is missing'), and per-CLI-version waiting instructions. Both when and when-not are covered.

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

All Damper toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources