diff --git a/packages/warriorjs-abilities/src/attack.js b/packages/warriorjs-abilities/src/attack.js
index 7aba3e5a..b8837fab 100644
--- a/packages/warriorjs-abilities/src/attack.js
+++ b/packages/warriorjs-abilities/src/attack.js
@@ -3,15 +3,17 @@ import { BACKWARD, FORWARD } from '@warriorjs/geography';
 const defaultDirection = FORWARD;
 
 function attack({ power }) {
+  const backwardPower = Math.ceil(power / 2.0);
   return unit => ({
     action: true,
-    description: `Attacks a unit in the given direction (\`'${defaultDirection}'\` by default), dealing ${power} HP of damage.`,
+    argumentsDescription: `direction = '${defaultDirection}'`,
+    description: `Attacks a unit in the given direction (${defaultDirection} by default), dealing ${power} HP of damage in any direction except backward (reduced to ${backwardPower} if attacking backward).`,
     perform(direction = defaultDirection) {
       const receiver = unit.getSpaceAt(direction).getUnit();
       if (receiver) {
         unit.log(`attacks ${direction} and hits ${receiver}`);
         const attackingBackward = direction === BACKWARD;
-        const amount = attackingBackward ? Math.ceil(power / 2.0) : power;
+        const amount = attackingBackward ? backwardPower : power;
         unit.damage(receiver, amount);
       } else {
         unit.log(`attacks ${direction} and hits nothing`);
diff --git a/packages/warriorjs-abilities/src/attack.test.js b/packages/warriorjs-abilities/src/attack.test.js
index 8693fb23..a3c7b7f7 100644
--- a/packages/warriorjs-abilities/src/attack.test.js
+++ b/packages/warriorjs-abilities/src/attack.test.js
@@ -20,7 +20,7 @@ describe('attack', () => {
 
   test('has a description', () => {
     expect(attack.description).toBe(
-      `Attacks a unit in the given direction (\`'${FORWARD}'\` by default), dealing 3 HP of damage.`,
+      `Attacks a unit in the given direction (${FORWARD} by default), dealing 3 HP of damage in any direction except backward (reduced to 2 if attacking backward).`,
     );
   });
 
diff --git a/packages/warriorjs-abilities/src/bind.js b/packages/warriorjs-abilities/src/bind.js
index 4a3a25bb..7b4152bb 100644
--- a/packages/warriorjs-abilities/src/bind.js
+++ b/packages/warriorjs-abilities/src/bind.js
@@ -5,7 +5,8 @@ const defaultDirection = FORWARD;
 function bind() {
   return unit => ({
     action: true,
-    description: `Binds a unit in the given direction (\`'${defaultDirection}'\` by default) to keep him from moving.`,
+    argumentsDescription: `direction = '${defaultDirection}'`,
+    description: `Binds a unit in the given direction (${defaultDirection} by default) to keep him from moving.`,
     perform(direction = defaultDirection) {
       const receiver = unit.getSpaceAt(direction).getUnit();
       if (receiver) {
diff --git a/packages/warriorjs-abilities/src/bind.test.js b/packages/warriorjs-abilities/src/bind.test.js
index 7b58a547..34eb4b56 100644
--- a/packages/warriorjs-abilities/src/bind.test.js
+++ b/packages/warriorjs-abilities/src/bind.test.js
@@ -17,7 +17,7 @@ describe('bind', () => {
 
   test('has a description', () => {
     expect(bind.description).toBe(
-      `Binds a unit in the given direction (\`'${FORWARD}'\` by default) to keep him from moving.`,
+      `Binds a unit in the given direction (${FORWARD} by default) to keep him from moving.`,
     );
   });
 
diff --git a/packages/warriorjs-abilities/src/detonate.js b/packages/warriorjs-abilities/src/detonate.js
index 56d4b989..2929edc3 100644
--- a/packages/warriorjs-abilities/src/detonate.js
+++ b/packages/warriorjs-abilities/src/detonate.js
@@ -6,7 +6,8 @@ const surroundingOffsets = [[1, 1], [1, -1], [2, 0], [0, 0]];
 function detonate({ targetPower, surroundingPower }) {
   return unit => ({
     action: true,
-    description: `Detonates a bomb in a given direction (\`'${defaultDirection}'\` by default), dealing ${targetPower} HP of damage to that space and ${surroundingPower} HP of damage to surrounding 4 spaces (including yourself).`,
+    argumentsDescription: `direction = '${defaultDirection}'`,
+    description: `Detonates a bomb in a given direction (${defaultDirection} by default), dealing ${targetPower} HP of damage to that space and ${surroundingPower} HP of damage to surrounding 4 spaces (including yourself).`,
     perform(direction = defaultDirection) {
       unit.log(`detonates a bomb ${direction} launching a deadly explosion`);
       const targetSpace = unit.getSpaceAt(direction);
diff --git a/packages/warriorjs-abilities/src/detonate.test.js b/packages/warriorjs-abilities/src/detonate.test.js
index 4b157051..4dabf497 100644
--- a/packages/warriorjs-abilities/src/detonate.test.js
+++ b/packages/warriorjs-abilities/src/detonate.test.js
@@ -21,7 +21,7 @@ describe('detonate', () => {
 
   test('has a description', () => {
     expect(detonate.description).toBe(
-      `Detonates a bomb in a given direction (\`'${FORWARD}'\` by default), dealing 4 HP of damage to that space and 2 HP of damage to surrounding 4 spaces (including yourself).`,
+      `Detonates a bomb in a given direction (${FORWARD} by default), dealing 4 HP of damage to that space and 2 HP of damage to surrounding 4 spaces (including yourself).`,
     );
   });
 
diff --git a/packages/warriorjs-abilities/src/directionOf.js b/packages/warriorjs-abilities/src/directionOf.js
index 72cd9e76..0dff5ba7 100644
--- a/packages/warriorjs-abilities/src/directionOf.js
+++ b/packages/warriorjs-abilities/src/directionOf.js
@@ -2,7 +2,7 @@ import { BACKWARD, FORWARD, LEFT, RIGHT } from '@warriorjs/geography';
 
 function directionOf() {
   return unit => ({
-    description: `Returns the direction (${FORWARD}, ${RIGHT}, ${BACKWARD} or ${LEFT}) to the given space.`,
+    description: `Returns the direction (\`'${FORWARD}'\`, \`'${RIGHT}'\`, \`'${BACKWARD}'\` or \`'${LEFT}'\`) to the given space.`,
     perform(space) {
       return unit.getDirectionOf(space);
     },
diff --git a/packages/warriorjs-abilities/src/directionOf.test.js b/packages/warriorjs-abilities/src/directionOf.test.js
index 4bf32a60..7a9ebe96 100644
--- a/packages/warriorjs-abilities/src/directionOf.test.js
+++ b/packages/warriorjs-abilities/src/directionOf.test.js
@@ -17,7 +17,7 @@ describe('directionOf', () => {
 
   test('has a description', () => {
     expect(directionOf.description).toBe(
-      `Returns the direction (${FORWARD}, ${RIGHT}, ${BACKWARD} or ${LEFT}) to the given space.`,
+      `Returns the direction (\`'${FORWARD}'\`, \`'${RIGHT}'\`, \`'${BACKWARD}'\` or \`'${LEFT}'\`) to the given space.`,
     );
   });
 
diff --git a/packages/warriorjs-abilities/src/directionOfStairs.js b/packages/warriorjs-abilities/src/directionOfStairs.js
index 15d0e10c..a618dd59 100644
--- a/packages/warriorjs-abilities/src/directionOfStairs.js
+++ b/packages/warriorjs-abilities/src/directionOfStairs.js
@@ -2,7 +2,7 @@ import { BACKWARD, FORWARD, LEFT, RIGHT } from '@warriorjs/geography';
 
 function directionOfStairs() {
   return unit => ({
-    description: `Returns the direction (${FORWARD}, ${RIGHT}, ${BACKWARD} or ${LEFT}) the stairs are from your location.`,
+    description: `Returns the direction (\`'${FORWARD}'\`, \`'${RIGHT}'\`, \`'${BACKWARD}'\` or \`'${LEFT}'\`) the stairs are from your location.`,
     perform() {
       return unit.getDirectionOfStairs();
     },
diff --git a/packages/warriorjs-abilities/src/directionOfStairs.test.js b/packages/warriorjs-abilities/src/directionOfStairs.test.js
index bd39b112..06e4494f 100644
--- a/packages/warriorjs-abilities/src/directionOfStairs.test.js
+++ b/packages/warriorjs-abilities/src/directionOfStairs.test.js
@@ -17,7 +17,7 @@ describe('directionOfStairs', () => {
 
   test('has a description', () => {
     expect(directionOfStairs.description).toBe(
-      `Returns the direction (${FORWARD}, ${RIGHT}, ${BACKWARD} or ${LEFT}) the stairs are from your location.`,
+      `Returns the direction (\`'${FORWARD}'\`, \`'${RIGHT}'\`, \`'${BACKWARD}'\` or \`'${LEFT}'\`) the stairs are from your location.`,
     );
   });
 
diff --git a/packages/warriorjs-abilities/src/feel.js b/packages/warriorjs-abilities/src/feel.js
index 581c3fd8..bab413b1 100644
--- a/packages/warriorjs-abilities/src/feel.js
+++ b/packages/warriorjs-abilities/src/feel.js
@@ -4,7 +4,8 @@ const defaultDirection = FORWARD;
 
 function feel() {
   return unit => ({
-    description: `Returns the adjacent space in the given direction (\`'${defaultDirection}'\` by default).`,
+    argumentsDescription: `direction = '${defaultDirection}'`,
+    description: `Returns a \`Space\` object for the adjacent space in the given direction (${defaultDirection} by default).`,
     perform(direction = defaultDirection) {
       return unit.getSensedSpaceAt(direction);
     },
diff --git a/packages/warriorjs-abilities/src/feel.test.js b/packages/warriorjs-abilities/src/feel.test.js
index 58fa6323..e358abc4 100644
--- a/packages/warriorjs-abilities/src/feel.test.js
+++ b/packages/warriorjs-abilities/src/feel.test.js
@@ -17,7 +17,7 @@ describe('feel', () => {
 
   test('has a description', () => {
     expect(feel.description).toBe(
-      `Returns the adjacent space in the given direction (\`'${FORWARD}'\` by default).`,
+      `Returns a \`Space\` object for the adjacent space in the given direction (${FORWARD} by default).`,
     );
   });
 
diff --git a/packages/warriorjs-abilities/src/listen.js b/packages/warriorjs-abilities/src/listen.js
index ac886f53..dce668e4 100644
--- a/packages/warriorjs-abilities/src/listen.js
+++ b/packages/warriorjs-abilities/src/listen.js
@@ -3,7 +3,7 @@ import { FORWARD, getRelativeOffset } from '@warriorjs/geography';
 function listen() {
   return unit => ({
     description:
-      'Returns an array of all spaces which have units in them (excluding yourself).',
+      'Returns an array of all `Space`s which have units in them (excluding yourself).',
     perform() {
       return unit
         .getOtherUnits()
diff --git a/packages/warriorjs-abilities/src/listen.test.js b/packages/warriorjs-abilities/src/listen.test.js
index f410f2a4..caa6d917 100644
--- a/packages/warriorjs-abilities/src/listen.test.js
+++ b/packages/warriorjs-abilities/src/listen.test.js
@@ -27,7 +27,7 @@ describe('listen', () => {
 
   test('has a description', () => {
     expect(listen.description).toBe(
-      'Returns an array of all spaces which have units in them (excluding yourself).',
+      'Returns an array of all `Space`s which have units in them (excluding yourself).',
     );
   });
 
diff --git a/packages/warriorjs-abilities/src/look.js b/packages/warriorjs-abilities/src/look.js
index 57b44fa3..ddd04485 100644
--- a/packages/warriorjs-abilities/src/look.js
+++ b/packages/warriorjs-abilities/src/look.js
@@ -4,7 +4,8 @@ const defaultDirection = FORWARD;
 
 function look({ range }) {
   return unit => ({
-    description: `Returns an array of up to ${range} spaces in the given direction (\`'${defaultDirection}'\` by default).`,
+    argumentsDescription: `direction = '${defaultDirection}'`,
+    description: `Returns an array of up to ${range} \`Space\`s in the given direction (${defaultDirection} by default).`,
     perform(direction = defaultDirection) {
       const offsets = Array.from(new Array(range), (_, index) => index + 1);
       const spaces = offsets.map(offset =>
diff --git a/packages/warriorjs-abilities/src/look.test.js b/packages/warriorjs-abilities/src/look.test.js
index b3247d44..1da53874 100644
--- a/packages/warriorjs-abilities/src/look.test.js
+++ b/packages/warriorjs-abilities/src/look.test.js
@@ -17,7 +17,7 @@ describe('look', () => {
 
   test('has a description', () => {
     expect(look.description).toBe(
-      `Returns an array of up to 3 spaces in the given direction (\`'${FORWARD}'\` by default).`,
+      `Returns an array of up to 3 \`Space\`s in the given direction (${FORWARD} by default).`,
     );
   });
 
diff --git a/packages/warriorjs-abilities/src/pivot.js b/packages/warriorjs-abilities/src/pivot.js
index 53657edc..0a126957 100644
--- a/packages/warriorjs-abilities/src/pivot.js
+++ b/packages/warriorjs-abilities/src/pivot.js
@@ -5,7 +5,8 @@ const defaultDirection = BACKWARD;
 function pivot() {
   return unit => ({
     action: true,
-    description: `Rotates in the given direction (\`'${defaultDirection}'\` by default).`,
+    argumentsDescription: `direction = '${defaultDirection}'`,
+    description: `Rotates in the given direction (${defaultDirection} by default).`,
     perform(direction = defaultDirection) {
       unit.rotate(direction);
       unit.log(`pivots ${direction}`);
diff --git a/packages/warriorjs-abilities/src/pivot.test.js b/packages/warriorjs-abilities/src/pivot.test.js
index 1a7e37c9..a55a5b21 100644
--- a/packages/warriorjs-abilities/src/pivot.test.js
+++ b/packages/warriorjs-abilities/src/pivot.test.js
@@ -20,7 +20,7 @@ describe('pivot', () => {
 
   test('has a description', () => {
     expect(pivot.description).toBe(
-      `Rotates in the given direction (\`'${BACKWARD}'\` by default).`,
+      `Rotates in the given direction (${BACKWARD} by default).`,
     );
   });
 
diff --git a/packages/warriorjs-abilities/src/rescue.js b/packages/warriorjs-abilities/src/rescue.js
index d7164d86..f9b7a35b 100644
--- a/packages/warriorjs-abilities/src/rescue.js
+++ b/packages/warriorjs-abilities/src/rescue.js
@@ -5,7 +5,8 @@ const defaultDirection = FORWARD;
 function rescue() {
   return unit => ({
     action: true,
-    description: `Releases a unit from his chains in the given direction (\`'${defaultDirection}'\` by default).`,
+    argumentsDescription: `direction = '${defaultDirection}'`,
+    description: `Releases a unit from his chains in the given direction (${defaultDirection} by default).`,
     perform(direction = defaultDirection) {
       const receiver = unit.getSpaceAt(direction).getUnit();
       if (receiver && receiver.isBound()) {
diff --git a/packages/warriorjs-abilities/src/rescue.test.js b/packages/warriorjs-abilities/src/rescue.test.js
index 24c88aa1..ed6f1109 100644
--- a/packages/warriorjs-abilities/src/rescue.test.js
+++ b/packages/warriorjs-abilities/src/rescue.test.js
@@ -20,7 +20,7 @@ describe('rescue', () => {
 
   test('has a description', () => {
     expect(rescue.description).toBe(
-      `Releases a unit from his chains in the given direction (\`'${FORWARD}'\` by default).`,
+      `Releases a unit from his chains in the given direction (${FORWARD} by default).`,
     );
   });
 
diff --git a/packages/warriorjs-abilities/src/rest.js b/packages/warriorjs-abilities/src/rest.js
index 5829e33f..d78ac59d 100644
--- a/packages/warriorjs-abilities/src/rest.js
+++ b/packages/warriorjs-abilities/src/rest.js
@@ -2,7 +2,7 @@ function rest({ healthGain }) {
   const healthGainPercentage = healthGain * 100;
   return unit => ({
     action: true,
-    description: `Gains ${healthGainPercentage}% of max health back, but does nothing more.`,
+    description: `Gains ${healthGainPercentage}% of max health back (rounded half-up to the nearest integer), but does nothing more.`,
     perform() {
       if (unit.health < unit.maxHealth) {
         unit.log('rests');
diff --git a/packages/warriorjs-abilities/src/rest.test.js b/packages/warriorjs-abilities/src/rest.test.js
index 1bb3062e..4d89a173 100644
--- a/packages/warriorjs-abilities/src/rest.test.js
+++ b/packages/warriorjs-abilities/src/rest.test.js
@@ -20,7 +20,7 @@ describe('rest', () => {
 
   test('has a description', () => {
     expect(rest.description).toBe(
-      'Gains 10% of max health back, but does nothing more.',
+      'Gains 10% of max health back (rounded half-up to the nearest integer), but does nothing more.',
     );
   });
 
diff --git a/packages/warriorjs-abilities/src/shoot.js b/packages/warriorjs-abilities/src/shoot.js
index e836cb3e..f108078f 100644
--- a/packages/warriorjs-abilities/src/shoot.js
+++ b/packages/warriorjs-abilities/src/shoot.js
@@ -5,7 +5,8 @@ const defaultDirection = FORWARD;
 function shoot({ power, range }) {
   return unit => ({
     action: true,
-    description: `Shoots the bow & arrow in the given direction (\`'${defaultDirection}'\` by default), dealing ${power} HP of damage to the first unit in a range of ${range} spaces.`,
+    argumentsDescription: `direction = '${defaultDirection}'`,
+    description: `Shoots the bow & arrow in the given direction (${defaultDirection} by default), dealing ${power} HP of damage to the first unit in a range of ${range} spaces.`,
     perform(direction = defaultDirection) {
       const offsets = Array.from(new Array(range), (_, index) => index + 1);
       const receiver = offsets
diff --git a/packages/warriorjs-abilities/src/shoot.test.js b/packages/warriorjs-abilities/src/shoot.test.js
index 4fe576c1..b487b94e 100644
--- a/packages/warriorjs-abilities/src/shoot.test.js
+++ b/packages/warriorjs-abilities/src/shoot.test.js
@@ -20,7 +20,7 @@ describe('shoot', () => {
 
   test('has a description', () => {
     expect(shoot.description).toBe(
-      `Shoots the bow & arrow in the given direction (\`'${FORWARD}'\` by default), dealing 3 HP of damage to the first unit in a range of 3 spaces.`,
+      `Shoots the bow & arrow in the given direction (${FORWARD} by default), dealing 3 HP of damage to the first unit in a range of 3 spaces.`,
     );
   });
 
diff --git a/packages/warriorjs-abilities/src/think.js b/packages/warriorjs-abilities/src/think.js
index aa1d4405..2439418c 100644
--- a/packages/warriorjs-abilities/src/think.js
+++ b/packages/warriorjs-abilities/src/think.js
@@ -2,6 +2,7 @@ import util from 'util';
 
 function think() {
   return unit => ({
+    argumentsDescription: `thought`,
     description: 'Thinks out loud (`console.log` replacement).',
     perform(...args) {
       const thought = args.length > 0 ? util.format(...args) : 'nothing';
diff --git a/packages/warriorjs-abilities/src/walk.js b/packages/warriorjs-abilities/src/walk.js
index 00fe5238..77742eac 100644
--- a/packages/warriorjs-abilities/src/walk.js
+++ b/packages/warriorjs-abilities/src/walk.js
@@ -5,7 +5,8 @@ const defaultDirection = FORWARD;
 function walk() {
   return unit => ({
     action: true,
-    description: `Moves one space in the given direction (\`'${defaultDirection}'\` by default).`,
+    argumentsDescription: `direction = '${defaultDirection}'`,
+    description: `Moves one space in the given direction (${defaultDirection} by default).`,
     perform(direction = defaultDirection) {
       const space = unit.getSpaceAt(direction);
       if (space.isEmpty()) {
diff --git a/packages/warriorjs-abilities/src/walk.test.js b/packages/warriorjs-abilities/src/walk.test.js
index b62a1964..e665dcd2 100644
--- a/packages/warriorjs-abilities/src/walk.test.js
+++ b/packages/warriorjs-abilities/src/walk.test.js
@@ -20,7 +20,7 @@ describe('walk', () => {
 
   test('has a description', () => {
     expect(walk.description).toBe(
-      `Moves one space in the given direction (\`'${FORWARD}'\` by default).`,
+      `Moves one space in the given direction (${FORWARD} by default).`,
     );
   });
 
diff --git a/packages/warriorjs-cli/templates/readme/ability.ejs b/packages/warriorjs-cli/templates/readme/ability.ejs
index bbe7b899..74dcee8d 100644
--- a/packages/warriorjs-cli/templates/readme/ability.ejs
+++ b/packages/warriorjs-cli/templates/readme/ability.ejs
@@ -1 +1 @@
-- `warrior.<%- ability.name %>()`: <%- ability.description -%>
+- `warrior.<%- ability.name %>(<%- ability.argumentsDescription %>)`: <%- ability.description -%>
diff --git a/packages/warriorjs-core/src/Warrior.js b/packages/warriorjs-core/src/Warrior.js
index 2187866e..28c27f34 100644
--- a/packages/warriorjs-core/src/Warrior.js
+++ b/packages/warriorjs-core/src/Warrior.js
@@ -38,9 +38,10 @@ class Warrior extends Unit {
    */
   getAbilities() {
     const abilities = [...this.abilities].map(
-      ([name, { action, description }]) => ({
+      ([name, { action, argumentsDescription, description }]) => ({
         name,
         action,
+        argumentsDescription,
         description,
       }),
     );
diff --git a/packages/warriorjs-core/src/getLevel.test.js b/packages/warriorjs-core/src/getLevel.test.js
index fcd66116..fea5c861 100644
--- a/packages/warriorjs-core/src/getLevel.test.js
+++ b/packages/warriorjs-core/src/getLevel.test.js
@@ -26,14 +26,14 @@ const levelConfig = {
       abilities: {
         walk: () => ({
           action: true,
-          description: `Moves one space in the given direction (\`'${FORWARD}'\` by default).`,
+          description: `Moves one space in the given direction (${FORWARD} by default).`,
         }),
         attack: () => ({
           action: true,
-          description: `Attacks a unit in the given direction (\`'${FORWARD}'\` by default), dealing 5 HP of damage.`,
+          description: `Attacks a unit in the given direction (${FORWARD} by default), dealing 5 HP of damage.`,
         }),
         feel: () => ({
-          description: `Returns the adjacent space in the given direction (\`'${FORWARD}'\` by default).`,
+          description: `Returns the adjacent space in the given direction (${FORWARD} by default).`,
         }),
       },
       position: {
@@ -51,10 +51,10 @@ const levelConfig = {
         abilities: {
           attack: () => ({
             action: true,
-            description: `Attacks a unit in the given direction (\`'${FORWARD}'\` by default), dealing 3 HP of damage.`,
+            description: `Attacks a unit in the given direction (${FORWARD} by default), dealing 3 HP of damage.`,
           }),
           feel: () => ({
-            description: `Returns the adjacent space in the given direction (\`'${FORWARD}'\` by default).`,
+            description: `Returns the adjacent space in the given direction (${FORWARD} by default).`,
           }),
         },
         playTurn(sludge) {
@@ -145,19 +145,19 @@ test('returns level', () => {
         {
           name: 'attack',
           description:
-            "Attacks a unit in the given direction (`'forward'` by default), dealing 5 HP of damage.",
+            'Attacks a unit in the given direction (forward by default), dealing 5 HP of damage.',
         },
         {
           name: 'walk',
           description:
-            "Moves one space in the given direction (`'forward'` by default).",
+            'Moves one space in the given direction (forward by default).',
         },
       ],
       senses: [
         {
           name: 'feel',
           description:
-            "Returns the adjacent space in the given direction (`'forward'` by default).",
+            'Returns the adjacent space in the given direction (forward by default).',
         },
       ],
     },