Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@codebugs log a critical bug in src/utils.py"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A code-finding, requirements, and release tracker for AI assistants — one where a finding has an identity. SQLite-backed, exposed via an MCP server and a CLI.
Most trackers treat every report as a new row, so the second agent to notice the same bug files it again, and the queue fills with copies of one defect. codebugs treats a finding as a defect, and each report of it as one observation of that defect:
$ codebugs add -s high -c n_plus_one -f src/api.py -d "Query in loop at line 42" --new-category
Added: CB-1
$ codebugs add -s high -c n_plus_one -f src/api.py -d "Query in loop at line 42"
Bumped: CB-1 (occurrence 2)
$ codebugs update CB-1 --status fixed
Updated: CB-1 (status=fixed, severity=high)
$ codebugs add -s high -c n_plus_one -f src/api.py -d "Query in loop at line 42"
Reopened as regression: CB-1 (occurrence 3)One card, three observations, and a regression recorded on the row it belongs to. Filing an observation again is normal and useful, not noise.
Deduplication is the point, not a side effect — and the rest of the design falls out of that one decision.
Filing the same finding twice does not create two cards. The second report bumps the first: its occurrence count goes up, and its severity rises if this sighting was worse than the last. Severity only ever escalates under observation, so a card filed low and re-seen critical stops hiding from a --severity critical query. Lowering it back is a deliberate update, never an accident of the last report.
A card that was fixed and comes back is a regression, not a duplicate. Re-filing reopens the same card and records the regression on it, so one defect's whole history stays on one row.
A decision stays decided. Re-filing something already dismissed as wont_fix or not_a_bug does not quietly reopen the argument. It files a new card pointing back at the dismissal, so the recurrence is visible and the original ruling survives.
The place in the code outlives the edit. When a report names a line range, the location is anchored at filing time from git. After the file is edited around it, anchor_resolve reports where that code went — moved, with the new line numbers — instead of pointing at whatever now occupies the old line.
Parallel agents don't collide. claims_claim gives one agent a card and refuses the second, naming who holds it and from which repo, so two agents cannot silently fix the same thing. Closing a card releases the claim in the same transaction.
Findings can be related and grouped. Cards link to each other, and a similarity report proposes families of near-duplicate findings as a dry run you inspect before merging anything.
It tells you when it could not look. A tracker it cannot read, a file it cannot stat, an anchor whose card never named a code span — each of these comes back as undetermined, with the reason, rather than as a confident wrong answer. codebugs where will tell you which tracker a command is actually bound to and which channel decided that, because a binding you cannot see is a binding you cannot debug.
Underneath that, it is durable memory across sessions: findings survive the conversation that produced them, requirements are checked against the code that claims to implement them, blocked work resurfaces when its dependency resolves, and a release knows what is still stranded on a branch.
codebugs is one SQLite database (.codebugs/findings.db). Modules are self-registering, and the running server reports its own tool catalogue — the module table below is the set of them.
Related MCP server: iranti
# Global install (recommended)
pipx install codebugs
# Or with pip/uv
pip install codebugsRun this once per project, in the project root:
codebugs initThis creates .codebugs/findings.db. init is the only command that creates the .codebugs/ directory — every other command discovers an existing one by walking up from the current directory (unless you point it somewhere explicitly, see below), and refuses with an actionable error if there is none. That refusal is deliberate: silently creating an empty database is how findings go missing.
There is one deliberate exception, and it is worth stating precisely because it looks like the rule being broken. The upward walk treats an existing .codebugs/ directory as the opt-in, so if that directory is there but holds no findings.db, the next command creates the database inside it rather than refusing. The common way to end up in that state is an interrupted init — the directory is created before the database — and self-healing on the next command is more useful there than demanding a second init.
A tracker you name explicitly is held to the stricter rule. --repo, --tracker-root and $CODEBUGS_ROOT must resolve to a directory that actually contains findings.db; a .codebugs/ without one is refused, and the message names which channel pointed there. The difference is about evidence: standing inside a directory says something about where you are, while a named path is an assertion that can be mistyped, or exported into a shell days ago and inherited by an unrelated process. That is exactly where a silent empty tracker does the most damage.
Two consequences worth knowing:
Run init at the project root, not in a subdirectory. Discovery binds to the nearest .codebugs/, so a nested tracker hides the project's real one from everything beneath it. init refuses to do this unless you pass --force.
Git worktrees share the main repo's tracker. A worktree's .git is a file pointing at the main repo, which discovery follows — so findings filed from a worktree land in the project's database, not in a throwaway that dies with the worktree. init refuses to run inside a worktree for the same reason; run it in the main checkout.
Two layouts are the exception: if the main repo is bare or was created with --separate-git-dir, git records no path back to a main checkout — its own git worktree list reports the git directory instead. Discovery usually refuses those with an explicit error rather than guessing. There is one case it cannot detect: a --separate-git-dir repo whose git directory is itself named .git looks exactly like a normal checkout, so discovery binds to the directory holding the git dir instead of the real checkout, silently. Nothing local can distinguish the two — git reports that directory as a valid work tree as well — so the remedy is to state the root explicitly (below). Run init in the main checkout before creating worktrees.
Discovery is a heuristic, so it has an override:
codebugs --tracker-root /path/to/project query # this invocation only
export CODEBUGS_ROOT=/path/to/project # this shell and anything it spawnsResolution order, most specific first: a command's own explicit path argument (--repo, where a command has one) → --tracker-root → CODEBUGS_ROOT → walking up from the current directory. A per-command argument outranks a declaration because it names one operation's target, while a declaration is process-wide.
codebugs where # show the current binding and which channel decided itwhere is a diagnostic, not a precedence level: it prints the resolved root, the database path, and the channel — the fastest way to check that a command is about to read the tracker you think it is.
One thing is true of every declared root, for every command except init: a root that contains no .codebugs/ is a hard error, never a new tracker. The value may be a stale export inherited from another shell, and silently creating an empty database there is how findings go missing.
init is the exception, and it treats the two channels differently, because they carry different evidence. --tracker-root DIR init creates the tracker in DIR — the flag is typed on the command line being run, so it is an assertion about this invocation, exactly like a path argument. CODEBUGS_ROOT is ignored by init, which creates where you are standing, and warns that later commands will read somewhere else: an environment variable exported days ago and inherited by an unrelated process must never conjure a tracker in a directory you are not in. Whenever the tracker init created is not the one the next command would read, it says so on stderr, since otherwise it would report success for a dead end.
CODEBUGS_ROOT is inherited by every subprocess, so export it only when you mean "this shell works on that project". For one-off use across projects, prefer --tracker-root.
Add to ~/.claude.json (global) or .mcp.json (per-project):
{
"mcpServers": {
"codebugs": {
"command": "codebugs-mcp"
}
}
}The database lives at .codebugs/findings.db, discovered by walking up from the server's working directory — each project gets its own. Run codebugs init in the project first (see above), or every tool call will fail with "no .codebugs/ found".
The server connects lazily, per tool call, so it starts successfully even when no tracker is reachable. At startup it writes a diagnostic to stderr — which MCP clients log — if discovery failed, or if a root was declared rather than discovered; on the ordinary path it says nothing. It never refuses to start: a project directory that appears later must still work.
To pin one server to one tracker instead of deriving it from the working directory:
{
"mcpServers": {
"codebugs": {
"command": "codebugs-mcp",
"args": ["--tracker-root", "/path/to/project"]
}
}
}Only do this when you want that server bound to a single project — the default cwd-derived behavior is what lets one registration serve many. Add .codebugs/ to your .gitignore.
Use --mode to load only the tools you need:
{
"mcpServers": {
"codebugs": {
"command": "codebugs-mcp",
"args": ["--mode", "findings"]
}
}
}Any module name from the module table below is a valid mode, and all — the default — loads everything. The CLI takes the same flag: codebugs --mode findings summary.
One asymmetry is worth knowing before you rely on it: usage is a CLI-only mode. It registers a command but no MCP tools, so codebugs --mode usage usage works, while codebugs-mcp --mode usage does not start at all — the server does not accept that value, and refuses it with argument --mode: invalid choice: 'usage' and exit code 2. It is not a server that runs with an empty catalogue; there is no server. The two lists of accepted modes are compared with each other, and with the module table below, by the test suite — so a mode that appears on one surface and not the other turns a test red rather than surprising you here.
Any MCP-compatible client can connect to codebugs-mcp via stdio transport.
Every name in this table is a valid --mode value.
Module | Domain | Headline tools |
findings | Bugs, tech-debt, review findings |
|
reqs | Functional requirements (FR-N) |
|
blockers | "X is blocked by Y" dependency graph |
|
sweep | Batch iteration with state machines |
|
bench | Performance benchmark snapshots |
|
merge | Parallel-agent merge serialization |
|
milestones | Releases, streams, capacity-aware pull |
|
provenance | Staleness vs git history, commit trailers |
|
claims | Which agent holds a finding or requirement |
|
loc | Where in the code a finding is, across edits |
|
similarity | Near-duplicate findings, as a dry run |
|
relations | Typed, retractable links between findings |
|
grouping | Reads the axes the tracker stores but never exposed |
|
usage | Tool-call counters (CLI only — no MCP tools) | — |
Modules are self-registering — adding a new one is local to its own file. See docs/superpowers/specs/ for the architecture history.
Not every MCP tool has a CLI verb. The milestones module is where the gap is widest: milestone_create, milestone_update, milestone_add_item, milestone_move_item, milestone_set_status, milestone_defer, milestone_close, triage_dismiss, triage_promote, pull_next and release_item are reachable through MCP only. From a terminal you can inspect a release, but you cannot create one or pull work from it.
MCP tools:
Tool | Purpose |
| Dashboard overview — start here for orientation |
| File an observation. Creates, bumps, reopens or refiles — read |
| File several observations at once |
| Change status, severity, notes, tags or metadata ( |
| Search/filter with pagination and group-by |
| Fetch one finding by id, with its full body and occurrence history |
| Findings touched at or after a date — the one call for "what closed since" |
| Cross-tabulated counts (severity x category/file/status) |
| List existing categories — call before |
| Fold twin category spellings together. Dry run by default |
staleness_check lives in the provenance module rather than here, and anchor_resolve in loc; both are listed in the module table. The tools behind the opening section — anchors, similarity, relations and grouping — have their own entry under Identity, location and grouping below.
CLI:
codebugs add -s high -c n_plus_one -f src/api.py -d "Query in loop at line 42" --new-category
codebugs summary
codebugs query --status open --severity critical
codebugs update CB-1 --status fixed --append-note "Fixed in PR #42"
codebugs categories--new-category is needed the first time a category is used, and only then. A category the tracker has never seen is refused, naming the closest existing spellings, because the common way a category set fragments is a typo — n-plus-one beside n_plus_one — and a fragmented category set is what makes categories stop revealing patterns. Once n_plus_one exists, later findings use it without the flag. Spelling is normalized on the way in, so hyphens, spaces and case do not mint twins.
--append-note adds to a finding's notes; --notes replaces them wholesale. Prefer --append-note when recording investigation history — --notes will discard whatever was there, which is usually not what you want on a finding others have been working.
When a new finding is added, the milestones auto-router automatically attaches it to stream/triage (or stream/security when severity=critical and category starts with security:). The finding and its triage entry land in the same transaction.
MCP tools:
Tool | Purpose |
| Requirements dashboard — start here |
| Add a requirement (FR-001, priority, status, test coverage) |
| Change status, description, priority, test coverage |
| Search/filter by status, priority, section, free text |
| Fetch a single requirement by ID with full body |
| Cross-tabulated counts (status x priority) |
| Automated checks: ghost test files, duplicate IDs, status contradictions |
| Import from REQUIREMENTS.md (parses markdown tables) |
| Store embedding vectors |
| Semantic search across requirements |
| Report on embedding coverage |
CLI:
codebugs reqs-import REQUIREMENTS.md
codebugs reqs-summary
codebugs reqs-verify
codebugs reqs-query --status Implemented --priority Must
codebugs reqs-update FR-090 --status Superseded --notes "Replaced by vault architecture"
codebugs reqs-export REQUIREMENTS.mdMCP tools:
Tool | Purpose |
| Defer an item until another item resolves, a date passes, or a manual signal |
| List blockers filtered by item, dependency, trigger type |
| Find currently-actionable items (all blockers satisfied) |
| Cancel or manually resolve a blocker |
Triggers come in three flavors: entity_resolved (waits for another finding/requirement to reach a terminal state), date (unblocks on a specific datetime), and manual (operator signal). When you mark a finding fixed, every blocker that was waiting on it auto-unblocks and surfaces in the next blockers_check.
MCP tools:
Tool | Purpose |
| Rollup for one milestone (counts by status/size, branch-only, blocked, days to target) |
| List milestones, filter by kind / state |
| Create a release or stream |
| Mutate |
| Attach a bug / requirement / external ref to a milestone |
| Move an item between milestones |
| Open / in_progress / done / dismissed / deferred |
| Move to |
| Refuses if open / branch-only / blocked items remain (force overrides, except for streams) |
| Full state-transition history |
| Items waiting to be triaged |
| Reject a triage item; propagates to underlying entity |
| Move a triage item to a target milestone |
| Atomically claim the next eligible item for the calling agent |
| Free agent capacity ( |
| Snapshot of |
| Flag an item as living on a feature branch only |
| Mark merged-to-main with commit SHA; clears branch_only |
Four seed milestones are created automatically:
stream/triage — inbox for unsorted findings (default destination)
stream/maintenance — deferred / boy-scout work
stream/security — urgent fixes (preempts release work)
release/1.1 — first post-1.0 release
pull_next priority order: stream/security > release/* (earliest target_date first) > stream/triage > stream/maintenance. Within a milestone: priority ASC, then created_at ASC.
Eligibility: item is open, no active blockers (skipped for item_kind='external'), acceptance required for size='large', and a large bug in a release milestone must declare linked_frs whose ids resolve to rows in requirements. Concurrent calls from multiple agents are atomic — claims are serialized via BEGIN IMMEDIATE.
CLI:
codebugs milestone-list
codebugs milestone-status release/1.1
codebugs triage-inbox
codebugs wip-status
codebugs milestone-audit --milestone release/1.1A typical autonomous-agent loop:
# 1. Agent claims the next eligible item.
item = pull_next(agent_id="agent-A", capacity={"large": 1, "small": 2, "triage": 5})
# 2. (Optional) flag a feature branch.
mark_branch_only(item_ref=item["item_ref"], branch_name="feat/CB-1234")
# 3. After integration, mark it done with the commit SHA.
mark_integrated(item_ref=item["item_ref"], commit="abc123…")
# 4. Free the agent's capacity slot.
release_item(item_ref=item["item_ref"], status="done")Closing a release runs the close-gate: unfinished, branch-only, and blocker-gated items refuse to let the milestone ship. force=True (with a logged reason) overrides — but stream/* milestones cannot be closed, even with force.
MCP tools:
Tool | Purpose |
| Create a new sweep (optional |
| Add items. Atomic upsert: existing items bump |
| Next batch of unprocessed (non-terminal, non-archived) items |
| Transition state (legacy |
| Progress overview |
| Soft-delete |
| Inspection |
codebugs sweep-create --name lint-pass --batch-size 5
codebugs sweep-add lint-pass src/*.py --tags critical
codebugs sweep-next lint-pass
codebugs sweep-mark lint-pass src/api.py
codebugs sweep-status lint-passWith a custom lifecycle (e.g. for retro findings):
codebugs sweep-create --name retro-findings \
--lifecycle DETECTED,CONFIRMED,ESCALATED,RESOLVED,DROPPED \
--terminal-states RESOLVED,DROPPED
codebugs sweep-add retro-findings finding-2026-04-todo-bypassed --tags silent_abandonment
codebugs sweep-mark retro-findings finding-2026-04-todo-bypassed --state CONFIRMED
codebugs sweep-archive-items retro-findings --state RESOLVED --older-than 30dMCP tools:
Tool | Purpose |
| Import benchmark results (file or inline) |
| Filter and trend metrics across runs |
| List recorded runs |
| Remove a run |
MCP tools:
Tool | Purpose |
| Open a merge session |
| Claim files for the session (advisory file-level claims) |
| Check for overlapping claims against |
| Mark merge in progress (acquires the global merge lock with TTL) |
| Release the lock |
| List all files a session has claimed, in claim order |
| List merge sessions with claim counts |
| Dashboard: session counts by status, total active claims |
| Close a session for good, so its files stop blocking everyone else |
The opening section's claims about identity, location and grouping rest on loc, similarity, relations and grouping, and none of them had an entry here before.
Tool | Purpose |
| Where a finding's code is now — |
| Rebuild stored anchors from the git object store. Dry run by default |
| Preview what the file-time annotator would stamp for an observation |
| Similarity families as auditable evidence — a scrub you read, never a merge it performs |
| Assert a typed relation ( |
| List relations touching a finding, in both directions |
| Retract a relation. Tombstones it — the row and its history remain |
| Connected components of the hand-written CB-id reference graph |
| Tag pivots: counts, co-occurrence, near-duplicate taxonomy strings |
| Split lineages and shared filing events |
An anchor needs the filing to name a code span. The location is captured from meta.line / meta.lines (and a few equivalent spellings) at the moment the finding is filed. A report that names only a file has nothing to anchor, and anchor_resolve says so — unknown, reason no_grammar — instead of guessing a line. Most findings in practice name no span, so this is the ordinary case, not an error:
$ codebugs anchor-resolve --finding-id CB-2 --repo . --json
...
"anchor": {
"status": "moved",
"path": "src_api.py",
"line": 25,
"end": 27,
"channel": "git",
"reason": null,
"survived": "3/3",
...That card was filed against lines 5–7. Twenty lines were then inserted above it. The stored line numbers are stale; the anchor is not.
The ... are elision marks rather than output: this is one entry lifted out of a larger JSON document, and the anchor object carries one further key below survived — resolved_against, the root, commit and on-disk file the answer was computed against. Nothing is ever omitted because it was absent. Every key is present on every answer, so "reason": null here means there is nothing to explain, because there is an answer — never this field is missing.
AI code review sessions produce findings that get lost. Multiple agents working in parallel double-claim work. Requirements files drift. Releases lose track of what's in them.
codebugs stores everything in one local SQLite database. AI assistants write findings, requirements, and milestone items as they discover them, then query the database in future sessions for instant context recovery. Concurrent agents coordinate via the same database — no race conditions, atomic claims.
Token savings: a summary call returns one small structured overview — counts by severity, the top categories, the hottest files — instead of the file reading and conversation replay it would otherwise take to re-establish the same picture.
Code review loop. This is the same loop the MCP server tells every client that connects, so the two cannot drift apart:
File the observation with add (or batch_add for several at once). Call categories first when you are unsure of the naming.
Read what came back before doing anything else. dedup_action says whether this created a new card, bumped or reopened an existing one, or refiled one already dismissed. attention is the server's own flag when your observation raised the card's severity or diverged from its stored category — a card you thought you were filing fresh but which the tracker already knew about, differently.
The code location is anchored at file time when the observation names one; anchor_resolve reports whether that anchor still points at live code.
Close the card with update CB-N --status fixed once it is actually fixed.
Working alongside other agents on the same tracker? Claim the card with claims_claim before starting and release it with claims_release when done, or two agents can end up fixing the same thing. Closing the card releases the claim on its own.
Each add also auto-routes the finding to stream/triage, and over time categories reveals systemic issues — "12 tz_naive_datetime fixed across 9 files → time for a lint rule."
Requirements (reqs_add, reqs_query, ...) are a separate, authored entity next to findings, and they have no deduplication. Do not file a requirement through add, or a defect through reqs_add.
Release loop:
Triage: AI calls triage_inbox → triage_dismiss non-bugs, triage_promote real items to release/1.1 (with linked_frs for the ones that need an FR row).
Execution: Each parallel agent calls pull_next(agent_id=..., capacity=...) → claims the next eligible item.
After landing: mark_integrated(item, commit) → release_item(item, status='done').
Close: milestone_close("release/1.1"). Refuses if anything is stranded on a branch; lists the offenders with the branch name.
All tables share .codebugs/findings.db with flexible JSON columns. Schemas are additive — every module owns its tables, declares dependencies, and migrates additively.
Field | Type | Description |
| text | Auto-generated ( |
| text |
|
| text | User-defined (e.g. |
| text | File path relative to project root |
| text |
|
| text | What's wrong |
| text |
|
| json | Array of strings for ad-hoc grouping |
| json |
|
| text | Provenance for staleness checks |
Field | Type | Description |
| text | User-provided ( |
| text | per-row metadata |
| blob | Optional float32 vector for semantic search |
| json |
Table | Purpose |
| Slug ( |
|
|
| Append-only log: actor, action, from_state → to_state, reason, timestamp |
| Per-agent WIP ( |
Item kinds are bug (validated against findings), requirement (validated against requirements), or external (free-form, blockers skipped). The (milestone_id, item_kind, item_ref) unique constraint prevents double-attach.
Field | Type | Description |
| text | Blocked entity (e.g. |
| text | Dependency (or null for date/manual triggers) |
| text |
|
| text | UTC datetime for date triggers |
| text | Human explanation |
Table | Purpose |
|
|
|
|
$ codebugs categories
category total open fixed
------------------------ ----- ---- -----
tz_naive_datetime 15 3 12
n_plus_one 8 2 6
missing_input_validation 6 4 2If you keep fixing the same category → time for a lint rule. codebugs turns reactive bug-fixing into proactive prevention.
This is the view the category gate above protects. Had half those findings been filed as tz_naive_dt, the table would show two rows of 8 and 7 instead of one row of 15, and there would be no pattern to see. Normalization handles the punctuation-and-case twins on its own; the gate is what catches a genuinely different name for the same thing.
reqs_verify catches documentation rot before it ships:
$ codebugs reqs-verify
Verified 3 requirements.
4 issue(s) found:
check sev id message
------ ------ ------ -----------------------------------------------------------
ids medium -- Numbering gaps (5+): FR-007..FR-089, FR-091..FR-349
status medium FR-006 Must-priority requirement implemented without test coverage
status high FR-090 Description mentions 'superseded' but status is 'planned'
status medium FR-350 Must-priority requirement implemented without test coverageStore embeddings (caller generates vectors via any embedding API) and find related requirements semantically:
reqs_embed(req_id="FR-001", embedding=[0.1, 0.2, ...])
reqs_search_similar(query_embedding=[...], limit=5, min_similarity=0.3)Float32 BLOB storage in SQLite; brute-force cosine similarity — fast for thousands of requirements.
milestone_close won't let you ship a release with work stranded on a branch. First, what the release looks like:
$ codebugs milestone-status release/1.1
release/1.1 (release, state=open)
target: 2026-09-15 (19 days)
First post-1.0 feature release. Target date set later.
Items: 3 total (3 open/in_progress, 0 done)
By status:
open 3
By size:
small 3
Branch-only: CB-1
Blocked: CB-2Then closing it. milestone_close is one of the milestone tools with no CLI verb — this is the error the MCP tool returns, raised as a ValueError from the domain function, on a single line:
cannot close release/1.1: unfinished items (3): CB-1, CB-2, CB-3; branch-only items (1): CB-1@feat/CB-1; items with active blockers (1): CB-2 (use force=True with reason to override)force=True with a logged reason overrides that. Streams do not have an override — milestone_close(id="stream/triage", force=True, reason="x") still refuses with streams cannot be closed (milestone=stream/triage), because they are permanent buckets rather than things that ship.
Python 3.11+
One runtime dependency: mcp>=2.0.0,<3, for the server. The 2.0 floor is not cosmetic — server.py uses MCPServer, the class that replaced FastMCP in the 2.0 SDK, so an older mcp will not start.
SQLite (bundled with Python)
# Run tests
uv run --extra dev python -m pytest tests/ -q
# Lint — this is the gate
uv run --extra dev ruff check src/ tests/pytest and ruff live in the dev extra, which uv run does not install by default, so --extra dev is not optional in a fresh clone.
ruff format is deliberately not run over this tree. Much of the existing code does not conform to it, so ruff format src/ tests/ would rewrite most of the repository in one commit. ruff check is the gate; formatting is left alone on purpose.
See CLAUDE.md for architectural rules and conventions.
MIT
Record a code finding observation (deduplicated by fingerprint).
If the fingerprint matches a live finding, that finding's occurrence count
is bumped and IT is returned (was_new: false, dedup_action: "bumped");
a match on a fixed finding reopens it as a regression ("reopened"); a
match on a wont_fix/not_a_bug finding creates a new row linked via
meta.recurrence_of. Without a fingerprint a conservative server-side one
is derived from category, file and the normalized description.
dedup_action has exactly four values — "created", "bumped", "reopened"
and "recurrence_of_closed" — and the fourth is the one to read carefully:
a recurrence of a DISMISSED twin files a NEW row and therefore reports
was_new: true, so a client that tells create from match by gating on
was_new == false misses the event entirely. The twin's id is always in
meta.recurrence_of, and meta.similar_to usually carries its status
alongside; on the paths where it does not — a caller-supplied fingerprint
whose text does not resemble the twin, or a normalized description under
the similarity minimum — the twin's status is NOT in this response at
all, and costs one get.
attention is a top-level list, ALWAYS present and often empty: an empty
list means "evaluated, nothing serious fired", which is a different fact
from an absent channel. Two record forms exist, and a list may carry both
(severity first, category second; each form at most once).
{signal: severity_escalated, from, to} says THIS observation raised the
finding's stored severity. It appears only where a stored severity was
raised — the bumped and reopened branches — and severity is monotonic
under observation, so there is no de-escalation record to expect.
{signal: category_divergence, observed, stored} says this observation
does not NAME the matched finding's category. It appears on every branch
that HAS a matched row: bumped, reopened, and the recurrence branch,
where the comparison is against the DISMISSED TWIN rather than the new
row. Both sides are normalized, so a difference of spelling
(Process Improvement vs process-improvement) is deliberately not a
signal while a difference of name is; a stored category that is not text
is skipped rather than raising. A newly created finding matched nothing,
so it emits neither record.
stripped_meta_keys is a top-level list, ALWAYS present and often
empty, following the same discipline as attention: [] means
"checked, nothing to strip", never "no such channel". A meta key
that is identity machinery OUTPUT (e.g. occurrences, recurrence_of,
category_minted) is stripped from what gets stored rather than
refused, so a caller that copies a fetched card's meta forward
(get -> modify -> add) can tell, from this response alone, which
of its own keys silently did not land. resolver_errors is the one
exception: it reports a FAILURE state, not machinery input, so it is
REFUSED outright rather than stripped, on this path exactly as on
update's meta_update. This is the ADD-side contract only — CSV
import strips the same dynamic reserved union but silently, with no
equivalent response key (a decided, separate contract, CB-51), and
update's meta_update still refuses every reserved key rather than
stripping any of them.
stripped_description_tail is a top-level boolean, ALWAYS present and
usually False, following that same discipline: False means "checked,
nothing to cut", never "no such channel". Some filing agents leak a
slice of their own tool call into the end of description; when the
text after a </description> marker is nothing but envelope lines, that
tail is CUT rather than refused — the finding is real and only its tail
is junk — and cut BEFORE the fingerprint is derived, so a tailed and a
clean report of one defect collapse onto one card instead of two. Prose
that merely quotes the marker is not cut. True means the text stored
is not byte-for-byte the text you passed.
Args:
severity: critical, high, medium, or low (case-insensitive, no aliases)
category: Finding category (e.g. tz_naive_datetime, n_plus_one, missing_validation). Call categories first to reuse existing category names. Spelling is normalized (casefold, hyphen/whitespace -> "_"); a category this tracker does not already hold is REFUSED with a hint unless new_category=true — but only when the observation would CREATE a row: a fingerprint match on a known live or fixed finding is recorded regardless, with the observed category kept in the occurrence ring.
file: File path relative to project root
description: What's wrong
lines: WHERE IN THE CODE this finding is, and the only input that gives the card a durable ANCHOR. An anchor stores the surrounding source text and the commit it was read at, so the card still points at the right code after the file is edited and the line numbers move; a path written in description does not, and is never read as a location. WITHOUT THIS THE CARD HAS NO ANCHOR — nothing else in this call supplies one. Four spellings, all accepted: a bare line number ("1850") or range ("1850-1870"), which are read against the file argument above; a full "path/file.py:1850" token, whose path must name the same file as file or the anchor is refused rather than pointed at another file's line numbers; and a list ("[1850, 1870]"), which is N SEPARATE lines and never a range. Pass it whenever the finding is about a place in the code. Omit it — do not invent one — when the finding is about a process, a decision or a whole file: a made-up anchor is worse than none. Same field as meta.lines; supplying both with different values is refused.
source: First reporter of this defect (default: claude). Frozen at first report by design (BT-4): a re-observation keeps the original; newest sources live in the occurrence ring (meta.occurrences[*].source) — and an imported observation's ring source can be a peer tracker's.
tags: Optional tags for grouping
meta: Optional JSON metadata for anything this call has no argument for (module, rule_code, and so on). The code location is NOT one of those: it has its own lines argument above, and that is the spelling to use. meta.lines remains the same field and still works, so the two must not disagree — passing both with different values is refused rather than one silently winning. Top-level meta is the row's AUTHORED state, observation-frozen (BT-4): a re-observation's meta lands only as per-occurrence evidence in meta.occurrences[*].meta. Promoting specific keys into the row is a future allowlist by measured demand, not a general merge.
reported_at_commit: Git SHA when finding was created (auto-detected from HEAD if omitted)
reported_at_ref: Version/tag label (e.g. "v2.1.0"), always caller-supplied. Observation-frozen: a bump never updates it (per-occurrence refs stay in the ring as evidence) — but manually mutable BY DESIGN via update(reported_at_ref=), since a release is tagged after filing.
fingerprint: Stable identity token for this defect, computed from the INVARIANT part of the observation (normalized error signature + failing test + anchor file — no timestamps, SHAs, run ids). Same defect → same fingerprint. The auto: prefix is reserved for server-derived values.
new_category: Explicit permission to MINT a category the tracker does not hold yet (CB-60). Minting is stamped as meta.category_minted for later counting. Existing categories never need this.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | ||
| meta | No | ||
| tags | No | ||
| lines | No | ||
| source | No | claude | |
| category | Yes | ||
| severity | Yes | ||
| description | Yes | ||
| fingerprint | No | ||
| new_category | No | ||
| reported_at_ref | No | ||
| reported_at_commit | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it delivers: it discloses dedup_action's four values, which branches set was_new, the always-present attention and stripped_meta_keys lists, severity monotonicity, source freezing, animation of meta, and the stripped_description_tail behavior. It even warns about the recurrence-of-dismissed-twin case where gating on was_new misses events. This is unusually complete behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but structurally sound: core dedup behavior first, response contracts next, then per-argument semantics. Nearly every sentence earns its place given the genuinely complex behavior, though there is minor redundancy (the meta.lines conflict rule is stated twice) and some response details could have been left to the output schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 12-parameter write tool with complex dedup, recurrence, anchor, and response semantics, the description covers everything an agent needs: all required behaviors, edge cases, failure paths, return-signal meanings, and costs. The only absent details, such as exact response shapes, are presumably supplied by the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate entirely, and it does: every one of the 12 parameters gets semantic detail beyond its type. Severity gets a case-insensitive enum, category gets normalization and minting rules, lines gets four accepted spellings and anchoring semantics, fingerprint gets invariance rules, and meta gets observation-frozen behavior plus a conflict rule with lines.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Record a code finding observation' with deduplication by fingerprint. It immediately distinguishes the add path from related write operations by describing create/bump/reopen/recurrence semantics, so an agent can tell this from update and batch_add without opening their schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: call categories first, use new_category only when creating a row, pass lines when the finding is code-located, and omit lines for process-level findings. It also contrasts the add-side contract with update's meta_update and CSV import, making the selection boundary clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rebuild stored location anchors from the git object store. DRY RUN by default.
The sanctioned repair path: meta.loc is writable through
update_finding(meta_update=) and NOTHING validates it there, so a
hand-assembled object is accepted at the write and read back as
unknown(invalid_anchor). This verb builds the object itself, from the
same capture the file-time resolver uses.
Four behaviours are specified rather than incidental. A FAILED capture
never replaces a valid stored anchor (outcome kept) — the refusal is
usually about the environment, and the anchor it would destroy is still
good in a clone that has the history. The loc: null tombstone ("do not
recapture") is left alone unless force_tombstone says otherwise. The
git work runs outside any transaction, and only the version check and
the write share one — so a row whose anchor changed while the capture
ran is reported stale and left to the other writer.
include_unanchored widens the POPULATION to rows that never carried an
anchor at all — every finding filed before the capture seam landed, since
capture runs only when a genuine new finding is filed. They report
would_backfill/backfilled, never folded into would_update/updated:
"acquired an anchor for the first time" is the number this exists to
produce. It is NOT force_tombstone (a loc: null tombstone is a key
that is present and null, and this flag never touches it) and it is NOT a
fingerprint backfill — nothing here reads or writes that column.
Args:
finding_id: Repair one finding instead of a population
status: Status filter; "all" widens to every status (default: open)
category: Restrict to one category
file: Restrict to one file (the finding's file column)
project_dir: The repository to capture from. Omitting it makes every capture refuse with no_root, which by the rule above leaves every valid anchor untouched
apply: Write the rebuilt anchors (default: report only)
force_tombstone: Overwrite a loc: null tombstone
include_unanchored: Also take rows carrying no loc key at all (the backfill population). Leaves tombstones alone; still a dry run unless apply is set
limit: Maximum findings examined (default 10000). 0 means NO findings are examined; a negative value is an error (it used to mean "no limit").
| Name | Required | Description | Default |
|---|---|---|---|
| file | No | ||
| apply | No | ||
| limit | No | ||
| status | No | open | |
| category | No | ||
| finding_id | No | ||
| project_dir | No | ||
| force_tombstone | No | ||
| include_unanchored | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden — and it does so excellently. It discloses dry-run default, failure-capture never replacing valid anchors, tombstone preservation unless force_tombstone, git work running outside the transaction with stale outcomes, and the distinct backfill outcome family for include_unanchored. This is far richer behavioral disclosure than annotations would typically provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long, but the tool is genuinely complex with nine parameters, multiple outcome families, and a transactional caveat. The first line front-loads purpose and default mode, and later paragraphs each add non-obvious behavior that materially affects invocation. Minor redundancy, such as restating the dry-run default inside the apply argument, keeps it just short of a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and zero schema descriptions, the description leaves little uncovered: it defines outcome vocabulary (kept/stale/would_backfill/backfilled), default behavior, failure modes (no_root, negative limit), population filters, and the relationship to update_finding. An output schema exists, so return-value detail is not required. A caller has everything needed to decide whether to run this tool and with which flags.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate entirely for the bare input schema. The Args section covers all nine parameters with non-obvious semantics: include_unanchored's population-widening and dry-run interaction, project_dir's no_root failure mode, the changed limit semantics (0 means no findings, negative is an error), and the meaning of apply, force_tombstone, status, category, file, and finding_id. No parameter is left as a bare title.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Rebuild stored location anchors from the git object store' and immediately signals the default dry-run mode. It distinguishes this verb from the nearby repair path (update_finding with meta_update) and from sibling anchor tooling, making the tool's role as the sanctioned anchor-repair operation unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when this tool is the right choice: it is the sanctioned repair path because update_finding does not validate hand-assembled anchors, and it explicitly says what the tool is NOT (force_tombstone, fingerprint backfill). It does not name a specific sibling tool as the alternative for ordinary anchor lookup or resolution, so the guidance is strong but not a complete when-to-use vs alternate-to-use routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve stored location anchors to their current lines on HEAD.
Each anchored finding gets a record: status (current / moved /
moved_file / lost / ambiguous / unknown), the coordinate, the channel
that produced it ("git" for reverse blame, "content" for the secondary
text channel), a reason token when there is no answer, and
survived as "/" when part of a span outlived the rest.
moved_file is a status of its own, not moved with a different path:
the code left the file the finding names, and a consumer must see that
rather than receive a line number in a file it never asked about.
THE SUMMARY'S DENOMINATOR IS anchored, NOT total. anchored counts
the rows that CARRY an anchor (a persisted refusal and the tombstone
included); rows filed before anchors existed carry none and are counted
in without_anchor instead. So a moved_file share is
summary["moved_file"] / anchored; computing it against total is a
share of a population the number does not describe.
Args:
finding_id: Resolve one finding instead of a population
status: Status filter; "all" widens to every status (default: open)
category: Restrict to one category
file: Restrict to one file (the finding's file column)
project_dir: The repository the anchors resolve against. Omitting it reports no_root rather than reading whatever tree the server process happens to stand in — a long-lived server's cwd has nothing to do with the tracker a call is about
limit: Maximum findings examined (default 10000). 0 means NO findings are examined; a negative value is an error (it used to mean "no limit").
| Name | Required | Description | Default |
|---|---|---|---|
| file | No | ||
| limit | No | ||
| status | No | open | |
| category | No | ||
| finding_id | No | ||
| project_dir | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and delivers extensive behavioral detail: each record's fields and statuses, the special meaning of moved_file, the summary denominator being anchored rather than total, and the unexpected behaviors of project_dir and limit. These are exactly the kinds of traps an agent needs to know about.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every section earns its place: core purpose, output record format, status semantics, a critical denominator warning, then parameter explanations. It is front-loaded with the most important information and contains no filler or tautology.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the tool and the presence of an output schema, the description is complete. It explains the return record structure, all statuses, the denominator semantics, and parameter edge cases. Nothing an agent needs to invoke the tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it does thoroughly. Every parameter receives a purpose explanation, and the trickiest ones get edge-case warnings: project_dir's no_root behavior, limit's 0 meaning no findings and negative being an error, and the distinction between open and all for status.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb-resource pair: 'Resolve stored location anchors to their current lines on HEAD.' This clearly identifies what the tool does. However, it does not explicitly distinguish itself from the sibling tool anchor_recapture, so while the purpose is unambiguous, sibling differentiation is left to inference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use the tool and how to narrow scope: finding_id for a single finding, status filters, category, file, project_dir, and limit. It includes notable guidance such as omitting project_dir yielding no_root rather than using the server's cwd. However, it does not explicitly mention alternatives or when-not-to-use it compared to related siblings like anchor_recapture.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record multiple finding observations at once (deduplicated by fingerprint).
Members are deduplicated exactly like add — including against each other,
so two members sharing a fingerprint yield one insert plus one bump. One
result per input, in input order. Unknown member keys are refused.
Each result carries the same discriminators add returns, and the same
four dedup_action values: "created", "bumped", "reopened" and
"recurrence_of_closed", the last of which reports was_new: true because
it files a NEW row linked to a dismissed twin via meta.recurrence_of.
Each result also carries its OWN attention list — always present, often
empty, never shared between members. Two record forms exist, in this
order and at most once each:
{signal: severity_escalated, from, to} on the bumped and reopened
branches, meaning that member's observation raised the stored finding's
severity; and {signal: category_divergence, observed, stored} on every
branch with a matched row (bumped, reopened, and the recurrence
branch, where the comparison is against the dismissed twin), meaning that
member does not NAME the matched finding's category. Both category sides
are normalized, so a difference of spelling is not a signal; a stored
category that is not text is skipped rather than raising.
Each result also carries its OWN stripped_meta_keys list — always
present, often empty, never shared between members — following the
same discipline: a meta key that is identity machinery OUTPUT (e.g.
occurrences, recurrence_of, category_minted) is stripped from
what gets stored rather than refused, and reported here so a caller
forwarding a fetched card's meta can tell which of its own keys
silently did not land. resolver_errors is refused outright instead
(a FAILURE state, not machinery input), on this path exactly as on
add.
Each result likewise carries its OWN stripped_description_tail
boolean — always present, usually False, meaning "checked, nothing to
cut" rather than "no such channel". A leaked tool-call tail on that
member's description (envelope lines and nothing else after a
</description> marker) is CUT rather than refused, before the
fingerprint is derived so a tailed and a clean report of one defect
collapse onto one card; prose merely quoting the marker is left alone.
True means that member's stored text is not the text you passed.
Args:
findings: List of finding objects, each with keys: severity, category, file, description, and optionally: lines, source, tags, meta, reported_at_commit, reported_at_ref, fingerprint. lines is per-member and works exactly as it does on add: it is WHERE IN THE CODE that member is, and the only input that gives its card a durable ANCHOR surviving later edits to the file. A bare number ("1850"), a range ("1850-1870"), a full "path/file.py:1850" token (whose path must name that member's own file) or a list of lines. Omit it on a member that describes no place in the code rather than inventing one. It is the same field as that member's meta.lines, and the two are refused when they disagree.
reported_at_commit: Default commit SHA for all findings (auto-detected if omitted). Per-finding values override this.
reported_at_ref: Default version label for all findings. Per-finding values override this.
new_category: Batch-wide permission to MINT categories the tracker does not hold yet (CB-60); the first member introducing a category is stamped meta.category_minted.
| Name | Required | Description | Default |
|---|---|---|---|
| findings | Yes | ||
| new_category | No | ||
| reported_at_ref | No | ||
| reported_at_commit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility for behavioral disclosure. It does so extensively: deduplication across members, result ordering, one-result-per-input, refusal of unknown keys, the four `dedup_action` branches, per-member `attention`, `stripped_meta_keys`, `stripped_description_tail`, and `new_category` minting behavior. This is far beyond a minimal safety or mutation warning.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long, but the complexity of the behavior justifies most of it. It is front-loaded with the central purpose and dedup rule, then methodically covers result semantics and argument details. Some redundancy exists (e.g., repeated 'always present, often empty, never shared' phrasing), so it is not maximally concise, but every major clause adds operational value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the sparse schema, absent annotations, and rich behavioral surface, the description is remarkably complete. It covers input requirements, deduplication, result shape, edge cases for meta stripping and description tails, failure behavior for unknown keys and `resolver_errors`, and category minting. An agent can invoke this tool correctly without needing external documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is nearly empty—0% schema description coverage—so the description fully compensates. The Args section details every parameter: `findings` item keys with `lines` semantics and constraints, per-finding overrides for `reported_at_commit` and `reported_at_ref`, and the batch-wide `new_category` permission. This gives an agent everything needed to construct valid arguments.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence, 'Record multiple finding observations at once (deduplicated by fingerprint)', states a specific verb, resource, and key behavior. It clearly distinguishes this tool from single-item alternatives like `add` and other sibling tools by emphasizing batch operation and deduplication semantics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the tool's intended use evident—recording multiple findings at once—and repeatedly anchors behavior to `add`, making the relationship to the single-finding alternative clear. It does not explicitly say 'use this when you have multiple findings and use `add` for a single one', but the batch focus and cross-references provide strong contextual guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Defer an item by adding a blocker.
Args:
item_id: The blocked entity (e.g. "CB-5", "FR-012")
reason: Why it's blocked
blocked_by: Dependency entity (e.g. "CB-3"). Required for entity_resolved triggers.
trigger_type: entity_resolved, date, or manual. Defaults to entity_resolved if blocked_by provided, manual otherwise.
trigger_at: Date/datetime for date triggers (e.g. "2026-04-10"). Normalized to UTC.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | Yes | ||
| item_id | Yes | ||
| blocked_by | No | ||
| trigger_at | No | ||
| trigger_type | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It usefully discloses default trigger_type behavior, the blocked_by conditional requirement, and UTC normalization. However, it does not describe side effects beyond 'defer', reversibility, auth requirements, or failure behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The lead sentence is direct and the argument list is tight and scannable. Each line conveys necessary information without filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
All five parameters and their defaulting rules are covered, and an output schema exists so return details need not be explained. Still, for a mutation tool there is no explicit statement of post-conditions or reversibility, leaving slight incompleteness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully compensate. It does: every parameter gets meaningful semantics, examples, default behavior, conditional requirements, and format normalization.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action: 'Defer an item by adding a blocker.' This makes the primary function clear and separates it from blocker query/check/resolve siblings, though it does not explicitly name those alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance about when to use this tool versus alternatives like blockers_resolve or milestone_defer. The description gives parameter logic but no context for choosing this tool or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scan for currently actionable items — items whose blockers are all satisfied.
Returns actionable items (all blockers met), partially unblocked items (some blockers met), and overdue date triggers.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the behavioral burden. It frames the operation as a non-mutating scan and explicitly describes what is returned: actionable items, partially unblocked items, and overdue date triggers. It does not discuss auth or rate limits, but for a zero-parameter check tool the key behavior is well conveyed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loads the core scanning purpose, then adds the useful return categories. There is minor redundancy in defining actionable items twice, but no wasted sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with an output schema and no annotations, the description covers what the tool scans and what classes of results it returns. The main missing piece is explicit guidance about when to use this tool over the sibling blocker query/resolution tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is empty and the tool has zero parameters, so there is no parameter meaning for the description to add. Per the rubric, zero parameters receive a baseline of 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies a clear verb ('Scan') and resource ('currently actionable items — items whose blockers are all satisfied'), and it names the return categories. It does not explicitly differentiate this tool from sibling blockers_query, so it stops just short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Scan for currently actionable items' implies the intended use case, and the returned categories add context. However, there is no explicit when-to-use/when-not-to-use guidance or mention of alternatives such as blockers_query or blockers_resolve.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List blockers with filters. Each result includes computed satisfaction state.
Args:
item_id: Filter by blocked item (e.g. "CB-5")
blocked_by: Filter by dependency ("what does CB-3 unblock?")
trigger_type: Filter by trigger type (entity_resolved, date, manual)
active_only: Only unsatisfied, uncancelled blockers (default: true)
| Name | Required | Description | Default |
|---|---|---|---|
| item_id | No | ||
| blocked_by | No | ||
| active_only | No | ||
| trigger_type | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It adds useful details such as 'computed satisfaction state' and the active_only default semantics, but it does not clarify whether filtering is conjunctive, how results are ordered, or whether any side effects exist beyond reading.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the purpose, followed by compact bullet explanations for each parameter. Every sentence earns its place, and the examples add meaningful value without bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists, the description covers all parameters and the key computed output concept. It is slightly incomplete in lacking alternative-tool routing and filter combination semantics, but is otherwise well-rounded for a query tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description fully compensates by explaining all four parameters with concrete examples, allowed values for trigger_type, and the default for active_only. This is strong parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists blockers and mentions filtering, which is specific and distinct from siblings like blockers_add and blockers_resolve. It does not explicitly contrast with blockers_check, so it stops short of full sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for listing blockers with filters, but provides no explicit guidance on when to choose this tool over alternatives like blockers_check or blockers_resolve. No usage context or exclusion criteria are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cancel or manually resolve a blocker.
Args:
blocker_id: The blocker row ID
action: 'cancel' (any trigger type) or 'resolve' (manual triggers only)
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | ||
| blocker_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral disclosure burden. It does explain the two allowed actions and the manual-trigger restriction for 'resolve', but it does not disclose side effects, reversibility, permissions, or the post-condition state of the blocker. This is a moderate disclosure gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short, front-loaded with the main purpose, and uses a compact bulleted argument list. Every sentence contributes semantic value without redundant repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with an output schema present, the description provides enough information to invoke it correctly, including both parameter meanings and the conditional action rules. It stops short of full completeness due to the lack of behavioral side-effect disclosure, but nothing critical to basic invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must fully compensate. It defines blocker_id as 'the blocker row ID' and enumerates the exact allowed action values with their applicability conditions, adding meaning well beyond the raw schema fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool cancels or manually resolves a blocker, using specific verbs and a defined resource. It is distinct from the sibling tools like blockers_add, blockers_query, and blockers_check by expressing its resolution/cancellation purpose directly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides actionable usage constraints: 'cancel' works with any trigger type, while 'resolve' is limited to manual triggers. It does not explicitly contrast with related blockers_* tools, but the action-level guidance is clear enough for correct invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all existing categories with counts. Call this before adding findings to reuse consistent category names.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, and the description labels the tool as a list operation, which implies read-only behavior. It discloses that counts are returned and offers workflow context, but it does not define what the counts refer to or any edge behavior such as empty results. This is adequate but minimal for a zero-parameter query tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with the primary action front-loaded and the workflow hint in the second sentence. No filler or redundant restating of the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-parameter list tool with an output schema available, the description covers what the tool returns ('categories with counts') and when to use it. Nothing needed to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes no parameters, so there is no schema burden for the description to carry. The description's focus on purpose is sufficient given the empty input schema, matching the baseline for zero-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States an unambiguous action — 'List all existing categories with counts' — with a direct object and expected payload. The verb 'List' separates it from sibling normalize/write tools even without naming them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to call before adding findings so category names are reused consistently, giving clear situational context. It does not state when not to use it or name an alternative like categories_normalize, so it stops short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rename stored categories and re-key their fingerprints (CB-61).
TWO MODES, and the second is a working mode rather than a side effect.
Without fold_map this folds every stored SPELLING to its canonical
form, for rows filed before write-time canonicalization existed, whose
stored auto:v1 fingerprint still carries the old spelling and therefore
forks identity when the same defect is reported again. With a fold_map
it MERGES CATEGORY NAMES: any stored name may be renamed to any canonical
target, and the two need not be spellings of each other. That second mode
is how a tracker's rare category names are collapsed into its common ones.
DRY RUN BY DEFAULT — without apply=true nothing is written and the
report tells you exactly what would change. A key that matches no stored
category is accepted and renames nothing, and unmatched_fold_keys names
every one of them, so a typo on the left-hand side is stated rather than
left to be spotted as a pair missing from the from -> to table. A typo
in a TARGET is refused instead — see new_category. Matching is exact
against the stored spelling, so a canonical key does not reach a stored
Process Improvement and is reported unmatched. Take an export-csv
backup before applying; restore-csv puts findings back verbatim into an
EMPTY tracker, but milestone items and audit history are not in a CSV
export and are not restored.
Each renamed row's fingerprint is handled by kind: a NULL or a
caller-SUPPLIED fingerprint is left byte-identical, an auto:v1 one is
re-derived with the new category after its stored inputs are verified to
reproduce the stored hash. A row that fails that round trip is skipped
WHOLE and reported under unverifiable. The occurrence ring
(meta.occurrences) is never rewritten.
If the fold would put two LIVE findings on one fingerprint, the run
writes NOTHING and reports the colliding pair by id — merging two cards
is a decision, not a migration step. Any OTHER identity merge — two closed
cards, or a closed card and a live one — is legal, so it is reported under
merged_identities rather than refused: the run proceeds, and you are told
which cards this fold fused. Both unmatched_fold_keys and
merged_identities are always present; [] means "checked, none".
Args:
fold_map: Optional {stored category name: canonical target name} map, as an object or a JSON string. The key is matched exactly against the stored value and may be any name the table holds. Every target must already be canonical (casefold, hyphen/whitespace -> "_"). Omit it to fold every stored spelling to its own normalized form; {} is an explicit no-op.
apply: Write the changes. Default false (report only).
new_category: Permission to fold INTO a category this tracker does not hold yet, for the whole map at once. Without it such a target is refused, naming the nearest existing categories — an operation meant to REDUCE the number of category names must not invent one by typo. The refusal stops at the first bad target.
| Name | Required | Description | Default |
|---|---|---|---|
| apply | No | ||
| fold_map | No | ||
| new_category | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral burden and does so thoroughly. It discloses dry-run behavior, the exact effects of apply=true, per-kind fingerprint handling, collision safety (writes NOTHING on live-fingerprint collisions), refusal of typo targets, and that meta.occurrences is never rewritten.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but densely informative, and every paragraph earns its place given the data-integrity stakes. It front-loads the core purpose and modes, then uses structured paragraphs and an Args list for details, keeping the material navigable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex migration tool with an output schema, no annotations, and zero schema parameter descriptions, this description is remarkably complete. It covers prerequisites, failure modes, collision behavior, skipped rows, report fields, and parameter semantics, leaving no critical decision point unexplained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully compensate. It does: fold_map is explained with exact-match semantics, accepted value forms, and {} as an explicit no-op; apply is tied to dry-run default; new_category is explained with its refusal behavior and purpose. All three parameters receive rich, actionable meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening line, 'Rename stored categories and re-key their fingerprints (CB-61)', states a specific verb, resource, and scope. It then distinguishes two modes (spelling normalization vs. category merging), making the tool's purpose precise and distinguishing it from sibling category and grouping tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when each mode is appropriate: without fold_map for legacy spellings, with fold_map for collapsing rare categories into common ones. It also advises taking an export-csv backup before applying and warns about restore-csv limitations, though it does not explicitly name alternative sibling tools to use instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim a finding or requirement so parallel agents do not collide.
Args:
entity_id: CB-N, FR-N or NFR-N
holder: who is claiming — a branch name, agent id, or person
holder_kind: branch | agent | human
holder_repo: absolute path of the repo owning the branch, if any
note: free-text reason, kept on renewal unless replaced
project: also move a finding to in_progress (requirements never project)
allow_terminal: claim even if the entity is already resolved
Returns:
outcome: claimed | already_mine | held_by_other | entity_terminal | undetermined. On held_by_other the holder fields name the INCUMBENT. On undetermined, re-issue the identical call — it converges on already_mine.
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | ||
| holder | Yes | ||
| project | No | ||
| entity_id | Yes | ||
| holder_kind | No | agent | |
| holder_repo | No | ||
| allow_terminal | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations supplied, the description carries the full burden and does a good job: it discloses outcome values, the side effect for project, the allow_terminal override, and the convergence behavior on undetermined. It does not discuss persistence or permissions, but for a claim tool the core behaviors are covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a one-line purpose, then organized Args/Returns sections. Every line carries genuinely useful information; nothing is redundant with the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity, seven parameters, and no annotations, the description fully equips an agent to call the tool correctly: it explains entity ID formats, holder semantics, option effects, and all possible outcomes including the recovery path. The output behavior is documented despite the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it does: every one of the seven parameters is explained with types/domains and edge-case behavior (e.g., note renewal, project exception). This adds substantial meaning beyond the bare schema titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Claim') and resource ('a finding or requirement'), and gives the coordination rationale ('so parallel agents do not collide'). This distinguishes it from query-style claim siblings like claims_who_holds and claims_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: use it to claim a finding or requirement and avoid parallel-agent collisions. It does not explicitly name alternatives or when-not-to-use conditions, but the purpose is unambiguous and sufficient for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Everything a given holder currently holds.
| Name | Required | Description | Default |
|---|---|---|---|
| holder | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. 'Everything' and 'currently holds' convey complete, current-state read semantics, which is useful, but there is no mention of edge cases, ordering, permissions, or how any errors or empty results are handled.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is six words long, front-loaded, and contains no filler or redundant restatement of the tool name. Every word contributes to the basic meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is low-complexity and has an output schema, but the description still leaves key context ambiguous. It does not clarify the holder value format or distinguish this tool from closely related claim tools, so an agent may not be able to invoke it correctly without additional inference.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one required holder parameter with 0% description coverage, and the description only echoes the word 'holder' without adding real semantics. It does not explain whether holder is a name, ID, username, or how to handle an unknown holder.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the operation as retrieving everything a given holder currently holds, which is understandable in the claims domain. It lacks an explicit verb and does not differentiate from sibling tools like claims_who_holds or claims_list, but the core resource and scope are evident.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus siblings such as claims_who_holds, claims_list, or codemerge_claims. No exclusions, prerequisites, or alternative conditions are mentioned, so the agent must infer usage from the name and one-line description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List live claims, optionally filtered by kind, holder or holder kind.
Args:
kind: Entity kind filter (e.g. "finding"), or omit for every kind.
holder: Holder name filter, or omit for every holder.
holder_kind: Holder kind filter (e.g. "branch"), or omit for every kind.
limit: Max rows (default 200). 0 means NO rows; a negative value is an error (it used to mean "no limit").
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | ||
| limit | No | ||
| holder | No | ||
| holder_kind | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It explains the 'live' scope, all optional filtering behavior, and supplies useful edge-case semantics for limit: '0 means NO rows; a negative value is an error (it used to mean no limit)'. It doesn't discuss ordering or pagination, but the output schema covers return shape.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: one clear purpose sentence followed by a bulleted Args list. Every line adds useful information, including examples and an important edge-case note, with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with four optional parameters and an output schema, the description is complete: it names the resource, the filters, defaults, and limit edge cases. The output schema covers return values, so nothing essential is missing for an agent to invoke this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates by documenting every parameter: kind, holder, holder_kind, and limit, including defaults and the non-obvious zero/negative-value behavior. This adds substantial meaning beyond the bare type/default data in the input schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'List live claims', and immediately names the three available filters. This clearly distinguishes it from sibling tools like claims_claim, claims_release, claims_who_holds, and claims_held_by, which are about claiming, releasing, or querying holders rather than listing claims.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description establishes clear context: this tool lists claims and can narrow results by kind, holder, or holder kind. It doesn't explicitly state when to prefer this over alternatives or when not to use it, but the purpose is specific enough that an agent can infer appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Release a claim. Authorized on the full (holder, holder_kind, holder_repo) triple — pass exactly what you claimed with.
Returns:
outcome: released | not_yours | not_claimed | undetermined. A projected status is restored only if it still holds the projected value, so finished work is never resurrected.
| Name | Required | Description | Default |
|---|---|---|---|
| holder | Yes | ||
| reason | No | explicit | |
| entity_id | Yes | ||
| holder_kind | No | agent | |
| holder_repo | No | ||
| restore_status | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full disclosure burden. It reveals that releasing is an authorization-gated mutation, enumerates the possible outcomes, and explains the nuanced projected-status restoration rule. This goes well beyond what the schema alone provides.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the core action, and uses a short outcome list. Every sentence adds operational information without filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 6-parameter tool with no annotations, the description covers authorization, outcome semantics, and restoration behavior well. It still leaves entity_id and reason undefined, but the presence of an output schema reduces the need to spell out return details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds real meaning to the holder/holder_kind/holder_repo parameters by requiring exact match with the original claim, and it hints at restore_status behavior with the projected-value condition. But entity_id and reason are not explained, and schema description coverage is 0%, so parameter guidance remains partial.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Release a claim,' a specific verb and resource, and clarifies the claim-scoped authorization on the holder triple. It does not explicitly contrast with sibling tools such as release_item, but the resource and operation are unambiguous enough for selection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear invocation guidance: pass the exact holder/holder_kind/holder_repo values used when claiming. However, it does not state when to choose this tool over related siblings like claims_who_holds or claims_list, so the when-to-use context is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Who currently holds this entity, if anyone.
| Name | Required | Description | Default |
|---|---|---|---|
| entity_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds 'currently' and 'if anyone', indicating the result is a point-in-time holder that may be absent. With no annotations, it carries the behavioral burden, but it stops short of explaining what 'holds' means or what state changes (if any) occur; this is likely a read-only lookup, but that is left implicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One short sentence, no filler, and the core operation is front-loaded. Nothing could be trimmed without removing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one required parameter) and an output schema exists, so a terse description is justifiable. The main gap is the lack of usage/sibling guidance, but enough is present to call it once an entity_id is at hand.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no property descriptions, so the description is the only semantic source; it merely maps 'this entity' to entity_id and says nothing about the ID format, domain meaning, or how absence is represented. The parameter name is self-explanatory, but the description adds almost no parameter-level value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The phrase 'Who currently holds this entity' names a specific lookup action and resource, and the 'if anyone' qualifier makes the nullable outcome clear. However, it does not differentiate this from the sibling claims_held_by, which appears to describe the same query.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No statement of when to call this vs claims_held_by, claims_list, or claims_claim. The only contextual cue is the query-like wording, which leaves an agent to infer it is for checking current holders.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a single run or all runs for a benchmark.
Args:
run_id: Delete a specific run (e.g. "BE-1")
benchmark: Delete all runs for a benchmark name
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | No | ||
| benchmark | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden of behavioral disclosure. It states the destructive nature of the operation, but it omits important behavioral details: whether deletion is permanent, whether benchmark deletion cascades to all related runs, what happens with invalid IDs, and what response is returned. This is a significant gap for a destructive mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the core purpose appears in the first sentence, and the parameter explanations are presented as a minimal bullet-like list. Every sentence earns its place, with no redundant fluff or restatement of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that this is a destructive tool with no annotations and poorly documented parameters, the description is too thin. It does not state whether arguments are required, what happens if both are provided, whether deletion is reversible, or the effect of deleting a benchmark on its associated runs. The agent has enough to form a basic intention but not enough to invoke the tool confidently in edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Since schema description coverage is 0%, the description must compensate, and it does by explaining each parameter's meaning with a concrete example ('BE-1') and distinguishing the two deletion modes. It does not specify constraints like mutual exclusivity or the requirement to provide one of the parameters, but it adds valuable meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Delete') and resource ('a single run or all runs for a benchmark'), clearly distinguishing the tool's two operational modes. This allows an agent to understand what the tool does and how it differs from sibling codebench_* tools without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear parameter-level usage guidance: run_id deletes a specific run, benchmark deletes all runs for a benchmark. However, it does not explicitly state when to prefer this tool over alternatives, does not say that at least one parameter must be provided, and does not explain what happens if both are supplied. The usage context is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Import benchmark results from CSV or JSON.
CSV convention: first column is the row label, remaining columns are metric names with finite numeric values.
JSON convention: array of objects, first key is the row label, rest are metric keys with finite numeric values.
Each (row label, metric) pair may appear only once per import, and NaN/Infinity are refused: a non-finite measurement is not one.
Args:
benchmark: Benchmark name (e.g. "search-perf")
csv_data: CSV string (header + data rows). Provide csv_data OR json_data.
json_data: JSON array string. Provide csv_data OR json_data.
date: Run date (default: today, ISO format YYYY-MM-DD)
tags: Optional tags (e.g. ["nightly", "v2.1"])
meta: Optional metadata (e.g. {"git_sha": "abc123", "ci_url": "..."})
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | ||
| meta | No | ||
| tags | No | ||
| csv_data | No | ||
| benchmark | Yes | ||
| json_data | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses uniqueness constraints per row/metric pair, refusal of NaN/Infinity, default date behavior, and the either/or requirement for csv_data/json_data. It does not state whether imports append to or replace existing data, which is a relevant mutation behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The main behavior and input conventions are front-loaded before the parameter list, and every argument earns its place. It is slightly long, but the format specifications and constraints justify the length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is quite complete for a 6-parameter import tool, especially since an output schema exists and return values need not be explained. The notable gap is behavior when both csv_data and json_data are supplied, and whether duplicate row/metric pairs are rejected against pre-existing data or only within the import.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description compensates fully by explaining every parameter: benchmark with an example, csv_data/json_data with structural conventions, date default, tags example, and meta example. It also clarifies the mutual-exclusion constraint that the schema alone would not imply.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource ('Import benchmark results from CSV or JSON'), immediately distinguishing this import tool from query/list/delete siblings. It also clearly states the supported data formats, making the tool's function unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly conveys it is for importing benchmark data and not for reading or mutating other entities, but it does not explicitly name an alternative tool or state when not to use it. The 'CSV or JSON' format guidance gives the agent a clear context for invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List benchmarks or runs.
Without benchmark: lists all benchmark names with run counts. With benchmark: lists runs for that benchmark.
Args:
benchmark: If provided, list runs for this benchmark
last_n: Limit to last N runs. Requires benchmark — supplying last_n without one is an ERROR, because benchmark names have no runs to limit and the argument would otherwise be silently discarded. 0 means NO runs; omit it for no limit. A negative value is an error.
| Name | Required | Description | Default |
|---|---|---|---|
| last_n | No | ||
| benchmark | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well by disclosing the error condition for last_n without benchmark, the meaning of 0 ('NO runs'), and that negative values are errors. It also clarifies that omitting last_n means no limit. It does not discuss mutability or side effects, but 'list' semantics plus these explicit constraints are sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tightly structured with a one-line summary followed by mode explanations and a clean bullet list. Every sentence earns its place, and the most important behavioral constraint (last_n requires benchmark) is called out explicitly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter list tool with an output schema, the description covers all needed usage context: modes, parameter semantics, error conditions, and default behavior. Nothing material is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates. It explains both parameters in detail: benchmark determines whether runs or benchmark names are listed, and last_n limits to last N runs with the crucial requirements and edge cases spelled out.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource pair, 'List benchmarks or runs,' and immediately breaks out the two modes: without benchmark lists benchmark names with run counts, with benchmark lists runs for that benchmark. This clearly distinguishes it from sibling codebench tools like codebench_import and codebench_query.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to supply benchmark and when not to, plus explicit guidance that last_n requires benchmark and that omitting it is an error. It does not name alternative sibling tools for comparison, but it provides enough context that an agent can correctly decide when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query and pivot benchmark results.
group_by="row": original table shape (row_labels as rows, metrics as columns). Returns one table per run.
group_by="run": trend view (runs as rows, metrics as columns). Returns one table per row_label.
Args:
benchmark: Benchmark name to query
runs: Specific run IDs (default: all matching)
date_from: Start date filter (inclusive, YYYY-MM-DD)
date_to: End date filter (inclusive, YYYY-MM-DD)
metrics: Which metrics to include (default: all)
rows: Which row_labels to include (default: all)
group_by: Pivot axis — "row" or "run"
last_n: Limit to last N runs by date. 0 means NO runs; omit it for no limit. A negative value is an error (it used to mean "no limit").
format: Output — "json" or "csv"
| Name | Required | Description | Default |
|---|---|---|---|
| rows | No | ||
| runs | No | ||
| format | No | json | |
| last_n | No | ||
| date_to | No | ||
| metrics | No | ||
| group_by | No | row | |
| benchmark | Yes | ||
| date_from | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden and covers the important traits: table orientation for each group_by value, 'Returns one table per run/row_label,' inclusive date filters, and the notable last_n behavior ('0 means NO runs; omit it for no limit; negative is an error'). It does not explicitly state that the operation is read-only, but 'query' strongly implies it and output behavior is well specified.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently organized: a one-line purpose, two compact group_by mode explanations, then a bulleted parameter list. Every sentence adds information, including the necessary warning about last_n's historical negative-value semantics, with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a nine-parameter query tool, the description covers all inputs, defaults, pivot behavior, and output format. Since an output schema exists, the return shape does not need to be restated. Nothing needed for an agent to call this tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it does: it documents all nine parameters with defaults ('runs default: all matching', 'format default json'), value domains ('row' or 'run', 'json' or 'csv'), date format, inclusive date semantics, and the last_n corner-case. This goes well beyond what the bare JSON schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Query and pivot benchmark results,' a specific verb+resource statement, and then distinguishes the tool from benchmark-management siblings by explaining the two pivot modes and their return shapes. An agent can tell this apart from codebench_list, codebench_delete, and codebench_import without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use it (querying/pivoting benchmark results) and explains how the two group_by modes change the returned table shape. It does not explicitly name alternatives or state when not to use it, but the purpose is unambiguous and the grouping semantics provide practical usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Close a session for good, so its files stop blocking everyone else.
This is the way OUT of a session that will not be merged under its own lock — including the case an agent hits routinely: the branch was integrated by some other route (a merge harness holding its own lock), so codemerge_merge refuses with reason='main_moved' and the session is stranded in 'active', which codemerge_finish will not accept. Until it is abandoned, its claimed files are reported as conflicts to every later session, with no expiry — so closing it is what keeps codemerge_check worth consulting.
What it does, stated exactly: the session's claim rows are NOT deleted, they stop being reported, because the conflict query selects on session status. The merge lock is released only if this session holds it.
Re-issuing it is safe: a second call on an already-abandoned session changes nothing but the timestamps. A 'done' session is REFUSED — that would erase the record of a merge that succeeded — and an unknown session_id is an error.
Args:
session_id: The merge session ID. Whatever session is NAMED is the one closed; nothing ties it to the caller, so passing a stale or mistyped id closes someone else's work.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it delivers: claim rows are NOT deleted but stop being reported because the conflict query selects on session status; the merge lock is released only if this session holds it; re-issuing is safe; done sessions are refused; unknown ids error. This is exemplary behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but densely packed with necessary caveats and edge cases for a destructive-looking operation. It is structured with a headline, motivation, exact-behavior explanation, and parameter warning. Minor redundancy about files blocking others appears twice, but overall every section earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter, high-stakes state-changing tool with no annotations, the description is thorough: it covers semantics, side effects, idempotency, refusal conditions, error behavior, and the caller-identity risk. An output schema exists, so documenting return values is unnecessary; nothing an agent needs to invoke this safely is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must carry parameter meaning. It does: session_id names the exact session to close, nothing ties it to the caller, and a stale or mistyped id closes someone else's work. This adds crucial semantics far beyond the bare schema string type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: close/abandon a merge session so its claimed files stop blocking others. It clearly distinguishes this tool from siblings by name — codemerge_merge refuses with reason='main_moved', codemerge_finish will not accept the stranded session — so an agent can tell exactly what this tool is for.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains precisely when to use this tool: as the way out when a session cannot be merged under its own lock, including the routine main_moved case where codemerge_finish rejects the session. It also gives exclusions: a 'done' session is refused and an unknown session_id is an error.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check for overlapping file claims with other sessions.
Returns whether the session is clean to proceed, lists any conflicts, and records the current main HEAD for CAS comparison at merge time.
Args:
session_id: The merge session ID
main_changed_files: Files changed on main since base (optional, for overlap check)
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes | ||
| main_changed_files | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite having no annotations, the description discloses an important side effect: it 'records the current main HEAD for CAS comparison at merge time.' It also summarizes the return behavior (clean status and conflict list), which is useful beyond the raw schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: one-sentence purpose, one-sentence behavior/side-effect, and a minimal Args list. No filler or repetition of the schema's structural details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a straightforward check with two parameters and an output schema, and the description covers purpose, side effect, and parameters. It could be slightly richer about what happens when main_changed_files is omitted or what 'CAS comparison' entails, but nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides no parameter descriptions (0% coverage), but the description compensates by explaining session_id as 'the merge session ID' and main_changed_files as 'Files changed on main since base (optional, for overlap check).' Both parameters receive meaningful semantic context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Check for overlapping file claims with other sessions.' It clearly states the core purpose and the possible outcome (clean/proceed vs conflicts), though it does not explicitly differentiate itself from sibling tools like codemerge_claims or claims_check.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied by phrases like 'clean to proceed' and 'at merge time,' suggesting the tool is a pre-flight check before continuing a merge. However, the description never states when not to use it or names alternative tools for related checking tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim a file as being modified by this session.
Args:
session_id: The merge session ID
file_path: File path being modified (relative to repo root)
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | ||
| session_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of disclosing side effects. It states only that a file is claimed as modified, without mentioning whether claims are exclusive, whether a prior claim is overwritten, whether the claim can be released, or what happens on conflict. This is thin for a state-changing tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two compact components: a one-sentence purpose statement and a bulleted argument list. It contains no filler, front-loads the core action, and presents parameter definitions in a scannable structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with an output schema, the basics are present: session_id and file_path are documented and required. But because this is a mutation with no annotations and no usage or conflict semantics, an agent may not know when claims are valid or how to recover from a failed claim. The description is minimally adequate but leaves operational gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does define both required parameters: file_path is clarified as 'relative to repo root' and session_id as 'The merge session ID.' While session_id adds little beyond its name, the file_path scoping is useful. The description covers the parameters sufficiently despite the empty schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb and object: 'Claim a file as being modified by this session.' This identifies the action and resource unambiguously. However, it does not differentiate from closely named siblings like codemerge_claims or claims_claim, so it stops short of full sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as codemerge_status, codemerge_merge, or claims_claim. There is no mention of prerequisites, sequencing within the merge workflow, or exclusions, so the agent must infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all files a session has claimed, in claim order.
Args:
session_id: The merge session ID.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. 'List' signals a read-only operation, and it adds meaningful behavior details: it returns all files, scoped to a session, in claim order. It does not discuss prerequisites like session existence, but for a straightforward query tool this is adequate and does not contradict any annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded: one clear purpose sentence followed by a compact Args section. There is no filler, tautology, or redundant schema restatement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read-only listing tool with an output schema present, the description provides everything needed to invoke it correctly: what is listed, the session scoping, the ordering, and the required argument. Remaining details such as error behavior are minor and reasonably left to the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description's Args block explains the sole parameter: 'session_id: The merge session ID.' This goes beyond the schema's bare title and is sufficient for an agent to provide the correct input, even if it does not add format or source guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List'), names the exact resource ('files a session has claimed'), and adds an ordering constraint ('in claim order'). This clearly distinguishes it from the general claims_* and codemerge_* siblings by scoping it to a merge session's claimed-file list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given about when to prefer this over claims_list, codemerge_status, or codemerge_sessions. The intended use is implied by the wording, but there are no exclusions or alternative recommendations, leaving the agent to infer routing from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Finish a merge session and release the lock.
Call this after codemerge_merge() returned proceed=true; the session must
be in 'merging' state or this refuses in BOTH directions of success.
Args:
session_id: The merge session ID
success: True if the merge succeeded (status→done). False if the git merge/cherry-pick failed (status→active): the lock is released and the session stays alive so it can try again. False does NOT close the session — use codemerge_abandon for that.
| Name | Required | Description | Default |
|---|---|---|---|
| success | No | ||
| session_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility and does well: it discloses that the tool refuses if the session is not in the correct state, releases the lock, changes status to done on success, and keeps the session alive on failure. It also clarifies that success=false does not close the session, leaving no major behavioral surprises.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: purpose first, then the call precondition, then parameter explanations. Every sentence adds essential information that is not available from the schema or annotations, and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with two parameters and an output schema, the description covers invocation context, state requirements, success/failure behavior, and the relationship to sibling tools. Nothing critical is missing for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully document both parameters. It does: session_id is identified as the merge session ID, and success gets detailed semantics including status transitions and session lifecycle effects. This far exceeds the sparse schema information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Finish a merge session and release the lock.' It clearly differentiates from related tools by explicitly referencing codemerge_merge() and codemerge_abandon, so an agent can distinguish when this tool is the right one.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit when-to-use guidance: call after codemerge_merge() returned proceed=true and only when the session is in 'merging' state. It also explains what to do when success=false and points to codemerge_abandon for closing a session, which is strong alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Acquire the merge lock and proceed with merging.
Uses compare-and-swap on main HEAD to prevent races. If main has moved since check, returns proceed=False with reason='main_moved'. If another session holds the lock, returns proceed=False with reason='lock_held'.
Args:
session_id: The merge session ID
expected_main_head: The main HEAD SHA recorded during codemerge_check
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes | ||
| expected_main_head | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral disclosure burden. It does this well by explaining the lock acquisition, compare-and-swap race prevention, and the two concrete declined-proceed outcomes. It stops short of detailing success-side effects or what happens to the session after a successful merge.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well structured: purpose first, then behavioral guarantees, then parameter definitions. Every sentence earns its place and there is no redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists and the operation has only two parameters, this description covers what an agent needs to invoke the tool correctly. It explains the required expected_main_head provenance, the locking semantics, and the reasons a call may decline to merge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It provides useful glosses for both parameters, especially expected_main_head, which it correctly anchors to the value recorded during codemerge_check. session_id is explained only trivially as 'the merge session ID', but the overall semantic guidance is adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action with clear resource scope: acquire the merge lock and proceed with the merge. It further distinguishes this from other codemerge_* siblings by describing CAS on main HEAD and referencing the codemerge_check flow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates this is the merge execution step that follows codemerge_check, evidenced by expected_main_head being the SHA recorded during that check. It explains failure conditions, but does not explicitly name alternatives or state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List merge sessions with claim counts.
Args:
status: Filter by status ('active', 'merging', 'done', 'abandoned'). Omit for all sessions.
| Name | Required | Description | Default |
|---|---|---|---|
| status | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral disclosure burden. It states that the tool lists sessions and includes claim counts, which implies a read-only operation, but it does not explicitly confirm no side effects, pagination behavior, or ordering. It is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief, front-loaded with the primary purpose, and every sentence adds value. The parameter documentation is compact and directly actionable, with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple: one optional parameter, no required fields, and an output schema exists to define return values. The description covers the parameter semantics and core behavior well. It is only missing when-to-use guidance relative to the many codemerge siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It fully does: it lists the four allowed status values ('active', 'merging', 'done', 'abandoned') and clarifies that omitting the parameter returns all sessions. This goes beyond the schema's vague nullable string.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'List merge sessions with claim counts.' This clearly identifies the operation and one key output detail. However, it does not explicitly differentiate itself from related siblings like codemerge_status or codemerge_claims, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains how to filter by status but gives no guidance on when to choose this tool over alternatives. Sibling tools such as codemerge_status and codemerge_claims exist, yet no exclusions or selection criteria are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start a new merge session for a branch.
Args:
session_id: Unique identifier for this merge session
branch: Git branch name being merged
description: Human-readable description of the work
base_commit: Git commit SHA this branch diverged from
repo_root: Repo root path (default: cwd)
allow_restart: If True, reuse this session_id when its previous session is finished — 'abandoned' or 'done'. Restarting DELETES that session's file claims, so re-claim anything you still need. It does NOT restart a live one: starting over an 'active' or 'merging' session is an error whether or not this is set.
| Name | Required | Description | Default |
|---|---|---|---|
| branch | Yes | ||
| repo_root | No | ||
| session_id | Yes | ||
| base_commit | No | ||
| description | No | ||
| allow_restart | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and handles it well. It discloses important behavioral details: restarting deletes prior file claims, restarting a live session is an error, and repo_root defaults to cwd. This goes well beyond the bare schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a one-line purpose, followed by a compact argument list. Each item adds necessary semantic value, and the allow_restart explanation is detailed but directly relevant to avoiding destructive misuse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description thoroughly covers parameters, side effects, and error conditions for a tool with an output schema already present. The only minor gap is that it does not state what happens when session_id already exists and allow_restart is false, leaving one edge case ambiguous.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description fully compensates by explaining every parameter: session_id uniqueness, branch meaning, description purpose, base_commit definition, repo_root default, and the nuanced allow_restart behavior. This is essential meaning the schema alone does not provide.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Start a new merge session for a branch.' It clearly identifies the tool's lifecycle role and distinguishes it from sibling tools like codemerge_status, codemerge_merge, and codemerge_finish by focusing on session creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by the phrase 'Start a new merge session' and gives detailed restart semantics, but it never explicitly states when to prefer this tool over siblings or when not to use it. The context is clear, but exclusions and alternatives are left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Dashboard summary: session counts by status, total active claims, and who (if anyone) holds the merge lock.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the read-only/side-effect story. It does disclose what the agent will receive—aggregated session counts, active claims, and lock holder—and 'summary' implies a non-mutating read, but it never explicitly states that calling it modifies nothing, nor does it mention staleness or lock semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One compact sentence, front-loaded with the 'Dashboard summary' label, followed by a scoped list of contents. No filler or repeated schema information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-argument, read-only summary with an output schema, the definition is largely sufficient: it names the data areas and has no inputs to document. It is slightly incomplete only because it does not position itself against the granular siblings, but the output schema and low complexity make this minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool accepts zero parameters, so there are no parameter semantics to document. The baseline 4 applies because nothing in the description is needed, and nothing is missing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Dashboard summary', immediately signaling a status/aggregation tool rather than an action. It names concrete output segments—session counts by status, total active claims, and merge lock holder—so an agent can distinguish it from mutating siblings like codemerge_merge or codemerge_abandon.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit 'use when...' or 'prefer X over Y' guidance is provided. The phrase 'Dashboard summary' implies high-level review, and sibling tools like codemerge_sessions and claims_who_holds offer more granular alternatives, but the description does not state when to choose this over those, so the agent must infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add items to a sweep. Atomic upsert: existing items have their
recurrence_count bumped instead of being silently skipped, their
last_seen updated, and their archive flag cleared (R5: re-detected
archived items un-archive automatically).
Args:
sweep_ref: Sweep ID (SW-N) or name
items: Item identifiers to add
tags: Optional tags applied to this batch (overwrite on bump)
Returns: {sweep_id, added, recurrence_bumped, duplicates_skipped (alias)}
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | ||
| items | Yes | ||
| sweep_ref | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses the mutation semantics: recurrence_count bump, last_seen update, archive flag clearing, tag overwrite on bump, and returned fields. This goes well beyond a basic 'add' statement and makes side effects predictable. Minor ambiguity around the duplicates_skipped alias does not undermine the disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a one-line purpose, then a concise behavior note, parameter list, and return shape. No sentence is wasted and no structured field is repeated needlessly. The layout is easy for an agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose, non-obvious side effects, all parameters, and return fields, which is sufficient for a 3-parameter tool with no annotations. The R5 archive-flag rule gives critical edge-case context. Nothing needed for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters are given semantic descriptions that the bare schema lacks: sweep_ref accepts 'SW-N' or name, items are identifiers to add, and tags are per-batch with overwrite behavior. This fully compensates for 0% schema description coverage. Item identifier format is not specified but the type is clear from the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Add items to a sweep.' It then clarifies the atomic upsert behavior, making the tool's function unmistakable and distinct from sweep creation/listing siblings. This is not a tautology and leaves no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states the operation ('Add items to a sweep') and the atomic upsert semantics, giving an agent clear context for when to call it. It does not name alternative siblings or exclusions, but the namespaced function name and explicit action make the intended use unambiguous. This is clearer than mere implication.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Archive a sweep. Archived sweeps are excluded from codesweep_list by default.
For entry-level archive, use codesweep_archive_items.
Args:
sweep_ref: Sweep ID (SW-N) or name
| Name | Required | Description | Default |
|---|---|---|---|
| sweep_ref | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations at all, the description carries the full burden. It usefully discloses that archived sweeps are excluded from codesweep_list by default, which is a real behavioral consequence. However, it does not mention reversibility, idempotency, permissions, or whether archiving affects items or related data, so some mutation context is still missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the primary action and its key side effect come first, followed by the sibling routing and then the parameter clarification. Every sentence adds useful information with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter operation with an output schema present, the description covers the essential behavioral consequence and parameter format. It does not explain edge cases like already-archived sweeps or interaction with codesweep_archive_items more deeply, but nothing critical is missing for selecting and invoking the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only a bare required string with no property description, so the description must compensate. It does so effectively by defining sweep_ref as 'Sweep ID (SW-N) or name', which gives the agent the exact accepted format and reference style. A small gap remains in that it does not explain ambiguity resolution if both ID and name are possible.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a clear verb-resource pair ('Archive a sweep') and immediately adds the consequential behavior: archived sweeps are excluded from codesweep_list by default. It also names the sibling codesweep_archive_items, distinguishing the whole-sweep archive action from the item-level archive action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives concrete routing guidance: for entry-level archiving, use codesweep_archive_items instead. This tells the agent which sibling alternative applies in a distinct case, though it does not spell out broader when-to-use or when-not-to-use scenarios beyond that distinction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Selectively archive entries within a sweep (soft-delete).
Archived entries are excluded from codesweep_next, codesweep_status
totals, and default codesweep_list_items. They remain matchable by
codesweep_add for recurrence detection — re-adding un-archives them
with recurrence_count carried forward (R5 invariant).
At least one filter is required.
Args:
sweep_ref: Sweep ID (SW-N) or name
items: Specific item identifiers to archive. An EXPLICITLY EMPTY list selects nothing; passing it together with where_status or older_than is an ERROR, because those filters would then be silently ignored. Omit items entirely to archive by filter.
where_status: Archive entries currently in this state
older_than: Duration spec — '30d', '2w', '6m', '1y'. Compares against the entry's last activity timestamp.
reason: Free-form reason recorded on each archived entry
| Name | Required | Description | Default |
|---|---|---|---|
| items | No | ||
| reason | No | ||
| sweep_ref | Yes | ||
| older_than | No | ||
| where_status | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the behavioral disclosure burden. It reveals the soft-delete semantics, exclusion from codesweep_next, codesweep_status, and codesweep_list_items, the un-archive behavior via codesweep_add with recurrence_count carried forward, and the error condition for combining an empty items list with filters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, then efficiently covers behavioral side effects, a key invariant, and parameter details. Every sentence adds necessary information, including the subtle empty-list error case that would otherwise be easy to miss.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a five-parameter mutation tool with no annotations, the description covers required filters, parameter semantics, error conditions, behavioral consequences, and reversibility. An output schema exists, so omitting return-value details is acceptable; nothing essential for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description compensates completely by documenting all five parameters with meaningful semantics: sweep_ref is SW-N or name, older_than has duration spec formats and compares against last activity, and items has nuanced empty-list and omission semantics that are not visible in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Selectively archive entries within a sweep (soft-delete).' This clearly distinguishes it from sibling codesweep_archive, which implies whole-sweep archival, and names the exact scope of operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear operational context: it states that at least one filter is required, explains that omitting items archives by filter, and warns that an explicit empty items list combined with other filters is an error. However, it does not explicitly name alternatives or state when not to use this tool versus codesweep_archive or codesweep_mark.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new sweep for batch iteration over items.
Args:
name: Optional human-readable name (must be unique)
description: What this sweep is for
default_batch_size: Default items per batch (default: 10)
lifecycle: Ordered list of allowed states (default ["pending","done"]). For retro-style workflows: ["DETECTED","CONFIRMED","ESCALATED", "POSTPONED","RESOLVED","DROPPED"].
terminal_states: States that count as "processed" (default ["done"]).
transitions: Optional dict[state, list[allowed_next_state]] for DAG-constrained lifecycles. None = unconstrained transitions.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| lifecycle | No | ||
| description | No | ||
| transitions | No | ||
| terminal_states | No | ||
| default_batch_size | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosing behavior. It does explain creation semantics and important defaults/constraints like lifecycle defaults, terminal_states meaning 'processed', and transitions as an optional DAG constraint. However, it does not disclose side effects, error behavior on duplicate names, idempotency, or persistence details beyond the act of creating.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a one-sentence purpose, followed by a compact, well-organized Args list. Every line adds useful information about a parameter or default, with no filler or redundancy. The retro lifecycle example is valuable rather than decorative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a creation tool with six optional parameters and non-trivial lifecycle semantics, the description covers all parameters and gives enough context to call it correctly. An output schema exists, so return-value documentation is not required. The main gap is the lack of guidance on what happens after creation or how creation relates to codesweep_add, but this is not essential for invoking this specific tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it does thoroughly. Every parameter is explained with its meaning, default value, and relevant examples — for instance, lifecycle includes a concrete retro-style workflow and transitions explicitly explains that None means unconstrained. This adds substantial semantic value beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Create a new sweep for batch iteration over items.' This clearly identifies the tool's action and domain, and distinguishes it from sibling tools like codesweep_add, codesweep_next, and codesweep_mark that operate on existing sweeps rather than creating new ones.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context about when this is relevant (setting up a sweep for batch iteration, with retro-style lifecycles as a notable use case). However, it never explicitly says when NOT to use it or points to alternatives such as codesweep_add for adding items to an existing sweep. Usage is implied rather than directly guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all sweeps with summary counts.
Args:
include_archived: Include archived sweeps (default: false)
| Name | Required | Description | Default |
|---|---|---|---|
| include_archived | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations available, the description carries the behavioral disclosure burden. It communicates that the tool returns summary counts and that archived sweeps are excluded by default via 'include_archived ... default: false.' However, it does not disclose ordering, pagination, permission requirements, or potential side effects, though the verb 'List' strongly implies a non-mutating operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately short and front-loaded with the core purpose: 'List all sweeps with summary counts.' The argument documentation is compact and useful. It is concise without being under-specified for a tool this simple.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one optional parameter and an output schema available, the description covers the essential behavior: what is listed, what counts are included, and how archived sweeps are handled. It does not explain pagination or ordering, but those are less critical given the tool's simplicity and existing output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It restates the single parameter 'include_archived' with the clarification 'Include archived sweeps' and the default value. This adds some plain-language meaning, though the schema already includes the title 'Include Archived' and default false, so the added value is marginal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action and resource: 'List all sweeps with summary counts.' This distinguishes it from sibling tools like codesweep_list_items, which presumably lists items, and codesweep_status, which likely shows a single sweep's state. It lacks an explicit sibling comparison but is specific enough to orient an agent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as codesweep_list_items or codesweep_status. The phrase 'List all sweeps' implies a broad listing use case, but no explicit conditions, exclusions, or alternative tool recommendations are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List items in a sweep with optional filters.
Args:
sweep_ref: Sweep ID (SW-N) or name
state: Filter to a specific state
tag: Filter to items having this tag
include_archived: Include archived entries alongside live ones
archived_only: Show only archived entries. Mutually exclusive with include_archived: passing both as true is an error (it used to mean archived-only, returning FEWER entries than include_archived alone).
limit: Max number of entries to return. 0 means NO entries; omit it for no limit. A negative value is an error (it used to mean "no limit").
| Name | Required | Description | Default |
|---|---|---|---|
| tag | No | ||
| limit | No | ||
| state | No | ||
| sweep_ref | Yes | ||
| archived_only | No | ||
| include_archived | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses important behavioral edge cases: archived_only and include_archived are mutually exclusive, 0 limit means no entries, and negative limits are errors. It also explains legacy behavior changes. Since no annotations are present, this detail carries the full burden and does so well, though it never explicitly states that the operation is read-only.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with a clear summary sentence, followed by a tight bullet list. The historical notes are verbose but earn their place by preventing serious misinterpretation of limit and archived_only behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all six parameters and their tricky semantics, and the output schema covers return shape. It lacks details like valid state values or ordering behavior, but those are less critical for a filtered listing tool with such thorough parameter documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only provides types and defaults, while the description adds rich semantics: sweep_ref accepts SW-N ID or name, limit's 0/negative behavior, archived-only semantics, and the mutual exclusivity constraint. This far exceeds the schema and compensates fully for the 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List items in a sweep with optional filters,' giving a specific verb and resource. It does not explicitly differentiate from the sibling codesweep_list, but the 'items in a sweep' wording sufficiently narrows the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as codesweep_list, codesweep_status, or codebench_list. The description explains what the tool does but not when it should be preferred or avoided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark items by state transition.
Args:
sweep_ref: Sweep ID (SW-N) or name
items: Item identifiers to mark
processed: Legacy mode — True maps to first terminal state, False to first non-terminal state. Omit it entirely (the default) to get the same effect as True. MUTUALLY EXCLUSIVE with state: sending both is an error, including when the two happen to agree, because state names one state and processed names a class of them.
state: Explicit target state. Validated against the sweep's lifecycle and transitions DAG (if declared). Mutually exclusive with processed — send one or the other, never both.
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | ||
| state | No | ||
| processed | No | ||
| sweep_ref | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It does disclose useful behaviors: `processed` maps to terminal/non-terminal states, `state` is validated against the lifecycle/transitions DAG, and sending both parameters is an error. However, it does not cover reversibility, permissions, idempotency, or failure behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a one-line purpose and then uses a clean Args structure. It is focused and informative, though the mutual exclusivity warning is repeated in both `processed` and `state`, which is mildly redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a four-parameter mutation tool with an output schema, the description covers the important call decisions: target sweep, items, state selection, and validation against lifecycle/transitions. It leaves some domain specifics implicit, such as exact state vocabulary and behavior when no lifecycle DAG is declared, but is generally complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully compensate. It does so exceptionally: it explains `sweep_ref` formats, `items` purpose, the legacy `processed` default and semantic mapping, and the mutual exclusivity between `processed` and `state`, including the subtle case where agreeing values are still an error.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Mark items by state transition,' which states a specific action and resource, and the args clarify this applies to sweeps via sweep_ref and lifecycle/transitions. It is clear but does not differentiate from sibling mark tools like mark_integrated or mark_branch_only.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives detailed guidance on choosing between `processed` and `state`, but this is parameter-level guidance, not tool-level alternatives. It never says when to use this tool versus sibling marking tools, so usage context is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get next batch of unprocessed (non-terminal, non-archived) items in insertion order.
Args:
sweep_ref: Sweep ID (SW-N) or name
limit: Batch size (overrides sweep default). 0 means NO items; omit it to use the sweep's own default batch size. A negative value is an error (it used to mean "no limit").
tags: Filter to items matching any of these tags
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | ||
| limit | No | ||
| sweep_ref | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral burden. It discloses ordering ('insertion order'), the definition of 'unprocessed', and precise limit semantics including edge cases: '0 means NO items', 'omit it to use the sweep's own default batch size', and 'A negative value is an error (it used to mean no limit)'. This is strong behavioral context, though it doesn't mention side effects or permissions (likely none for a get operation).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficient: a single summary sentence followed by a clean Args list. Every sentence adds value, especially the detailed limit explanation which prevents misuse. No redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool of this complexity, the description covers the essential behavioral and parameter context. Return values are presumably handled by the output schema, so lack of return documentation is acceptable. Minor omissions like explicit idempotency or 'does this consume the items' are not critical given the 'Get' framing, but could have been slightly stronger.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully compensate. It does: each parameter is explained with meaningful semantics beyond the schema. sweep_ref gets format hints, limit gets detailed behavior including override and error cases, and tags gets filtering semantics. This is exemplary parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get') and a clearly defined resource: 'next batch of unprocessed (non-terminal, non-archived) items in insertion order.' This goes beyond the name and conveys the exact scope. It doesn't explicitly call out sibling differentiation, but the behavior is distinct enough that an agent understands what it does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: when you need the next batch of unprocessed items in a sweep. However, it gives no explicit guidance about alternatives such as codesweep_list_items or pull_next, nor any 'when not to use' statement. This is implied rather than stated, so it earns a 3.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sweep overview — total/processed/remaining/archived counts, per-tag and
per-state breakdowns. Archived entries are excluded from total/processed/
remaining and reported separately as archived.
Args:
sweep_ref: Sweep ID (SW-N) or name
| Name | Required | Description | Default |
|---|---|---|---|
| sweep_ref | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses a non-obvious behavior: archived entries are excluded from the total/processed/remaining counts and are surfaced separately as `archived`. It does not explicitly state that the call is read-only, but 'overview' and the absence of any side-effect language make that reasonably clear, especially given the output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core behavior is captured in a single front-loaded sentence, followed by one argument line with no filler. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with an output schema, the description covers the input format, the output areas (counts and breakdowns), and the special archived handling. The output schema relieves the description of explaining individual return fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only says sweep_ref is a required string, while the description adds the expected format (SW-N) and that a name is also accepted. This fully compensates for the 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource (a sweep) and the result (total/processed/remaining/archived counts plus per-tag and per-state breakdowns), which sets it apart from list- or mutation-oriented siblings like codesweep_list and codesweep_add. It loses a point because 'Sweep overview' is a noun phrase rather than an explicit action verb such as 'Returns' or 'Gets'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The use case is implied by the word 'status' and the overview counts, but the description never states when to choose this tool over similar status tools (e.g., codemerge_status, milestone_status) or alternatives like codesweep_list. There is no when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a single finding by ID with full body (description, severity, status, tags, meta, timestamps, commit refs).
The result carries an anchor summary saying where this card's code is
NOW: state tells a card with no anchor apart from one whose anchor was
retracted by hand and from one where capture looked and had nothing to
grab, and loc_status/moved_file/path report the resolution against
HEAD when it ran.
Raises a not-found error if the ID does not exist. For lenient batch
lookup that silently drops missing IDs, use query(ids=[...]).
Args:
finding_id: The finding ID (e.g. CB-1383)
resolve_anchors: Resolve the anchor against the repository (default ON — the cost is bounded by one card). Pass False for a read that must not spawn a process: no git available, no repository, or a caller that only wants to know whether an anchor exists at all.
| Name | Required | Description | Default |
|---|---|---|---|
| finding_id | Yes | ||
| resolve_anchors | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations supplied, the description carries the full behavioral burden and does so thoroughly. It discloses the not-found error behavior, the nuanced `anchor` summary semantics (no anchor vs. retracted vs. nothing to grab), the bounded cost of anchor resolution, and that setting `resolve_anchors=False` avoids spawning a process. This goes well beyond a basic 'get' description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The most important content is front-loaded with the single-finding fetch, and the Args section is clearly structured. The anchor-semantics paragraph is dense and slightly convoluted ('apart from one whose anchor was retracted by hand and from one where capture looked and had nothing to grab'), but every section earns its place in a tool with this behavioral nuance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a 2-parameter tool with an output schema, the description covers everything an agent needs to invoke it correctly: what it returns, how anchor resolution behaves, when it errors, how to avoid errors through the batch alternative, and when to disable process-spawning resolution. There are no meaningful gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate—and it does. `finding_id` gets a concrete example (CB-1383), and `resolve_anchors` is explained with its default behavior, performance bound, and the exact conditions under which a caller should pass False. Both parameters gain meaning far beyond the bare schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a precise verb and resource: 'Fetch a single finding by ID with full body' and enumerates the returned fields (description, severity, status, tags, meta, timestamps, commit refs). It further distinguishes itself from the lenient batch sibling by explicitly directing users to `query(ids=[...])`, so an agent can select it correctly 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.
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 `get` for a single strict lookup that errors on missing IDs, and use `query(ids=[...])` for lenient batch lookup. It also provides concrete conditions for passing `resolve_anchors=False` (no git, no repository, or only anchor-existence needs), making the decision boundary clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Connected components of the hand-written CB-id reference graph.
READ-ONLY, and an ANNOTATION of what people already wrote — no link here is inferred. Every edge carries the field it came from and the quoted context of its first mention. A node whose degree exceeds hub_degree is a landmark many work units point AT, not a member of one: it does not transmit connectivity and is reported as an ANCHOR with its citers, so the components either side of it stay separate. References to ids outside the population are COUNTED as dangling, never dropped.
A pair you have declared DIFFERENT — relations_relate(a, "distinct_from", b) — stops being joined BY THAT REFERENCE, in either order; retracting the declaration brings the grouping back. The citation itself still appears, with its quoted context, in suppressed_edges: your declaration corrects the conclusion this tool draws from the reference, not the fact that somebody wrote it. Read still_grouped on each entry before trusting the separation — dropping one reference does not cut a graph, so if a third card cites both they are in one component regardless, and that flag (counted by still_grouped_total) is how the report tells you your declaration lost rather than leaving you to notice. This is the ONLY place distinct_from suppresses: grouping_filing's declared lineage (split_from / split_children) is untouched, because overriding one declaration with another is a different question from overriding a guess.
Args:
status: Narrow/widen the population (default: live statuses; "all")
category: Restrict to one category
hub_degree: Degree above which a node becomes an anchor (default 3, chosen on the outcome — see DEFAULT_HUB_DEGREE); None disables hub splitting and returns the raw components
component_limit: Max components returned (totals stay visible)
member_limit: Max members per component (edges follow the page)
anchor_limit: Max anchors returned (default 25)
orphan_limit: Max orphan ids returned (default 50)
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | ||
| category | No | ||
| hub_degree | No | ||
| anchor_limit | No | ||
| member_limit | No | ||
| orphan_limit | No | ||
| component_limit | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the full disclosure burden and exceeds it: READ-ONLY guarantee, non-inference of links, edge payloads (source field + quoted first-mention context), hub-to-anchor transformation with loss of connectivity transmission, dangling references counted rather than dropped, and the precise semantics of suppressed_edges and still_grouped. These are substantive behaviors no structured field could convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long, but the tool's semantics are genuinely complex (graph components, anchors, dangling refs, cross-tool declaration interaction) and every paragraph adds necessary information rather than padding. Core purpose and read-only status are front-loaded, followed by edge cases, the sibling boundary, and a cleanly ordered parameter list; it sits at the justified upper bound of length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-parameter, zero-annotation tool with subtle graph behavior, the description covers the algorithm, hub/anchor handling, dangling references, the distinct_from interaction, the still_grouped caveat, and the grouping_filing boundary. An output schema exists to document the return structure, while the description already names the key output concepts (components, anchors, suppressed_edges, still_grouped_total) so the agent can interpret results correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully compensate, and its Args section does: all 7 parameters receive meaning beyond bare types (e.g., hub_degree: 'None disables hub splitting and returns the raw components'; component_limit: 'totals stay visible'; member_limit: 'edges follow the page'). The parameter documentation adds genuine operational value at the exact point where the schema is silent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening line, 'Connected components of the hand-written CB-id reference graph,' names a precise resource and operation, and immediately adds the READ-ONLY qualifier that it is an annotation of what people wrote, not inferred links. It explicitly carves out sibling grouping_filing ('declared lineage ... is untouched'), so an agent can tell them apart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
States the exact scope boundary: 'This is the ONLY place distinct_from suppresses,' and distinguishes from grouping_filing's split_from/split_children lineage, which is deliberately not affected. It also gives a concrete directive — 'Read still_grouped on each entry before trusting the separation' — and explains the failure mode where a third citation keeps two nodes joined despite a distinct_from declaration.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Split lineages and shared filing events (sprint / plan).
READ-ONLY. LINEAGE IS TRAVERSED, NOT GROUPED: A → B → C is one lineage
with depths, and its links resolve against EVERY card in the tracker,
not just the population, so a fixed middle card does not sever the
chain. A lineage surfaces when at least one member is in the population;
a lineage value naming no card is reported unresolved, not dropped.
Filing events are grouped by exact value within the population.
Args:
status: Narrow/widen the population (default: live statuses; "all")
category: Restrict to one category
lineage_limit: Max lineages returned (totals stay visible)
event_limit: Max filing events returned (totals stay visible)
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | ||
| category | No | ||
| event_limit | No | ||
| lineage_limit | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It explicitly states READ-ONLY, explains that lineage is traversed not grouped, details the resolved/unresolved behavior, and notes that totals stay visible despite limits. This is rich, specific, and directly actionable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but well structured: READ-ONLY and the core semantic distinction are front-loaded, followed by lineage details and a clean Args list. Every sentence earns its place and contributes to correct invocation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of lineage traversal and grouping behavior, the description covers population filtering, resolution rules, unresolved values, and limit behavior. An output schema is present, so return-value details are not required; nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the Args section compensates for all four parameters with meaningful behavior: status has a default and 'all' option, category restricts, and limits preserve totals. It adds real semantics beyond bare schema types, though the status description is slightly terse.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb/resource: 'Split lineages and shared filing events (sprint / plan)' and clarifies the scope with a READ-ONLY summary. It is distinguishable from sibling grouping tools like grouping_citations and grouping_tags by domain, though 'Split' is slightly unconventional and no sibling comparison is made.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: the agent should use this when it needs lineage or filing-event groupings. However, there is no explicit statement about when to choose this tool over grouping_citations or grouping_tags, and no exclusion conditions or alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tag pivots: counts, co-occurrence, and near-duplicate taxonomy strings.
READ-ONLY. Co-occurrence carries Jaccard beside the raw count, because
on a corpus with one 390-card tag the raw count ranks that tag's pairs
first no matter how weak the association is. variants spans tags AND
categories in one namespace: the taxonomy drift is not confined to one
column (process_improvement / process-improvement).
Args:
status: Narrow/widen the population (default: live statuses; "all")
category: Restrict to one category
min_pair_count: Drop tag pairs co-occurring fewer times (default 2)
tag_limit: Max tags returned (totals stay visible)
pair_limit: Max pairs returned (default 50; None for all)
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | ||
| category | No | ||
| tag_limit | No | ||
| pair_limit | No | ||
| min_pair_count | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so unusually well. It explicitly says READ-ONLY, explains why Jaccard is included alongside raw counts, reveals that variants span tags and categories in one namespace, and notes that tag_limit keeps totals visible.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a front-loaded summary, a short rationale block, and an Args list. The Jaccard explanation is slightly verbose but earns its place by clarifying behavior that affects interpretation of results.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The output schema is present, so return-value details do not need to be restated. The description covers defaults, key behavioral caveats, and the read-only nature, but it does not explicitly distinguish itself from sibling grouping tools, which is a small but relevant gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it covers all five parameters with concise meaning and defaults. It could add more detail about value formats or accepted status values, but it still provides enough semantic grounding for an agent to invoke the tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource (tags) and the kinds of output produced: counts, co-occurrence, and near-duplicate taxonomy strings. The term 'Tag pivots' is somewhat jargon-heavy, and it does not explicitly contrast with sibling tools like grouping_citations or grouping_filing, but an agent can infer that this tool is for tag-focused analysis.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies its use case: analyzing tag co-occurrence and taxonomic variants, with a READ-ONLY warning and rationale for Jaccard. However, it never explicitly states when to choose this tool over alternatives, nor does it mention when not to use it, leaving usage routing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Flag an item as living on a feature branch (not yet integrated). Called by worktree-setup.sh when a branch is created.
Args:
item_ref: The item id (e.g. CB-5).
branch_name: Git branch holding the work.
| Name | Required | Description | Default |
|---|---|---|---|
| item_ref | Yes | ||
| branch_name | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosure. It explains the semantic effect (marking an item as unintegrated branch-only work), but does not mention idempotency, overwrite behavior, preconditions, or whether the flag can be reversed by mark_integrated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: purpose in the first sentence, trigger in the second, then a short args list. Every sentence contributes information without repetition or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-required-parameter flagging tool with an output schema, the description covers purpose, trigger, and both arguments. It lacks only minor context about edge cases like re-marking an already flagged item or the inverse operation, which are useful but not essential.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain parameters, and it does: item_ref is an item id with an example (CB-5) and branch_name is the Git branch holding the work. It adds real meaning beyond the bare schema property names, though branch_name formatting/constraints are not detailed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence uses a specific verb ('Flag') and resource ('an item') and adds the state 'living on a feature branch (not yet integrated)', which clearly distinguishes it from the sibling mark_integrated. The operation is unambiguous even before reading the args.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It names a concrete trigger: 'Called by worktree-setup.sh when a branch is created.' This gives clear context for when the tool is relevant, though it does not explicitly list when not to use it or name mark_integrated as the inverse alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark an item as merged to main. Sets done_commit, status='done', clears branch_only. Called by worktree-finish.sh.
Args:
item_ref: The item id (e.g. CB-5).
commit: Commit SHA where the work landed on main.
| Name | Required | Description | Default |
|---|---|---|---|
| commit | Yes | ||
| item_ref | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the burden of behavioral disclosure. It explicitly lists the side effects: setting done_commit, status='done', and clearing branch_only. It could additionally mention idempotency or reversibility, but the core state transition is clearly disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is succinct and front-loaded: the operation and its effects appear in the first sentence, followed by a brief caller note and parameter definitions. Every sentence adds value, with no repetition of the tool name or schema information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with only two parameters, and the description covers its purpose, side effects, and parameter meanings. The presence of an output schema means return values do not need explanation. Minor gaps are the lack of explicit guidance on when not to use it or what happens if invoked on an already-integrated item, but overall it is adequately complete for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no property descriptions, so the description fully compensates. It defines item_ref as 'The item id (e.g. CB-5)' and commit as 'Commit SHA where the work landed on main', giving both concrete meaning and an example. Both required parameters are semantically covered.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Mark an item as merged to main' and enumerates the exact state changes (sets done_commit, status='done', clears branch_only). This is distinct from the sibling 'mark_branch_only' and clearly communicates the tool's function without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it says the tool is 'Called by worktree-finish.sh' and defines the commit as 'where the work landed on main', implying it should be used after work has been merged. It does not explicitly name alternatives or exclusions, but the context is sufficient for a basic selection decision.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Attach an item (bug / requirement / external) to a milestone.
Args:
milestone_id: Target milestone slug.
item_kind: 'bug' (CB-N), 'requirement' (FR-N), or 'external'.
item_ref: The id of the underlying entity (must exist for bug/req).
size: 'large' (worktree+sprint), 'small' (1-2h), 'triage' (minutes).
priority: Lower = higher priority. Default 100.
acceptance: Markdown acceptance criteria. Required for size='large'.
linked_frs: Optional list of FR ids to link (used by pull_next eligibility).
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | small | |
| item_ref | Yes | ||
| priority | No | ||
| item_kind | Yes | ||
| acceptance | No | ||
| linked_frs | No | ||
| milestone_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral burden. It discloses key behavioral constraints: item_ref must exist for bug/req, acceptance is required for size='large', priority semantics, and linked_frs affects pull_next eligibility. It does not mention duplicate handling, reversibility, or permissions, but the core side effects and prerequisites of attaching an item are surfaced.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a one-sentence purpose, followed by a tight bullet list of parameters. Every bullet adds necessary semantic value, and there is no filler or repeated schema boilerplate. The structure makes the tool easy for an agent to scan and apply.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, no annotations, and an output schema that removes the need to document return values, the description covers all invocation-relevant information: parameter semantics, required-condition behavior, and cross-tool eligibility effects. Nothing essential for correctly calling the tool is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description fully compensates by explaining every parameter with meaningful detail beyond the schema: milestone_id is a slug, item_kind values map to CB-N/FR-N, size values carry effort meaning, priority semantics are clarified, and linked_frs has a cross-tool purpose. This is a model example of description-level parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence is a specific verb+resource statement: 'Attach an item (bug / requirement / external) to a milestone.' This clearly distinguishes the tool from sibling milestone tools like milestone_create, milestone_update, and milestone_move_item, none of which describe attaching an existing item. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when the tool is appropriate: any time an item should be attached to a milestone. However, it does not explicitly name alternatives or state when NOT to use this tool versus milestone_move_item or milestone_update. The lack of explicit exclusions keeps it just below a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Audit log query with filters. Returns most-recent rows first.
Args:
milestone_id: Filter by milestone slug.
item_ref: Filter by item id.
actor: Filter by actor.
since: ISO datetime — only rows at or after this time.
limit: Max rows (default 200). 0 means NO rows; a negative value is an error (it used to mean "no limit").
| Name | Required | Description | Default |
|---|---|---|---|
| actor | No | ||
| limit | No | ||
| since | No | ||
| item_ref | No | ||
| milestone_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden and does a solid job: it discloses sort order, datetime filtering semantics, and the unusual limit edge cases where 0 returns no rows and negative values are errors. This adds meaningful runtime behavior beyond the schema, though it does not mention whether filters combine or any access requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and immediately front-loads the core purpose before moving into a clean bulleted parameter list. Every line adds information, and the historical note about limit is placed exactly where relevant without extra verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 5-parameter optional filter query with an output schema present, the description covers all parameters, ordering, and edge cases. The main gap is that it does not state whether multiple filters are combined with AND semantics, which could matter to an agent planning a query with several filters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it fully does. Every parameter is explained with meaningful semantics: milestone_id is a slug, item_ref is an item id, since is an ISO datetime with at-or-after semantics, and limit gets defaults plus edge-case behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb plus resource: 'Audit log query with filters,' and adds concrete behavior ('Returns most-recent rows first'). It clearly identifies this as the audit-log querying tool, which distinguishes it from sibling query tools like blockers_query, reqs_query, and relations_query.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied by the tool name and introductory phrase; an agent can infer it should be used when filtering audit log entries. However, the description gives no explicit guidance about when to prefer this over other query tools, nor any exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Close a release milestone. Refuses if items are unfinished, on a branch, or have unresolved blockers. Streams cannot be closed.
Args:
id: Milestone slug (must be kind='release').
force: Override the close-gate (still won't close streams). Audit-logged.
reason: Audit reason for the close.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| force | No | ||
| reason | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden, and it delivers: it discloses refusal conditions, the force override ('still won't close streams'), and that the operation is audit-logged. This goes well beyond the schema and gives an agent realistic expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loads the core operation, and uses a clear Args list. There is no filler or repetition beyond the necessary emphasis that streams cannot be closed even with force.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The context is adequate for a three-parameter tool: the gate conditions, force behavior, and audit semantics are all covered, and an output schema exists to describe return values. It could be slightly richer on permissions/error responses, but nothing critical is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the Args section compensates fully: id is defined as a milestone slug with kind='release', force is defined as overriding the close-gate while never closing streams, and reason is defined as the audit reason. Every parameter gains meaning beyond its type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource ('Close a release milestone') and scopes the tool to release milestones over other milestone operations. It does not explicitly name sibling alternatives like milestone_defer or milestone_update, so the differentiation is implicit rather than direct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear context for when the close will be accepted vs refused ('Refuses if items are unfinished, on a branch, or have unresolved blockers') and warns that streams cannot be closed. It stops short of recommending an alternative tool for deferred/stalled milestones, so the when-not guidance is present but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new milestone.
Args:
id: Slug identifier, e.g. 'release/1.2' or 'stream/security'.
kind: 'release' or 'stream'. Streams never close.
description: Short charter for the milestone.
target_date: ISO date (e.g. '2026-06-30'). Optional, releases only.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| kind | Yes | ||
| description | Yes | ||
| target_date | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the disclosure burden. It does add meaningful behavioral context: streams never close, and target_date is optional and releases-only. It stops short of describing duplicate-ID behavior or other failure modes, but the side effect of creation is clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a one-sentence purpose followed by a compact, front-loaded Args list. Every line earns its place with examples, allowed values, or constraints. There is no padding or repetition of the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a four-parameter creation tool with an output schema, the description defines every argument with examples and constraints, so an agent can construct a valid call. It lacks routing guidance and some edge-case behavior, but the core invocation context is well covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description fully compensates. It explains id with concrete slug examples, constrains kind to 'release' or 'stream', describes description as a charter, and provides ISO format plus release-only semantics for target_date. This is far richer than the bare schema fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Create a new milestone.' The word 'new' clearly distinguishes this from mutation-focused siblings such as milestone_update, milestone_close, and milestone_defer. No ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance about when to use milestone_create versus alternatives like milestone_update, milestone_add_item, or milestone_close. The only rule provided, 'Streams never close,' is a domain constraint, not a routing instruction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move an item to stream/maintenance (or another milestone) and mark it deferred.
Args:
item_ref: The item to defer.
to_milestone: Destination (default 'stream/maintenance').
reason: Optional audit reason.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | No | ||
| item_ref | Yes | ||
| to_milestone | No | stream/maintenance |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It discloses the core mutation: an item is moved and marked deferred, and it mentions the optional audit reason. However, it does not explain reversibility, side effects on the item's previous milestone, permissions, or what 'deferred' means operationally downstream.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The first sentence is concise and front-loaded with the main purpose. However, the Args block largely duplicates the input schema's property names, types, and defaults, so not every line earns its place. The overall size is still compact and readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no schema property descriptions, and many sibling milestone/status tools, the description is too thin. It does not clarify when to prefer this over milestone_move_item, how item_ref or milestone names should be formatted, or what effects 'deferred' has. An output schema exists, but that does not fill the invocation and selection gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, so the description needed to compensate. The Args section mostly restates the parameter names: 'item_ref: The item to defer' and 'to_milestone: Destination' add minimal meaning beyond the schema's property names. Only 'reason: Optional audit reason' provides extra semantic color; no formats, accepted reference syntax, or examples are given.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action: 'Move an item to stream/maintenance (or another milestone) and mark it deferred.' This clearly identifies the operation and distinguishes it from a plain move by adding the 'mark deferred' behavior. However, it does not explicitly contrast itself with sibling tools like milestone_move_item or milestone_set_status, so it stops short of full sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance about when to use this tool versus alternatives such as milestone_move_item, milestone_add_item, mark_branch_only, or release_item. The usage context is only implied by the operation itself, with no when/when-not advice or mention of prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List milestones with optional filters.
Args:
kind: 'release' or 'stream'.
state: 'open' / 'closing' / 'shipped' / 'archived'.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | ||
| state | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. The verb 'List' implies a read-only operation, and the filter values give some sense of behavior, but the description does not explicitly state side effects, authorization needs, or pagination behavior. It is minimally adequate for a listing tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded with the main action, followed by a compact list of parameter values. Every sentence earns its place, and there is no redundant or vague filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two optional parameters and an output schema, the description covers the essential invocation details, including allowed values. It lacks explicit usage guidance and a clear statement of non-mutation, but these gaps are minor for a straightforward listing operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only property names with string/null types and no enums, so the description fully compensates by enumerating valid values for both parameters: kind as 'release' or 'stream' and state as 'open'/'closing'/'shipped'/'archived'. This adds essential meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'List milestones with optional filters.' This clearly identifies what the tool does and distinguishes it from sibling milestone tools like milestone_create or milestone_status. The purpose is immediately understandable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as milestone_audit_query or milestone_status. It only describes what the tool does, not the conditions that would make it the right choice among the many sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move an item to a different milestone.
Args:
item_ref: The item to move (e.g. CB-5).
to_milestone: Destination milestone slug.
reason: One-line audit reason.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | No | ||
| item_ref | Yes | ||
| to_milestone | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It states only the core effect and does not disclose side effects such as removal from the source milestone, permission requirements, or whether the item must already belong to a milestone. The audit-reason parameter hints at logging but does not explain enforcement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact: one clear imperative sentence followed by a minimal labeled argument list. Every sentence earns its place, and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple three-parameter tool with an output schema, the description provides enough to invoke it correctly: the operation is clear and all parameters are explained. It lacks explicit alternative guidance and side-effect disclosure, but these are not critical to making a basic correct call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the Args list compensates by giving every parameter meaningful semantics beyond the schema: item_ref gets a concrete example, to_milestone is specified as a slug, and reason is described as a one-line audit reason. It does not provide exhaustive constraints, but it covers all parameters clearly and briefly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Move') and resource ('an item to a different milestone'), and the item_ref example CB-5 clarifies the target. It is clear and not a tautology, but it does not explicitly differentiate itself from sibling tools like milestone_add_item or milestone_set_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance about when to use this tool versus milestone_add_item, milestone_set_status, or milestone_update. The description implies the context of moving items between milestones, but it provides no explicit prerequisites, alternatives, or exclusion conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One-time repair (CB-107) for stream items whose source finding or requirement resolved before the status-change hook existed (CB-26). The hook keeps new resolutions in sync; this is the retroactive fix for rows it never saw.
DRY RUN BY DEFAULT — without apply=true nothing is written, and the response still lists every candidate transition it WOULD make. This is a bulk mutation, and CLAUDE.md is explicit that a repair tool which writes by default is how it becomes an accident, so the dry-run default is load-bearing and this wrapper refuses to weaken it.
Args:
apply: Must be a literal JSON boolean. Defaults to false (dry run). Rejected outright for any other JSON type (a string like "false", a number, null) rather than coerced by truthiness — an MCP client sends JSON over the wire, and Python's bool("0") and bool("false") are both True, which would silently turn a client's intended dry run into a write (CB-82's class of bug). CB-151: strict typing refuses this at the pydantic boundary before the tool body runs, closing the one hole the previous union annotation + isinstance check left open (1.0/0.0 coerced to a real bool before isinstance could see it).
| Name | Required | Description | Default |
|---|---|---|---|
| apply | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does so thoroughly. It discloses the dry-run default, that nothing is written without apply=true, that the response lists candidate transitions, that this is a bulk mutation, and the strict rejection of non-boolean values — all beyond what the schema offers.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with purpose and the most critical safety behavior before moving to parameter details. It is long, but every sentence earns its place by explaining non-obvious behavior; there is no filler or repetition of schema data.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with no annotations but an output schema, the description covers the operation's niche, the dry-run safety model, write behavior, and strict parameter requirements. Nothing an agent needs to invoke it safely is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description fully compensates for the single parameter. It explains that apply must be a literal JSON boolean, defaults to false, is rejected for other JSON types rather than coerced, and even documents the historical bug class motivating the strict typing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific operation ('one-time repair') and a precise resource class ('stream items whose source finding or requirement resolved before the status-change hook existed'). It clearly distinguishes this tool from the hook that handles new resolutions, though it does not name or explicitly contrast a sibling tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear usage context: the hook keeps new resolutions in sync, while this tool is the retroactive fix for rows the hook never saw. It also explains the critical apply/dry-run semantics, but it does not formally state when not to use it or list alternative tool names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set an item's status. Records done_commit if status is terminal.
Args:
item_ref: The item id (e.g. CB-5).
status: open / in_progress / done / deferred / dismissed.
commit: SHA where the work landed on main (recorded for terminal status).
reason: Optional audit reason.
| Name | Required | Description | Default |
|---|---|---|---|
| commit | No | ||
| reason | No | ||
| status | Yes | ||
| item_ref | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose one key side effect: 'Records done_commit if status is terminal.' It also hints at audit via 'Optional audit reason,' but it does not explain transition rules, reversibility, permissions, or what happens when a status is changed away from a terminal value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the core action, and uses a clean bulleted Args list. Every part earns its place without redundant elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all parameters and the main side effect, and an output schema exists to document returns. However, it leaves out important operational context such as which statuses count as terminal, whether transitions are validated, and when to choose this over closely related status-changing siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it does: it explains item_ref with an example, enumerates the five valid statuses, defines commit as a SHA on main, and marks reason as optional. This adds meaningful semantics beyond the schema's bare titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: 'Set an item's status' within a milestone context, and it lists the allowed status values. It does not explicitly distinguish itself from sibling tools like milestone_close or milestone_defer, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives such as milestone_close, milestone_defer, or mark_integrated. There are no when-not-to-use conditions or explicit exclusions, leaving the agent to infer appropriate usage from the argument list alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Detailed rollup for one milestone: item counts by status / size, blockers, branch-only items, days to target.
Args:
id: Milestone slug.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. 'Rollup' communicates a read-only aggregation action, and the listed output fields—counts, blockers, branch-only items, days to target—tell the agent what kind of information will be produced. It does not discuss errors or freshness, but for a status-report tool this is sufficient transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: a one-sentence summary of purpose and content, followed by a clearly labeled Args section. Every sentence adds useful information with no filler or repetition of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one parameter and a provided output schema, the description is complete: it identifies the input format and describes the categories of data returned. It would not be reasonable to expect more detail for a simple milestone-status rollup.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does by explaining that 'id' is the 'Milestone slug', adding meaningful semantic content beyond the raw schema field name. This is a complete and precise parameter definition for the single required argument.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: a 'Detailed rollup for one milestone' and enumerates the exact contents of the rollup (counts by status/size, blockers, branch-only items, days to target). This clearly distinguishes it from sibling tools like milestone_list and milestone_audit_query by emphasizing a single-milestone aggregate view.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Detailed rollup for one milestone' gives a clear context for when to use this tool: when an agent needs a comprehensive status/summary of a specific milestone. It does not explicitly name alternative tools or exclusions, but the one-milestone scope is an unambiguous selection signal among the sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update mutable fields of a milestone. id and kind are immutable.
Args:
id: Milestone slug.
description: New description (or None to skip).
target_date: New ISO target date (or None to skip).
state: New state (open / closing / shipped / archived).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| state | No | ||
| description | No | ||
| target_date | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses partial-update semantics ('or None to skip') and immutable fields, but does not disclose side effects such as state-transition rules, whether updates are reflected elsewhere, or failure behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded, with a one-line purpose followed by a clean Args list. Every sentence adds information; there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter update tool with an output schema, the description covers the essential semantics and constraints. It only lacks explicit routing relative to sibling milestone state/status tools, which would make it fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully compensates: it defines id as a milestone slug, target_date as an ISO date, state as an enumerated set, and clarifies that None means skip rather than clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource, 'Update mutable fields of a milestone', and explicitly states what is out of scope ('id and kind are immutable'), which helps distinguish it from milestone_create or other milestone operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage is implied rather than contrasted with alternatives: it is for changing milestone mutable fields, and the immutability note adds a constraint. However, it does not say when to choose this over closely related siblings like milestone_set_status or milestone_close.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim the next eligible item for the calling agent. Returns the item dict or None if nothing eligible.
Priority: stream/security > release/* (earliest target_date) > stream/triage > stream/maintenance.
Args:
agent_id: Stable id for the calling agent. Used as actor in audit.
capacity: Dict like {'large':1,'small':2,'triage':5}. Defaults to those values if not provided.
| Name | Required | Description | Default |
|---|---|---|---|
| agent_id | Yes | ||
| capacity | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations to fall back on, the description discloses key behavior: it returns the item dict or None, applies a priority order, and uses agent_id as the audit actor. It also reveals capacity defaults. It does not explicitly state that claiming is a persistent state change, though 'Claim' implies mutation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the action and return value; the priority block and args are clearly separated. The priority syntax is slightly dense but not wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, return behavior, selection priority, and both parameters. It does not define 'eligible' in detail or explain how capacity interacts with eligibility, but the provided info is sufficient for basic invocation, especially with an output schema present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only provides names and types; the description supplies essential semantics: agent_id is a stable id used as actor in audit, and capacity is a dict with example keys and default values. This fully compensates for the 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and object: 'Claim the next eligible item for the calling agent,' and states the return type. It conveys the tool's role in a queue, but it does not explicitly differentiate from sibling claim tools like claims_claim or codesweep_next, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains how the tool selects items via a priority order but gives no guidance on when to choose pull_next over sibling tools such as claims_claim or codesweep_next. There are no explicit when-to-use or when-not-to-use instructions, and no alternative tool is mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search and filter findings. Returns structured results.
Supports lookup by ID via id= (single) or ids= (batch). Missing IDs
are silently absent from the result so the caller can diff. For a strict
single-ID fetch that errors on miss, use get instead.
Args:
id: Fetch a single finding by exact ID (e.g. CB-1383)
ids: Fetch multiple findings by ID list; missing IDs are skipped
status: Filter by status (open, in_progress, fixed, not_a_bug, wont_fix, stale, deferred). Aliases accepted. Use 'deferred' to find items with active blockers.
severity: Filter by severity (critical, high, medium, low)
category: Filter by exact category
file: Filter by file path (substring match)
source: Filter by source (claude, ruff, human, etc.). Compares the FIRST reporter — the column is frozen at first report (BT-4); later observations' sources live only in the occurrence ring (meta.occurrences[*].source), and an imported observation's ring source can be a peer tracker's.
tag: Filter by tag (finds findings containing this tag)
meta_key: Filter by metadata key existence. Reads the row's AUTHORED top-level meta (the column), never the occurrence ring.
meta_value: Filter by metadata value (requires meta_key; same authored top-level meta as meta_key — ring meta is not consulted)
commit: Matches the first-report column OR any occurrence in the ring (prefix match, hex validated) — "what was observed on this commit" (CB-128). staleness_check uses the NEWEST ring entry instead: a different question.
ref: Filter by reported_at_ref (exact match, never prefix) — matches the first-observed or manually assigned release ref (BT-4); per-occurrence refs in the ring are not consulted.
fingerprint: Filter by identity fingerprint (exact match)
group_by: Group results by: severity, category, status, file, source, tag, meta: (source groups count FIRST reporters — the column is frozen at first report). tag and meta:<key> do NOT partition the population: a card with two tags is counted under both, and a card carrying no value on the axis is in no group at all. The response therefore always carries population, ungrouped_rows, multi_group_rows and nonscalar_value_rows beside groups; the counts sum to the population only while the last three are 0. meta:<key> reads the AUTHORED top-level meta, like meta_key does, and a key holding ., [, ] or " is REFUSED — SQLite cannot tell such a name from a path (CB-167). A key that is absent, JSON null, or holds an object/array is ungrouped rather than invented. OVERLAPS grouping_tags DELIBERATELY and differently: that tool is a tag census with pair co-occurrence over status/category only; this is a distribution that composes with every filter on this tool.
limit: Max results. A limit you PASS is always honoured: 0 means NO results, and it means that with id/ids too (CB-158 — an id list used to raise any smaller limit to fit itself, so limit=0 came back full). A negative value is an error (it used to mean "no limit"). Omit it and the page size is 100, widened to fit an ids list so a batch lookup returns every id it asked for.
offset: Pagination offset
resolve_anchors: Resolve each result's location anchor against the repository HEAD, so a card whose code moved reports its new path. OFF by default because it costs 2-4 git calls per ANCHORED row and this is the primary read path; the cheap half — whether a card carries an anchor at all, and the refusal token when capture found nothing to grab — is in every result either way. get resolves one card by default.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | ||
| ids | No | ||
| ref | No | ||
| tag | No | ||
| file | No | ||
| limit | No | ||
| commit | No | ||
| offset | No | ||
| source | No | ||
| status | No | ||
| category | No | ||
| group_by | No | ||
| meta_key | No | ||
| severity | No | ||
| meta_value | No | ||
| fingerprint | No | ||
| resolve_anchors | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations supplied, the description carries the full behavioral burden and exceeds it. It discloses silent omission of missing IDs, the honored `limit=0` semantics, non-partitioning behavior of tag/meta grouping, first-reporter source semantics, meta/ring consultation boundaries, and the real git-call cost of `resolve_anchors`.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The definition is dense and long, but it is organized as a clear bulleted Args list with the core purpose and ID behavior front-loaded. It earns most of its length given 17 parameters and zero schema descriptions, though a few historical bug notes could be trimmed without much loss.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 17 parameters, no annotations, and no schema-level parameter descriptions, the description is unusually complete: every parameter is documented, subtle response guarantees are called out, and sibling comparisons fill selection context. An output schema exists, so not re-specifying return shapes is appropriate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so every parameter's meaning must come from the tool description. Each of the 17 parameters receives substantive semantics: enum values, matching modes, required companion params, prefix vs exact matching, and edge-case behavior for limit and offset.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with 'Search and filter findings' and 'Returns structured results', giving a specific verb and resource. It differentiates itself from siblings by explicitly contrasting with `get` for strict single-ID fetches, and later with `staleness_check` and `grouping_tags`.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit routing: use `get` for a strict single-ID fetch that errors on miss, use `staleness_check` when asking about the newest ring entry, and contrasts its `group_by` distribution with the `grouping_tags` census. It tells the agent not only what the tool does but when a sibling is the better choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Findings TOUCHED at or after a date — the one call for "what closed since".
WHAT THIS MEASURES: updated_at, the time of the LAST WRITE to the row,
and not the moment the finding was closed. There is no close timestamp
anywhere in the schema. A status change moves updated_at, and so do a
re-tag, an AUTHORED meta patch, a severity re-triage, an append_note,
and a DEDUPLICATED OBSERVATION — a repeat report bumps the occurrence
count and stamps updated_at while the status stays exactly where it was.
AUTHORED is doing work in that sentence since CB-230: the tracker's own
housekeeping (refreshing a card's code anchor) writes meta WITHOUT
stamping, so a maintenance pass no longer floods this reader with every
card it touched.
So recent(since=..., status="fixed") means "cards that are fixed NOW and
were touched since that date", NOT "cards closed since that date". The
error is ONE-SIDED: false positives are possible, misses are not, because
closing a card always writes updated_at — guaranteed rather than merely
true, since housekeeping is refused outright when it carries a status.
Rows come back newest touch first, with rowid breaking the whole-second
ties updated_at produces, so a paged walk is stable.
Args:
since: Lower bound on updated_at, INCLUSIVE. 'YYYY-MM-DD' or 'YYYY-MM-DDTHH:MM:SSZ'. REQUIRED — an unparseable value is refused rather than defaulted, because a silently widened window answers a question nobody asked.
status: Filter by status (open, in_progress, fixed, not_a_bug, wont_fix, stale). Aliases accepted. Omit for every status. The deferred pseudo-status of query is NOT accepted here and is refused rather than ignored — use query for it.
limit: Max results (default 100). 0 means NO results. A negative value is an error (it used to mean "no limit"). The neighbouring query tool answers the same argument the same way.
offset: Pagination offset
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| since | Yes | ||
| offset | No | ||
| status | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so thoroughly. It covers what updates `updated_at`, what does not, the guaranteed write on close, deterministic ordering with `rowid` tie-breaks, and refusal behaviors for invalid inputs. This goes well beyond a typical tool description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but dense, and nearly every sentence adds crucial nuance that would be impossible to infer from the schema alone. The structured 'Args:' section makes parameter details easy to scan. It earns its length, though a few explanatory asides could be tightened without losing essential behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the subtle semantics around `updated_at`, the lack of annotations, and the presence of an output schema, this description is complete. It covers argument behavior, error handling, sort order, pagination stability, and the exact meaning of filtering by status, leaving no critical gap for an agent selecting or invoking the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates. It explains `since` inclusiveness and accepted formats, requiredness and parse failures; enumerates valid `status` values and notes alias handling; explains `limit` edge cases including 0 and negative values; and clarifies `offset` as pagination offset.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as returning findings touched at or after a given date, and explicitly frames it as the one call for 'what closed since'. It distinguishes the resource and semantics from the neighboring query tool by spelling out what is measured (`updated_at`) and what is not measured (a close timestamp).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance on when this tool is appropriate, including the exact meaning of `recent(since=..., status="fixed")` and the one-sided error behavior. It also names the `query` tool as the place to use for the `deferred` pseudo-status, giving a concrete alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List relations touching a finding, in both directions.
Args:
entity_id: Finding to look up (e.g. "CB-5"). Omit to list all.
rel: Filter by relation. rel="distinct_from" alone lists every live suppression, which is worth reviewing periodically.
include_retracted: Include tombstoned edges (default: false)
| Name | Required | Description | Default |
|---|---|---|---|
| rel | No | ||
| entity_id | No | ||
| include_retracted | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the behavioral disclosure burden. It discloses important traits: both directions, default exclusion of tombstoned edges, and the special behavior of rel='distinct_from' returning live suppressions. It implicitly signals read-only via 'List' but does not explicitly state safety guarantees.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: a one-sentence purpose followed by a bulleted args list. Each line is informative, and the distinct_from tip adds practical value without redundancy. It is appropriately sized for a 3-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple query tool with no required parameters and an output schema (which can explain return values), the description covers all invocation-relevant details: optionality, filtering, booleans, and a notable use case. Nothing needed 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.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it does for all three parameters. entity_id gets a concrete example and behavior when omitted; rel gets a meaningful example value; include_retracted explains the tombstoned-edge concept and default. This fully disambiguates the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a precise verb and resource: 'List relations touching a finding, in both directions.' It clearly identifies the operation as a read-only listing and differentiates from sibling mutation tools like relations_relate and relations_unrelate. The phrase 'in both directions' adds specific scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for using the tool, such as omitting entity_id to list all relations and filtering by rel. The specific tip that rel='distinct_from' lists live suppressions is a practical use case. It does not explicitly name alternatives or exclusions, but the listing verbs and the example make the intended usage evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Assert a typed relation between two findings.
Args:
src_id: Source finding (e.g. "CB-5"). For duplicate_of this is the LOSER — the card that dies.
rel: duplicate_of, split_from, follow_up_of, found_during, distinct_from, or related_to.
dst_id: Target finding. For duplicate_of this is the SURVIVOR.
source: Who is asserting this (e.g. "owner", "goldset-2026-08-17").
note: Optional reasoning.
| Name | Required | Description | Default |
|---|---|---|---|
| rel | Yes | ||
| note | No | ||
| dst_id | Yes | ||
| source | Yes | ||
| src_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden and does disclose meaningful asymmetry for duplicate_of relations ('LOSER — the card that dies' vs. 'SURVIVOR') and source attribution. It does not mention idempotency, whether re-asserting a relation errors or replaces, permissions, or other side effects, so the disclosure is useful but incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description opens with a one-sentence purpose and then uses a clean Args list with one line per parameter. There is no filler, and the formatting makes the parameter semantics scannable for an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a five-parameter mutation tool with no annotations, the description covers all parameters, the controlled vocabulary, and the crucial duplicate_of directionality; the output schema likely covers return values. It could be more complete by explaining the other relation types' directionality and the effect of re-asserting an existing relation, but it is not missing anything essential for a basic correct call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully compensates by explaining every parameter, listing all valid values for rel, and giving concrete examples for src_id and source. It also adds critical semantic meaning for src_id and dst_id in the duplicate_of case, which the schema alone does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a precise action ('Assert a typed relation between two findings') and names the resource ('findings'), with a list of valid relation types that make the operation concrete. It does not explicitly differentiate from sibling tools relations_unrelate and relations_query, but 'assert' plus the enumerated relation types make it identifiable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage is implied: call this when creating a typed relation, as opposed to relations_unrelate or relations_query for removing or inspecting relations. However, there is no explicit when-to-use or when-not-to-use guidance, and no sibling tools are named as alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retract a relation. Tombstones it — the row and its history remain.
Args:
src_id: Source finding
rel: The relation to retract
dst_id: Target finding
retracted_by: Who is retracting it
reason: Why
| Name | Required | Description | Default |
|---|---|---|---|
| rel | Yes | ||
| dst_id | Yes | ||
| reason | No | ||
| src_id | Yes | ||
| retracted_by | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral disclosure burden. It does disclose the key side effect: the relation is tombstoned, not deleted, and history remains. However, it does not address reversibility, idempotence, what happens if the relation is already tombstoned, or any permission requirements. The tombstone disclosure is valuable but incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the first sentence states the core action and likely the most important behavioral detail. The parameter list is clean and every line adds a small semantic increment. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the five parameters, all are covered with at least a basic explanation, the tombstone behavior is disclosed, and an output schema exists so return values need not be described. Minor gaps remain—no mention of failure modes, idempotence, or whether an active relation is required—but the description is sufficient for a competent agent to invoke the tool safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must compensate. It provides brief semantic labels for all five parameters—'Source finding', 'Target finding', 'Who is retracting it', 'Why'—which is useful. But 'rel: The relation to retract' is nearly tautological, and no parameter receives format, source, or constraint details beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Retract a relation.' It adds a clarifying behavioral detail—'Tombstones it — the row and its history remain'—which clearly distinguishes this from deletion and from the sibling relations_relate. The purpose is immediately understandable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The implied usage is clear: use this when you want to retract a relation while preserving its history. However, it provides no explicit guidance about when to prefer this tool over alternatives, does not name relations_relate as the counterpart, and gives no conditions or prerequisites such as whether the relation must currently be active.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Free agent capacity for an item.
Args:
item_ref: The item id (e.g. CB-5).
status: 'done' (terminal) or 'abandoned' (returns item to 'open').
commit: SHA where the work landed (recorded if status='done').
| Name | Required | Description | Default |
|---|---|---|---|
| commit | No | ||
| status | No | done | |
| item_ref | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full burden. It does disclose key state transitions—'done' is terminal, 'abandoned' returns the item to 'open'—and that commit is only recorded for done. However, it doesn't clarify what 'free agent capacity' concretely changes, side effects on existing claims, or reversibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded with a clear one-line purpose, followed by a compact, scannable Args list. No filler or redundant restatement of the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The core call contract is covered: all parameters are semantically defined and the state transitions are described. Minor gaps remain around prerequisites (e.g., must the item be currently claimed?) and whether 'done' requires the commit field, but the tool is largely usable as documented.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates: it explains item_ref with an example, enumerates the two status values with their behavioral consequences, and specifies when commit is recorded. This adds substantial meaning beyond the raw JSON schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('free') and resource ('agent capacity for an item'), with a concrete item reference example (CB-5). However, it doesn't explicitly distinguish release_item from the sibling claims_release, leaving some ambiguity about the precise workflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The Args section gives conditional behavior for status values ('done' terminal, 'abandoned' returns item to open), which implies a workflow. But there's no explicit 'when to use' guidance, no exclusion, and no reference to alternatives like claims_release, so the agent must infer when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a requirement.
Args:
req_id: Requirement ID (e.g. FR-001)
description: What the system shall do
section: Section name (e.g. "1.10 Document Sorting")
priority: must, should, or could
status: planned, partial, implemented, verified, superseded, obsolete
source: Where this requirement came from (e.g. Take 26, NEW)
test_coverage: Test file name(s)
tags: Optional tags
meta: Optional metadata
| Name | Required | Description | Default |
|---|---|---|---|
| meta | No | ||
| tags | No | ||
| req_id | Yes | ||
| source | No | ||
| status | No | planned | |
| section | No | ||
| priority | No | should | |
| description | Yes | ||
| test_coverage | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits, but it only states the add action. It does not mention what happens if a requirement with the same req_id already exists, whether the operation is persisted immediately, or any side effects on related data. This is a significant gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: a one-sentence purpose followed by a clean Args list. Each parameter has a short explanatory note, and the content is front-loaded. It is slightly repetitive with the schema names but earns its length by adding examples and allowed values.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 9-parameter mutation tool with no annotations, the description is incomplete. It lacks operational context such as conflict behavior on duplicate req_id, required preconditions, or how the added requirement integrates with existing data. An output schema exists, so return values are covered, but the missing behavioral and usage context leaves significant gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the Args list in the description must compensate, and it does. It provides concrete examples (FR-001, '1.10 Document Sorting', 'Take 26'), enumerates allowed values for priority ('must, should, or could') and status ('planned, partial, implemented, verified, superseded, obsolete'), and clarifies the meaning of description and source. Some entries like 'Optional tags' and 'Optional metadata' are thin, but overall the description adds substantial value beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Add a requirement' states a specific verb and resource, clearly indicating the tool creates a single requirement. It does not explicitly distinguish itself from siblings like batch_add or reqs_update, but the reqs_ prefix and singular phrasing make the core purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance about when to use this tool versus alternatives such as batch_add, reqs_import, or reqs_update. It does not mention scenarios, prerequisites, or exclusions, leaving the agent to infer appropriateness solely from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Store embeddings for multiple requirements at once.
Same preconditions as reqs_embed: you compute the vectors yourself and pass finished numbers, the requirement text never reaches this tool, and codebugs stores them locally and sends them nowhere.
Every vector in one call must have the same number of components as every other vector in the call AND as the vectors already stored in this tracker; empty vectors, non-numbers, NaN and infinity are refused. The self-consistency rule is a separate one: in an empty tracker there is nothing to compare against, so without it a single call could create the mixed state the rules exist to prevent.
Args:
embeddings: Dict mapping requirement ID to float vector
| Name | Required | Description | Default |
|---|---|---|---|
| embeddings | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses local-only storage, no exfiltration, strict dimension consistency across the call and tracker, refusal of empty/non-number/NaN/infinity values, and the rationale for the self-consistency rule.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose is front-loaded and each block adds preconditions, validation, or argument semantics. The self-consistency explanation is somewhat verbose but still earns its place by clarifying an otherwise surprising edge case.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a single parameter and a detailed description covering preconditions, privacy, validation, and dimensionality, an agent has enough to invoke it correctly. An output schema exists, so the lack of return-value discussion is not a gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description maps 'embeddings' to a dict of requirement ID to float vector, which adds meaning beyond the generic object schema. It also clarifies per-vector constraints such as same dimensionality and rejecting NaN/infinity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence names a specific verb ('Store') and resource ('embeddings for multiple requirements'), and the phrase 'multiple... at once' plus the reference to reqs_embed distinguishes this batch tool from the single-embedding sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states clear preconditions: callers compute vectors themselves, pass finished numbers, and requirement text never reaches the tool. The alternative reqs_embed is referenced, but it does not explicitly say 'use reqs_embed for a single requirement,' so the when-not-to-use guidance is slightly implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Store an embedding vector for a requirement.
YOU compute the embedding, in your own process, and pass the finished numbers here. This tool never receives the requirement's text. codebugs stores the vector in its own local SQLite file and sends it nowhere. (Scope, stated precisely rather than loudly, because a promise wider than its check is worse than no promise. The route above is the claim. A test enforces two narrower things beside it: this package's own source imports none of the socket-opening modules that test lists, and it imports nothing at all from outside the package and the standard library without a declared, reasoned entry — so a network client nobody anticipated is still refused. Neither says "codebugs cannot reach the network": the MCP transport your client is talking over is a separate layer, and it is not covered.)
Because there is no embedding provider inside codebugs, nothing here knows the "right" dimensionality — it is whatever the first stored vector had. So the vector is refused if it is empty, contains a non-number, contains NaN or infinity, or has a different number of components than the vectors already stored in this tracker. Each of those would otherwise break reqs_search_similar: a mismatched width makes it unable to score the other rows, and a NaN makes a row drop out of every result with no error at all.
Once a tracker holds vectors of one width you cannot switch embedding model: there is no clear-and-re-embed operation in this package. reqs_embedding_stats reports which widths are actually present.
Args:
req_id: Requirement ID
embedding: Float vector. Any dimensionality, but the SAME one for every requirement in a given tracker.
| Name | Required | Description | Default |
|---|---|---|---|
| req_id | Yes | ||
| embedding | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the behavioral burden and does so thoroughly. It discloses local SQLite storage, that data is sent nowhere, the network-scope caveat, exact rejection conditions (empty, non-number, NaN, infinity, width mismatch), and the permanent width constraint per tracker.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with paragraphs and an Args section, and the core purpose is front-loaded. However, the privacy/scope passage is longer than needed for tool invocation and includes verbose philosophical framing. Several sentences add trust context rather than call-relevant guidance, making it less concise than it could be.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is highly complete for a two-parameter tool: it explains when to call, how vectors are validated, what happens with mismatched widths, why those rules exist, and how to inspect current widths. Since an output schema is present, not explaining return values does not hurt completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds meaningful semantics for 'embedding': float vector, arbitrary dimensionality, consistent width per tracker, and invalid value conditions. 'req_id' gets only minimal elaboration ('Requirement ID'), which is thin but acceptable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the operation: 'Store an embedding vector for a requirement' and clarifies that the caller computes the embedding and passes finished numbers. It is specific about verb and resource, but it does not explicitly distinguish itself from the sibling reqs_batch_embed, so it stops short of full sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context on when to call it: after the caller has computed an embedding, and with strong warnings about consistent dimensionality and the inability to switch embedding models later. It points to reqs_embedding_stats for checking widths, but it does not explicitly state when to prefer this over reqs_batch_embed or other alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report on embedding coverage --- how many requirements have embeddings.
This tool takes no input at all, so it is not a privacy surface and carries no precondition block of its own; that is said explicitly rather than left as an omission a reader has to interpret.
Beyond coverage it reports dimensions --- which vector widths this
tracker actually holds, and how many rows each --- plus mixed, true
when there is more than one. That is the channel for noticing a tracker
that received vectors from two different embedding models:
reqs_search_similar silently excludes rows of a width other than your
query's, and being able to see the split here is what keeps that from
looking like "nothing is similar". Both keys are always present; an
empty dimensions list means no vectors are stored, never that the
check did not run.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden of behavioral disclosure. It explicitly states the tool takes no input, is not a privacy surface, and has no precondition block. It also explains the always-present keys and the critical interpretation that an empty dimensions list means no vectors are stored, not that the check did not run.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and then provides meaningful detail about output semantics and the use case for diagnosing mixed vector widths. One meta-commentary clause about saying something explicitly rather than leaving it as an omission is unnecessary and slightly verbose, but the overall structure is clear and focused.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter reporting tool with an output schema available, the description covers the purpose, all key output fields, and the main edge-case interpretation. It explicitly addresses the most likely confusion around empty dimensions and connects the tool's value to reqs_search_similar behavior, making it complete for correct invocation and interpretation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so the schema is trivially complete. The description goes beyond the schema by explicitly stating the tool takes no input and therefore carries no privacy or precondition implications, removing any ambiguity about required context or arguments.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence states a precise operation: report on embedding coverage, specifically how many requirements have embeddings. It further distinguishes the tool from siblings by describing the additional dimensions and mixed keys and by referencing reqs_search_similar's behavior. Purpose is unambiguous and specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a concrete diagnostic scenario: use this tool to detect a tracker holding vectors from multiple embedding models, especially when reqs_search_similar returns no matches due to silently excluded width mismatches. It clearly explains the no-input nature and lack of preconditions, though it does not explicitly enumerate alternatives or say when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a single requirement by ID with full body.
Raises a not-found error if the ID does not exist. For lenient batch
lookup that silently drops missing IDs, use reqs_query(ids=[...]).
Args:
req_id: The requirement ID (e.g. FR-001)
| Name | Required | Description | Default |
|---|---|---|---|
| req_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. It discloses the not-found error behavior and the 'full body' response characteristic. It could additionally state read-only/idempotent nature explicitly, but the verb 'Fetch' plus error semantics provide reasonable transparency for this simple read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the core purpose is the first sentence, followed by error behavior and the alternative tool, then the parameter documentation. Every sentence earns its place with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (one required parameter), the presence of an output schema, and the clear behavioral/alternative guidance, the description covers everything an agent needs to invoke it correctly. Nothing important is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, but the description compensates by documenting req_id as 'The requirement ID (e.g. FR-001)', which adds domain meaning and an example format beyond the bare string type. For a single parameter, this is sufficient added value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Fetch a single requirement by ID with full body.' This clearly distinguishes it from the sibling reqs_query by emphasizing single-item strict lookup, so an agent can tell what the tool does and how it differs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states the strict error-raising behavior for missing IDs and directs the agent to reqs_query(ids=[...]) for lenient batch lookup that silently drops missing IDs. This is an explicit when-to-use/when-not-to-use guideline with a named alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Import requirements from a REQUIREMENTS.md file.
Parses markdown tables with columns: | ID | Requirement | Priority | Status | Source | Test Coverage |
Uses INSERT OR REPLACE, so re-importing updates existing entries.
Args:
markdown_path: Path to the REQUIREMENTS.md file
| Name | Required | Description | Default |
|---|---|---|---|
| markdown_path | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the important behavioral trait beyond annotations: it parses markdown tables and uses INSERT OR REPLACE, so re-importing updates existing entries. This is meaningful for an agent because it implies overwrite semantics. No contradictions with annotations exist since none were provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded, with every sentence earning its place: what the tool does, the exact markdown format, the upsert behavior, and the argument. There is no redundant prose or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter import tool, the description covers the file format, the import/update semantics, and the required argument. Since an output schema exists, explaining return values is not necessary. Minor missing detail like error handling or required table header exactness prevents a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description only restates the parameter as 'Path to the REQUIREMENTS.md file', which is essentially the same as the schema title 'Markdown Path'. With 0% schema description coverage, the description fails to add meaningful constraints, examples, or clarification about path format or resolution.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Import requirements from a REQUIREMENTS.md file') and a concrete resource, which clearly differentiates this from reqs_add/reqs_update by file-based ingestion. However, it does not explicitly name or contrast sibling tools, so it stops short of full sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use case is clear: use this when requirements need to be loaded from a markdown file, and re-imports will refresh existing entries. It does not explicitly mention alternatives like reqs_add or reqs_update, nor does it describe when not to use this tool, so exclusions are absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search and filter requirements.
Supports lookup by ID via id= (single) or ids= (batch). Missing IDs
are silently absent from the result. For a strict single-ID fetch that
errors on miss, use reqs_get.
Args:
id: Fetch a single requirement by exact ID (e.g. FR-001)
ids: Fetch multiple requirements by ID list; missing IDs are skipped
status: Filter by status (planned, partial, implemented, verified, superseded, obsolete, deferred). Use 'deferred' to find requirements with active blockers.
priority: Filter by priority (must, should, could)
section: Filter by section (substring match)
search: Search in description and ID
source: Filter by source (substring match)
tag: Filter by tag
group_by: Group by: section, status, priority, source
limit: Max results. A limit you PASS is always honoured: 0 means NO results, and it means that with id/ids too (CB-158 — an id list used to raise any smaller limit to fit itself, so limit=0 came back full). A negative value is an error (it used to mean "no limit"). Omit it and the page size is 100, widened to fit an ids list so a batch lookup returns every id it asked for.
offset: Pagination offset
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | ||
| ids | No | ||
| tag | No | ||
| limit | No | ||
| offset | No | ||
| search | No | ||
| source | No | ||
| status | No | ||
| section | No | ||
| group_by | No | ||
| priority | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral burden and succeeds. It discloses that missing IDs are silently skipped, documents the historically surprising limit behavior (0 means no results, negative errors, default page size, ids batch widening), and explains status filter semantics such as using 'deferred' to find blocked requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and the key sibling distinction, then uses a tight arg list. Every parameter earns its entry, and even lengthier notes on limit behavior are justified because the behavior is genuinely non-obvious and historically inconsistent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 11-parameter tool with no annotations, no schema descriptions, and complex behavioral edge cases, this description is complete. It covers all parameters, gives filtering values, explains missing-ID handling, pagination defaults, and the sibling fallback. The output schema exists, so explaining return values is unnecessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema description coverage is 0%, so the description must fully compensate. It documents all 11 parameters with concrete semantics, enum-like values for status/priority/group_by, substring matching for section/source, and detailed limit/offset behavior beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb and resource: 'Search and filter requirements.' It clearly defines the tool's scope and differentiates it from the sibling reqs_get by explicitly saying reqs_query returns missing IDs silently absent while reqs_get errors on a strict single-ID miss.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
States when to use the tool versus an alternative: 'For a strict single-ID fetch that errors on miss, use reqs_get.' This gives an agent a concrete decision rule between two closely related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find requirements semantically similar to a query.
Pass a query embedding (from the same model used to embed requirements). You compute it yourself; no text is sent anywhere by this tool, and the query vector is not stored.
Requirements whose stored vector has a different number of components than your query are EXCLUDED from the search rather than compared, so one foreign vector can no longer make the whole search fail. That also means they are invisible here: if you get fewer results than you expect, call reqs_embedding_stats, which reports which widths this tracker holds. A query vector that is empty or contains NaN or infinity is refused, because it would match nothing and return an empty list indistinguishable from an empty tracker.
Returns requirements ranked by cosine similarity.
Args:
query_embedding: Query vector
limit: Max results (default 10)
min_similarity: Minimum cosine similarity (default 0.3)
status: Optional status filter
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| status | No | ||
| min_similarity | No | ||
| query_embedding | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral disclosure burden and does so thoroughly. It explains that mismatched-width vectors are excluded rather than failing the search, empty/NaN/infinity vectors are refused, the query is not stored, and results are ranked by cosine similarity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average but every section adds necessary behavioral or usage detail, and the Args list provides quick parameter reference. It is front-loaded with the core purpose and organized into digestible paragraphs with clear caveats.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
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-value details are not required. The description covers preconditions, edge cases, failure behavior, and even gives a follow-up tool for diagnostics. For a semantic-search tool with no annotations, this is highly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does so by explaining each parameter: query_embedding is the query vector with model-matching and validity constraints, limit is max results, min_similarity is a cosine threshold, and status is an optional filter. This adds meaningful semantics beyond the bare schema titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Find requirements semantically similar to a query.' It clearly differentiates this semantic-search tool from other requirement operations by emphasizing embedding-based similarity and even references the alternative reqs_embedding_stats for a related diagnostic case.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage conditions: pass a query embedding from the same model used for requirements, compute it yourself, and note that no text is sent or stored. It also tells the agent what to do when results are fewer than expected by naming reqs_embedding_stats as the diagnostic follow-up.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Aggregated requirement counts by status x priority.
Args:
group_by: Group by: status, priority, section, source
| Name | Required | Description | Default |
|---|---|---|---|
| group_by | No | status |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description itself must convey behavior. 'Aggregated' strongly implies a read-only computation and not mutation, but it does not disclose scoping defaults, whether the aggregation covers all requirements, or how missing groups are represented. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short items with no filler, and the core aggregation statement is front-loaded before the parameter notes. The Args section adds the one piece of non-schema information an agent needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple: one optional parameter and an output schema exist, so return value details are covered elsewhere. The main gap is the absence of usage context, but that is already penalized in dimension 2; for a one-param stats tool this is otherwise complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only a title, default, and type for group_by, with 0% description coverage. The description compensates by listing the valid values: status, priority, section, source. It still leaves the meaning of section/source implicit, so it is not a 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear operation and object: 'aggregated requirement counts' by status/priority. It is not vague or a tautology, but it does not distinguish reqs_stats from similar siblings like reqs_summary or stats, so it earns a 4 rather than a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No conditions or alternative tools are mentioned. An agent is left to infer that this is the right tool whenever requirement aggregates are needed, but there is no guidance on when a sibling like reqs_query or reqs_summary would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Dashboard overview --- status breakdown, priority split, section progress, requirements without tests, deferred counts. Start here.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It discloses the scope of the overview (status, priority, progress, coverage gaps, deferred counts) and its dashboard nature, which strongly implies a read-only aggregate operation. It does not explicitly assert read-only behavior, data freshness, or how counts are derived, but for a zero-parameter dashboard these omissions are moderate rather than severe.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single compact line that front-loads 'Dashboard overview,' enumerates the five metric groups in a scannable dash-separated list, and closes with a two-word directive. Every element earns its place with zero waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter aggregate tool with an output schema that already documents the return shape, the description is complete: it states the tool's role ('Start here'), what content it covers, and requires no parameter guidance. The only unstated element is which sibling handles drill-down, which is a minor gap given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters and an empty schema, there is nothing for the description to document about arguments; the baseline of 4 applies. The description instead orients the agent to what the output contains, which is the only meaningful semantic contribution possible for this tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies the tool as a 'Dashboard overview' and enumerates its concrete contents: status breakdown, priority split, section progress, requirements without tests, deferred counts. This distinguishes it from sibling detail tools like reqs_get and reqs_query, but it lacks an explicit verb such as 'returns' or 'lists,' so it falls just short of the highest bar.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The closing directive 'Start here' is an explicit entry-point instruction, telling the agent to invoke this tool first before drilling into the requirements domain. However, it never names alternatives or states when not to use it (e.g., when a filtered query is preferred), so the guidance is clear but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a requirement's status, description, or metadata.
Args:
req_id: Requirement ID (e.g. FR-001)
status: New status: planned, partial, implemented, verified, superseded, obsolete
description: Updated description
priority: Updated priority: must, should, could
section: Updated section name
test_coverage: Updated test file reference
notes: Notes (stored in meta.notes). REPLACES the stored notes wholesale. If meta_update also carries a "notes" key, the meta_update value is the one that lands — see meta_update.
tags: Replace tags
meta_update: Merge metadata keys. notes and meta_update compose over ONE dict: notes replaces first, meta_update merges LAST. So passing both notes= and meta_update={"notes": ...} in a single call is neither an error nor a refusal — meta_update wins the collision, on every key it names. That precedence is deliberate: meta_update names the storage key directly, so it is the repair path for a key no other argument can write. Unlike the findings update tool there is no append_note here, so there is no third writer.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | ||
| notes | No | ||
| req_id | Yes | ||
| status | No | ||
| section | No | ||
| priority | No | ||
| description | No | ||
| meta_update | No | ||
| test_coverage | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full disclosure burden and does so thoroughly: it explains that notes replace stored notes wholesale, meta_update merges last and wins collisions, and passing both is neither an error nor a refusal. It also documents that the precedence is deliberate and that no third writer exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average, but the length is justified by the genuinely complex notes/meta_update interaction. The bulleted Args list keeps it scannable, and the core purpose is front-loaded in the first sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a nine-argument mutation tool with no annotations and no schema descriptions, the description is complete: every parameter is documented, update and replacement semantics are explicit, and the most confusing collision behavior is fully resolved. Since an output schema exists, omitting return-value details is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description is the only semantic source for all nine parameters. It lists every argument, enumerates valid status and priority values, and explains the replacement/merge/collision behavior for notes, tags, and meta_update. This fully compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence names a specific operation ('Update'), a concrete resource ('a requirement'), and the targeted facets ('status, description, or metadata'). This makes the tool immediately distinguishable from sibling read/create tools like reqs_get, reqs_query, and reqs_add.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context for the tricky parameters: meta_update is the 'repair path for a key no other argument can write,' and it explicitly contrasts this tool with the findings `update` tool by noting there is no append_note. It does not spell out all alternatives, but the update-vs-add distinction is obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verify requirements for issues.
Runs automated checks to find problems:
tests: do referenced test files actually exist?
ids: duplicate IDs, numbering gaps
status: contradictions (description says superseded but status says planned)
Args:
checks: List of checks to run (default: all). Options: tests, ids, status
project_dir: Project root for test file verification (default: cwd)
| Name | Required | Description | Default |
|---|---|---|---|
| checks | No | ||
| project_dir | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the behavioral burden; it does so by spelling out exactly what each check does (test file existence, duplicate IDs/numbering gaps, status contradictions). It does not explicitly state that the tool is read-only or describe side effects, but the enumerated checks plus the verb 'verify' give an agent a solid model of its behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: a one-line purpose, a bulleted behavior list, and a short Args section. There is no filler, and the scannable structure makes the check scopes and defaults immediately accessible.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with two optional parameters and an existing output schema, the description covers the operation, the selectable checks, and the path-dependent parameter. It leaves minor gaps such as prerequisites (expected project layout, file search scope) and explicit side-effect/read-only confirmation, but those are not critical for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage and no enums, the description is the sole documentation of parameters, and it fully compensates: it defines 'checks' with the exact allowed values (tests, ids, status) and default 'all', and 'project_dir' with its purpose ('root for test file verification') and default cwd. This adds meaning the raw schema completely lacks.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Verify') and resource ('requirements for issues'), then clarifies with concrete check categories (tests, ids, status). This clearly distinguishes it from sibling read/query tools such as reqs_query and reqs_get: it is an automated problem-finding verification rather than a retrieval or stats operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The check options and the phrase 'Runs automated checks to find problems' imply when to use the tool: after requirements are written, to catch file, ID, or status inconsistencies. However, it never names alternative tools, states when not to use it, or gives explicit routing guidance relative to the many reqs_* siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Preview what the file-time annotator would stamp for an observation.
Applies EXACTLY the resolver's policy: same candidate pool (live + dismissed, same category, newest 500), same minimum-text-length gate, same scoring. Advisory only — nothing is written.
Args:
description: The observation's description text
category: Category to search within (annotation never crosses it)
meta: Optional observation meta (volatile values are stripped from the text before scoring, same as fingerprint normalization)
threshold: Minimum similarity in [0, 1] (default 0.7, calibrated)
limit: Max matches returned (default 5)
| Name | Required | Description | Default |
|---|---|---|---|
| meta | No | ||
| limit | No | ||
| category | Yes | ||
| threshold | No | ||
| description | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure and does so thoroughly. It explicitly states the operation is non-mutating, applies EXACTLY the resolver's policy, and reveals the candidate pool, minimum-text-length gate, scoring behavior, and volatile-meta stripping. This goes far beyond a generic description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a one-sentence purpose, followed by a compact policy note and a tidy bulleted argument list. There is no filler or redundancy; every line adds actionable information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 5-parameter tool with no annotations and no schema-level parameter descriptions, the description covers purpose, all parameters, safety, and policy in a way that makes invocation practical. The only real gap is the absence of explicit when-to-use or when-not-to-use guidance relative to sibling tools, though the advisory nature partly mitigates this.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it fully does. Every parameter gets meaningful semantics: description text, category confinement, meta volatile-value stripping, threshold range/calibration, and limit as max matches. This is an exemplary compensation for a bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a concrete verb and resource: 'Preview what the file-time annotator would stamp for an observation,' and clarifies this is advisory, not a write. However, it does not explicitly differentiate itself from similar siblings like similarity_report or reqs_search_similar, leaving the distinction mostly to inference from 'preview.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended usage is implied: call this before writing an annotation to see what the resolver would produce, reinforced by 'Advisory only — nothing is written.' But it never states when to prefer this tool over alternatives or when not to use it, and no sibling tools are mentioned for routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Offline grouping scrub: similarity families as auditable evidence.
Families are connected components with min_pair_score and edge lists — the dry run for any future backfill/merge (the blocked backfill card); no merge is performed or implied. Default population is LIVE rows; pass status= to widen (the sentinel "all" means every status). Wall-clock is quadratic per category block (~115k pair comparisons on a 3k-row tracker); prefer the CLI for very large trackers.
Args:
threshold: Minimum similarity in [0, 1] (default 0.7, calibrated)
category: Restrict to one category
status: Widen/narrow the population (default: live statuses; "all")
family_limit: Max families returned (totals stay visible)
member_limit: Max members per family (totals stay visible)
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | ||
| category | No | ||
| threshold | No | ||
| family_limit | No | ||
| member_limit | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full disclosure burden and does so well. It reveals the non-mutating nature ('dry run', 'no merge is performed or implied'), the default population (LIVE rows), the wall-clock scaling behavior (quadratic per category block), and the effect of family_limit/member_limit on visibility of totals.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence earns its place: core semantics, mutation disclaimer, population defaults, performance warning, and per-argument meaning. The bolded key terms and bullet-style Args list make it easy to parse despite the length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 optional parameters and no annotations, the description covers purpose, behavior, parameters, defaults, and performance constraints. An output schema exists, so not detailing the exact return structure is acceptable; the description still provides enough for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully compensate, and it does. The Args section explains threshold's range and default, status's sentinel value, family_limit and member_limit semantics, and that totals remain visible even when limits are applied.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Offline grouping scrub: similarity families as auditable evidence,' clearly defining the tool's purpose and deliverable. It explains that families are connected components with min_pair_score and edge lists, and explicitly distinguishes this from a merge/backfill operation, making it distinct from siblings like codemerge_merge or mark_integrated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage context: it is 'the dry run for any future backfill/merge' and states that 'no merge is performed or implied.' It also names an alternative ('prefer the CLI for very large trackers') and explains how to widen or narrow the population via the status parameter, giving clear when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check if findings are stale by comparing against git history.
Staleness is checked against each finding's NEWEST observation: a
deduplicated re-observation records its commit in the occurrence ring,
and that commit — not the frozen first-report reported_at_commit —
is what the file is compared from; findings with no ring fall back to
the first report. Each result carries checked_commit, the commit the
verdict was computed against.
Returns file_status for each finding:
current: file unchanged since finding was reported
modified: file changed but still exists
renamed: file was renamed/moved
deleted: file no longer exists
unknown: can't determine, with a reason naming which question could
not be answered — no provenance data, an unreachable commit, a path
outside this repository's worktree, a path the reported commit never
contained (a glob, free text, or a file added later), an empty or
malformed value, a path that is neither a file nor a directory, or a
git/stat call that failed
Args:
finding_id: Check a single finding (e.g. CB-1)
status: Filter by finding status (default: open)
category: Filter by category
file: Filter by file path (substring match)
resolve_anchors: Also resolve each finding's location anchor against HEAD, so a record says where the reported LINES are now and not only what became of the file. OFF by default: this query permits ten thousand rows and already spends git per file. Every record carries the cheap half of the summary either way — whether the card has an anchor at all.
| Name | Required | Description | Default |
|---|---|---|---|
| file | No | ||
| status | No | ||
| category | No | ||
| finding_id | No | ||
| resolve_anchors | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden; it discloses the dedup/re-observation commit logic, the fallback to first report, checked_commit, every unknown reason, and the default/perf behavior of resolve_anchors. This is considerably more transparent than required.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded one-line summary, then structured statuses before params. Although detailed, the length is justified by the tool's complexity and every section serves selection or invocation; no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 5-param optional query that already has an output schema, the description still covers algorithm, edge cases, return semantics, defaults, and performance tradeoff. An agent can safely invoke and interpret results without needing the structured output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the Args section compensates fully: finding_id gets an example, status gets its default, file gets 'substring match', and resolve_anchors gets a detailed explanation of behavior and cost. This adds real meaning beyond the bare schema names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb and resource: 'Check if findings are stale by comparing against git history.' It also enumerates the exact file_status verdicts (current/modified/renamed/deleted/unknown), making the purpose concrete and distinct from any sibling tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use it (staleness against git history, optional filters by finding_id/status/category/file) and explains the cost tradeoff of resolve_anchors. It does not explicitly name alternatives or when-not-to-use cases, so it falls just short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Aggregated cross-tabulated counts.
Args:
group_by: Group by: severity, category, status, file, source, tag, meta: (source buckets count FIRST reporters — the column is frozen at first report, BT-4). With tag or meta:<key> the rows do NOT partition: a card with two tags is cross-tabulated under both of them, so the totals exceed the number of findings. population, ungrouped_rows, multi_group_rows and nonscalar_value_rows ride beside groups on every axis and are what make that readable. A meta key holding ., [, ] or " is refused (CB-167).
| Name | Required | Description | Default |
|---|---|---|---|
| group_by | No | severity |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral transparency and does an excellent job. It discloses that source buckets freeze the reporter at first report (BT-4), that tag/meta groupings cross-tabulate cards into multiple rows causing totals to exceed finding counts, that auxiliary rows like 'population' and 'ungrouped_rows' appear on every axis, and that certain meta keys are refused (CB-167). These are non-obvious behaviors beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a one-line summary and every subsequent clause adds meaningful behavior. It is dense and somewhat run-on, making parsing more difficult than ideal, but no sentence is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with only one optional parameter and an output schema present, the description covers the parameter's allowed values, edge-case counting behavior, special output-row semantics, and an error condition. Nothing essential is missing for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate for the undocumented group_by parameter. It lists all valid values, explains special semantics for source, tag, and meta:<key>, and documents the quoting restriction for meta keys. This is far more than the schema alone provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Aggregated cross-tabulated counts', which names the output as counts and signals a multi-dimensional grouping operation. The group_by list (severity, category, status, file, source, tag, meta:<key>) makes the resource and dimension explicit. It is clear, though it does not explicitly distinguish itself from sibling tools like summary or categories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: an agent can infer this tool is for retrieving aggregated counts over specified grouping dimensions. However, the description never explicitly says when to choose this tool over alternatives, and the sibling list contains several potentially overlapping reporting tools. There are no exclusions or alternative routing hints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Dashboard overview — open/resolved counts, severity breakdown, top categories, hottest files, deferred counts. Start here for orientation.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of conveying behavior. 'Dashboard overview' plus the listed data fields strongly implies a read-only, side-effect-free report, and 'Start here' adds orientation context. It could be even more explicit about safety, but the wording is sufficient for a zero-parameter summary.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence that lists concrete contents and ends with a guidance phrase. Every part earns its place, with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters, an output schema, and no annotations, the description provides enough context for an agent to know what this tool returns and when to start with it. It lacks only explicit sibling differentiation and alternative routing, which would make it fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the input schema fully covers semantics. Per the rubric baseline for zero-parameter tools, this is appropriate; there are no parameter details for the description to add.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as a dashboard overview and enumerates the exact metrics it provides (open/resolved counts, severity breakdown, top categories, hottest files, deferred counts). It is explicit about what the tool reports, though it does not explicitly contrast itself with sibling tools like stats or query.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Start here for orientation' clearly advises when to use this tool as an entry point. However, it does not mention specific alternatives or when not to use it, so it stops short of full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark a triage item as dismissed. Propagates to the underlying entity: bug → finding 'not_a_bug'; requirement → requirement 'obsolete'; external → no propagation.
Args:
bug_id: The item id (e.g. CB-5).
reason: Required one-line audit reason.
| Name | Required | Description | Default |
|---|---|---|---|
| bug_id | Yes | ||
| reason | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden, and it does disclose the key side effect: dismissing propagates to the underlying entity and sets specific states for bugs and requirements while external items do not propagate. It stops short of stating reversibility, permissions, or failure behavior, but the propagation detail is substantial and genuinely useful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: one purpose sentence, one side-effect/propagation sentence, and a short Args list. It front-loads the core action, and every sentence adds new information without filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter state-changing tool with no annotations and no schema descriptions, the description provides the essential operational semantics: arguments, propagation effects, and audit reason. An output schema presumably covers return values, so the main omission is guidance on when to choose this over sibling tools, but the definition remains adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the properties are only titled 'Bug Id' and 'Reason', so the description must compensate. It does by explaining that bug_id is an item id with a concrete example (CB-5) and by specifying reason as a required one-line audit reason, materially clarifying both parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence 'Mark a triage item as dismissed' states a specific verb and resource, and the propagation map ('bug → finding not_a_bug; requirement → requirement obsolete; external → no propagation') further defines exact scope. This clearly differentiates the tool from siblings like triage_promote and mark_integrated without opening their schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given on when to use this tool versus alternatives such as triage_promote or mark_integrated. The propagation rules imply some context, but the description never states when dismissal is appropriate or which sibling should be preferred in other situations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List open items in stream/triage, oldest first.
Args:
limit: Max rows (default 50).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry behavioral disclosure. 'List' safely implies a read-only operation, and 'oldest first' discloses ordering behavior. It does not explain what 'open' excludes, whether pagination is built-in, or any side effects, but the tool is simple enough that these are minor gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact: a one-sentence behavior statement plus a single-argument line. Every element earns its place, and the core purpose is front-loaded before the argument detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one optional parameter and an available output schema, the description covers the essential selection and invocation facts: what is listed, in what order, and how to cap rows. It does not define 'stream/triage' or 'open', but these appear to be domain terms and are not critical at this level of simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only provides 'default: 50' with no property description, while the description adds 'Max rows', giving the limit parameter real semantic meaning. For a single self-explanatory parameter this sufficiently compensates for the 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('List'), a targeted resource ('open items in stream/triage'), and a defining trait ('oldest first'). It does not explicitly contrast this with sibling tools like triage_dismiss or triage_promote, so differentiation requires some inference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose sentence implies this tool is for viewing open triage items, but there is no explicit 'when to use' or 'instead of X' guidance. An agent can infer the use case, but alternative selection is left unaddressed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move a triage item to a target milestone.
Args:
bug_id: The item id (e.g. CB-5).
to_milestone: Destination milestone slug.
size: 'large' / 'small' / 'triage'. Default 'small'.
acceptance: Required for size='large'.
priority: Lower = higher priority. Default 100.
linked_frs: FR ids linked to this item (required for size='large' bugs in release milestones to be pull-eligible).
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | small | |
| bug_id | Yes | ||
| priority | No | ||
| acceptance | No | ||
| linked_frs | No | ||
| to_milestone | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the safety burden. It clearly says 'Move,' implying a state change, and adds useful conditional behavior such as acceptance being required for size='large' and linked_frs being needed for pull-eligibility. It does not mention reversibility or what happens to the original triage state, but it does disclose the main non-obvious constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: one front-loaded purpose sentence followed by a concise bullet list of parameters. Every line earns its place and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a six-parameter mutation tool with no annotations, the description covers the operation, all arguments, defaults, and conditional requirements, and an output schema exists so return values need not be explained. It is slightly incomplete only in that it does not clarify how the move affects the source triage state or how this tool relates to nearby milestone/triage siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description compensates fully by explaining all six parameters: bug_id with an example, to_milestone as a slug, size valid values and default, acceptance's conditional requirement, priority semantics, and linked_frs' conditional role. This adds significant meaning beyond the bare schema titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence, 'Move a triage item to a target milestone,' uses a specific verb and resource, making the core action clear. It is not explicitly differentiated from siblings like milestone_move_item or milestone_add_item, but the meaning is unambiguous enough for an agent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to prefer triage_promote over conceptually similar siblings such as triage_dismiss, milestone_move_item, or milestone_add_item. The description focuses on how the operation works, not when it should be chosen.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a finding's status, severity, notes, tags, or metadata.
Args:
finding_id: The finding ID (e.g. CB-1)
status: New status: open, in_progress, fixed, not_a_bug, wont_fix, stale. Aliases accepted: done/resolved/implemented/closed → fixed, wontfix → wont_fix, invalid → not_a_bug, active/working/in-progress → in_progress
severity: Re-triage the finding: critical, high, medium, or low. Case-insensitive, but no aliases — unlike status, "crit" and "P0" are refused.
notes: REPLACES the notes wholesale, discarding whatever was there. To add to an existing record without destroying it, use append_note instead. If meta_update also carries a "notes" key, the meta_update value is the one that lands — see meta_update for why that is deliberate.
append_note: Appends a newline-joined line, preserving the prior notes. This is the safe way to add evidence to a long-lived card.
tags: Replace tags list
meta_update: Merge additional metadata keys. The three meta-writing arguments compose over ONE dict, in this order: notes replaces, append_note then extends that replacement, and meta_update merges LAST. So passing both notes= and meta_update={"notes": ...} in a single call is neither an error nor a refusal — meta_update wins the collision, on every key it names. That precedence is deliberate rather than incidental: meta_update names the storage key directly, which makes it the repair path for keys no other argument can reach (similar_to, category_minted, fingerprint_refusals), and a stamp no argument could overwrite would be an unrepairable one.
reported_at_ref: Update version/tag label (e.g. "v2.1.0"). This is the SANCTIONED manual mutation of an observation-frozen column (BT-4): observations never move it, this call does — a release is tagged after filing.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | ||
| notes | No | ||
| status | No | ||
| severity | No | ||
| finding_id | Yes | ||
| append_note | No | ||
| meta_update | No | ||
| reported_at_ref | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries behavioral disclosure. It warns that notes REPLACES wholesale and discards prior content, explains the composition order of the three write arguments, states that meta_update wins collisions deliberately, and flags reported_at_ref as a sanctioned mutation of an observation-frozen column. This is far beyond a typical update description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a clear summary and uses a labeled Args list. It is long, but the complexity of the compose-order and alias rules justifies the length. A few explanatory sentences in meta_update are slightly verbose, but not wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite 0% schema coverage and no annotations, the description covers every parameter, edge cases, collision precedence, destructive behavior, and the special semantics of reported_at_ref. An output schema exists, so return-value details are not needed. The tool is fully callable from this description alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description documents all 8 parameters, including accepted enum values, case sensitivity, aliases, examples, and semantic behavior (replace vs append vs merge). This fully compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence states a specific action and target: 'Update a finding's status, severity, notes, tags, or metadata.' This clearly identifies the resource (findings) and the exact fields, distinguishing it from generic 'update' and from sibling tools targeting requirements or milestones.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit internal routing: notes says to use append_note instead for safe additions, and meta_update is described as the repair path for keys no other argument can reach. It lacks an explicit statement like 'for requirement updates, use reqs_update,' but the finding-focused context makes the intended domain clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Snapshot of agent_capacity. agent_id=None returns all agents.
Args:
agent_id: Filter to one agent (None = all).
| Name | Required | Description | Default |
|---|---|---|---|
| agent_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. 'Snapshot' implies a read-only, point-in-time view, and the description explicitly notes that agent_id=None returns all agents. However, it does not disclose whether the snapshot is cached, how capacity is calculated, or what fields are returned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely compact and front-loaded: the purpose appears in the first sentence, and the parameter explanation is minimal and clear. Every sentence earns its place without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter, read-only status tool with an output schema present, the description is largely complete. It explains the only parameter and the core behavior. It could add a bit more context around what 'agent_capacity' means, but the low complexity keeps the gap minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It does: 'agent_id: Filter to one agent (None = all)' adds the crucial meaning that null is not just a default but selects all agents. This goes beyond the schema's title and default value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool returns a 'Snapshot of agent_capacity', which identifies both the resource (agent capacity) and the operation (status snapshot). It does not explicitly contrast with sibling status tools like milestone_status or codesweep_status, so it falls short of full differentiation, but the resource focus makes it clear among siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It only explains the agent_id filtering behavior, which is parameter-level usage, not tool-level selection guidance. There are no exclusions or alternative tool references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.2.2addanchor_recaptureanchor_resolvebatch_addblockers_addblockers_checkblockers_queryblockers_resolvecategoriescategories_normalizeclaims_claimclaims_held_byclaims_listclaims_releaseclaims_who_holdscodebench_deletecodebench_importcodebench_listcodebench_querycodemerge_abandoncodemerge_checkcodemerge_claimcodemerge_claimscodemerge_finishcodemerge_mergecodemerge_sessionscodemerge_startcodemerge_statuscodesweep_addcodesweep_archivecodesweep_archive_itemscodesweep_createcodesweep_listcodesweep_list_itemscodesweep_markcodesweep_nextcodesweep_statusgetgrouping_citationsgrouping_filinggrouping_tagsmark_branch_onlymark_integratedmilestone_add_itemmilestone_audit_querymilestone_closemilestone_createmilestone_defermilestone_listmilestone_move_itemmilestone_reconcilemilestone_set_statusmilestone_statusmilestone_updatepull_nextqueryrecentrelations_queryrelations_relaterelations_unrelaterelease_itemreqs_addreqs_batch_embedreqs_embedreqs_embedding_statsreqs_getreqs_importreqs_queryreqs_search_similarreqs_statsreqs_summaryreqs_updatereqs_verifysimilarity_checksimilarity_reportstaleness_checkstatssummarytriage_dismisstriage_inboxtriage_promoteupdatewip_statusDomain prefixes (reqs_, milestone_, blockers_, codemerge_, codebench_, codesweep_, grouping_, relations_, anchor_) make most tools' purposes clear at a glance, and overlapping-sounding pairs like codebench_query vs reqs_query are cleanly separated by prefix. A few genuinely confusable pairs remain: milestone_defer and blockers_add are two different mechanisms for deferring an item; mark_integrated and milestone_set_status both record completion; and claims_claim vs codemerge_claim use the same verb for two different claim systems.
The dominant pattern is consistent verb_noun within prefixed domains (milestone_create, milestone_move_item, codesweep_archive_items, relations_unrelate), and the code* family is uniformly codemerge_/codebench_/codesweep_. The main flaw is a two-tier system: core finding tools are unprefixed (add, get, query, update, stats, summary) while every other domain is prefixed, and there are verb/noun collisions such as claims_claim, codemerge_claim (verb) vs codemerge_claims (noun).
83 tools is more than three times the 25+ 'too many' threshold, creating a heavy tool-selection surface for any agent even with good organization. The server bundles nine distinct subdomains (findings, requirements, milestones, blockers, claims, triage, merge sessions, benchmarks, sweeps) that would typically be split across separate servers. Each tool does earn its place within its own subdomain, so the count is excessive rather than chaotic.
Every subdomain has near-complete lifecycle coverage: findings and requirements have create/read/update/analytics plus verification and embedding; milestones, blockers, claims, codemerge, and sweeps all have full workflows including audit and repair paths. The absence of hard delete is a deliberate audit-trail design, with status-based retirement covering removal. The one notable gap is that categories_normalize references export-csv/restore-csv backup tools that are not exposed in the MCP surface.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Give your AI agent a persistent map of your project's structure, dependencies, and bugs.
Project memory for coding agents: requirements, decisions, code graph and delivery telemetry.
Shared memory for coding agents. Stop re-explaining your codebase every session.
Persistent cross-session memory shared by Codex, Claude Code, ChatGPT, and other AI agents.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/faxik/codebugs'
If you have feedback or need assistance with the MCP directory API, please join our Discord server