# Tool description

The description is the model's only clue about when to use a tool. Vague descriptions lead to wrong tool choices.

AI developers · Part 03: Tool calling · Card 3 of 10 · Last updated 2026-10-13

## Analogy

API docs for an audience that takes every word literally. "Gets stuff" is as useful to the model as it is to your teammates.

## Code example

`descriptions.ts`

```typescript
// Bad: the model can't tell when to use it
description: "Gets PR data",

// Good: says what, when, and what comes back
description:
  "List open pull requests for a repo. Use when the user asks " +
  "about blocked, stale or pending PRs. Returns id, title, author, ageDays.",
```

## In an agent

Bad descriptions are the most common agent bug. Rewriting them is often the fix for "it picked the wrong tool".

## Questions people ask

### How do I write a good tool description?

Say what the tool does, when to use it and what comes back. For example: list open pull requests for a repo; use when the user asks about blocked or stale PRs; returns number, title and age. The model takes every word literally, so vague text like gets PR data leads to wrong choices.

### Why does my agent pick the wrong tool?

Most often the descriptions are vague or overlap, so the model cannot tell the tools apart. Rewrite each description to say exactly when it applies and when it does not. Also check that you are not offering too many tools in one prompt; fewer, clearer tools lead to better choices.

## Related concepts

- [What a tool is](https://studyvisually.com/learn/tech/ai-developers/tool-calling/what-a-tool-is)
- [Function schema](https://studyvisually.com/learn/tech/ai-developers/tool-calling/function-schema)
- [The tool_calls reply](https://studyvisually.com/learn/tech/ai-developers/tool-calling/tool-calls-response)
- [Arguments are a string](https://studyvisually.com/learn/tech/ai-developers/tool-calling/tool-arguments-string)

Web page: https://studyvisually.com/learn/tech/ai-developers/tool-calling/tool-description
Study this card in the app: https://studyvisually.com/app/learn?category=ai-developers&card=tool-description