angreal-tool-descriptions

# Angreal ToolDescriptions

Write effective ToolDescription prose to guide AI agents using your tasks.

## Why ToolDescriptions Matter

When AI agents discover tasks via `angreal tree --long`, they see:
- Command name and arguments
- **Your ToolDescription**

The ToolDescription is the primary guidance for AI agents deciding whether and how to use your task. Think of it as a mini-prompt that teaches agents when and how to use your tool.

## Basic Usage

```python
import angreal

@angreal.command(
    name="deploy",
    about="Deploy to environment",
    tool=angreal.ToolDescription(
        """
        Deploy the application to a specified environment.

        ## When to use
        - After successful build and tests pass
        - When user explicitly requests deployment

        ## When NOT to use
        - Directly from feature branches
        - Without running tests first

        ## Examples
        ```
        angreal deploy --env staging
        angreal deploy --env production --version v1.2.3
        ```
        """,
        risk_level="destructive"
    )
)
def deploy(env, version=None):
    pass
```

## ToolDescription Constructor

```python
angreal.ToolDescription(
    description,          # Prose description (required)
    risk_level="safe"     # "safe", "read_only", or "destructive"
)
```

## Risk Levels

| Level | Meaning | Use When |
|-------|---------|----------|
| `safe` | No destructive effects | Default. Build, test, lint tasks |
| `read_only` | Only reads/reports | Status checks, info gathering |
| `destructive` | May modify or delete | Deploy, clean, database migrations |

## Structuring Descriptions

Use consistent markdown sections:

```python
tool=angreal.ToolDescription(
    """
    One-line summary of what the tool does.

    ## When to use
    - Scenario 1
    - Scenario 2

    ## When NOT to use
    - Anti-pattern 1
    - Anti-pattern 2

    ## Examples
    Concrete invocation examples with real arguments

    ## Preconditions
    What