Content
61%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 is well structured and actionable, with executable examples verified against the actual script. The main weaknesses are duplicated constraint/ranking content across sections, a missing validation or retry loop for the batch per-sentence API workflow, and a dead reference to tests/test_finder.py.
Suggestions
Merge the 'Key Features' bullets with the 'Implementation Details' sections — ranking signals, allowed host, timeout, endpoints, and top-N are each stated twice; a single consolidated section would cut roughly a quarter of the body.
Add a validation/recovery step for the batch per-sentence API loop (e.g., retry with backoff on timeout, verify retrieved PMID count vs. requested, skip-and-report on failed sentences) so the workflow includes explicit checkpoints.
Remove the dead 'tests/test_finder.py' reference (the file does not exist), fix the example output placeholder "pmid": "PMID:" to a realistic value, and signal when to read references/evaluation-checklist.md (e.g., 'See the evaluation checklist before accepting results').
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is mostly efficient and assumes Claude's competence, but facts are duplicated across sections: ranking signals, the host allowlist, the 30s timeout, the endpoints, and top-N=3 each appear both in "Key Features" and again in "Implementation Details". This is more than anchor 4's "minor instances" but less than anchor 2's padded explanatory fluff, so anchor 3 fits best. | 3 / 5 |
Actionability | The Python example is executable and matches the actual "find_references" function in scripts/find_refs.py, and the CLI commands are copy-paste ready, matching anchor 4. It is not 5 because the example output contains a placeholder value ("pmid": "PMID:") rather than a realistic record, and options such as max_refs/top-N are mentioned but never demonstrated. | 4 / 5 |
Workflow Clarity | The data flow (sentence splitting → ESearch → EFetch → field extraction → ranking) is clearly sequenced with concrete endpoints, but this is a batch operation (one API request pair per sentence, with rate limiting) and no validation or verification steps or retry guidance exist — only a promise of readable error messages. Per the batch-operation rule, workflow clarity is capped at 3; it is above 2 because the sequence itself is well defined. | 3 / 5 |
Progressive Disclosure | Sections are well organized, the body stays at overview size, and references are one level deep (scripts/find_refs.py and references/evaluation-checklist.md both exist), matching anchor 4. It is not 5 because "tests/test_finder.py" is referenced but does not exist in the bundle, and the evaluation checklist is listed under "Related project files" without signaling when Claude should read it. | 4 / 5 |
Total | 14 / 20 Passed |