Command Decorator

A decorator that identifies a function as an Angreal command.

command(name=None, about="", long_about="", tool=None, **attrs) -> None

import angreal

@angreal.command(
    name='test-command',
    about='Run the test suite',
    tool=angreal.ToolDescription("""
Run the complete test suite for the project.

## When to use
- After code changes
- Before committing
- During CI/CD

## When NOT to use
- In production environments
- When tests are known to be broken

## Examples

angreal test-command angreal test-command –verbose

""", risk_level="safe")
)
def command_function():
    pass

# invoked with `angreal test-command`

• name (str, optional): The name to be used to invoke a command. Defaults to the function name.
• about (str, optional): A short description of what the command does. Defaults to “”.
• long_about (str, optional): A longer description of what the command does. Defaults to the docstring on the decorated function.
• tool (ToolDescription, optional): Rich description for MCP/AI agent integration. Includes prose guidance and risk level annotation. See ToolDescription below.

The ToolDescription class provides rich metadata for AI agent integration via MCP:

angreal.ToolDescription(description, risk_level="safe")

Parameters:

• description (str): Prose description with markdown formatting. Include “When to use”, “When NOT to use”, and “Examples” sections.
• risk_level (str): One of “safe”, “read_only”, or “destructive”. Maps to MCP tool annotations.

Risk Levels: