Skip to main content
Glama
JeanFrancoisGagne

crapkit

by JeanFrancoisGagne
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Next function to fix

get_next_item
Read-onlyIdempotent

Get the next function to fix from the current trusted run, returned as a work packet with source and context. Use it to start a fix, or request multiple packets by setting top.

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)
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, so cov, crap and uncovered_lines describe an older tree; crapkit coverage --reuse-unchanged (get_function_brief's commands.refresh) clears it
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
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. 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"
+]
  2. Addedv0.6.0

TDQS

A5/5.0
Behavior5/5

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

Annotations already mark it readOnly, non-destructive, and idempotent. The description adds behavior beyond that: 'It runs no tests', 'empty true means the queue is spent, not the work, so read reasons', 'Filters cut before top counts', and 'an unknown scope name is a config error.' No contradiction.

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?

Four sentences, each serving a distinct purpose: purpose, usage routing, behavioral caveat, filter semantics. Front-loaded and dense without fluff.

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 and annotations covering safety, the description addresses usage, filtering, error conditions, and queue semantics. It is complete for an agent to decide when and how to invoke it.

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?

Schema descriptions cover all four parameters, but the description enriches them: it explains filter ordering ('Filters cut before top counts'), gives a concrete example (top 3 with exclude ["tests/"]), and states scope errors. This is additive 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 'Returns the next function to fix as a work packet, the newest trusted run's worst row by crap.' This names the verb, resource, and ranking criterion, and later contrasts it with list_worklist and get_function_brief, making its purpose unambiguous.

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?

It explicitly states 'Use it to start a fix, list_worklist to survey the same run by risk, and get_function_brief once a function is chosen.' This gives clear when-to-use and alternatives, plus the note 'It runs no tests' adds a usage caveat.

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