Anatomy of a Great Description

When Claude decides which tool to call, it reads the tool descriptions, not the names. The description is the primary selection mechanism. A clever name with a vague description loses every time.

So a great description is not documentation you write for humans. It is the routing signal the model uses to pick the right action under pressure.

In this lesson we dissect the anatomy of that signal: purpose, return values, input formats, edge cases, and applicability boundaries.

A description that reliably routes work contains five parts:

• Purpose — what the tool does and when to reach for it
• Return values — what comes back, so the model can plan its next step
• Input formats — field shapes, with concrete examples
• Edge cases — empty results, ambiguity, failures
• Applicability boundaries — when NOT to use it

Drop any one of these and selection reliability drops. Overlapping or ambiguous descriptions cause misrouting between similar tools.