diff --git a/doc/compiled.json b/doc/compiled.json
index 7927c2830..b8f71f0ca 100644
--- a/doc/compiled.json
+++ b/doc/compiled.json
@@ -12129,7 +12129,7 @@
                     "example": "https://example.atlassian.net/browse/FOO"
                   },
                   "tags": {
-                    "description": "tags of keys that should be included within the job",
+                    "description": "tags of keys that should be included within the job.\n\n*Note: a tag matches every key currently carrying that tag, not just the ones you just tagged. For example, if hundreds of pre-existing keys already share the tag `myUploadTag`, adding it here pulls in every one of them, not only the key you just tagged. Use `translation_key_ids` to scope the job to specific keys instead.*\n",
                     "type": "array",
                     "items": {
                       "type": "string"
diff --git a/paths/jobs/create.yaml b/paths/jobs/create.yaml
index 47818db1f..29d855a97 100644
--- a/paths/jobs/create.yaml
+++ b/paths/jobs/create.yaml
@@ -85,7 +85,10 @@ requestBody:
             type: string
             example: https://example.atlassian.net/browse/FOO
           tags:
-            description: tags of keys that should be included within the job
+            description: |
+              tags of keys that should be included within the job.
+
+              *Note: a tag matches every key currently carrying that tag, not just the ones you just tagged. For example, if hundreds of pre-existing keys already share the tag `myUploadTag`, adding it here pulls in every one of them, not only the key you just tagged. Use `translation_key_ids` to scope the job to specific keys instead.*
             type: array
             items:
               type: string