Skip to content

Add tool description standard and restore argument docs on the V2 path - #290

Merged
hffmnnj merged 32 commits into
mainfrom
feat/tool-description-standard
Aug 5, 2026
Merged

hffmnnj merged 32 commits into
mainfrom
feat/tool-description-standard

Conversation

@hffmnnj

@hffmnnj hffmnnj commented Aug 4, 2026

Copy link
Copy Markdown
Owner

Foundation for making MCP tool schemas self-describing enough to be used correctly on first attempt.

Why

Tool descriptions across this package are thin, and several tools select behavior modes from optional arguments without saying so. That combination has produced repeated first-attempt misuse, including one case where an entire generated plan was lost because an optional identifier arrived as an empty string and silently switched a create into a patch.

This change establishes the standard and the enforcement mechanism. Description content itself is updated in follow-up branches.

A real defect found along the way

convertToolArgsToJsonSchema built tool arguments with tool.schema (the Zod instance bundled inside @opencode-ai/plugin) and then converted them with the workspace zod re-export. Those are two different Zod instances, and converting across them emits structurally valid JSON Schema while silently discarding every .describe() string.

The practical effect: no argument documentation reached V2 hosts at all. Confirmed by measurement — the richest tool emitted 2 descriptions before the fix and 20 after, on byte-identical structure.

The fix builds and converts with a single instance. Verified that required handling, additionalProperties, and nested shapes are unchanged, so restored description fields are the only difference.

Changes

  • references/tool-reference.md — new House Tool-Description Standard: named sections with defined order and presence rules, a shared 120-character floor, a 700-character ceiling raised to 1200 for an explicit high-friction allowlist, recursive argument-description rules, and required phrasing that tells callers to omit an argument rather than pass an empty string. Cross-field constraints stay in prose; oneOf/dependentRequired are avoided because real hosts break on them.
  • references/dispatch-patterns.md, agents/goop-orchestrator.md — now point at the standard instead of restating it, so the rules have exactly one home.
  • src/core/tools-v2.ts — same-instance conversion fix, with a comment documenting the trap.
  • src/core/tools-v2.test.ts — description-survival tests running against real registry output rather than fixtures, since a fixture is exactly what let this defect hide. Includes a regression test that fails if the cross-instance call returns.
  • src/tools/index.test.ts — conformance gate enforcing the standard: section presence, length bounds, recursive argument coverage, and detection of phrasing that endorses empty strings. Deliberately malformed fixtures exercise the same predicates as the live checks, proving the gate can actually fail.
  • src/features/prompt-audit/index.test.ts — documentation-size guards repinned to the new actuals, with the reasoning recorded. Assertions stay exact.

Current conformance: 0 of 38

PENDING_CONFORMANCE is seeded with all 38 registered tools, derived by running the checks and recording real failures rather than by estimate. No tool meets the standard today. Listed tools are exempt from content checks but still asserted to exist, so the suite stays green while the gap closes.

Follow-up branches remove their own entries; the list must reach empty before this effort closes. Progress is 38 − len(PENDING_CONFORMANCE). Guard tests reject typos, duplicates, and unregistered names so a stale entry cannot quietly switch the gate off.

Verification

  • Full suite: 2620 passed, 0 failed, across 125 files
  • Typecheck clean
  • Gate confirmed to bite: removing one tool from the exemption list produces three precise violations, then restores green

hffmnnj added 11 commits August 4, 2026 10:40
Establish the single normative definition for how every tool description
and argument description must be composed. Defines six named sections
(Purpose, WHEN TO USE, WHEN NOT TO USE, MODES, RETURNS, CAVEATS) with
exact labels, order, and presence rules. Sets length bounds at 120-700
characters for normal tools and 701-1200 for an explicit high-friction
allowlist stored as a TypeScript constant in the conformance test file.

