diff --git a/contracts/ibc-reflect-send/schema/execute_msg.json b/contracts/ibc-reflect-send/schema/execute_msg.json
index 36d36cd7b1..8a78e7b62b 100644
--- a/contracts/ibc-reflect-send/schema/execute_msg.json
+++ b/contracts/ibc-reflect-send/schema/execute_msg.json
@@ -435,9 +435,10 @@
       ]
     },
     "IbcTimeout": {
+      "description": "In IBC each package must set at least one type of timeout: the timestamp or the block height. Using this rather complex enum instead of two timeout fields we ensure that at least one timeout is set.",
       "anyOf": [
         {
-          "description": "block timestamp (nanoseconds since UNIX epoch) after which the packet times out (measured on the remote chain) See https://golang.org/pkg/time/#Time.UnixNano",
+          "description": "Block timestamp (nanoseconds since UNIX epoch) after which the packet times out (measured on the remote chain).",
           "type": "object",
           "required": [
             "timestamp"
@@ -450,7 +451,7 @@
           "additionalProperties": false
         },
         {
-          "description": "block after which the packet times out (measured on remote chain)",
+          "description": "Block after which the packet times out (measured on remote chain).",
           "type": "object",
           "required": [
             "block"
@@ -463,6 +464,7 @@
           "additionalProperties": false
         },
         {
+          "description": "Use this to set both timestamp and block timeout. The package then times out once the first of both timeouts is hit.",
           "type": "object",
           "required": [
             "both"
diff --git a/contracts/ibc-reflect-send/schema/packet_msg.json b/contracts/ibc-reflect-send/schema/packet_msg.json
index 55cb01fedd..502f680adc 100644
--- a/contracts/ibc-reflect-send/schema/packet_msg.json
+++ b/contracts/ibc-reflect-send/schema/packet_msg.json
@@ -388,9 +388,10 @@
       ]
     },
     "IbcTimeout": {
+      "description": "In IBC each package must set at least one type of timeout: the timestamp or the block height. Using this rather complex enum instead of two timeout fields we ensure that at least one timeout is set.",
       "anyOf": [
         {
-          "description": "block timestamp (nanoseconds since UNIX epoch) after which the packet times out (measured on the remote chain) See https://golang.org/pkg/time/#Time.UnixNano",
+          "description": "Block timestamp (nanoseconds since UNIX epoch) after which the packet times out (measured on the remote chain).",
           "type": "object",
           "required": [
             "timestamp"
@@ -403,7 +404,7 @@
           "additionalProperties": false
         },
         {
-          "description": "block after which the packet times out (measured on remote chain)",
+          "description": "Block after which the packet times out (measured on remote chain).",
           "type": "object",
           "required": [
             "block"
@@ -416,6 +417,7 @@
           "additionalProperties": false
         },
         {
+          "description": "Use this to set both timestamp and block timeout. The package then times out once the first of both timeouts is hit.",
           "type": "object",
           "required": [
             "both"
diff --git a/contracts/ibc-reflect/schema/packet_msg.json b/contracts/ibc-reflect/schema/packet_msg.json
index 1df378509b..a16d8cb3f6 100644
--- a/contracts/ibc-reflect/schema/packet_msg.json
+++ b/contracts/ibc-reflect/schema/packet_msg.json
@@ -387,9 +387,10 @@
       ]
     },
     "IbcTimeout": {
+      "description": "In IBC each package must set at least one type of timeout: the timestamp or the block height. Using this rather complex enum instead of two timeout fields we ensure that at least one timeout is set.",
       "anyOf": [
         {
-          "description": "block timestamp (nanoseconds since UNIX epoch) after which the packet times out (measured on the remote chain) See https://golang.org/pkg/time/#Time.UnixNano",
+          "description": "Block timestamp (nanoseconds since UNIX epoch) after which the packet times out (measured on the remote chain).",
           "type": "object",
           "required": [
             "timestamp"
@@ -402,7 +403,7 @@
           "additionalProperties": false
         },
         {
-          "description": "block after which the packet times out (measured on remote chain)",
+          "description": "Block after which the packet times out (measured on remote chain).",
           "type": "object",
           "required": [
             "block"
@@ -415,6 +416,7 @@
           "additionalProperties": false
         },
         {
+          "description": "Use this to set both timestamp and block timeout. The package then times out once the first of both timeouts is hit.",
           "type": "object",
           "required": [
             "both"
diff --git a/contracts/reflect/schema/execute_msg.json b/contracts/reflect/schema/execute_msg.json
index 6fff1e258d..6e2cc1611f 100644
--- a/contracts/reflect/schema/execute_msg.json
+++ b/contracts/reflect/schema/execute_msg.json
@@ -431,9 +431,10 @@
       ]
     },
     "IbcTimeout": {
+      "description": "In IBC each package must set at least one type of timeout: the timestamp or the block height. Using this rather complex enum instead of two timeout fields we ensure that at least one timeout is set.",
       "anyOf": [
         {
-          "description": "block timestamp (nanoseconds since UNIX epoch) after which the packet times out (measured on the remote chain) See https://golang.org/pkg/time/#Time.UnixNano",
+          "description": "Block timestamp (nanoseconds since UNIX epoch) after which the packet times out (measured on the remote chain).",
           "type": "object",
           "required": [
             "timestamp"
@@ -446,7 +447,7 @@
           "additionalProperties": false
         },
         {
-          "description": "block after which the packet times out (measured on remote chain)",
+          "description": "Block after which the packet times out (measured on remote chain).",
           "type": "object",
           "required": [
             "block"
@@ -459,6 +460,7 @@
           "additionalProperties": false
         },
         {
+          "description": "Use this to set both timestamp and block timeout. The package then times out once the first of both timeouts is hit.",
           "type": "object",
           "required": [
             "both"
diff --git a/contracts/reflect/schema/response_for__custom_msg.json b/contracts/reflect/schema/response_for__custom_msg.json
index f98154dc17..3fffad4acc 100644
--- a/contracts/reflect/schema/response_for__custom_msg.json
+++ b/contracts/reflect/schema/response_for__custom_msg.json
@@ -419,9 +419,10 @@
       ]
     },
     "IbcTimeout": {
+      "description": "In IBC each package must set at least one type of timeout: the timestamp or the block height. Using this rather complex enum instead of two timeout fields we ensure that at least one timeout is set.",
       "anyOf": [
         {
-          "description": "block timestamp (nanoseconds since UNIX epoch) after which the packet times out (measured on the remote chain) See https://golang.org/pkg/time/#Time.UnixNano",
+          "description": "Block timestamp (nanoseconds since UNIX epoch) after which the packet times out (measured on the remote chain).",
           "type": "object",
           "required": [
             "timestamp"
@@ -434,7 +435,7 @@
           "additionalProperties": false
         },
         {
-          "description": "block after which the packet times out (measured on remote chain)",
+          "description": "Block after which the packet times out (measured on remote chain).",
           "type": "object",
           "required": [
             "block"
@@ -447,6 +448,7 @@
           "additionalProperties": false
         },
         {
+          "description": "Use this to set both timestamp and block timeout. The package then times out once the first of both timeouts is hit.",
           "type": "object",
           "required": [
             "both"
diff --git a/packages/std/src/ibc.rs b/packages/std/src/ibc.rs
index 4614cc2093..147812cc24 100644
--- a/packages/std/src/ibc.rs
+++ b/packages/std/src/ibc.rs
@@ -54,15 +54,19 @@ pub struct IbcEndpoint {
     pub channel_id: String,
 }
 
+/// In IBC each package must set at least one type of timeout:
+/// the timestamp or the block height. Using this rather complex enum instead of
+/// two timeout fields we ensure that at least one timeout is set.
 #[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
 #[serde(rename_all = "snake_case")]
 pub enum IbcTimeout {
-    /// block timestamp (nanoseconds since UNIX epoch) after which the packet times out
-    /// (measured on the remote chain)
-    /// See https://golang.org/pkg/time/#Time.UnixNano
+    /// Block timestamp (nanoseconds since UNIX epoch) after which the packet times out
+    /// (measured on the remote chain).
     Timestamp(Timestamp),
-    /// block after which the packet times out (measured on remote chain)
+    /// Block after which the packet times out (measured on remote chain).
     Block(IbcTimeoutBlock),
+    /// Use this to set both timestamp and block timeout. The package then times out once
+    /// the first of both timeouts is hit.
     Both {
         timestamp: Timestamp,
         block: IbcTimeoutBlock,