diff --git a/spark_executor/models.py b/spark_executor/models.py
index 9e35af8..96f7bbb 100644
--- a/spark_executor/models.py
+++ b/spark_executor/models.py
@@ -96,6 +96,8 @@ class Connection(BaseModel):
             "List of fnmatch glob patterns for hosts the fetch_url tool may access. "
             "The list is mandatory-opt-in: an empty list (the default) denies all "
             "hosts, so you must populate it before fetch_url can access any URL. "
+            "Set or change via save_connection (pass url_allowlist on create) or "
+            "update_connection (PATCH the field on an existing connection). "
             "Useful for clusters whose hostnames do NOT share a common suffix — "
             "e.g. single-label hosts like 'ccam1'-'ccam99' (configure ['ccam*']) "
             "or HDFS namenode on a different subdomain ('*.hadoop.internal'). "
diff --git a/spark_executor/server.py b/spark_executor/server.py
index 4b26128..dc7510d 100644
--- a/spark_executor/server.py
+++ b/spark_executor/server.py
@@ -549,7 +549,8 @@ def _update_job_file(req: UpdateJobFileRequest):
         "guardrails — the allowlist is the only gate — so keep it tight. The "
         "Connection's saved auth is reused, so the agent does not need cluster "
         "credentials.\n\n"
-        "30s timeout, redirects followed."
+        "**Limits:** 30s timeout, redirects followed, response body capped at "
+        "1 MB (the response includes a `truncated` boolean when this kicks in)."
     ),
 )
 def _fetch_url(req: FetchUrlRequest):
diff --git a/spark_executor/tools/requests.py b/spark_executor/tools/requests.py
index 9cb1f0f..39d3c46 100644
--- a/spark_executor/tools/requests.py
+++ b/spark_executor/tools/requests.py
@@ -408,8 +408,10 @@ class FetchUrlRequest(BaseModel):
         ...,
         description=(
             "Name of a saved Connection (see list_connections). The "
-            "Connection's yarn_rm_url defines the allowed host domain. "
-            "The Connection's auth_type / auth_user / auth_password / "
+            "Connection's url_allowlist is the host gate for this tool — "
+            "**not yarn_rm_url** (yarn_rm_url is only used by the "
+            "get_external_* tools to locate the YARN RM). The "
+            "Connection's auth_type / auth_user / auth_password / "
             "ssl_verify / ssl_ca_bundle are reused for the request."
         ),
     )