Content
71%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 a strongly actionable, executable reference with a clear detection-first workflow and thorough troubleshooting, held back by heavy repetition of the runtime-separation warning and an unreferenced helper script. Moving the per-method field detail to a reference file and citing the script would materially improve both conciseness and navigation.
Suggestions
State the terminal-vs-execute_code separation once (e.g. in a short 'Runtimes' note) and remove the five other repetitions across Detection Flow, Installation, Method 2, Limitations, Troubleshooting, and Pitfalls (conciseness currently 3).
Reference `scripts/duckduckgo.sh` in the CLI section (e.g. "or run `scripts/duckduckgo.sh <query> [max]` for a wrapped default") so the existing bundle file is discoverable, or remove it if unused (progressive_disclosure currently 3).
Move the four per-method return-field lists and Quick Reference table into a `references/api.md` and keep only one CLI and one Python example inline, tightening the main body (progressive_disclosure and conciseness).
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is mostly lean — commands, code, and tables with little concept explanation — but the terminal-vs-execute_code runtime separation warning is repeated at least six times ("Terminal and `execute_code` are separate runtimes" appears in Detection Flow, Installation, Method 2's intro, Limitations, Troubleshooting, and Pitfalls), which is unnecessary padding. This matches 'Mostly efficient but includes some unnecessary explanation or could be tightened' rather than 4, where over-explanation would be only a minor instance rather than a recurring theme. | 3 / 5 |
Actionability | Every section provides copy-paste-ready material: concrete `ddgs` CLI invocations with flags (`ddgs text -q "..." -m 5 -r us-en -t w -o json`), a flag table, complete executable Python snippets using `with DDGS()`, and a troubleshooting table mapping problems to causes and fixes. Fully executable and covering the common cases (text, news, images, videos, region/time filtering, JSON output) — a clear match for the top anchor. | 5 / 5 |
Workflow Clarity | The Detection Flow sequences the decision explicitly (check `command -v ddgs` → prefer CLI → verify runtime before Python use), installation includes a verification step (`ddgs --help`), the Search-then-Extract workflow is ordered, and the Troubleshooting/Pitfalls sections provide error-recovery feedback (empty results → wait and retry). This matches 'Clear sequence with most checkpoints present; minor validation gaps' — it falls short of 5 because there is no explicit retry/validate loop around the install-then-import path (e.g. verify `from ddgs import DDGS` succeeds before proceeding), only the cautionary prose. | 4 / 5 |
Progressive Disclosure | Sections are well-organized with headers and tables, but the body inlines the full API surface for four search types (~225 lines including per-method field lists and a Quick Reference table) that would fit a separate reference file, and the one bundle file that does exist — `scripts/duckduckgo.sh` — is never referenced anywhere in the body, leaving it undiscoverable. Per the guideline to score against the actual bundle structure, this matches 'Some structure but could be better organized; references present but not clearly signaled' rather than 4, where references would be mostly clearly signaled. | 3 / 5 |
Total | 15 / 20 Passed |