update-tools-coverage

---
name: update-tools-coverage
description: Refresh dev-docs/tools-coverage.md against the upstream Claude Code tools reference and the Codex app-server item schema. Use when checkpointing tool-renderer/provider coverage, after adding/removing a renderer or Codex adapter, or when either upstream taxonomy may have changed.
---

# Update Tool Coverage

Keeps [`dev-docs/tools-coverage.md`](../../../dev-docs/tools-coverage.md) in
sync with the upstream contracts and our implementation:

1. **Upstream** — the documented tool list at
   <https://code.claude.com/docs/en/tools-reference>.
2. **Us** — `TOOL_INPUT_MODELS` / `TOOL_OUTPUT_PARSERS` in
   [`claude_code_log/factories/tool_factory.py`](../../../claude_code_log/factories/tool_factory.py).
3. **Codex** — the installed version's generated app-server `ThreadItem`
   schema, plus the rollout adapters in `providers/codex.py`,
   `providers/codex_tools.py`, and `providers/codex_javascript.py`.

The doc grades each documented tool **Full** (typed input + typed output),
**Input only** (typed input, generic output), or **Generic** (no registry
entry → params-table + raw-`<pre>` fallback), and separately lists tools we
support that upstream no longer documents (renames like `Task`→`Agent`,
supersessions like `MultiEdit`, legacy aliases, undocumented features).

## Claude Code procedure

1. **Fetch the upstream tool names.** WebFetch the reference and ask only
   for the tool-table names (the page is ~80 KB; a targeted prompt keeps it
   manageable):

   > WebFetch `https://code.claude.com/docs/en/tools-reference` —
   > "List the exact tool names in the main tools table, one per line.
   > Names only, no descriptions."

   Note any tool the page marks deprecated/renamed — that's a candidate for
   the second table.

2. **Compute the truth mechanically.** Feed those names to the bundled
   helper (run from the repo root; `uv run` is required so `pydantic`
   resolves — bare `python3` fails with `ModuleNotFoundError: pydantic`):

   ```bash
   printf 'Agent Artifact AskUserQuestion ... Write' \
     | uv run python .claude/skills/update-tools-coverage/check_coverage.py
   ```

   It prints each tool's support level, the totals, the "we register but
   upstream doesn't document" set, and — if the doc exists — a **drift
   report** (missing / mismatched / stale rows). If it says `in sync [OK]` and
   the upstream name set is unchanged, there is nothing to do.

3. **Reconcile the doc.** Apply the helper's output to
   `dev-docs/tools-coverage.md`:
   - Move rows between the two tables as tools enter/leave the upstream list —
     **never delete** a row for a tool we still register. A tool leaving the
     reference moves to the "no longer documented" table (it's history a
     transcript viewer must still render); it does not lose support.
   - Fix any support-level the drift report flags.
   - Update the **totals line** and the **snapshot date** in the intro
     (`snapshot YYYY-MM-DD`).
   - The **Notes column is hand-maintained** — carry notes forward; only the
     support level is machine-derived.

4. **Re-run the helper** to confirm `in sync [OK]`.

## Codex procedure

Codex function/MCP/plugin names are open-ended, so do not try to create a
closed upstream function-name list. Check two separate tables instead:

1. Generate the public semantic item schema for the installed Codex version:

   ```bash
   codex --version
   codex app-server generate-json-schema --out /tmp/codex-app-server-schema
   ```

2. Read `definitions.ThreadItem.oneOf` in
   `/tmp/codex-app-server-schema/codex_app_server_protocol.v2.schemas.json`.
   Reconcile added/removed variants with "Codex provider coverage / Public
   item families" and update its version, date, and totals.
   Run the local drift checker after editing:

   ```bash
   uv run python .claude/skills/update-tools-coverage/check_codex_coverage.py \
     /tmp/codex-app-server-schema/codex_app_server_protocol.v2.schemas.json
   ```

3. Reconcile concrete call mappings with `_canonicalize()` in
   `providers/codex_tools.py`, result/batch reconstruction in
   `providers/codex.py`, and the `test/test_codex_*` contracts.
4. Reconcile the static-JavaScript list with the whitelisted transfer
   functions in `providers/codex_javascript.py`. Never describe legacy-regex
   support as production fallback: it is retained only as an explicit test
   comparison baseline.

The generated schema is version-specific and the rollout format is not a
public wire contract. State both facts in the documentation snapshot.

## Guardrails

- **Generic is a feature, not a gap.** Unknown / `mcp__*` / plugin tools
  *should* fall back to generic rendering. Only type a tool when it's common
  or carries structure worth surfacing — see
  [`implementing-a-tool-renderer.md`](../../../dev-docs/implementing-a-tool-renderer.md)
  (or the `tool-renderer` skill) to actually add one.
- **Undocumented ≠ obsolete.** The reference table isn't a full census of
  what lands in a JSONL file (e.g. `TeamCreate`/`TeamDelete` are typed both
  sides but never appeared upstream). Keep those under "no longer /never
  documented" with a note, not removed.
- **Dead models.** `GlobOutput` / `GrepOutput` exist in `models.py` but no
  parser constructs them, so `Glob`/`Grep` are **Input only**. If a future
  change wires up a parser, they graduate to Full automatically — the helper
  will show the flip.