Covers recursive argument descriptions (including nested object and array
item fields), requires .describe() as the final Zod chain method for V2
metadata survival, prohibits oneOf/anyOf/allOf/dependentRequired in favor
of prose cross-field contracts, and requires explicit omit-don't-empty
phrasing for mode-selecting optional arguments.

Preserves the factual 38-tool baseline with citation to the inventory audit.
States friction-reporting ownership in this one place; all other documents
point here.
…e standard

Replace the self-contained friction-reporting instruction in the
orchestrator definition with a pointer to tool-reference.md §Friction
Reporting, making tool-reference the single authority. Add a companion
pointer in dispatch-patterns.md noting that tool description composition
rules live in tool-reference and are not restated here.
Tool argument schemas are built with tool.schema (the Zod instance bundled
inside @opencode-ai/plugin), but convertToolArgsToJsonSchema was wrapping
them with the workspace zod and calling its toJSONSchema. That cross-instance
conversion silently dropped every .describe() string, so V2 hosts never saw
any argument documentation.

Build and convert with the same instance: tool.schema.object +
tool.schema.toJSONSchema. Structurally identical output (verified on
goop_write_wave: $schema, type, properties, required, additionalProperties
all unchanged); only the description fields are restored.

Adds survival tests on real createTools() output at three depths (top-level
arg, nested object property, array item field) plus a regression test that
builds a controlled schema with tool.schema and fails immediately if the
converter reverts to a cross-instance call.
Mechanizes the house tool-description standard from tool-reference.md so
later description-enrichment work is measured against one fixed gate.

The gate asserts, for every tool returned by createTools():
  - exactly 38 tools are registered
  - descriptions carry the mandatory WHEN TO USE:, WHEN NOT TO USE:,
    and RETURNS: section labels
  - description length is within 120-700 chars, or 120-1200 for tools on
    the HIGH_FRICTION_TOOLS allowlist (declared here as the single source
    of truth named by the reference)
  - every argument field at every nesting depth — including nested object
    properties and array item element fields — carries a host-visible
    .describe() string, walked via the same convertToolArgsToJsonSchema
    path V2 hosts read
  - no optional argument description endorses passing an empty string to
    achieve skip/preserve/clear semantics; corrective phrasing is allowed

The current tree is not yet conformant, so a PENDING_CONFORMANCE list
holds the tools that skip content assertions today. It is seeded
empirically: running every predicate against the tree shows all 38
registered tools fail (none carry the mandatory labels, and most also
lack argument descriptions or fall under the 120-char floor). Each
later description wave removes its own entries; the list must be empty
before the workflow closes. Safety-net tests reject typos, duplicates,
and unregistered names in both lists so a stale entry cannot silently
disable the gate.

Bad-fixture proofs exercise the same predicate functions the live gate
uses: a missing section, an under-120 description, an over-700
description blocked only when not allowlisted, an over-1200 description
blocked even when allowlisted, a nested argument missing a description,
and empty-string-endorsing phrasing. A conformant description and clean
schema prove the predicates accept good input too.
Update three pinned guard values to reflect intentional growth of the
documentation surface that now owns the tool-description standard:

- agents category: 83,373 -> 83,412 bytes (goop-orchestrator.md's
  standalone friction-reporting instruction trimmed to a pointer at
  tool-reference.md; +39 bytes, absolute hits and bold spans unchanged).
- references category: 164,672 -> 170,674 bytes (tool-reference.md gained
  the House Tool-Description Standard section, +5,630; dispatch-patterns.md
  gained a pointer rather than restating the rules, +372).
