훌륭한 설명의 구조

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.

Start with a crisp statement of purpose: the action plus the trigger condition. Compare a weak description to a strong one.

The weak one ("Order tool") forces the model to guess. The strong one tells the model exactly when this tool is the right call versus a neighbor.

The model plans the next step in the agentic loop from what your tool returns. If the description hides the shape of the result, the model can't chain tools intelligently.

State what comes back and in what form. Mention the fields the model will likely act on next, such as an order_id it must pass to a later tool.

Ambiguous input formats cause silent failures. Spell out the expected shape of each field and give a concrete example value. Examples remove guesswork far better than prose alone.

Show the date format, the ID pattern, the units. The model generalizes from a single clear example.

Tell the model how the tool behaves at the edges, so it can recover instead of stalling. Three edges matter most:

• Empty result — a valid "no matches", which is different from a failure
• Ambiguity — multiple customers match; the model should ask for more identifiers, never guess
• Failure — distinguish an access failure (maybe retry) from a clean empty result

Naming these in the description turns dead ends into next moves.

The fastest way to stop misrouting between two similar tools is to write the boundary into both descriptions. Say explicitly when NOT to use each one and point at its neighbor.

This is essential when descriptions overlap. Without an explicit boundary, the model picks one almost at random and the wrong action fires.

Sharp boundaries also help you scope tools to a role. The optimal load is about 4 to 5 tools per agent; once you pass roughly 18 tools, selection reliability degrades badly.

If a tool's boundary says "this is for billing, not support", that's a signal it belongs to a different agent entirely. Give each subagent the least-privilege set it actually needs.

A description guides behavior, but it is still probabilistic (~90% reliable). It cannot guarantee a policy. When a rule has financial, legal, or safety consequences, enforce it deterministically.

Write the intent in the description AND back it with a hook. A PostToolUse or outgoing-call hook can block a refund over $500 with 100% determinism, no matter how the model reasoned.

Describe to guide; hook to guarantee.

A great description promises useful failures. "Operation failed" blocks recovery; a structured error enables intelligent routing.

Design your tool to return isError:true plus an errorCategory (transient / validation / business / permission), an isRetryable flag, the attempted_query, and any partial_results. Then say so in the description so the model knows it can trust and act on those fields.

Before you ship a tool, run its description through this checklist:

• Purpose — action plus a clear trigger condition?
• Returns — fields the model needs for the next step?
• Inputs — formats with at least one concrete example?
• Edge cases — empty, ambiguous, and failure behavior named?
• Boundaries — explicit "do NOT use for…", pointing to the neighbor tool?

If two tools could plausibly answer the same request, their boundaries are not sharp enough. Rewrite until only one is the obvious choice.

An architect reviews two tools whose descriptions are short and overlap. The agent keeps calling the wrong one. What is the most effective fix?

Tool descriptions are routing signals, and the description — not the name — is what the model selects on.

A great one has five parts: purpose (action + trigger), return values (for the next step), input formats (with examples), edge cases (empty vs. ambiguous vs. failure), and applicability boundaries (when NOT to use it).

Keep agents to ~4–5 scoped tools. Use descriptions to guide, but enforce financial, legal, or safety rules with deterministic hooks. And design tools to return structured errors so failures route intelligently. Write the boundary until only one tool is ever the obvious choice.