Content
75%Weight 40%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
Highly actionable content with executable commands, a complete worked example, and good error-recovery guidance organized in a clear workflow. The main weakness is token efficiency: a large generic-SQL pattern section and low-level caching implementation details add material Claude either already knows or does not need.
Suggestions
Cut or drastically trim the "Analysis Patterns" section to only patterns specific to this tool (e.g., cross-file joins using auto-registered table names); Claude already knows basic SQL, window functions, and pivot idioms.
Condense the "Caching" section to the two or three user-relevant facts (transparent caching, keyed by file name and content, stop analyses before manually clearing) and drop implementation details like SHA256 digests and atomic manifest replacement.
Move extended error-handling rules (duplicate JSON column names, non-finite number rejection) into a short reference file, keeping only one example of each rule inline in the main workflow.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is mostly efficient (commands, parameter tables, naming rules), but the ~60-line "Analysis Patterns" section teaches generic SQL — `SELECT COUNT(*)`, `RANK() OVER (…)`, pivot `CASE WHEN` — that Claude already knows, and the Caching section details implementation internals (SHA256 digests, atomic manifest replacement) beyond what is needed to use the tool. This is more than the 'minor instances of over-explanation' of the level above, so it sits at 'mostly efficient but includes some unnecessary explanation'. | 3 / 5 |
Actionability | Fully executable, copy-paste-ready CLI commands with every flag shown, a parameters table, a complete worked example covering inspect → query → summary → export, and precise error-handling guidance (aliasing duplicate JSON column names, `CASE WHEN isfinite(ratio)` for non-finite values). Common cases are comprehensively covered, matching the top anchor. | 5 / 5 |
Workflow Clarity | A clear Step 1 → Step 2 → Step 3 sequence with `inspect` serving as an explicit schema checkpoint ("Use the SQL names shown by `inspect`"), plus built-in error feedback (failed legacy workbooks reported and skipped, duplicate column names listed in the error). It falls short of the top anchor because there is no explicit result-verification step, but checkpoints and recovery guidance are present, keeping it above the 'validation gaps' level. | 4 / 5 |
Progressive Disclosure | The body is well-sectioned with clear headers, and the single bundle file (`scripts/analyze.py`) is clearly referenced throughout at one level deep with no nested references. It does not reach the top anchor because the generic SQL cookbook and cache internals could be split into reference files, but structure and navigation are solidly above the 'could be better organized' midpoint. | 4 / 5 |
Total | 16 / 20 Passed |