RU
Get in touch
Chapter 19

The Tool Description Is Part of the Prompt

Until now the model has only talked. As soon as it takes up tools, the tool description becomes part of the prompt: the model picks a tool by its name, description, parameters, and the current context. A bad interface can't be rescued by a system instruction.

SQL
name: preview_refund
description: |
  Calculates refund eligibility and amount without changing data.
  Use after obtaining order_id, when the user asks about a refund
  or wants to issue one. Don't use to cancel a delivery.
input:
  order_id: "ID from account_read, never from a guess"
  reason_code: "one of the enum, chosen from the user's message"
output:
  eligible: boolean
  amount: Money | null
  policy_source_id: string
  confirmation_summary: string
side_effects: none
next_step: confirm_refund requires explicit user approval

The difference between a bad and a good tool is almost always the same.

  • list_all_contacts -> search_contacts. Doesn't spend context on irrelevant records.
  • do_order -> orders_preview_refund. A clear namespace and no hidden side effect.
  • A UUID with no label -> an ID plus a human-readable name. Fewer matching errors.
  • Three low-level calls -> one domain tool. Reduces the tool loop and hides the technical mechanics.

And a counterintuitive rule about quantity.

Many tools don't mean more capability. Overlapping and vague tools create new forks where the model can go wrong. Anthropic advises a few well-considered high-impact tools; OpenAI - namespaces and deferred tool search for large surfaces.

Links