proofcut

Overview Schema Source Related Servers Discussions Admin

review_add

Destructive

Register an existing render, sheet, or A/B member for a review round by pointing a name at its file—no copying. Controls must match a baseline's sha256 to be accepted.

Instructions

Never copies source — a render already lives in renders/, a sheet in reframe_sheet's own directory — this just points name at it, so a served round has something to stream and a verdict has something to attach to.

Registering a name that already exists replaces that entry, and the verdict recorded against it stays — so re-pointing a name at a different file leaves yesterday's answer attached to today's bytes. Register the new file under a new name unless replacing it is what you mean.

kind is one of render, sheet, ab, control. A control requires baseline, the name of an already-registered item, and the two files' sha256 must match — a mismatch refuses the call. This is the rule the round that went wrong exists to enforce (HISTORY.md § The bumper the teaser never had): a page once served three cuts, one mislabelled "control" when it was a different, later render. Nothing is labelled a control here unless it is byte-identical to what it claims.

Input Schema

TableJSON Schema

Name	Required	Description
`kind`	Yes	One of `render`, `sheet`, `ab`, `control`.
`name`	Yes	What to call this item in the served round. Re-using a name replaces that entry while its verdict stays attached.
`path`	No	The project directory to act on. Omit it — the usual case — when this server is bound to a project (started as `proofcut -C DIR mcp`, or inside a project; `ping` says which): it then resolves to that one bound project, a relative path resolves against it, and a path outside it is refused by name. Unbound, `path` is the whole address and omitting it refuses rather than guessing.
`source`	Yes	The file to point at — never copied. A render already lives in `renders/`, a sheet in the sheet directory.
`baseline`	No	Required for `kind="control"`: the name of the already-registered item this one claims to be identical to. Both files' sha256 must match or the call is refused — nothing is labelled a control here unless it is byte-identical to what it claims.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed15 schema fields changedv0.25.0Sep 16, 2026

removedInput schema / properties / baseline / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedInput schema / properties / baseline / description

Added value: +"Required for `kind=\"control\"`: the name of the already-registered item this one claims to be identical to. Both files' sha256 must match or the call is refused — nothing is labelled a control here unless it is byte-identical to what it claims."

removedInput schema / properties / baseline / title
```
Removed value: -"Baseline"
```
addedInput schema / properties / baseline / type
```
Added value: +[
+  "string",
+  "null"
+]
```

addedInput schema / properties / kind / description

Added value: +"One of `render`, `sheet`, `ab`, `control`."

removedInput schema / properties / kind / title
```
Removed value: -"Kind"
```

addedInput schema / properties / name / description

Added value: +"What to call this item in the served round. Re-using a name replaces that entry while its verdict stays attached."

removedInput schema / properties / name / title
```
Removed value: -"Name"
```

removedInput schema / properties / path / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedInput schema / properties / path / description

Added value: +"The project directory to act on. Omit it — the usual case — when this server is bound to a project (started as `proofcut -C DIR mcp`, or inside a project; `ping` says which): it then resolves to that one bound project, a relative path resolves against it, and a path outside it is refused by name. Unbound, `path` is the whole address and omitting it refuses rather than guessing."

removedInput schema / properties / path / title
```
Removed value: -"Path"
```

addedInput schema / properties / path / type

Added value: +[
+  "string",
+  "null"
+]

addedInput schema / properties / source / description

Added value: +"The file to point at — never copied. A render already lives in `renders/`, a sheet in the sheet directory."

removedInput schema / properties / source / title
```
Removed value: -"Source"
```
removedInput schema / title
```
Removed value: -"review_addArguments"
```

First observedv0.24.0Sep 15, 2026

TDQS

A4.8/5.0

Behavior5/5

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

The description goes well beyond the annotations (destructiveHint=true) by detailing that registering an existing name replaces that entry while keeping its verdict, and that a control requires byte-identical sha256 or the call is refused. It also explains the non-copying behavior and the historical rationale. This is rich, specific behavioral disclosure that matches the destructive hint.

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?

The description is well-structured: it states the core purpose in the first sentence, then clarifies non-copying, then explains replacement semantics, and finally details the control rule with a historical note. Every sentence earns its place; nothing is redundant. It is appropriately sized for the complexity.

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?

Given the presence of an output schema and rich annotations, the description covers all essential operational aspects: behavior, side effects, constraints, and usage context. It even includes a rationale for the control rule. An agent has everything needed to invoke this tool correctly without further lookup.

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

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema coverage, the baseline is 3, but the description adds substantial meaning: it explains that `source` is never copied, that re-using `name` replaces the entry with verdict retention, that `baseline` is required for controls with sha256 enforcement, and that `path` resolves against the bound project or refuses outside it. This enriches every parameter beyond 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?

The description opens with a clear verb+resource statement: 'Register a rendered file, sheet or A/B member for `proofcut review serve`.' It explicitly states what the tool does and its domain. It distinguishes from sibling review tools (review_verdict, review_list) by focusing on registration and clarifying that it never copies source files.

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?

The description gives clear context on when to use it: when a render already exists and needs to be pointed at for review. It explains that it never copies and that a control requires a baseline with sha256 match. It implicitly distinguishes from alternatives like review_list (to view) and review_verdict (to judge) but doesn't explicitly name them. Still, the guidance is sufficient for an agent to decide when to call this tool.

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

Deploy Server