# Descriptions and Errors That Help the Model — Agent Frameworks and MCP Basics

Source: https://www.geekswithgeeks.com/en/agent-frameworks-mcp/ops-tool-quality

> Write tool descriptions and error messages the model can act on.

## Say when, not just what

A description like "Searches issues" is vague. Better: "Search open issues by keyword. Use when the user asks about known bugs. Returns up to 10 results with id and title." Errors should say how to recover, for example "Unknown project key; call list_projects first".

## Make it dependable

Good descriptions, tests and traces turn a working demo into something you can maintain.

![Three habits: describe, test, observe.](assets/figures/agent-frameworks-mcp/section-7-map.svg) — Figure 7.1 — Describe, test and observe.

## A well-described tool

The docstring states purpose, when to use it and what comes back. The raised error tells the model what to do next.

```python
@mcp.tool()
def search_issues(keyword: str, limit: int = 10) -> list[dict]:
    """Search open issues by keyword.

    Use when the user asks about known bugs. Returns up to `limit`
    results as {id, title}. Call get_issue for full details.
    """
    if not 1 <= limit <= 50:
        raise ValueError("limit must be between 1 and 50")
    return tracker.search(keyword, limit)
```

## Return small results

Huge tool outputs fill the context. Paginate, summarise, or return IDs the model can expand with a second call.

**Quiz:** Which error message best helps the model recover?

- [ ] "Error"
- [ ] A 200-line stack trace
- [x] "Unknown project key; call list_projects first"
- [ ] "Something went wrong"

*Answer:* "Unknown project key; call list_projects first". It names the problem and the next action, which the model can follow.