Content
82%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.
A high-quality, operator-specific body: exact tool names, verified queries with real hit counts, a critical query-grammar section capturing non-obvious API quirks, and a well-routed workflow with mandatory caveats. The main weakness is duplication between the inline worked examples/field tables and references/openfda_fields.md, plus the absence of an explicit query-failure retry step.
Suggestions
Deduplicate the worked examples: keep 2-3 inline as canonical patterns and move the rest to references/openfda_fields.md, which already repeats all five (pacemaker 16619, Medtronic 1896, ketorolac 799, Cosmetics 52214, carprofen 46469) — this would raise both conciseness and progressive_disclosure.
Add an explicit retry checkpoint to the workflow, e.g. 'If a query errors or returns 0 hits, simplify the value to a single token (drop / ( ) +) and re-run' — currently that recovery guidance is only implicit in the Query Grammar section.
Complete the 'DO NOT USE' list in the frontmatter description, which is truncated at 'PRR / ROR /...', so the boundary with the pharmacovigilance skills is fully stated where trigger decisions are made.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | No padding or explanations of concepts Claude already knows, and every section carries non-obvious verified facts (e.g. 'Do NOT use +AND+', 'Dates are strings: device AE/MAUDE use YYYYMMDD'). However, the five worked examples and much of the interpretation-table content are duplicated verbatim in references/openfda_fields.md, so a meaningful block of tokens could be trimmed or delegated. Not 5 because of that duplication; not 3 because nothing reads as unnecessary explanation — it is mostly lean, operator-specific detail. | 4 / 5 |
Actionability | Fully executable, copy-paste-ready tool calls with real outputs: 'OpenFDA_search_device_adverse_events {"search":"device.generic_name:pacemaker AND event_type:Death","limit":1}' → 'total = 16619', plus exact field paths ('animal.species:Dog', 'reaction.veddra_term_name') and concrete interpretation of each result. The examples cover the common cases across all product classes. Not 4: there are no gaps — tool names, arguments, expected outputs, and interpretation are all specified. | 5 / 5 |
Workflow Clarity | The 7-step workflow (classify → pick tool → build query → run → interpret → summarize/cite → route out-of-scope) is clearly sequenced with useful checkpoints (read data.meta.results.total, cite query + total, limitations caveat, stop-and-route step 7). Not 5: there is no explicit validate-and-retry loop for failed/empty queries — the recovery advice (simplify the token, avoid special chars) lives in the grammar section rather than as a workflow checkpoint. Not 3: the sequence is complete with most checkpoints explicit; this is retrieval, not a destructive/batch operation, so the validation cap does not apply. | 4 / 5 |
Progressive Disclosure | Good structure: the body is a navigable overview (tool map, grammar, workflow, examples, limitations) with a clearly signaled, real, one-level-deep reference ('See references/openfda_fields.md for the full per-endpoint field reference and additional query examples' — the file exists and matches). Not 5 because the inline interpretation tables and all five worked examples substantially duplicate the reference file, so the split is not clean; not 3 because the reference is well signaled and the core/most-needed content is appropriately inline. | 4 / 5 |
Total | 17 / 20 Passed |