- total absolute-language hits: 311 -> 318. The +7 delta is the standard's
  mandatory-wording rules themselves, verified against the audit regex:
  +6 in tool-reference.md (six rule-bearing lines, each one must/only) and
  +1 in dispatch-patterns.md (the pointer's "must be composed"). The
  orchestrator friction-pointer swap added zero.

Assertion strength is unchanged: exact-match pinning is preserved. Comment
narration is extended in the established voice to explain each delta. File
counts (15 agents, 19 references) are unchanged; no other file changed
size, confirmed by diffing the documentation trees against the pre-standard
baseline.
…, not a floor

The allowlist row read "701-1200 characters", which on a strict reading
implied an allowlisted tool was required to exceed 700. The conformance
gate treats allowlisting as a raised ceiling: an allowlisted description
may range 120-1200, and the headroom above 700 is optional, not
obligatory. Forcing padding to 701 would defeat the token-budget goal the
standard exists to protect.

Reword the length-bounds table and criteria to state that unambiguously:
the row is now "120-1200", with an explicit note that allowlisting raises
the ceiling from 700 to 1200 and never requires a description to exceed
700, so a concise allowlisted description in 120-700 still passes.

Repin the prompt-audit doc-size guards to the new actuals, verified
against the audit module rather than assumed: references rollup
170674 -> 171170 bytes, and the absolute-language total 318 -> 319 (the
single added "never" in the clarified wording). No gate logic in
src/tools/index.test.ts and no allowlist membership changed.
Rewrite the goop_write_wave description and add a .describe() to every
argument (top-level and nested, including items[] entries and the
verifications[]/traceability[] row fields) so a competent caller succeeds
on the first attempt from the schema alone.

The description now makes the four write modes and their mutual
exclusivity explicit: single-wave, task_updates[], items[], and
traceability-only. It states that wave_number is required for every mode
except traceability-only (including items[], where each item carries its
own wave_number), that per-item verifications/traceability are the only
side-payload form allowed in items[] batch mode, the preserve-vs-overwrite
rule for omitted metadata (including empty strings), the completion
verification gate (done/completed needs a passing or explicit-skip row),
and the all-or-nothing transaction semantics.

Improve the wave_number-required error to tell items[] callers explicitly
to supply a top-level wave_number even when every entry carries its own.

Add rejection-message tests that assert the full corrective content of
each error (not just that it throws), covering the recorded first-attempt
failures: items[] without a top-level wave_number, status alongside
task_updates, top-level verifications/traceability alongside items[], a
completion attempt without verification evidence, and status:"" injection.

Move goop_write_wave out of PENDING_CONFORMANCE and onto the
HIGH_FRICTION_TOOLS allowlist (description is 1187 chars, above the 700
normal ceiling but inside the 1200 high-friction ceiling). Update the
tools-v2 conversion regression guard to the new wave_id description, which
now also documents the inheritance/override rule.
Rewrite the description to the house standard (Purpose, WHEN TO USE,
WHEN NOT TO USE, MODES, RETURNS, CAVEATS) and add a terminal .describe()
to every argument so the action-dependent contract is host-visible.

The tool has 17 actions whose arguments are legal or ignored depending
on which action is selected. The description now enumerates every action
grouped by its required arguments, and each .describe() states per field
whether it is required, optional, or silently ignored for that action.

Key contracts now unambiguous:
- Arguments the selected action does not name are silently ignored, not
  rejected (the highest-value detail for first-try correctness).
- workflowId is read only by set-active-workflow and create-workflow;
  every other action targets the active workflow and ignores it.
- force on transition bypasses the guard and sets manualOverride, which
  suspends automatic progression until clear-manual-override clears it.
- lazy is honored only when autopilot is true; turning autopilot off
  forces lazy off regardless of input.
- currentWave is one-based by convention (1 = first wave, 0 = none) and
  stored verbatim without validation.
- Optional string-enum args (phase, mode, depth) must be omitted, not
  passed as empty strings.

Add contract tests asserting the ignored-argument outcome (silent ignore,
not rejection), the lazy-drop-when-off behavior, verbatim storage of
currentWave, and that missing-required-argument errors name the field and
action so the caller can correct the call without guessing.

Bring goop_state into conformance: remove it from PENDING_CONFORMANCE and
add it to HIGH_FRICTION_TOOLS (the 17-action contract genuinely needs
>700 chars). No runtime behavior changes.
Apply the house tool-description standard to goop_blocker. Its four modes
(open, resolve, list, items[]) each consult a different subset of arguments,
so the description now states which fields belong to which mode, that
status is forced to open/resolved on those actions and only filters list,
and that top-level operation fields alongside items[] are rejected.

Every argument now carries a terminal .describe(), including every nested
items[] field. goop_blocker joins the high-friction allowlist: its mandatory
mode content cannot fit under the 700-char ceiling (1067 chars).

Tests pin that open/resolve ignore a caller-supplied status, that list
honors status as a filter, and that missing required fields surface
actionable errors naming the field. PENDING_CONFORMANCE drops by one.
Apply the house tool-description standard to goop_read_wave,
goop_acceptance_audit, goop_query_decisions, goop_timeline, and
goop_dashboard. Each now states WHEN TO USE / WHEN NOT TO USE / RETURNS /
CAVEATS, and every argument carries a terminal .describe().

Scoping defaults are the easy-to-get-wrong part and are now explicit:
- goop_read_wave is workflow-scoped and reads tracking rows, not documents;
  callers wanting SPEC/BLUEPRINT prose are redirected to goop_read_db.
- goop_query_decisions defaults to cross-workflow when workflow_id is omitted
  (not the active workflow), with rules[] overriding rule and types[]
  overriding type.
- goop_timeline is workflow-scoped (defaults to the active workflow).
- goop_acceptance_audit's wave_ids filters verifications and waves only, not
  blockers; include_all_blockers defaults to open-only.
- goop_dashboard is always cross-workflow: the workflow_id argument is
  declared but ignored at runtime — documented prominently and pinned by a
  test so a future fix is a deliberate change.

All five fit under the 700-char ceiling; none join the allowlist. Tests pin
the cross-workflow default, the wave_ids-does-not-filter-blockers caveat,
the empty-wave_numbers boundary, and the ignored workflow_id contract.
PENDING_CONFORMANCE drops from 35 to 30.
Callers can rely on ADL entries always landing under the active
workflow. The schema declares no workflow selector; supplying
workflow_id has no effect. Switch via goop_state set-active-workflow.
hffmnnj and others added 18 commits August 4, 2026 15:53
Tool-call serialization in some hosts injects empty strings the caller never
authored — into status fields, mode selectors, and nested task_updates[]
entries. An empty string is never a legitimate value for those fields but
arrives as a present value, defeating the caller's intent: a mode conflict
the caller never created, an "invalid status" rejection, or "" stored as a
real value. Wave 2 rewrote goop_write_wave's description to warn against
passing empty strings; the next agent still failed the same way, because the
empty string is injected below the level any description can reach.

Add a single shared boundary (shared/coalesce.ts) that treats an exact "" as
absent (omitted) for fields where empty has no legitimate meaning, applied in
createTools so it runs on BOTH the V1 and V2 registration paths from one
source of truth. Recurses through arrays and nested objects; only exact "" is
affected (null/undefined/0/false/[]/{} and whitespace-only strings pass
through untouched); a non-empty value is never dropped.

Exempt an explicit, audited set of fields where empty is a documented
operation (EMPTY_STRING_LOAD_BEARING_KEYS): new_string/old_string (patch
delete + patch-mode activation on ""), pr_url/pr_branch/title (clear the
stored value). content is deliberately not exempt — an injected content:""
would silently destroy a document; coalescing yields a loud none-mode error.

goop_write_wave gains minimal tolerance for a status coalesced to absent in
task_updates[]/task_update (skip the no-op entry rather than storing
undefined), matching the existing !== undefined guard pattern already used
for optional status fields.

Regression test reproduces the exact Wave 2 verifier failure shape —
{wave_number, status:"", task_updates:[{task_index:0,status:""}],
verifications:[...]} — and asserts it now succeeds and records the
verifications. Exclusion tests prove empty new_string still deletes, empty
old_string still activates patch mode, and empty pr_url/pr_branch/title still
clear.
Add an "Empty-string argument coalescing" subsection under the House Tool-
Description Standard stating the behavior where callers will see it: what the
boundary does, why it exists (descriptions cannot fix host-injected empties),
the recursion contract, and the full exclusion table with the reason each
exempt field's empty value is load-bearing (new_string/old_string delete and
patch activation; pr_url/pr_branch/title clear). Notes that content is
deliberately not exempt.

