crapkit

Overview Schema Source Related Servers Discussions Admin

Ratchet debt burn-down

get_ratchet_report

Read-onlyIdempotent

Report ratchet debt burn-down by listing open marks with ages, repayments, and policy findings so you can judge whether marked debt is repaid or piling up.

Instructions

Reports the ratchet debt burn-down: open marks with their age, repayments and policy findings. Use it to judge whether marked debt is repaid or piling up, and get_function_history for one function's mark. It reads the marks file and its git history only, and ages count from the newest commit touching that file, never the clock. Open marks are the file's rows, committed or not. A deleted or emptied file reports the marks its history last held as open, none repaid, and no file with no history reports zeros. repo may be any directory under the checkout.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`repo`	No	path to the scored repo's root (default: the repo the server was started in); a leading ~ is the home directory

Output Schema

TableJSON Schema

Name	Required	Description
`open`	No	marks open on disk, working tree included: an uncommitted seed counts
`oldest`	No	up to 20 open marks, oldest first
`schema`	No	payload schema version, 1
`shallow`	No	true when this checkout is a shallow clone: ages and repayments count only the commits the clone holds; set fetch-depth: 0 on the checkout or run git fetch --unshallow for the real counts, and crapkit ratchet report --enforce refuses to judge the debt policy there (exit 4)
`anchor_ts`	No	unix seconds of the newest commit that touched the ratchet file; every age and window counts back from here, never from the wall clock; 0 with no ratchet history
`truncated`	No	present only when the whole answer was longer than one tool result the server sends (7,500 characters): each list, string or object field it cut, at any depth, keeps its start, and full is the CLI command that prints the whole answer
`uncommitted`	No	marks the working tree and the newest committed ratchet file disagree on: added, repaid or tightened but not committed
`dropped_total`	No	marks repaid over the whole committed history
`dropped_last_30d`	No	marks repaid in the 30 days before anchor_ts
`dropped_last_90d`	No	marks repaid in the 90 days before anchor_ts
`policy_violations`	No	null when no debt policy is configured, [] when the policy ran clean, else the findings as sentences

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv0.8.1Oct 1, 2026

changedInput schema / properties / repo / description

Previous value: -"path to the scored repo's root (default: the repo the server was started in)"New value: +"path to the scored repo's root (default: the repo the server was started in); a leading ~ is the home directory"

addedOutput schema / properties / shallow

Added value: +{
+  "description": "true when this checkout is a shallow clone: ages and repayments count only the commits the clone holds; set fetch-depth: 0 on the checkout or run git fetch --unshallow for the real counts, and crapkit ratchet report --enforce refuses to judge the debt policy there (exit 4)",
+  "type": "boolean"
+}

addedOutput schema / properties / truncated

Added value: +{
+  "description": "present only when the whole answer was longer than one tool result the server sends (7,500 characters): each list, string or object field it cut, at any depth, keeps its start, and full is the CLI command that prints the whole answer",
+  "properties": {
+    "fields": {
+      "additionalProperties": {
+        "properties": {
+          "kept": {
+            "description": "how many the answer keeps",
+            "type": "integer"
+          },
+          "of": {
+            "description": "how many the whole answer has",
+            "type": "integer"
+          }
+        },
+        "type": "object"
+      },
+      "description": "each cut field, named by its keys joined with dots (gate.breaches) -> kept and of: elements for a list, entries for an object, characters for a string",
+      "type": "object"
+    },
+    "full": {
+      "description": "the crapkit command that prints the whole answer, spelled for the server's shell",
+      "type": "string"
+    }
+  },
+  "type": "object"
+}

Addedv0.6.0Sep 6, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description goes further with non-obvious behavior: ages derive from the newest commit touching the marks file rather than the clock, the file plus its git history are the only inputs, and deleted/emptied/no-history files have defined outputs (last-held marks as open, or zeros). These edge cases materially change how an agent interprets results.

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 purpose, then behavior, then the parameter note; every sentence carries information. The prose is telegraphic in places ('it reads the marks file and its git history only'), which costs a little readability but not content.

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?

An output schema exists, so return-format detail is unnecessary, and the description instead covers exactly what structured fields do not: age semantics, deletion/empty/no-history edge cases, and single-param scoping. Complete for a read-only report tool.

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, but the description adds real semantics for repo ('may be any directory under the checkout'). That clarification sits in slight tension with the schema's 'root of the scored repo', which is the only reason it is not a 5.

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 ('Reports the ratchet debt burn-down') and enumerates the payload: open marks with age, repayments, policy findings. It explicitly names the sibling it is not, get_function_history, so an agent can separate the aggregate view from the single-function view without opening either 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?

Provides a decision rule ('Use it to judge whether marked debt is repaid or piling up') and routes the adjacent case to get_function_history for one function's mark. Nothing about when to reach for this tool versus its siblings is left to inference.

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

Deploy Server