crapkit

Overview Schema Source Related Servers Discussions Admin

Start-editing packet for one function

get_function_brief

Read-onlyIdempotent

Retrieve a chosen function's editing packet: its score, uncovered lines, and test, gate, and verify commands. Get the exact details needed to start work without executing any commands.

Instructions

Returns one function's start-editing packet from the newest trusted run: scored row, uncovered lines and the refresh, test, gate and verify command lines, none of them run. Use it once a function is chosen. Skip it for picking what to fix, that is get_next_item, and for a score across runs, get_function_history. Every call shingles the repo for twins, seconds on a large corpus. name must live in path. name takes the long name, a bare identifier, a start line or NAME#2, exact match first. A miss lists the file's functions instead of erroring.

Input Schema

TableJSON Schema

Name	Required	Description
`name`	Yes	the bare identifier (classify, or route for a Rust `route cmd : & Cmd`) or the whole long_name get_next_item printed (classify( score , late )); both resolve, exact match first
`path`	Yes	repo-relative source file, forward slashes
`repo`	No	path to the scored repo's root (default: the repo the server was started in)

Output Schema

TableJSON Schema

Name	Required	Description
`lane`	No	the lane whose artifact produced cov and uncovered_lines, verbatim from the config; null when no lane covers the scope
`path`	No	the resolved file, repo-relative
`churn`	No	the file's churn, or null when it had no commits in the window
`notes`	No	prose the config carries for whoever edits here
`stale`	No	true when the run's commit is not HEAD, so every number here describes an older tree; run commands.refresh first
`commit`	No	that run's commit, full sha
`handle`	No	short name form: the bare identifier or (anonymous)#N, the same value get_next_item prints
`params`	No	parameters in declaration order, so a test can call the function without opening the file
`remedy`	No	decompose, split-lines, add-tests or ok: the branch the session takes; scored.remedy carries the same value
`run_id`	No	id of the run these numbers come from: the newest trusted run (a coverage run, or a verify run whose verdict passed)
`schema`	No	payload schema version, 1
`scored`	No	the whole scored row from the run
`source`	No	the function's own text, start to end inclusive, newlines intact: editable without reading the file
`target`	No	this scope's effective ccn ceiling, the same value as gate_rule.ceiling
`attempts`	No	every claim ever taken on this function, oldest first; [] on a first attempt, and a row with closed null is a claim still open
`commands`	No	the rest of the loop as whole command lines for this file and scope; run them as given
`coupling`	No	up to 5 change-coupling partners at support 5 and confidence 0.5, strongest first; empty when none qualify; list_coupled_files has the repo-wide list
`function`	No	the resolved lizard long name, whichever name form was asked with
`regrowth`	No	did this get fixed before
`versions`	No	what produced these numbers
`gate_rule`	No	what check_gate will judge this edit by
`est_splits`	No	0 when ccn <= target, else ceil(ccn / target)
`file_totals`	No	the file rolled up
`ratchet_mark`	No	the committed ratchet mark, or null when the function carries none or the repo has no ratchet file
`file_functions`	No	every scored function in the same file: where an extracted helper lands, and which names are taken
`uncovered_lines`	No	line numbers no test ran; [] when the span is fully covered; null when no artifact could answer, then uncovered_lines_note says why
`duplication_twins`	No	up to 10 near-duplicate functions at similarity 0.8, best first; empty is normal; list_duplicate_functions has the repo-wide pairs
`est_uncovered_paths`	No	round((1 - cov) x ccn)
`uncovered_lines_note`	No	present only when uncovered_lines is null: the reason and the move (stale artifact, no test imports the file, coverage_optional scope)

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 schema fields changedv0.7.6Sep 21, 2026

changedOutput schema / properties / file_functions / 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 / file_functions / items / properties / remedy / enum

Previous value: -[
-  "decompose",
-  "add-tests",
-  "ok"
-]New value: +[
+  "decompose",
+  "split-lines",
+  "add-tests",
+  "ok"
+]

changedOutput schema / properties / remedy / description

Previous value: -"decompose, add-tests or ok: the branch the session takes; scored.remedy carries the same value"New value: +"decompose, split-lines, add-tests or ok: the branch the session takes; scored.remedy carries the same value"

changedOutput schema / properties / remedy / enum

Previous value: -[
-  "decompose",
-  "add-tests",
-  "ok"
-]New value: +[
+  "decompose",
+  "split-lines",
+  "add-tests",
+  "ok"
+]

changedOutput schema / properties / scored / 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 / scored / properties / remedy / enum

Previous value: -[
-  "decompose",
-  "add-tests",
-  "ok"
-]New value: +[
+  "decompose",
+  "split-lines",
+  "add-tests",
+  "ok"
+]

Changed2 schema fields changedv0.7.0Sep 8, 2026

changedOutput schema / properties / commands / properties / refresh_writes_run / description

Previous value: -"always true: refresh is the one command here that writes a run to the store; the other three change nothing"New value: +"always true: refresh writes a coverage run to the store; other commands can also write caches or test artifacts"

changedOutput schema / properties / commands / properties / scoped_tests / description

Previous value: -"this scope's own test command with the file filled in, or null when the scope declares no [crapkit.scoped_tests] template"New value: +"the crapkit test-scoped call for this literal file, or null when the scope declares no [crapkit.scoped_tests] template"

Addedv0.6.0Sep 6, 2026

TDQS

A4.7/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: the packet's commands are 'none of them run', every call 'shingles the repo for twins' with a cost warning ('seconds on a large corpus'), and a miss 'lists the file's functions instead of erroring'. This is useful non-obvious behavior that annotations cannot express.

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?

The description is compact and front-loaded: the core return value is stated first, followed by usage routing, cost warning, and parameter semantics. Every sentence earns its place, and the sibling differentiation is packed into one sentence without bloat.

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?

The tool has an output schema, so return values need not be re-explained. The description covers purpose, usage timing, exclusions, cost, name resolution, and miss behavior. For a read-only, idempotent tool with 100% schema coverage and an output schema, 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.

Parameters4/5

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds meaning beyond the schema by explaining the name resolution order ('exact match first'), the accepted name forms ('long name, a bare identifier, a start line or NAME#2'), and the constraint that 'name must live in path'. It also clarifies the miss behavior, which helps an agent interpret a non-error response.

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 states a specific verb ('Returns'), a specific resource ('one function's start-editing packet from the newest trusted run'), and enumerates the packet's contents (scored row, uncovered lines, command lines). It also explicitly distinguishes itself from siblings get_next_item and get_function_history, so an agent can tell them apart without opening schemas.

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?

The description gives explicit when-to-use guidance ('Use it once a function is chosen') and explicit when-not-to-use guidance ('Skip it for picking what to fix, that is get_next_item, and for a score across runs, get_function_history'). It also names the alternative tools, leaving no ambiguity about routing.

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

Deploy Server