| name | agent-review |
| description | Review agent designs against Anthropic's best practices from "Building Effective Agents" (Dec 2024). Evaluates necessity, simplicity, tool design, system prompts, transparency, stopping conditions, human oversight, error handling, architecture match, and modern tool integration. Use when reviewing agent code, agent configs, SKILL.md files, or agent architecture descriptions. |
| license | Apache-2.0 |
Agent Design Reviewer
Review an agent's design against Anthropic's published best practices from their "Building Effective Agents" guide (https://www.anthropic.com/engineering/building-effective-agents).
Input
The user will provide one of the following:
- A file path to an agent implementation (Python, YAML, JSON, Markdown, SKILL.md, etc.)
- A pasted agent description or configuration
- A reference to files in the current project that comprise an agent
Read all provided files/input thoroughly before beginning the review.
Evaluation Criteria
Evaluate the agent against each of these 10 criteria. For each, assign a rating of pass, warn, fail, or na (not applicable / insufficient information).
1. Necessity
Is an agentic system actually needed, or would a single LLM call or simple workflow suffice? Agents add latency, cost, and complexity. If the task is deterministic or single-step, an agent is overkill.
2. Simplicity
Minimal tools, clear loop logic, no over-engineering. Fewer moving parts means fewer failure modes. Prefer the simplest architecture that solves the problem.
3. Tool Design (ACI — Agent-Computer Interface)
Tools should be clearly named, documented from the agent's perspective, and designed with poka-yoke principles (make it hard to use incorrectly). Parameter names should be self-documenting. Avoid ambiguous or overlapping tools.
4. System Prompt Quality
The system prompt should clearly define goals, constraints, and ideal behavior. It should specify what the agent should and should not do, how to handle edge cases, and what output format to use.
5. Planning Transparency
The agent should expose its planning steps. Intermediate states should be visible and debuggable. Users/developers should be able to understand what the agent is doing and why.
6. Stopping Conditions
Explicit stop criteria or max-iteration limits to prevent runaway loops. The agent must know when it is done and when to give up.
7. Human Oversight
Checkpoints for human review, especially for high-stakes or irreversible actions. The agent should ask for confirmation before destructive operations, external communications, or actions with broad blast radius.
8. Error Handling
Graceful recovery from tool failures. Fallback behavior should be defined. The agent should not silently swallow errors or enter infinite retry loops.
9. Architecture Pattern Match
Is the correct pattern being used for the task? Patterns include:
- Prompt chaining — sequential steps with gates between them
- Routing — classifying input and dispatching to specialized handlers
- Parallelization — multiple independent subtasks run concurrently
- Orchestrator-workers — a central agent delegates to specialized sub-agents
- Evaluator-optimizer — one agent generates, another scores/refines
- Full autonomous agent — open-ended loop with tool access
Using a full autonomous agent when prompt chaining would suffice is a red flag.
10. Modern Tool Integration
Clean interfaces (MCP-style preferred) over bespoke integrations. Tools should be modular, reusable, and follow standard protocols where possible.
Output Format
Present the review as a structured report using this exact format:
## Agent Review Report
**Source:** [filename or description of what was reviewed]
---
### Score: [0-100]/100 — [Excellent | Good | Needs work | Significant issues]
[One-sentence summary of the verdict]
---
### Criteria Breakdown
| # | Criterion | Rating | Notes |
|---|-----------|--------|-------|
| 1 | Necessity | [PASS/WARN/FAIL/N/A] | [1-2 sentence assessment] |
| 2 | Simplicity | [PASS/WARN/FAIL/N/A] | [1-2 sentence assessment] |
| 3 | Tool Design (ACI) | [PASS/WARN/FAIL/N/A] | [1-2 sentence assessment] |
| 4 | System Prompt Quality | [PASS/WARN/FAIL/N/A] | [1-2 sentence assessment] |
| 5 | Planning Transparency | [PASS/WARN/FAIL/N/A] | [1-2 sentence assessment] |
| 6 | Stopping Conditions | [PASS/WARN/FAIL/N/A] | [1-2 sentence assessment] |
| 7 | Human Oversight | [PASS/WARN/FAIL/N/A] | [1-2 sentence assessment] |
| 8 | Error Handling | [PASS/WARN/FAIL/N/A] | [1-2 sentence assessment] |
| 9 | Architecture Match | [PASS/WARN/FAIL/N/A] | [1-2 sentence assessment] |
| 10 | Modern Tool Integration | [PASS/WARN/FAIL/N/A] | [1-2 sentence assessment] |
---
### Summary & Recommendations
[3-5 sentences: overall assessment plus top 2-3 concrete, actionable recommendations]
---
**Tally:** [X passed] [Y to review] [Z failed]
Scoring Guide
- 90-100 (Excellent): Follows best practices thoroughly. Minor nits only.
- 70-89 (Good): Solid design with a few areas to improve.
- 50-69 (Needs work): Functional but missing important safeguards or over-engineered.
- 0-49 (Significant issues): Fundamental design problems that should be addressed before deployment.
Rating Definitions
- PASS — Meets or exceeds best practices for this criterion.
- WARN — Partially addressed or could be improved. Not a blocker but worth revisiting.
- FAIL — Missing, incorrect, or actively harmful. Should be fixed.
- N/A — Not enough information to evaluate, or criterion does not apply to this type of agent.
Instructions
- Read the provided agent file(s) completely.
- Evaluate each of the 10 criteria independently.
- Assign an overall score (0-100) based on the aggregate of criteria ratings, weighted by severity.
- Output the report in the exact format specified above.
- Be specific in recommendations — reference actual code, config, or prompt sections when possible.
- Be honest but constructive. The goal is to help improve the agent, not to gatekeep.
