# Descriptions and Parameter Docs — AI Agents and Tool Use

Source: https://www.geekswithgeeks.com/en/ai-agents-mcp/design-descriptions

> 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.

```text
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."
```

**Quiz:** Which detail most helps the model use a date parameter correctly?

- [x] 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.