Skip to main content
Glama

Start-editing packet for one function

get_function_brief
Read-onlyIdempotent

Get one function's start-editing packet from the newest trusted run, including its score, uncovered lines, and refresh, test, gate, and verify command lines.

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. Twins come from the run's stored index, whose first build takes seconds. name must live in path. A miss is a tool error (isError true, the exit-1 error object) whose message lists the file's functions.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
nameYesthe long_name get_next_item printed (classify( score , late )), the bare identifier (classify, or route for a Rust `route cmd : & Cmd`), a fragment of either, the line the function starts on, or a handle such as NAME#2 for a twin or (anonymous)#2; exact match first
pathYessource file, repo-relative or absolute inside the repo; a backslash separates folders on Windows only
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
laneNothe lane whose artifact produced cov and uncovered_lines, verbatim from the config; null when no lane covers the scope
pathNothe resolved file, repo-relative
churnNothe file's churn, or null when it had no commits in the window
notesNoprose the config carries for whoever edits here
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
handleNoshort name form: the bare identifier or (anonymous)#N, the same value get_next_item prints
paramsNoparameters in declaration order, so a test can call the function without opening the file
remedyNodecompose, split-lines, add-tests or ok: the branch the session takes; scored.remedy carries the same value
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
scoredNothe whole scored row from the run
sourceNothe function's own text, start to end inclusive, newlines intact: editable without reading the file
targetNothis scope's effective ceiling: the highest CRAP a function may carry, and so also the highest ccn; the same value as gate_rule.ceiling
shallowNotrue when this checkout is a shallow clone: churn and gate_rule.mark_age_days count only the commits the clone holds; set fetch-depth: 0 on the checkout or run git fetch --unshallow for the real counts
attemptsNoevery claim ever taken on this function, oldest first; [] on a first attempt, and a row with closed null is a claim still open
commandsNothe rest of the loop as whole command lines for this file and scope; run them as given
couplingNoup 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
functionNothe resolved lizard long name, whichever name form was asked with
regrowthNodid this get fixed before
versionsNowhat produced these numbers
gate_ruleNowhat check_gate will judge this edit by
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
est_splitsNo0 when ccn <= target, else ceil(ccn / target)
unmeasuredNotrue 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
file_totalsNothe file rolled up
ratchet_markNothe committed ratchet mark, or null when the function carries none or the repo has no ratchet file
file_functionsNoevery scored function in the same file: where an extracted helper lands, and which names are taken
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
uncovered_linesNoline numbers no test ran; [] when the span is fully covered; null when no artifact could answer, then uncovered_lines_note says why
duplication_twinsNoup to 10 near-duplicate functions at similarity 0.8, best first; empty is normal; list_duplicate_functions has the repo-wide pairs
est_uncovered_pathsNo(1 - cov) x ccn rounded half to even, so 2.5 reads 2
uncovered_lines_noteNopresent 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.

  1. Changed18 schema fields changedv0.8.1
    • changedInput schema / properties / name / description
      Previous value: -"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"New value: +"the long_name get_next_item printed (classify( score , late )), the bare identifier (classify, or route for a Rust `route cmd : & Cmd`), a fragment of either, the line the function starts on, or a handle such as NAME#2 for a twin or (anonymous)#2; exact match first"
    • changedInput schema / properties / path / description
      Previous value: -"repo-relative source file, forward slashes"New value: +"source file, repo-relative or absolute inside the repo; a backslash separates folders on Windows only"
    • 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 / commands / properties / refresh / description
      Previous value: -"crapkit coverage --reuse-unchanged: the cheapest run that clears stale"New value: +"crapkit coverage --reuse-unchanged: the cheapest run that brings scored_changes to 0 and clears stale"
    • changedOutput schema / properties / duplication_twins / items / properties / contained / description
      Previous value: -"true when every shingle of the smaller function appears in the larger: one can call the other"New value: +"true when the twin and this function nest in one file, one defined inside the other"
    • changedOutput schema / properties / est_uncovered_paths / description
      Previous value: -"round((1 - cov) x ccn)"New value: +"(1 - cov) x ccn rounded half to even, so 2.5 reads 2"
    • changedOutput schema / properties / file_functions / items / properties / crap / description
      Previous value: -"score"New value: +"score: ccn^2 x (1 - cov)^3 + ccn, or ccn on a cc-only or excluded row"
    • changedOutput schema / properties / file_totals / properties / crap_load / description
      Previous value: -"sum of crap over the file"New value: +"exact sum of crap over the file (math.fsum), two decimals"
    • changedOutput schema / properties / scored / properties / cov / description
      Previous value: -"branch coverage 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 / scored / 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 / scored / 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 / scored / properties / flag / enum
      Previous value: -[
      -  "measured",
      -  "untested",
      -  "no-lane",
      -  "cc-only"
      -]New value: +[
      +  "measured",
      +  "untested",
      +  "excluded",
      +  "no-lane",
      +  "cc-only"
      +]
    • 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: churn and gate_rule.mark_age_days 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 every number here describes an older tree; run commands.refresh first"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"
    • changedOutput schema / properties / target / description
      Previous value: -"this scope's effective ccn ceiling, the same value as gate_rule.ceiling"New value: +"this scope's effective ceiling: the highest CRAP a function may carry, and so also the highest ccn; the same value as gate_rule.ceiling"
    • 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"
      +}
    • addedOutput schema / 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"
      +}
  2. Changed5 schema fields changedv0.8.0
    • addedOutput schema / properties / file_functions / 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 / file_functions / 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)"
    • changedOutput schema / properties / regrowth / properties / history / description
      Previous value: -"one [run_id, ccn] pair per trusted run that scored the function, oldest first"New value: +"one [run_id, ccn] pair for every stored run that scored the function, whatever its kind, oldest first"
    • addedOutput schema / properties / scored / 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 / scored / 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. Changed6 schema fields changedv0.7.6
    • 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"
      +]
  4. Changed2 schema fields changedv0.7.0
    • 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"
  5. Addedv0.6.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), but the description adds behavior beyond them: the returned command lines are 'none of them run', twin handles come from a stored index whose 'first build takes seconds' (a latency hint), and the failure mode is spelled out ('isError true, the exit-1 error object') with a message that lists the file's functions. This is unusually rich disclosure.

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?

Dense but front-loaded: the first sentence defines the payload, the second routes usage, the remainder covers constraints and failure. Every sentence earns its place, though the run-on phrasing about the stored index is slightly cryptic.

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?

For a read-only lookup with an output schema and full param coverage, the description supplies everything else an agent needs: selection guidance, the name/path coupling, non-execution of the returned commands, and precise error semantics.

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% and both required params are fully documented there, which sets baseline 3. The description adds a relational constraint the schema does not state — 'name must live in path' — giving genuine meaning beyond the structured fields.

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 one function's start-editing packet from the newest trusted run') and enumerates the packet contents, so the agent knows exactly what comes back. It also names the sibling tools it is not, making it distinguishable without opening other 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?

Explicit triggering condition ('Use it once a function is chosen') plus two named exclusions with their alternatives: get_next_item for picking what to fix, get_function_history for scores across runs. Nothing 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.