diff --git a/api-ref/src/wadls/orchestration-api/src/v1/orchestration-api.wadl b/api-ref/src/wadls/orchestration-api/src/v1/orchestration-api.wadl
index 9f7b9c1af..b4692f256 100644
--- a/api-ref/src/wadls/orchestration-api/src/v1/orchestration-api.wadl
+++ b/api-ref/src/wadls/orchestration-api/src/v1/orchestration-api.wadl
@@ -920,7 +920,7 @@ are specified, this value overrides any value provided for
     <method name="DELETE" id="stack_delete">
         <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"
             title="Delete stack">
-            <para role="shortdesc">Deletes a specified stack.</para>
+            <para role="shortdesc">Deletes a specified stack and any snapshots of that stack.</para>
         </wadl:doc>
         <response status="204"/>
     </method>
@@ -944,7 +944,7 @@ are specified, this value overrides any value provided for
         <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"
             title="Snapshot stack">
             <para role="shortdesc">Takes a snapshot of all the resources in the
-                stack.</para>
+                stack. All snapshots are deleted upon deletion of the stack.</para>
         </wadl:doc>
         <request>
             <representation mediaType="application/json">
@@ -997,7 +997,9 @@ are specified, this value overrides any value provided for
     <method name="POST" id="stack_restore_snapshot">
         <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"
             title="Restore snapshot">
-            <para role="shortdesc">Restore a stack snapshot.</para>
+            <para role="shortdesc">Restore a stack snapshot. Only active stacks
+                can be restored from a snapshot. Deleted stacks must be
+                recreated.</para>
         </wadl:doc>
         <response status="202"/>
     </method>