Plugin Flip A Coin

flip_a_coin Plugin

flip_a_coin is a reference Rust native plugin for Ash. It simulates a fair coin toss and returns random binary decisions (HEADS or TAILS) or structured JSON statistics.

Capabilities and Arguments

Discovery & Documentation

flip_a_coin --ai-docs

Returns structured JSON:

{
  "Capabilities": [
    "Simulate flipping one or more fair coins.",
    "Return random outcomes (HEADS or TAILS) with count statistics."
  ],
  "Arguments": {
    "--count": "Number of coins to flip (positive integer, default: 1)",
    "--format": "Output format: 'json' (default) or 'text'",
    "--ai-docs": "Print AI documentation and exit",
    "--version": "Print version and exit",
    "--help": "Print help and exit"
  },
  "Return format": {
    "status": "success or error",
    "result": "HEADS or TAILS when count=1",
    "flips": "array of flip outcomes",
    "heads_count": "number of HEADS",
    "tails_count": "number of TAILS"
  },
  "Usage guidance for the AI": "A single call to flip_a_coin performs the coin toss. Do not repeat the call. Directly report the result from the JSON response to the user."
}

CLI Usage Examples

• Single flip (JSON default):

  flip_a_coin
  # Output: {"status":"success","result":"HEADS","flips":["HEADS"],"heads_count":1,"tails_count":0}

• Text format:

  flip_a_coin --format text
  # Output: HEADS

• Version check:

  flip_a_coin --version