Lesson 10 / 25

Descriptions and Parameter Docs

Write descriptions that say what the tool does, when to use it and what it returns.

The model reads it like a manual

The description is the model's only knowledge of your tool. A strong one states the purpose, when to use it (and when not), the format of important inputs with an example, and what comes back. Mention limits such as "returns at most 20 results" and side effects such as "sends an email".

Weak vs strong

The strong version removes guesswork about format, scope and side effects.

Weak:
  "Searches orders."

Strong:
  "Search the customer's orders by status or date range. Use for questions
   about past or current orders. Dates are ISO format, e.g. 2026-09-30.
   Returns up to 20 orders as {id, status, total}. Read-only."

Quick check: Which detail most helps the model use a date parameter correctly?

  • The expected format with an example
  • The author's name
  • The Git commit hash
  • The server's IP address
Answer

The expected format with an example — An explicit format plus example removes the guesswork that causes invalid arguments.