proofcut

by tydude001

Overview Schema Source Related Servers Discussions Admin

Python

Local

card_new

DestructiveIdempotent

Fill a template's slots to create a card, write its SVG and render PNG into assets/cards, ready for cues to point at.

Instructions

Make a card from a template: fill its slots, write the SVG, render it.

name is the <name> in card:<name> — the key a cue points at. Both the SVG source and the PNG are written under the project's assets/cards/, so the card can be re-edited later and re-rendered with card_render rather than redrawn.

A slot value is text. A newline inside one is a line break wherever the template accepts multiple lines; nothing wraps automatically, because a guessed wrap overflows the frame without saying so. Ratings are numbers out of five, to the nearest half.

Leave width/height unset unless you mean something other than this film. They default to the project's own canvas, which is what stops a card from pillarboxing inside the frame it was made for; naming a size that is not the project's is how a card loses a quarter of its width to black bar. Given at all, both must be.

Refused if a card of this name exists, unless overwrite — a cue may already point at it. Read font_warnings in the result: a template naming a face this machine lacks still renders, in a substitute, with nothing else to say so.

Input Schema

TableJSON Schema

Name	Required	Description
`name`	Yes	The `<name>` in `card:<name>` — the key a cue points at. The SVG and the PNG are both written under `assets/cards/`.
`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.
`slots`	Yes	The template's slots filled in, as text. A newline is a line break where the template takes several lines; ratings are numbers out of five, to the nearest half.
`width`	No	Render width. Leave it unset unless you mean something other than this film — it defaults to the project's canvas, which is what stops a card pillarboxing inside the frame it was made for. Given at all, `height` must be too.
`height`	No	Render height, given together with `width` or not at all.
`template`	Yes	Which template to fill; `card_templates` lists them with their slots. A per-aspect variant file is resolved from the canvas, never named here.
`overwrite`	No	Redraw a card of this name that already exists. Refused without it, since a cue may already point at that card.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed21 schema fields changedv0.25.0Sep 16, 2026

removedInput schema / properties / height / anyOf

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

addedInput schema / properties / height / description

Added value: +"Render height, given together with `width` or not at all."

removedInput schema / properties / height / title
```
Removed value: -"Height"
```
addedInput schema / properties / height / type
```
Added value: +[
+  "integer",
+  "null"
+]
```

addedInput schema / properties / name / description

Added value: +"The `<name>` in `card:<name>` — the key a cue points at. The SVG and the PNG are both written under `assets/cards/`."

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

addedInput schema / properties / overwrite / description

Added value: +"Redraw a card of this name that already exists. Refused without it, since a cue may already point at that card."

removedInput schema / properties / overwrite / title
```
Removed value: -"Overwrite"
```

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 / slots / description

Added value: +"The template's slots filled in, as text. A newline is a line break where the template takes several lines; ratings are numbers out of five, to the nearest half."

removedInput schema / properties / slots / title
```
Removed value: -"Slots"
```

addedInput schema / properties / template / description

Added value: +"Which template to fill; `card_templates` lists them with their slots. A per-aspect variant file is resolved from the canvas, never named here."

removedInput schema / properties / template / title
```
Removed value: -"Template"
```

removedInput schema / properties / width / anyOf

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

addedInput schema / properties / width / description

Added value: +"Render width. **Leave it unset unless you mean something other than this film** — it defaults to the project's canvas, which is what stops a card pillarboxing inside the frame it was made for. Given at all, `height` must be too."

removedInput schema / properties / width / title
```
Removed value: -"Width"
```

addedInput schema / properties / width / type

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

removedInput schema / title
```
Removed value: -"card_newArguments"
```

First observedv0.24.0Sep 15, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations already carry readOnlyHint=false, destructiveHint=true, idempotentHint=true. The description adds meaningful behavioral context: the overwrite refusal guard, the side effect of writing SVG+PNG to assets/cards, the non-wrapping newline behavior, and the font-substitution fallback. No contradiction with annotations.

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?

Front-loaded with a one-line summary, then structured paragraphs for storage, slots, size, and error/fallback behavior. Bold warning for width/height. Every sentence earns its place; no filler.

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?

Covers purpose, storage, parameter semantics, destructive-guard behavior, and result-reading (font_warnings). Good cross-references to card_render and card_templates. Given the output schema exists, nothing an agent needs to call it correctly is missing.

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

Parameters3/5

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds marginal nuance (e.g., 'nothing wraps automatically' and the pillarboxing warning for width/height), but these largely duplicate the schema text. Baseline 3 is appropriate.

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+resource: 'Make a card from a template: fill its slots, write the SVG, render it.' Distinguishes from card_render and card_reauthor by naming the rendering pipeline and the storage location, so an agent can tell it apart from 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?

Explicitly names alternatives: 're-rendered with card_render rather than redrawn' and 'card_templates lists them with their slots.' Gives concrete conditions: leave width/height unset unless you need a different size, and read font_warnings in the result. This is clear when-to-use and when-not-to-use guidance.

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

Deploy Server