[lukemaj]

What: Adds the case study, triggers section and anti-pattern entries for the lesson that MCP tool descriptions are activation contracts and deferred loading hides them.
Why: A Claude Code planner in T3 ran codex exec in the shell instead of spawn_thread because the tool was deferred and its description never named the shell route it replaces (toolboxmd/chromeria#66, fixed in #67).
So what: Luna max review of the exact head, then the user merges.

Closes #4
Refs #7

Changes

• case-studies/2026-09-29-t3-delegation-tool-descriptions.md (new): the failure, its three causes (the planner's own account), the fix at chromeria f8a22e9 with the before and after spawn_thread descriptions, what alwaysLoad does (Claude Code docs plus a new debug log), the n=1 fresh-session result, and seven things the evidence does not prove.
• docs/05-authoring/triggers.md: section "Tool descriptions are activation contracts too" (lead with when to use it; name the rationalized alternative; keep the few decision-point tools always loaded; trigger first under the 2,048-character truncation), with its claim boundary. Intro sentence and Sources updated.
• docs/10-anti-patterns.md: "Shell recipe in memory outranking the host's routing" and "Decision-point tool deferred behind tool search".
• GLOSSARY.md: Deferred tool, Decision-point tool.
• docs.json, README.md, loader SKILL.md routing row ("Before writing or changing an MCP tool description, or choosing which tools load at session start"), public/llms.txt regenerated.
• Candidate lesson 4 (alignment before mechanism) links 07-mechanism-vs-decoration.md "Measure, reword, mechanism last" instead of repeating it.

Evidence notes

• alwaysLoad re-check (posted on Tool descriptions are activation contracts; deferred loading hides them #4, Tool descriptions are activation contracts; deferred loading hides them #4 (comment)): the debug line is Dynamic tool loading: X/Y deferred tools included. One marked tool of two gives 0/1, no mark gives 0/2, and the model saw only the marked tool's schema. So the PR's "0/19 with the mark, 0/20 without" means 19 against 20 deferred, not zero deferred.
• Description lengths recomputed at f8a22e9: spawn_thread 541 characters (chromeria#67's body says 528, from before its review fix), prism_submit 470.
• Fresh-session check stated as recorded on Tool descriptions are activation contracts; deferred loading hides them #4: n=1, session started by the planner, a README second opinion rather than a PR diff, no pre-fix control, Codex/OpenCode/Grok not checked.
• Not changed: the loader's description frontmatter does not name tool descriptions, so the new row is reached only once the Skill loads for another action. Widening an always-listed description is outside this ticket's file-scope entry ("one row") and would need its own trigger check.
• No version bump: the repository has no .version-policy.json or VERSION (adoption is Gate version anchors and CHANGELOG entries in npm test #22).

Proof

• npm ci && npm test under Node 22.23.1 on this head: build-llms, check-docs-links (mint broken-links), llms coverage, no absolute paths, bare paths, provider-neutral docs all pass.
• Rebased onto origin/main 53f1864 (docs: activation and budget pages match measured behavior (#12) #28 merged).

Elon record

• Requirements and who asked: user, 2026-09-29: save the tool-description lesson (Tool descriptions are activation contracts; deferred loading hides them #4) and include it in the cleanup plan (Clean up the repository and apply the routing and benchmark learnings #7); ticket packet on Tool descriptions are activation contracts; deferred loading hides them #4 sets the file scope and acceptance.
• Deleted: doctrine for hosts nobody checked (Codex, OpenCode, Grok stated as unchecked); a hook blocking agent CLIs (user: last resort); widening the loader description.
• Bottleneck: the behavioral evidence is one run; the page states that boundary rather than waiting for more runs.
• Checked myself: read chromeria#66 and PR #67 and the source at f8a22e9 and its parent 26b5c3f; read Claude Code's MCP docs on tool search and alwaysLoad; ran the two-arm _meta debug-log probe on Claude Code 2.1.284; recomputed the description lengths; ran npm test.

🤖 Generated with Claude Code

[lukemaj]

APPROVE

No findings. I reviewed exact head 4feaefb03a484f3e1ca6a02c22b62917ef7cbd95 against Issue #4 and the repository evidence contract. Claims and citations are traceable; description lengths and the 0/19 vs 0/20 interpretation are consistent with the cited evidence; the fresh-session result is bounded by its n=1 caveats; acceptance criteria, scope, links, and llms.txt conventions are satisfied. No em dashes or /Users paths found.