# Assignment randomization engine

- Human page: https://happytails.ai/en/education-tools/assignment-randomization-engine/
- Markdown: https://happytails.ai/en/education-tools/assignment-randomization-engine.md
- Structured JSON: https://happytails.ai/agents/en/education-tools/assignment-randomization-engine/index.json
- Visibility: public

## Tool capabilities

| Property | Value |
| --- | --- |
| Tool ID | `assignment-randomization-engine` |
| Category | education-tools |
| Implementation | Registered implementation. Registration alone is not a production-quality guarantee. |
| Browser execution | Use the visible action or interactive controls. |
| Browser processing | Browser; see tool notes for network behavior. |
| HTTP API | Not callable through HTTP. |
| Browser-agent interface | run_current_tool |

### Implementation notes

Enter a JSON template with parameter ranges and exact answers. Versions are built in the background on this device, and nothing in the template is run as code.

### Inputs and settings

Text input: Question template (JSON).

Example or placeholder shown in the interface (not a validated fixture):

```text
{"title": "Practice", "questions": [{"id": "q1", "text": "Work out {a} x {b}.", "answer": "a*b", "parameters": {"a": {"from": 2, "to": 9}, "b": {"from": 2, "to": 9}}}]}
```

Give each question an id, text, answer and parameter ranges. Constraints and format are optional. Up to 50,000 characters. Review the settings before running.

| Setting | Meaning | Control type | Default | Constraints |
| --- | --- | --- | --- | --- |
| `versions` | Number of versions | number | 5 | min=1 max=50 step=1 |
| `shuffleQuestions` | Shuffle question order in versions 2 and later | checkbox | false |  |
| `seed` | Seed | number | 1 | min=1 max=4294967295 step=1 |

### Browser-agent workflow

1. Open the human page in a browser that supports WebMCP.
2. Discover the interface exposed by that page; use its actual schema.
3. Select files on the page first when the tool requires files.
4. Call `run_current_tool` with valid input and settings.
5. Inspect the returned result or error and the displayed output. Retrieve files from the displayed download links.

Calls do not automatically copy or download results. Browser permissions still apply. Interface availability alone is not proof of successful execution.

### Planning specification

Templates up to 50,000 characters with up to 25 questions, each with an id of up to 40 characters. Each question may have up to 6 parameters with up to 200 values each, up to 10 constraints, up to 10,000 combinations, and the whole template up to 50,000 combinations. Question text up to 500 characters and each expression up to 300 characters. 1 to 50 versions. Everything runs in the background on your device and nothing is uploaded. Downloads: JSON report with manifest, CSV of every version, printable HTML versions and HTML answer keys.

This describes intended requirements. Use the implementation notes, interface schema and observed output to determine current support.

### Complete machine-readable capability record

```json
{
  "id": "assignment-randomization-engine",
  "category": "education-tools",
  "built": true,
  "requirements": "Templates up to 50,000 characters with up to 25 questions, each with an id of up to 40 characters. Each question may have up to 6 parameters with up to 200 values each, up to 10 constraints, up to 10,000 combinations, and the whole template up to 50,000 combinations. Question text up to 500 characters and each expression up to 300 characters. 1 to 50 versions. Everything runs in the background on your device and nothing is uploaded. Downloads: JSON report with manifest, CSV of every version, printable HTML versions and HTML answer keys.",
  "implementation": {
    "fields": [
      {
        "key": "versions",
        "label": "Number of versions",
        "value": 5,
        "type": "number",
        "min": 1,
        "max": 50,
        "step": 1
      },
      {
        "key": "shuffleQuestions",
        "label": "Shuffle question order in versions 2 and later",
        "value": false,
        "type": "checkbox"
      },
      {
        "key": "seed",
        "label": "Seed",
        "value": 1,
        "type": "number",
        "min": 1,
        "max": 4294967295,
        "step": 1
      }
    ],
    "registrationFamily": "assessment-blueprint",
    "inputMaxLength": 50000,
    "inputErrorCode": "ASSESSMENT_BLUEPRINT_TOO_LONG_RANDOMIZER",
    "note": "Enter a JSON template with parameter ranges and exact answers. Versions are built in the background on this device, and nothing in the template is run as code.",
    "experience": {
      "automatic": false,
      "single": false,
      "inputMaxLength": 50000,
      "inputMode": "text",
      "label": "Question template (JSON)",
      "placeholder": "{\"title\": \"Practice\", \"questions\": [{\"id\": \"q1\", \"text\": \"Work out {a} x {b}.\", \"answer\": \"a*b\", \"parameters\": {\"a\": {\"from\": 2, \"to\": 9}, \"b\": {\"from\": 2, \"to\": 9}}}]}",
      "help": "Give each question an id, text, answer and parameter ranges. Constraints and format are optional. Up to 50,000 characters. Review the settings before running.",
      "action": null
    },
    "mode": "explicit",
    "interactive": false
  },
  "execution": "Browser interface",
  "api": null,
  "browser_agent": {
    "supported": true,
    "name": "run_current_tool",
    "discovery": "WebMCP on the human page in a supporting browser",
    "verification": "See audit/API-AUDIT.md; availability is not verification"
  }
}
```

