angreal-tool-descriptions

AI tool descriptions are written using a YAML frontmatter and a Markdown body to define operational instructions, set risk levels, and guide agent behavior when interacting with project tasks. This ensures consistent and safe usage.

Configuring a tool description requires a YAML frontmatter with name and description fields. Additional metadata fields such as tagline, complexity, category, keywords, dependencies, and components are also required to fully document task guidance.

You set risk levels and usage guidance by creating an angreal.ToolDescription with a suitable risk_level and attaching it to a task using the @angreal.command decorator, governing how the AI agent should interpret and interact with that task.

You need to document task expectations, preconditions, and postconditions when you want to ensure clear expectations and safe usage across AI tools. This provides the AI agent with the necessary context to execute tasks consistently.

No, this tool description format is specifically applicable within Angreal projects to document task guidance, set risk levels, and instruct AI on usage behavior. It requires the specific YAML and Markdown structure to function correctly.

The best way to structure files for AI task discovery is to use a SKILL.md file containing YAML frontmatter and Markdown body, alongside optional assets directories, to provide operational instructions and metadata for AI consumption.