CLAUDE CODE AGENTS: FUNDAMENTALS - Chapter 2, Exercise 2
Rewriting a Vague Agent Description
====================================================================================

QUESTION:
An agent's description field reads simply "helps with code." Explain why
this is a poorly written description, and rewrite it to be genuinely
useful, following this chapter's own tip box.

SOLUTION / EXPLANATION:

This chapter's tip box is explicit that a description needs to communicate
both WHAT an agent does and WHEN it should be used - "helps with code"
fails on both counts. It's so broad it could describe almost any coding
agent imaginable, giving no useful signal for distinguishing this agent
from any other, and it says nothing at all about which situation calls for
it versus a different available agent. Whoever - or whatever routing logic
- is trying to decide whether this agent fits a given task has no real
information to work with.

A genuinely useful rewrite needs to specify the actual task this agent
handles and the situation in which it should be reached for, following the
chapter's own example pattern ("use this agent after implementation is
finished and before merging, to check for bugs and style issues - not for
architecture decisions"). Applied to a generic "helps with code" agent, a
concrete rewrite might read:

"Use this agent when a function or module needs its logic refactored for
readability after the tests are already passing. Do not use it for adding
new features or fixing failing tests - use a dedicated coding or testing
agent for those instead."

This version names the specific task (refactoring for readability), the
specific trigger condition (after tests are already passing), and
explicitly rules out situations where a different agent would be more
appropriate - giving exactly the "what AND when" information the chapter
says a description needs to provide.

--------------------------------------------------------------------------
WHY THIS WORKS AS AN ANSWER:
It identifies specifically which two things "helps with code" fails to
communicate (what, and when), and produces a rewrite that supplies both,
including an explicit negative case (when NOT to use it) matching the
chapter's own example pattern rather than just restating the task more
verbosely.