diff --git a/homeassistant/components/mqtt/__init__.py b/homeassistant/components/mqtt/__init__.py
index 0721177c23d..ae47613339f 100644
--- a/homeassistant/components/mqtt/__init__.py
+++ b/homeassistant/components/mqtt/__init__.py
@@ -12,6 +12,7 @@ import socket
 import time
 
 
+from homeassistant.config import load_yaml_config_file
 from homeassistant.exceptions import HomeAssistantError
 import homeassistant.util as util
 from homeassistant.util import template
@@ -166,7 +167,11 @@ def setup(hass, config):
 
     hass.bus.listen_once(EVENT_HOMEASSISTANT_START, start_mqtt)
 
-    hass.services.register(DOMAIN, SERVICE_PUBLISH, publish_service)
+    descriptions = load_yaml_config_file(
+        os.path.join(os.path.dirname(__file__), 'services.yaml'))
+
+    hass.services.register(DOMAIN, SERVICE_PUBLISH, publish_service,
+                           descriptions.get(SERVICE_PUBLISH))
 
     return True
 
diff --git a/homeassistant/components/mqtt/services.yaml b/homeassistant/components/mqtt/services.yaml
new file mode 100644
index 00000000000..9c713787fac
--- /dev/null
+++ b/homeassistant/components/mqtt/services.yaml
@@ -0,0 +1,29 @@
+publish:
+  description: Publish a message to an MQTT topic
+
+  fields:
+    topic:
+      description: Topic to publish payload
+      example: /homeassistant/hello
+
+    payload:
+      description: Payload to publish
+      example: This is great
+
+    payload_template:
+      description: Template to render as payload value. Ignored if payload given.
+      example: "{{ states('sensor.temperature') }}"
+
+    qos:
+      description: Quality of Service
+      example: 2
+      values:
+        - 0
+        - 1
+        - 2
+      default: 0
+
+    retain:
+      description: If message should have the retain flag set.
+      example: true
+      default: false