diff --git a/docs/docs/api-reference/starlark-reference/service-config.md b/docs/docs/api-reference/starlark-reference/service-config.md
index b11a2edff9..d94fca7794 100644
--- a/docs/docs/api-reference/starlark-reference/service-config.md
+++ b/docs/docs/api-reference/starlark-reference/service-config.md
@@ -164,6 +164,7 @@ config = ServiceConfig(
     # This refers to Kubernetes Tolerations https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/
     # This has no effect on Docker
     # As of 2024-01-24 Taints and Tolerations to work with Kubernetes you need at least one untainted node
+    # Refer to the Toleration docs linked near the end of the page to learn more
     # OPTIONAL
     tolerations = [
         Toleration(
@@ -222,9 +223,9 @@ labels:
 ```
 :::
 
-The `user` field expects a `User`[user] object being passed.
+The `user` field expects a [`User`][user] object being passed.
 
-The `tolerations` field expects a list of `toleration[toleration]` object being passed.
+The `tolerations` field expects a list of [`Toleration`][toleration] objects being passed.
 
 <!--------------- ONLY LINKS BELOW THIS POINT ---------------------->
 [add-service-reference]: ./plan.md#add_service
diff --git a/docs/docs/api-reference/starlark-reference/toleration.md b/docs/docs/api-reference/starlark-reference/toleration.md
index 2c50ba83a4..fa4eb9688a 100644
--- a/docs/docs/api-reference/starlark-reference/toleration.md
+++ b/docs/docs/api-reference/starlark-reference/toleration.md
@@ -8,11 +8,33 @@ can be used with a [ServiceConfig][service-config] object.
 
 ```python
 toleration = Toleration(
-    key = "key",
-    operator = "Equal",
-    value = "value",
-    effect = "NoSchedule",
-    toleration_seconds = 64,
+	# key is the taint key that the toleration applies to. Empty means match all taint keys.
+	# If the key is empty, operator must be Exists; this combination means to match all values and all keys.
+	# OPTIONAL
+	key = "key",
+
+	# operator represents a key's relationship to the value.
+	# Valid operators are Exists and Equal. Defaults to Equal.
+	# Exists is equivalent to wildcard for value, so that a pod can tolerate all taints of a particular category.
+	# OPTIONAL
+	operator = "Equal",
+
+	# value is the taint value the toleration matches to.
+	# If the operator is Exists, the value should be empty, otherwise just a regular string.
+	# OPTIONAL
+	value = "value",
+
+	# effect indicates the taint effect to match. Empty means match all taint effects.
+	# When specified, allowed values are NoSchedule, PreferNoSchedule and NoExecute.
+	# OPTIONAL
+	effect = "NoSchedule",
+
+	# toleration_seconds represents the period of time the toleration (which must be
+	# of effect NoExecute, otherwise this field is ignored) tolerates the taint. By default,
+	# it is not set, which means tolerate the taint forever (do not evict). Zero and
+	# negative values will be treated as 0 (evict immediately) by the system.
+	# OPTIONAL
+	toleration_seconds = 64,
 )
 ```