Repin the prompt-audit byte-count and absolute-language assertions to the new
true values (references 171,170 -> 174,047 bytes; totalAbsoluteHits 319 ->
326, +7 contract invariants in the new section), with deltas documented in
the assertion comments. No assertion weakened or deleted.
…rect

Callers can now pick the right read surface from the description alone:
goop_read_db names the ADL trap (doc_type:adl returns 'No adl document
found' because the ADL is structured events, not a document row) and
redirects to goop_adl; goop_read_section states the separate-stores
boundary so a caller knows a goop_write_db document is not visible here
until a keyed section exists; goop_search_docs states that plural
filters OR within each set (widening, not narrowing) and AND across
types, eliminating the silent-wider-results surprise.
…st-try correct

Callers can now rely on the full mode and rejection contract before any
call. goop_write_db states all three modes (full/patch/batch) and the
four rejected combinations, plus that an empty content coalesces to
absent rather than wiping a document. goop_write_section adds the
write/delete action dimension, the items[]-rejected-for-delete rule, and
the _migrated-legacy-content reservation. goop_append_chronicle states
plainly that cross-store atomicity is unavailable across chronicle/ADL/
memory, that an aux failure after chronicle success leaves the chronicle
in place, and that the caller must retry the failed store separately.

All six document tools leave PENDING_CONFORMANCE; the three multi-mode
write tools enter HIGH_FRICTION_TOOLS because their rejection contracts
cannot fit under 700 without dropping a rule a caller needs to avoid an
error. Documentation and tests only; no runtime behavior changed.
…t-try correct

Bring goop_save_note, goop_search_notes, goop_reference, goop_boot,
goop_checkpoint, and goop_compact into conformance with the House
Tool-Description Standard (references/tool-reference.md): named sections
(WHEN TO USE / WHEN NOT TO USE / RETURNS), length bounds, recursive
argument .describe() on every field including nested items[] element
objects, and no empty-string-endorsing phrasing.

- goop_save_note: create/patch/batch modes with cross-field rejection;
  documents that items[] is now atomic (historically non-atomic). Allowlisted
  at 766 chars by parity with goop_write_db (same multi-mode write shape).
- goop_search_notes: documents the note_id escape hatch (bypasses ranking,
  returns full body) and the full/body_offset/body_limit window interaction.
- goop_reference: documents the exact case-insensitive section-match rule
  and that a miss returns full content rather than failing.
- goop_boot: adds .describe() to all 14 args; states documents load ONLY
  when doc_types is explicitly passed (no default set).
- goop_checkpoint: action/id/context described; save/load require id.
- goop_compact: states orchestrator-only, V1-only, next_step required and
  replayed as the resume action.

Removes all six from PENDING_CONFORMANCE; adds goop_save_note to
HIGH_FRICTION_TOOLS. Documentation and schema only; no runtime behavior
changes.
Bring memory_save, memory_search, and memory_forget to the house
tool-description standard and drop them from PENDING_CONFORMANCE
(17 -> 14).

memory_forget (allowlisted, 1074 chars): the destructive contract is
now unmissable. Documents the two mutually exclusive modes (id deletes
immediately and ignores confirm; query needs confirm:true), states
plainly that the operation is irreversible, and calls out the footgun
that the read-only preview caps at 20 rows while confirmed deletion
searches up to 100. Added to HIGH_FRICTION_TOOLS with justification.

memory_save (691 chars): documents what actually persists. Verifies
the per-type importance defaults (decision 7, note 4, else 5) at the
tool layer, the type=decision field-folding and fact auto-generation,
the id -1 graceful-degradation signal, and the deduplicate:true
reinforce-not-insert contract (importance=max(old,new), created_at
refreshed, content unchanged, no new row).

memory_search (695 chars): documents retrieval semantics honestly.
Filters AND-combine; concepts OR within the list as a substring match;
includeFieldNotes:true changes both membership and ranking via RRF
(k=60) and applies filters to the memory side only.

MH11/MH20 investigation: the 'query plus tag misses results that query
alone finds' observation is the intended AND-combination contract, not
a ranking bug. A record matching the query text but lacking the filter
is excluded by design. Confirmed under real FTS5 and pinned at both
the tool and manager levels. No algorithm change made or warranted.

Tests added:
- memory_forget: id precedence over query+confirm, confirm ignored on
  id path, query preview searches with limit 20, confirm-gates-query.
- memory_save: failed write degrades to id -1 rather than throwing.
- memory_search: limit clamp, empty-query no-results, concept filter
  narrows by design (tool level).
- features/memory (real FTS5): concept filter excludes a query match
  lacking the concept; substring/case-insensitive tag matching; and
  forgetByQuery deletes 30 > the 20-row preview ceiling.
Bring goop_setup, goop_spec, goop_infer_intent, goop_status,
goop_get_global_config, and slashcommand into conformance with the
house tool-description standard (WHEN TO USE / WHEN NOT TO USE /
RETURNS sections, recursive .describe() on every arg, length bounds).

PENDING_CONFORMANCE: 14 → 8.

Action-to-argument legality is now documented precisely for each tool:
- goop_setup: every action mapped to which args it reads vs ignores;
  scope is declared but silently ignored by every action;
  gitignoreGoopspec applies as a cross-action side effect regardless
  of action.
- goop_spec: file is read only by read; phase is ignored by all.
- goop_infer_intent: autoApply vs autoRun documented as separate
  mechanisms with different confidence gates (0.85 hard floor +
  threshold default 0.9 vs 0.75 autoRun floor); below-threshold is
  never an error.
- goop_status: verbose is declared but currently ignored.

Allowlisted (HIGH_FRICTION_TOOLS): goop_setup (1169), goop_spec (841),
goop_infer_intent (1152) — all carry mandatory mode/contract content
that cannot fit under 700.

Contract tests pin the three arguments-that-do-nothing (scope, phase,
verbose) and action-dependent arg legality for goop_setup.
…y correct

Bring ast_grep, difftastic, scip, background_command, background_status,
and background_cancel into conformance with the house tool-description
standard. Removes all six from PENDING_CONFORMANCE (8 -> 2); adds
ast_grep, scip, and difftastic to HIGH_FRICTION_TOOLS with per-tool
justifications.

Each description now carries the mandatory WHEN TO USE / WHEN NOT TO USE
/ RETURNS sections plus MODES/CAVEATS where applicable, and every
argument (including nested array item fields) carries a terminal
.describe(). Key load-bearing content added:

- ast_grep: documents the three modes (search / rewrite dry-run / rewrite
  apply) and the conditional no-op that apply:true without rewrite has no
  effect (-U is only appended inside the rewrite branch).
- scip: documents the action-dependent required field (symbol required for
  definitions/references/implementations, ignored by index) and that each
  action resolves a different binary (scip vs scip-typescript).
- difftastic: documents the alias-pair cross-field contract and the
  missing-binary-vs-no-differences distinction.
- background_command: keeps the verified timeout default (1800s/30min),
  the integer [1,86400] range with reject-not-clamp, and the kill-on-expiry.
- background_status: documents the lazy expiry sweep that marks timed-out
  without killing (eager timer owns the kill).
- background_cancel: documents the process-group SIGTERM->SIGKILL escalation.

No behavior changes; documentation and test-gate edits only.
…ORMANCE

generate_image (allowlisted, 1136 chars): full house-standard rewrite —
Purpose, WHEN TO USE/NOT TO USE, MODES (dryRun vs live), RETURNS, and
CAVEATS covering the png-only transparency constraint (green-screen +
local chromakey), default output path, count-suffix behavior, the
OAuth/credits cost model, and two dead arguments. mask and
outputCompression are declared on the schema but never read by execute()
nor forwarded to buildBody() — documented as 'Declared but not read by
the tool; supplying it has no effect.' Cross-field constraints surfaced
on out, outputFormat, and background so callers see them before the
call, not through a validation rejection.

goop_create_pr (allowlisted, 904 chars): documents the terminology gate
contract — scans title/body/branch, error-severity blocks while
warn-severity proceeds, code spans masked in title/body but never in
branch, reword-not-retry semantics with example rewrites. Dropped the
misleading merge-method sentence; documented honestly that no
merge-method argument is exposed and it is a repo setting on GitHub.

goop_spec (tightened from 841 to 632 chars, removed from allowlist):
the 3-action mode contract (file read only by read; phase ignored by
all) fits under 700 when the per-action file-ignored clauses are
collapsed into one. No contract lost.

PENDING_CONFORMANCE is now empty: all 38 tools face every predicate.
Full suite: 2690 pass, 0 fail.
The memory-save tool previously formatted decision rationale before passing it to the manager, which formatted the same fields again. Delegate content composition solely to the storage manager so persisted decision content and FTS weighting are not duplicated.

Changes:\n- Pass raw decision content from the tool\n- Pin manager composition and tool delegation contracts
Several action-dispatch errors identified a missing field without showing a corrected request. Include the tool context and a valid retry shape so callers can recover without consulting implementation details.

Changes:\n- Teach required state and blocker action payloads\n- Clarify memory deletion and setup reset confirmations
Reconcile secondary doc surfaces with what the code actually does so each
fact has one owner (the emitted schema) rather than stale copies.

AGENTS.md:
- Record the build-vs-source deployment gap in Gotchas: package.json
  points main/exports at src/index.ts, but the build script emits a
  dist/index.js bundle and the host loads that bundle, once per session,
  from an install path outside this worktree. Source edits here do not
  affect the running session; validating a behavior change needs a
  rebuild plus restart, and unit tests are the only in-session evidence.
- Fix the stale tool-factory count (30 -> 38), pinned by the registry
  tests; point at the emitted schema as the argument authority.
- Replace the restated ast_grep/difftastic/scip/generate_image/
  background_* argument and when-to-use lists with pointers to the
  emitted schemas. A restatement is a copy that silently goes stale;
  a prior version of this section fabricated model and inputFidelity
  args that generate_image never declared.

tool-reference.md (the maintained cheat sheet):
- Resolve two goop_write_wave contradictions that claimed
  verifications/traceability were 'not available alongside items batch
  mode'. They are supplied per-item inside each items[] entry;
  top-level side payloads alongside items[] are rejected, not dropped.
- Remove the phantom generate_image model/inputFidelity args and note
  mask/outputCompression are declared but ignored (owned by the schema).

prompt-audit test:
- Repin references.bytes 174_506 -> 174_965 to the true measured value.
  totalAbsoluteHits unchanged at 328 (no must/never/always/critical/
  only language added or removed).
Classify every registered tool for MODES and CAVEATS requirements so newly added tools cannot bypass the conditional section gate. Document the five additional mode-bearing tools and prove missing required conditional sections fail conformance.
Require mode sections for duplicate reinforcement, cross-store memory search, and draft pull-request creation. Document each opt-in path so callers can predict its execution and result.
Fix duplicated decision content and record the deployment gap
hffmnnj added 3 commits August 5, 2026 05:44
Stop discarding calls over values the caller never wrote
Make the highest-friction tool contracts explicit
@hffmnnj
hffmnnj merged commit 8ecc80b into main Aug 5, 2026
0 of 2 checks passed
@hffmnnj
hffmnnj deleted the feat/tool-description-standard branch August 5, 2026 12:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant