Token economy
An agent's edit-and-verify loop runs dozens of times per task. A cold dotnet test
dumps restore logs, build logs and per-test noise into the context window — thousands of
tokens, most of it irrelevant, every single iteration. Sidekit's whole design premise is that
the same questions can be answered well under 200 tokens.
The rules
These apply to every answer from every tool.
Null and default fields are omitted
A field that carries no signal does not appear. stack, diagnostic,
affected and a zero moreFailures are all absent unless they mean
something. Absence is information: it is how you know there was nothing to say.
Top-N plus an explicit remainder — never the firehose
Capped lists always come with a count of what was left out (moreFailures,
remainder). An agent is never silently shown a partial list, so it can always tell
whether asking for more is worth it.
Root-cause clustering
Tests failing from one cause are reported once with an affected count, biggest
clusters first. One broken helper failing eighty tests is one line, not eighty.
The unchanged short-circuit
Pass sinceGeneration from your last
get_status answer, and an unchanged
workspace answers in about 33 bytes:
{ "generation": 7, "unchanged": true }
Two shapes, and the smaller one is sent
find_usages can answer as a flat list of
file:line sites, or grouped by file with counts. Grouping wins on a heavily-used
symbol and loses on a lightly-used one, where the per-file header costs more than collapsing
saves — so both are built and the smaller one is what you get. There is no threshold constant,
because where the crossover falls depends on the paths, the line counts and the symbol's own
name.
Workspace-relative paths
The absolute workspace prefix is stripped from stacks, messages, diagnostics and build-file
paths. Nobody's context window should be paying to store
/home/you/src/repo/ a hundred times.
The capability envelope
Answers state what resolution to expect — runner is mtp,
vstest or none — so a degraded repository reports reduced capability
as data instead of failing and making the agent discover it the expensive way.
No decorative whitespace
Enums serialize as names ("BuildPassed"), fields are camelCase, and nothing is
pretty-printed. It is read by a machine.
The budgets
These are enforced by Sidekit's own test suite, not aspirations.
| Answer | Budget |
|---|---|
get_status — unchanged since your last call | ~33 bytes |
get_status — a full answer | ~250–400 bytes |
run_tests — a green run | ≤ 200 bytes |
run_tests — a hundred distinct failures | ≤ 800 bytes |
select_tests | ≤ 150 bytes |
get_tests_for_file | ≤ 100 bytes |
get_blast_radius | ≤ 200 bytes |
find_symbol — one match | ≤ 170 bytes |
find_usages — under ten uses, flat | ≤ 360 bytes |
find_usages — 480 uses across 60 files | ≤ 900 bytes |
The last one is the interesting one. A grouped answer names the busiest files and collapses the tail into a remainder, so it stops growing: 480 uses and 128 uses land two bytes apart across 3.75× the references. A budget that rose with the use count would mean the shaping had failed.
get_failures with
includeStacks, or naming specific tests. The budgets are met by not saying
useless things, not by hiding useful ones.
Getting the benefit
None of this helps if the agent never calls the server. The single highest-value thing you can
do is tell it when to reach for Sidekit instead of dotnet — there is a ready-made
instructions block in Agent host recipes.