## Page guide

Write each question once as a template with number ranges, and get up to 50 versions where every student sees different numbers but the same kind of question, each with an exact answer key.

How can we improve this tool?

Report a problem or share an idea.

Please leave out private information. Your message and the tool name go to our team via PostHog.

### How to use Assignment randomization engine

1. Write a JSON template with a title and a questions list. Give each question an id, text with {name} placeholders, an answer expression and parameter ranges.
2. Add constraints such as a < b or n % d != 0 to keep only the combinations you want.
3. Choose the number of versions, whether later versions shuffle the question order, and a seed.
4. Generate, then download the printable versions, the answer keys, the CSV and the JSON report with its reproducibility manifest.

## Useful next steps

- [Multiple Choice Answer Sheet Maker](https://happytails.ai/en/education-tools/multiple-choice-answer-sheet-maker/) ([Markdown](https://happytails.ai/en/education-tools/multiple-choice-answer-sheet-maker.md))

- [Quiz from notes](https://happytails.ai/en/education-tools/quiz-from-notes/) ([Markdown](https://happytails.ai/en/education-tools/quiz-from-notes.md))

- [Exit Ticket Maker](https://happytails.ai/en/education-tools/exit-ticket-maker/) ([Markdown](https://happytails.ai/en/education-tools/exit-ticket-maker.md))

## Template rules

Each question id is 1 to 40 letters, digits, hyphens or underscores and starts with a letter or digit, for example q1 or add-fractions. Each parameter is either a range such as {"from": 2, "to": 9, "step": 1} or a list such as {"values": \[5, 10, "1/2"\]}. In the question text, {a} shows a parameter and {=a\*c + b} shows a computed value; use {{ and }} for literal braces. Answers, constraints and computed values may use numbers, parameter names, + - \* / % ^, parentheses and abs, min, max, gcd and lcm. The % operator gives the remainder from 0 up to the divisor. The format key chooses fraction, mixed or decimal output; decimals that do not end within 6 places are shown as fractions.

### Exact and safe

The template is read by a small parser and evaluated with exact fractions. Nothing in it is ever run as code. A combination is skipped when a constraint fails or a value is undefined, for example division by zero, a non-integer exponent, % gcd or lcm of a non-integer, or a result with more than 30 digits in its numerator or denominator. Any whole-number exponent works while the result stays within 30 digits, so 2^20 is fine and 2^100 is skipped. The report counts how many combinations each question has, how many are valid and why the rest were skipped.

### Versions and reproducibility

Every parameterized question gets a different valid combination in every version, drawn without replacement with the same seeded generator used across Happytails.ai worksheets (linear congruential constants from Numerical Recipes, Press et al., 3rd edition 2007, and a Fisher-Yates shuffle as in Knuth, The Art of Computer Programming, volume 2, checked 2026-10-16). The manifest records the seed, the method and a SHA-256 digest of your template (NIST FIPS 180-4, 2015), so the same template and seed always rebuild the same versions.

### What equivalent means here

Versions are equivalent in structure: the same questions, the same answer expressions and values from the same ranges. They are not checked for equal difficulty, so a version with 1/2 + 1/3 may feel easier than one with 1/7 + 1/9. Use constraints to narrow the ranges if that matters.