Loading ToolBench
The shared vocabulary between you and Claude Code, at the engineering level. Plain-YAML architecture diagrams with a live browser canvas, headless SVG render in CI, and an installable Claude skill so the model treats the diagram as the spec.
Archik's 15 tools suffer from critical naming and schema deficiencies. Tool names like 'handleYaml', 'handleSidecar', 'handleAccept' use generic 'handle' verbs that obscure intent, LLMs cannot infer what these tools do from names alone. Descriptions are present but generic (avg ~80 chars, well below the 194-char baseline for A+ tools). Input schemas are minimal: most tools accept only 'method' (string) and optional 'body'/'path' parameters with no enums, ranges, or validation constraints. No output schemas are documented. Error handling is absent, no guidance on retryability, user-fixable vs fatal errors, or recovery paths. Tools conflate HTTP semantics (GET/PUT/DELETE) with business logic, forcing LLMs to reason about HTTP verbs rather than domain intent. No tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite clear read/write distinctions in the risk column.
POST handler to accept a pending suggestion sidecar, applying it over the main architecture file.
GET handler that returns actor artifacts as JSON, mirroring the --json CLI shape.
GET handler that returns alpha (essence) state artifacts as JSON, mirroring the --json CLI shape.
POST handler to accept a pending suggestion sidecar for a sub-architecture file, applying it over the main file.
Generic per-file endpoint for reading/writing sub-architecture files linked via a node's archikFile property. Supports GET/PUT/DELETE with path query parameter.
GET handler that renders a colour-coded SVG diff between the main architecture file and its pending suggestion sidecar.
GET handler that lists every archik file under the project root with a has-suggestion flag, driving the file-switcher dropdown.
Generic 'handle*' verb naming obscures intent. LLMs cannot infer action from names like 'handleYaml' or 'handleSidecar'. Should be 'get_architecture', 'put_architecture', 'get_suggestions', 'accept_suggestion', etc.
Input schemas are minimal and lack constraints. All tools accept only 'method' (string) with no enum validation. LLMs can pass invalid HTTP verbs (e.g., PATCH, OPTIONS) with no guidance. Missing: enums for method, ranges for path, format constraints.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | F | 34 | 2026-07-28+ | v2 |
GET handler that returns available node kinds for the project.
GET handler for sequence diagram files, supporting path query parameter.
GET/PUT/DELETE handler for the suggestion sidecar YAML file. Manages pending Claude-authored architecture suggestions.
GET handler that returns trace matrix data (use case x slice x test x seq x node coverage).
GET handler that returns per-file trace data for the trace canvas page, supporting path query parameter.
GET handler that lists concrete-run traces, mirroring the 'q traces --json' CLI output.
GET handler that returns use case artifacts as JSON, mirroring the --json CLI shape.
GET/PUT handler for the main architecture YAML document. Supports reading the document and writing with validation.
No output schemas documented. LLMs cannot plan downstream calls or extract required fields. Tools return unstructured responses (SVG, JSON, YAML) with no field documentation.
No error handling guidance. Tools expose HTTP semantics (GET/PUT/DELETE) directly to LLMs. No indication of retryability, user-fixable errors, or recovery paths. A PUT failure returns no guidance on why validation failed.
No tool annotations despite clear read/write semantics. Tools marked WRITE (handleYaml, handleSidecar, handleAccept, handleArchikFile, handleArchikAccept) lack destructiveHint. READ_ONLY tools lack readOnlyHint. Agents cannot reason about side effects.