# Tool capability cards — schema

audience: AI coding agents authoring or reading a card.

A card is a sibling JSON file next to the tool it describes:
`<tool-path>.card.json` (e.g. `bin/od-worktree.card.json` next to
`bin/od-worktree`). Sibling, not in-file: many Tier-1 tools are scripts an
agent must not edit the body of (`deck-sudo`, `land`, `ft`), and the set
spans bash/node/python — a sibling file is the one shape every tool can
carry without touching its own source. Adding a tool = dropping its card
next to it; nothing else changes.

## Fields

| Field | Type | Required | Meaning |
|---|---|---|---|
| `id` | string | yes | Stable identifier, independent of the executable's path or name (survives a rename). |
| `command` | string | yes | The exact command line an agent runs, with placeholders in `<angle-brackets>`. |
| `summary` | string | yes | One line, what it does. |
| `intent_phrases` | string[] | yes | Natural task phrasings that should surface this card — plural, how an agent would actually describe the need, not category labels. |
| `replaces` | string[] | no | Raw command shapes this wrapper supersedes (regex or literal, human-readable). |
| `preconditions` | string | no | What must be true before running it. |
| `effects` | string | yes | What it does to the system — state changed, files written, processes started. |
| `risk` | `"reversible"` \| `"destructive"` | yes | Reversible = safe to retry/undo. Destructive = data loss or irreversible external effect possible. |
| `example` | string | yes | One runnable example with real-looking arguments. |
| `help_probe` | string | no | The `--help`/equivalent command `deck tools <name>` runs after printing the card. |

## Generation

`modules/workstation/claude/scripts/gen-tool-index.mjs` walks the repo for
`*.card.json` files (excluding `node_modules/`, `.git/`, any `venv/`) and
writes `modules/workstation/claude/tool-index.json`. The drift test
regenerates into a temp file and diffs it against the checked-in index —
edit a card, forget to regenerate, the test fails.