Skip to main content
Glama
JeanFrancoisGagne

crapkit

by JeanFrancoisGagne
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Next function to fix

get_next_item
Read-onlyIdempotent

Return the next function to fix as a work packet ranked by crap score from the newest trusted run. Use it to start fixes; empty true means the queue is spent.

Instructions

Returns the next function to fix as a work packet, the newest trusted run's worst row by crap. Use it to start a fix, list_worklist to survey the same run by risk, and get_function_brief once a function is chosen. It runs no tests, and empty true means the queue is spent, not the work, so read reasons. Filters cut before top counts: top 3 with exclude ["tests/"] returns the three worst rows outside tests, and an unknown scope name is a config error.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
topNoreturn the next N packets as items instead of one item (N >= 1, default 1)
repoNopath to the scored repo's root (default: the repo the server was started in); a leading ~ is the home directory
scopeNorestrict the ranking to these declared scopes (exact [[scope]] names from crapkit.toml, one --scope each)
excludeNoskip rows whose path or long function name contains any of these fragments (one --exclude each)

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
itemNothe one packet, present when empty is false and top is absent or 1
emptyNotrue when the queue has nothing to hand out; then reasons is present and item and items are absent
itemsNoup to top packets in crap-descending order, present when empty is false and top is above 1
staleNotrue when the run's commit is not HEAD. It judges the commit, not the files: an amend or a commit that touched no scored file sets it, and an uncommitted edit leaves it false; scored_changes counts the files whose content moved. Schema 2 redefines it as that content difference
commitNothat run's commit, full sha
run_idNoid of the run these numbers come from: the newest trusted run (a coverage run, or a verify run whose verdict passed)
schemaNopayload schema version, 1
reasonsNowhy the queue is empty, present only when empty is true; the stop condition is empty true with skipped_claimed and no_lane_over_target both 0 or absent and scored_changes 0
shallowNotrue when this checkout is a shallow clone: commits, authors and the churn the ranking reads count only the commits the clone holds; set fetch-depth: 0 on the checkout or run git fetch --unshallow for the real counts
commandsNothe call that answers stale and scored_changes; run it as given
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
scored_changesNohow many files the run scored hold other content now than the run recorded, deleted files included; 0 means the numbers describe the files on disk; null when crapkit cannot compare: the run recorded no content (crapkit 0.8.0 or older wrote it) or git failed reading the tree; treat null like any count above 0 and run commands.refresh
skipped_claimedNorows another session's claim hid; present only when non-zero, and list_claims names the holders
skipped_no_laneNorows above the floor that no lane measures, kept out of the ranking because their cov 0 is a tooling gap, not a testing gap

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed21 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"
    • addedOutput schema / properties / commands
      Added value: +{
+  "description": "the call that answers stale and scored_changes; run it as given",
+  "properties": {
+    "refresh": {
+      "description": "crapkit coverage --reuse-unchanged: the cheapest run that brings scored_changes to 0 and clears stale",
+      "type": "string"
+    }
+  },
+  "type": "object"
+}
    • changedOutput schema / properties / item / properties / cov / description
      Previous value: -"branch coverage inside the span, 0.0 to 1.0"New value: +"branch coverage inside the span, 0.0 to 1.0; statement coverage when the span has no branches, and invoked-or-not (1.0 or 0.0) when it has no statements; Python and/or add to ccn but coverage.py records no branch arc for them; 0.0 on an untested, excluded, no-lane or cc-only row"
    • changedOutput schema / properties / item / properties / crap / description
      Previous value: -"the score: ccn^2 x (1 - cov)^3 + ccn"New value: +"the score: ccn^2 x (1 - cov)^3 + ccn, or ccn on a cc-only or excluded row"
    • changedOutput schema / properties / item / properties / est_uncovered_paths / description
      Previous value: -"round((1 - cov) x ccn): decision paths no test walks"New value: +"(1 - cov) x ccn rounded half to even, so 2.5 reads 2: decision paths no test walks"
    • changedOutput schema / properties / item / properties / flag / description
      Previous value: -"measured, untested, no-lane or cc-only: whether a lane artifact could measure this span"New value: +"measured, untested, excluded, no-lane or cc-only: whether a lane artifact could measure this span"
    • changedOutput schema / properties / item / properties / flag / enum
      Previous value: -[
-  "measured",
-  "untested",
-  "no-lane",
-  "cc-only"
-]New value: +[
+  "measured",
+  "untested",
+  "excluded",
+  "no-lane",
+  "cc-only"
+]
    • changedOutput schema / properties / item / properties / target / description
      Previous value: -"this scope's effective ccn ceiling"New value: +"this scope's effective ceiling: the highest CRAP a function may carry, and so also the highest ccn"
    • addedOutput schema / properties / item / properties / unmeasured
      Added value: +{
+  "description": "true when no measurement stands behind cov: flag no-lane (no lane covers the scope) or cc-only (the scope asks for no coverage). cov 0.0 and est_uncovered_paths are then stand-ins, not a count of paths no test walks",
+  "type": "boolean"
+}
    • changedOutput schema / properties / items / items / properties / cov / description
      Previous value: -"branch coverage inside the span, 0.0 to 1.0"New value: +"branch coverage inside the span, 0.0 to 1.0; statement coverage when the span has no branches, and invoked-or-not (1.0 or 0.0) when it has no statements; Python and/or add to ccn but coverage.py records no branch arc for them; 0.0 on an untested, excluded, no-lane or cc-only row"
    • changedOutput schema / properties / items / items / properties / crap / description
      Previous value: -"the score: ccn^2 x (1 - cov)^3 + ccn"New value: +"the score: ccn^2 x (1 - cov)^3 + ccn, or ccn on a cc-only or excluded row"
    • changedOutput schema / properties / items / items / properties / est_uncovered_paths / description
      Previous value: -"round((1 - cov) x ccn): decision paths no test walks"New value: +"(1 - cov) x ccn rounded half to even, so 2.5 reads 2: decision paths no test walks"
    • changedOutput schema / properties / items / items / properties / flag / description
      Previous value: -"measured, untested, no-lane or cc-only: whether a lane artifact could measure this span"New value: +"measured, untested, excluded, no-lane or cc-only: whether a lane artifact could measure this span"
    • changedOutput schema / properties / items / items / properties / flag / enum
      Previous value: -[
-  "measured",
-  "untested",
-  "no-lane",
-  "cc-only"
-]New value: +[
+  "measured",
+  "untested",
+  "excluded",
+  "no-lane",
+  "cc-only"
+]
    • changedOutput schema / properties / items / items / properties / target / description
      Previous value: -"this scope's effective ccn ceiling"New value: +"this scope's effective ceiling: the highest CRAP a function may carry, and so also the highest ccn"
    • addedOutput schema / properties / items / items / properties / unmeasured
      Added value: +{
+  "description": "true when no measurement stands behind cov: flag no-lane (no lane covers the scope) or cc-only (the scope asks for no coverage). cov 0.0 and est_uncovered_paths are then stand-ins, not a count of paths no test walks",
+  "type": "boolean"
+}
    • changedOutput schema / properties / reasons / description
      Previous value: -"why the queue is empty, present only when empty is true; the stop condition is empty true with skipped_claimed and no_lane_over_target both 0 or absent"New value: +"why the queue is empty, present only when empty is true; the stop condition is empty true with skipped_claimed and no_lane_over_target both 0 or absent and scored_changes 0"
    • addedOutput schema / properties / scored_changes
      Added value: +{
+  "description": "how many files the run scored hold other content now than the run recorded, deleted files included; 0 means the numbers describe the files on disk; null when crapkit cannot compare: the run recorded no content (crapkit 0.8.0 or older wrote it) or git failed reading the tree; treat null like any count above 0 and run commands.refresh",
+  "type": [
+    "integer",
+    "null"
+  ]
+}
    • addedOutput schema / properties / shallow
      Added value: +{
+  "description": "true when this checkout is a shallow clone: commits, authors and the churn the ranking reads count only the commits the clone holds; set fetch-depth: 0 on the checkout or run git fetch --unshallow for the real counts",
+  "type": "boolean"
+}
    • changedOutput schema / properties / stale / description
      Previous value: -"true when the run's commit is not HEAD, so cov, crap and uncovered_lines describe an older tree; crapkit coverage --reuse-unchanged (get_function_brief's commands.refresh) clears it"New value: +"true when the run's commit is not HEAD. It judges the commit, not the files: an amend or a commit that touched no scored file sets it, and an uncommitted edit leaves it false; scored_changes counts the files whose content moved. Schema 2 redefines it as that content difference"
    • 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. Changed4 schema fields changedv0.8.0
    • addedOutput schema / properties / item / properties / occurrence
      Added value: +{
+  "description": "source creation order among functions sharing start, from 1; 0 on an older row with no recorded position",
+  "type": "integer"
+}
    • changedOutput schema / properties / item / properties / remedy / description
      Previous value: -"decompose (ccn over ceiling), split-lines (another function shares its source lines, so coverage cannot tell them apart and no test lowers the score until the definitions sit on separate lines), add-tests (coverage short) or ok (nothing left to do)"New value: +"decompose (ccn over ceiling), split-lines (another function shares its source lines, or a Python def's body starts on the line its signature ends, where coverage.py reads it as the def statement, so coverage cannot tell them apart and no test lowers the score until they sit on separate lines), add-tests (coverage short) or ok (nothing left to do)"
    • addedOutput schema / properties / items / items / properties / occurrence
      Added value: +{
+  "description": "source creation order among functions sharing start, from 1; 0 on an older row with no recorded position",
+  "type": "integer"
+}
    • changedOutput schema / properties / items / items / properties / remedy / description
      Previous value: -"decompose (ccn over ceiling), split-lines (another function shares its source lines, so coverage cannot tell them apart and no test lowers the score until the definitions sit on separate lines), add-tests (coverage short) or ok (nothing left to do)"New value: +"decompose (ccn over ceiling), split-lines (another function shares its source lines, or a Python def's body starts on the line its signature ends, where coverage.py reads it as the def statement, so coverage cannot tell them apart and no test lowers the score until they sit on separate lines), add-tests (coverage short) or ok (nothing left to do)"
  3. Changed4 schema fields changedv0.7.6
    • changedOutput schema / properties / item / properties / remedy / description
      Previous value: -"decompose (ccn over ceiling), add-tests (coverage short) or ok (nothing left to do)"New value: +"decompose (ccn over ceiling), split-lines (another function shares its source lines, so coverage cannot tell them apart and no test lowers the score until the definitions sit on separate lines), add-tests (coverage short) or ok (nothing left to do)"
    • changedOutput schema / properties / item / properties / remedy / enum
      Previous value: -[
-  "decompose",
-  "add-tests",
-  "ok"
-]New value: +[
+  "decompose",
+  "split-lines",
+  "add-tests",
+  "ok"
+]
    • changedOutput schema / properties / items / items / properties / remedy / description
      Previous value: -"decompose (ccn over ceiling), add-tests (coverage short) or ok (nothing left to do)"New value: +"decompose (ccn over ceiling), split-lines (another function shares its source lines, so coverage cannot tell them apart and no test lowers the score until the definitions sit on separate lines), add-tests (coverage short) or ok (nothing left to do)"
    • changedOutput schema / properties / items / items / properties / remedy / enum
      Previous value: -[
-  "decompose",
-  "add-tests",
-  "ok"
-]New value: +[
+  "decompose",
+  "split-lines",
+  "add-tests",
+  "ok"
+]
  4. Addedv0.6.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), but the description adds genuinely new behavior: it runs no tests, an empty result has a specific interpreted meaning, filters apply before the top-N cut, and an unknown scope name is a config error rather than an empty result. These are non-obvious traits not derivable from annotations or schema.

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 purpose and selection rule in the first sentence, then packs routing, caveats, and filter semantics into the remainder. Every clause carries information, though the later sentences are dense and read as a run-on, which costs some scannability.

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?

With an output schema present, return values need no explanation, and the description still interprets the meaningful cases ('empty true', work packets as items). Combined with annotations covering safety and 100% schema coverage, an agent has everything needed to call this correctly.

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 each parameter is documented, making 3 the baseline. The description goes beyond it by explaining the interaction between parameters ('Filters cut before top counts: top 3 with exclude ["tests/"] returns the three worst rows outside tests'), which clarifies ordering semantics the schema does not state.

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 ('Returns the next function to fix as a work packet') and pins down the selection rule ('newest trusted run's worst row by crap'). It explicitly distinguishes itself from siblings list_worklist and get_function_brief, so an agent can route 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 when-to-use: 'Use it to start a fix', with named alternatives for adjacent intents ('list_worklist to survey the same run by risk', 'get_function_brief once a function is chosen'). It also flags the empty-queue case ('empty true means the queue is spent, not the work, so read reasons') and the unknown-scope failure mode.

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