Skip to main content
Glama
JeanFrancoisGagne

crapkit

by JeanFrancoisGagne
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Debt trend per run

get_trend
Read-onlyIdempotent

Track whole-repo quality over time with per-run totals and per-scope grades for every trusted run, oldest first; uses cached rollups after the first call.

Instructions

Returns per-run totals for every trusted run, oldest first, with a grade per scope. Use it for the whole repo's trajectory. Use get_function_history for one function and get_ratchet_report for marked debt. It runs no lane and spawns no git. The first call on a large store sums every run into a rollup cache and takes seconds. Later calls read the cache back. repo may be any directory under a checkout where crapkit init and crapkit coverage have run. One with no snapshot store yet answers isError true with the setup pointer.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
repoNopath to the scored repo's root (default: the repo the server was started in); a leading ~ is the home directory

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
runsNoone row per trusted run, oldest first
schemaNopayload schema version, 1
targetNothe [crapkit] target: the default ceiling, the highest CRAP a function may carry, and so also the highest ccn, that every scope inherits unless it sets its own
truncatedNopresent 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

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changedv0.8.1
    • 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"
    • changedOutput schema / properties / runs / items / properties / by_scope / additionalProperties / properties / crap_load / description
      Previous value: -"sum of crap over the scope"New value: +"exact sum of crap over the scope (math.fsum), two decimals"
    • changedOutput schema / properties / runs / items / properties / crap_load / description
      Previous value: -"sum of every function's crap, two decimals"New value: +"exact sum of every function's crap (math.fsum), two decimals"
    • changedOutput schema / properties / target / description
      Previous value: -"the [crapkit] target: the default ccn ceiling every scope inherits unless it sets its own"New value: +"the [crapkit] target: the default ceiling, the highest CRAP a function may carry, and so also the highest ccn, that every scope inherits unless it sets its own"
    • 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"
+}
  2. Addedv0.6.0

TDQS

A4.4/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety and idempotency profile is fully covered by structured data. What the description adds beyond that is operationally useful but partly redundant framing: 'runs no lane and spawns no git' echoes the no-side-effect annotations, while the first-call rollup caching cost (seconds on a large store) and the isError-with-setup-pointer failure mode are real, non-duplicated behavioral disclosures. Net, it adds modest context over the annotations rather than a rich set of new traits.

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-loads the return shape, then alternatives, then behavior and preconditions; each sentence carries information. It is denser and longer than strictly minimal — the 'runs no lane and spawns no git' clause restates annotation-level safety — but there is no padding for padding's sake.

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?

Return values need not be documented since an output schema exists, and the description already covers ordering, granularity, prime cost, cache reuse and the empty-store error path. Nothing an agent needs to call this correctly 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?

Only one parameter and schema coverage is 100%, so the baseline would be 3. The description lifts it by explaining that repo may be any directory under a checkout where init and coverage have already run, which clarifies accepted values beyond the schema's plain path/default description.

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+scope: per-run totals for every trusted run, oldest first, with a grade per scope. It explicitly distinguishes itself from siblings get_function_history (one function) and get_ratchet_report (marked debt), so an agent can route without opening any other 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 when-to-use ('the whole repo's trajectory') and names the two alternatives with their selecting conditions. It also states the repo precondition (any directory under a checkout where crapkit init and crapkit coverage ran), which is genuine usage guidance.

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

Deploy Server

Other Tools