diff --git a/README.md b/README.md
index 7a1cd35..5a11705 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,44 @@
-# tiled-plugins
+# Plugins for Tiled
+
+Two custom tool plugins for [Tiled Map Editor](https://www.mapeditor.org/).
+
+> **Disclaimer:** These plugins are provided as-is. I take no responsibility for what they do, how they work, any data loss, or any other consequences of using them. Use at your own risk.
+
+---
+
+## Installation
+
+Copy the `.js` files into your Tiled plugins directory:
+
+- **Linux/macOS:** `~/.config/tiled/plugins/`
+- **Windows:** `%APPDATA%\Tiled\plugins\`
+
+Restart Tiled. The tools will appear in the toolbar.
+
+---
+
+## random-tile-placer.js
+
+Paints a randomly selected tile from your current tileset selection onto a tile layer with each click.
+
+**Usage:**
+
+1. Select a tile layer in the Layers panel.
+2. In the Tilesets panel, select one or more tiles (hold Ctrl or Shift to select multiple).
+3. Activate the **Random Tile Placer** tool from the toolbar.
+4. Click on the map to place a random tile from your selection at that position.
+
+---
+
+## random-object-placer.js
+
+Places a randomly selected tile as a map object onto an object layer with each click. Has a 50% chance to flip the object horizontally, useful for adding natural variation to decorations.
+
+**Shortcut:** `R`
+
+**Usage:**
+
+1. Select an object layer in the Layers panel.
+2. In the Tilesets panel, select one or more tiles (hold Ctrl or Shift to select multiple).
+3. Activate the **Random Object Placer** tool from the toolbar (or press `R`).
+4. Click on the map to place a randomly chosen tile object, centered on your cursor. It will be randomly flipped horizontally about half the time.
diff --git a/random-object-placer.js b/random-object-placer.js
new file mode 100644
index 0000000..ea6ce40
--- /dev/null
+++ b/random-object-placer.js
@@ -0,0 +1,39 @@
+tiled.registerTool("RandomObjectPlacer", {
+  name: "Random Object Placer",
+  shortcut: "R",
+
+  mousePressed: function (button, x, y, modifiers) {
+    if (button !== 1) return;
+
+    var map = tiled.activeAsset;
+    if (!map || !map.isTileMap) return;
+
+    var layer = map.currentLayer;
+    if (!layer || !layer.isObjectLayer) {
+      tiled.warn("Select an object layer first.");
+      return;
+    }
+
+    var selectedTiles = tiled.mapEditor.tilesetsView.selectedTiles;
+    if (!selectedTiles || selectedTiles.length === 0) {
+      tiled.warn("Select some tiles in the Tilesets panel first.");
+      return;
+    }
+
+    var tile = selectedTiles[Math.floor(Math.random() * selectedTiles.length)];
+
+    var obj = new MapObject();
+    obj.tile = tile;
+    obj.x = x - tile.width / 2;
+    obj.y = y + tile.height / 2;
+    obj.width = tile.width;
+    obj.height = tile.height;
+
+    // Randomly flip horizontally
+    if (Math.random() < 0.5) {
+      obj.tileFlippedHorizontally = true;
+    }
+
+    layer.addObject(obj);
+  },
+});
diff --git a/random-tile-placer.js b/random-tile-placer.js
new file mode 100644
index 0000000..9b08ab7
--- /dev/null
+++ b/random-tile-placer.js
@@ -0,0 +1,31 @@
+tiled.registerTool("RandomTilePlacer", {
+  name: "Random Tile Placer",
+
+  mousePressed: function (button, x, y, modifiers) {
+    if (button !== 1) return;
+
+    var map = tiled.activeAsset;
+    if (!map || !map.isTileMap) return;
+
+    var layer = map.currentLayer;
+    if (!layer || !layer.isTileLayer) {
+      tiled.warn("Select a tile layer first.");
+      return;
+    }
+
+    var selectedTiles = tiled.mapEditor.tilesetsView.selectedTiles;
+    if (!selectedTiles || selectedTiles.length === 0) {
+      tiled.warn("Select some tiles in the Tilesets panel first.");
+      return;
+    }
+
+    var tile = selectedTiles[Math.floor(Math.random() * selectedTiles.length)];
+
+    var tileX = Math.floor(x / map.tileWidth);
+    var tileY = Math.floor(y / map.tileHeight);
+
+    var edit = layer.edit();
+    edit.setTile(tileX, tileY, tile);
+    edit.apply();
+  },
+});