Content
42%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.
The body contains genuinely useful tone-conversion material (conversion rules, example pairs, jargon dictionary, pitfalls), but it is buried under ~50% generic template boilerplate and documents an API and CLI that do not match the bundled scripts/main.py, so a user following Quick Start or the CLI examples would fail. The reference file is never named and reference-worthy content is inlined.
Suggestions
Delete the generic template sections (Output Requirements, Error Handling, Input Validation, Response Template, Implementation Details, and the duplicate description text in When to Use / Key Features) so only tone-adjuster-specific guidance remains.
Rewrite the code and CLI examples against the actual bundle: import ToneAdjuster from scripts/main.py, document its real API 'adjust(text, target_tone, level)' and CLI 'python scripts/main.py "<text>" <tone>', and remove the '--input/--direction/--assess/--help/demo' invocations and scripts/tone_adjuster.py references that don't exist.
Consolidate the overlapping 'Example run plan', 'Workflow', and 'Audit-Ready Commands' sections into one tone-conversion workflow with a concrete output-validation step (e.g., re-check reading level and jargon count after conversion), and move the jargon dictionary/examples tables into references/guidelines.md, linking it by name.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Roughly half the body is generic template boilerplate that assumes no competence and adds nothing tone-specific: 'Output Requirements', 'Error Handling', 'Input Validation', 'Response Template', plus circular filler like 'See `## Workflow` above for related details' and the frontmatter description pasted verbatim into 'When to Use' and 'Key Features'. Not 1 because the medical sections (conversion rules, examples table, jargon dictionary, pitfalls) carry real, non-generic content. | 2 / 5 |
Actionability | The guidance looks concrete but is not executable against the actual bundle: Quick Start imports 'from scripts.tone_adjuster import ToneAdjuster' (file does not exist; the real module is scripts/main.py), calls nonexistent methods 'convert()', 'to_patient_friendly()', 'assess_reading_level()', 'translate_jargon()', the CLI block uses 'python scripts/tone_adjuster.py --input ... --direction ...' and 'python scripts/main.py --help' / 'demo' which the real argparse-free CLI does not support, and the to_patient_friendly example contains a broken multi-line string literal. This matches the anchor of concrete-looking guidance that is effectively pseudocode relative to the real implementation. | 3 / 5 |
Workflow Clarity | Steps exist ('Example run plan', 'Workflow', 'Quick Check', 'Audit-Ready Commands') with a py_compile checkpoint, but they are generic process boilerplate ('Confirm the user objective... validate the request... return a structured result') duplicated across two overlapping run-plan sections, none specific to tone conversion, and there is no output validation (how to verify medical accuracy or achieved reading level, per its own Quality Checklist). This lands on the anchor of 'steps listed but checkpoints missing or implicit'. | 3 / 5 |
Progressive Disclosure | Section structure exists, but the body never names or links the actual bundle file references/guidelines.md (only 'Reference material available in `references/` for task-specific guidance'), while content that belongs in a reference file — the jargon dictionary JSON, the academic↔patient examples table, best practices — is inlined (~270-line body). This matches 'references present but not clearly signaled; content that should be separate is inline'. | 3 / 5 |
Total | 11 / 20 Passed |