surface: 16 of 59 tools have 0 calls ever — merge & prune plan

[1Croydan1]

Fact

16 of 59 registered tools have 0 calls in the entire observation history (13,105 sessions, 80,523 calls, including 76k dev): between, chains, flag, ideas, link_cloud, outcomes, path, read_chain, rename_initiative, reopen, reweight, surface, tagged, test, trace, unpin. Another ~10 have single-digit counts. A 60-tool surface dilutes choice and burns context on the tool listing; in deferred-tool environments the agent sees names only, and names like surface/ideas/flag mean nothing without a description (we even recorded a call to a nonexistent mcp__kaeru__hobbies — a hallucinated name).

Breakdown by fate (from the audit, verified)

Merge/collapse:

• path → a dry-run mode of chain (path's own description points to chain; chain is idempotent and reports disconnection);
• chains → let read_chain accept a member node and find its chains (absorbs chains);
• reweight → upsert semantics on link (link on an existing edge updates weight; weight is already set at creation — dozens of strong=true in transcripts);
• flag → alias of link edge_type=contradicts (identical semantics per under_review.rs; agents already run the review flow through link by hand);
• between → show edges in drill (the "why are A and B connected" question doesn't arise — drill already shows neighbors);
• ideas/outcomes → sections of overview (called 209 times — the display case already exists; today ideas is empty on the ENTIRE graph, outcomes=4 — these tools literally have nothing to return).

Leave as-is (zero base need, not discoverability): unpin (pin=4), rename_initiative — admin CRUD on explicit request.

Separate issues: test (epistemic cycle), link_cloud (cloud), tagged/surface/trace (read nudges + instructions).

Proposal

Walk the list above: each merge shrinks the surface without losing function. Success metric — the chains cluster read/write ratio (currently 3/25, and all "reads" are maintenance).

[GrumpyChubbyCat]

Partly acted on in 9d1af42, and I want to lay out what I did not do, because checking the plan against the code changed my mind on most of it.

Done: chains + read_chain → why. Your circularity observation is what made this the obvious one: the only advert for read_chain was the output of chains, which nobody called either. With zero calls between them there was no name worth preserving, so instead of one absorbing the other they became a new verb named after the question a chain answers — the docs already say a chain is the state → reasoning → decision story a fresh agent reads to understand WHY. One extra thing: a node in exactly one chain now gets that chain read straight back rather than a one-item menu, since the second call was the friction.

Not done — flag → link edge_type=contradicts. The issue calls these "identical semantics per under_review.rs"; they are not. mark_under_review writes a review episode carrying the reason (role:review, sig:high) and links it; link writes only an edge. Merging them would delete the place the why of a doubt lives — and with it the provenance half of close_review.

Not done — path → a dry-run mode of chain. path performs no writes; chain creates a node. Behind a flag, previewing a route becomes safe only if you remember the flag — and mis-set parameters are exactly the failure mode #50 documents. Trading a verb that cannot corrupt the graph for one that can, to save one name in a list, is a bad deal.

Not a merge — ideas/outcomes → overview sections. overview currently renders provenance, open questions and edge stats; there are no idea/outcome sections to fold into. Worth doing (you are right that both tools return nothing today while overview is called 209 times) but it is new work, not a collapse.

On the premise. Since #48 shipped, 9 of the 16 dead verbs are named in the server instructions for the first time (between, chains→now why, ideas, outcomes, read_chain→why, surface, tagged, test, trace). Your own natural experiment showed unmentioned verbs die at the same rate as truncated ones — so their death was never evidence they were unwanted, only that they were unseen. Pruning now would cut tools that have just been offered for the first time.

Proposal: keep this open as the measurement task — re-run the dead-tool count once the new instructions have been live for a while — and let the specific merges be judged on their own merits, as above.