diff --git a/compiler/src/model/utils.ts b/compiler/src/model/utils.ts
index a3e1e32cba..c0bf108e15 100644
--- a/compiler/src/model/utils.ts
+++ b/compiler/src/model/utils.ts
@@ -668,7 +668,7 @@ export function hoistRequestAnnotations (
       const privileges = [
         'all', 'cancel_task', 'create_snapshot', 'grant_api_key', 'manage', 'manage_api_key', 'manage_ccr',
         'manage_enrich', 'manage_ilm', 'manage_index_templates', 'manage_inference', 'manage_ingest_pipelines', 'manage_logstash_pipelines',
-        'manage_ml', 'manage_oidc', 'manage_own_api_key', 'manage_pipeline', 'manage_rollup', 'manage_saml', 'manage_search_application',
+        'manage_ml', 'manage_oidc', 'manage_own_api_key', 'manage_pipeline', 'manage_rollup', 'manage_saml', 'manage_search_application', 'manage_search_query_rules',
         'manage_security', 'manage_service_account', 'manage_slm', 'manage_token', 'manage_transform', 'manage_user_profile',
         'manage_watcher', 'monitor', 'monitor_ml', 'monitor_rollup', 'monitor_snapshot', 'monitor_text_structure',
         'monitor_transform', 'monitor_watcher', 'read_ccr', 'read_ilm', 'read_pipeline', 'read_security', 'read_slm', 'transport_client'
diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json
index a347449b84..882931ae5d 100644
--- a/output/openapi/elasticsearch-openapi.json
+++ b/output/openapi/elasticsearch-openapi.json
@@ -25008,13 +25008,13 @@
           "query_rules"
         ],
         "summary": "Create or update a query rule",
-        "description": "Create or update a query rule within a query ruleset.",
+        "description": "Create or update a query rule within a query ruleset.\n\nIMPORTANT: Due to limitations within pinned queries, you can only pin documents using ids or docs, but cannot use both in single rule.\nIt is advised to use one or the other in query rulesets, to avoid errors.\nAdditionally, pinned queries have a maximum limit of 100 pinned hits.\nIf multiple matching rules pin more than 100 documents, only the first 100 documents are pinned in the order they are specified in the ruleset.",
         "operationId": "query-rules-put-rule",
         "parameters": [
           {
             "in": "path",
             "name": "ruleset_id",
-            "description": "The unique identifier of the query ruleset containing the rule to be created or updated",
+            "description": "The unique identifier of the query ruleset containing the rule to be created or updated.",
             "required": true,
             "deprecated": false,
             "schema": {
@@ -25025,7 +25025,7 @@
           {
             "in": "path",
             "name": "rule_id",
-            "description": "The unique identifier of the query rule within the specified ruleset to be created or updated",
+            "description": "The unique identifier of the query rule within the specified ruleset to be created or updated.",
             "required": true,
             "deprecated": false,
             "schema": {
@@ -25044,6 +25044,7 @@
                     "$ref": "#/components/schemas/query_rules._types:QueryRuleType"
                   },
                   "criteria": {
+                    "description": "The criteria that must be met for the rule to be applied.\nIf multiple criteria are specified for a rule, all criteria must be met for the rule to be applied.",
                     "oneOf": [
                       {
                         "$ref": "#/components/schemas/query_rules._types:QueryRuleCriteria"
@@ -25100,7 +25101,7 @@
           "query_rules"
         ],
         "summary": "Delete a query rule",
-        "description": "Delete a query rule within a query ruleset.",
+        "description": "Delete a query rule within a query ruleset.\nThis is a destructive action that is only recoverable by re-adding the same rule with the create or update query rule API.",
         "operationId": "query-rules-delete-rule",
         "parameters": [
           {
@@ -25181,6 +25182,7 @@
           "query_rules"
         ],
         "summary": "Create or update a query ruleset",
+        "description": "There is a limit of 100 rules per ruleset.\nThis limit can be increased by using the `xpack.applications.rules.max_rules_per_ruleset` cluster setting.\n\nIMPORTANT: Due to limitations within pinned queries, you can only select documents using `ids` or `docs`, but cannot use both in single rule.\nIt is advised to use one or the other in query rulesets, to avoid errors.\nAdditionally, pinned queries have a maximum limit of 100 pinned hits.\nIf multiple matching rules pin more than 100 documents, only the first 100 documents are pinned in the order they are specified in the ruleset.",
         "externalDocs": {
           "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/search-using-query-rules.html"
         },
@@ -25189,7 +25191,7 @@
           {
             "in": "path",
             "name": "ruleset_id",
-            "description": "The unique identifier of the query ruleset to be created or updated",
+            "description": "The unique identifier of the query ruleset to be created or updated.",
             "required": true,
             "deprecated": false,
             "schema": {
@@ -25253,6 +25255,7 @@
           "query_rules"
         ],
         "summary": "Delete a query ruleset",
+        "description": "Remove a query ruleset and its associated data.\nThis is a destructive action that is not recoverable.",
         "operationId": "query-rules-delete-ruleset",
         "parameters": [
           {
@@ -25294,7 +25297,7 @@
           {
             "in": "query",
             "name": "from",
-            "description": "Starting offset (default: 0)",
+            "description": "The offset from the first result to fetch.",
             "deprecated": false,
             "schema": {
               "type": "number"
@@ -25304,7 +25307,7 @@
           {
             "in": "query",
             "name": "size",
-            "description": "specifies a max number of results to get",
+            "description": "The maximum number of results to retrieve.",
             "deprecated": false,
             "schema": {
               "type": "number"
@@ -25370,6 +25373,7 @@
                 "type": "object",
                 "properties": {
                   "match_criteria": {
+                    "description": "The match criteria to apply to rules in the given query ruleset.\nMatch criteria should match the keys defined in the `criteria.metadata` field of the rule.",
                     "type": "object",
                     "additionalProperties": {
                       "type": "object"
@@ -82244,6 +82248,7 @@
             "$ref": "#/components/schemas/query_rules._types:QueryRuleType"
           },
           "criteria": {
+            "description": "The criteria that must be met for the rule to be applied.\nIf multiple criteria are specified for a rule, all criteria must be met for the rule to be applied.",
             "oneOf": [
               {
                 "$ref": "#/components/schemas/query_rules._types:QueryRuleCriteria"
@@ -82284,9 +82289,11 @@
             "$ref": "#/components/schemas/query_rules._types:QueryRuleCriteriaType"
           },
           "metadata": {
+            "description": "The metadata field to match against.\nThis metadata will be used to match against `match_criteria` sent in the rule.\nIt is required for all criteria types except `always`.",
             "type": "string"
           },
           "values": {
+            "description": "The values to match against the `metadata` field.\nOnly one value must match for the criteria to be met.\nIt is required for all criteria types except `always`.",
             "type": "array",
             "items": {
               "type": "object"
@@ -82318,12 +82325,14 @@
         "type": "object",
         "properties": {
           "ids": {
+            "description": "The unique document IDs of the documents to apply the rule to.\nOnly one of `ids` or `docs` may be specified and at least one must be specified.",
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/_types:Id"
             }
           },
           "docs": {
+            "description": "The documents to apply the rule to.\nOnly one of `ids` or `docs` may be specified and at least one must be specified.\nThere is a maximum value of 100 documents in a rule.\nYou can specify the following attributes for each document:\n\n* `_index`: The index of the document to pin.\n* `_id`: The unique document ID.",
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/_types.query_dsl:PinnedDoc"
@@ -82338,7 +82347,7 @@
             "$ref": "#/components/schemas/_types:Id"
           },
           "rules": {
-            "description": "Rules associated with the query ruleset",
+            "description": "Rules associated with the query ruleset.",
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/query_rules._types:QueryRule"
@@ -82357,18 +82366,18 @@
             "$ref": "#/components/schemas/_types:Id"
           },
           "rule_total_count": {
-            "description": "The number of rules associated with this ruleset",
+            "description": "The number of rules associated with the ruleset.",
             "type": "number"
           },
           "rule_criteria_types_counts": {
-            "description": "A map of criteria type (e.g. exact) to the number of rules of that type",
+            "description": "A map of criteria type (for example, `exact`) to the number of rules of that type.\n\nNOTE: The counts in `rule_criteria_types_counts` may be larger than the value of `rule_total_count` because a rule may have multiple criteria.",
             "type": "object",
             "additionalProperties": {
               "type": "number"
             }
           },
           "rule_type_counts": {
-            "description": "A map of rule type (e.g. pinned) to the number of rules of that type",
+            "description": "A map of rule type (for example, `pinned`) to the number of rules of that type.",
             "type": "object",
             "additionalProperties": {
               "type": "number"
diff --git a/output/openapi/elasticsearch-serverless-openapi.json b/output/openapi/elasticsearch-serverless-openapi.json
index 4c2f97cdb7..c59067f5be 100644
--- a/output/openapi/elasticsearch-serverless-openapi.json
+++ b/output/openapi/elasticsearch-serverless-openapi.json
@@ -14962,13 +14962,13 @@
           "query_rules"
         ],
         "summary": "Create or update a query rule",
-        "description": "Create or update a query rule within a query ruleset.",
+        "description": "Create or update a query rule within a query ruleset.\n\nIMPORTANT: Due to limitations within pinned queries, you can only pin documents using ids or docs, but cannot use both in single rule.\nIt is advised to use one or the other in query rulesets, to avoid errors.\nAdditionally, pinned queries have a maximum limit of 100 pinned hits.\nIf multiple matching rules pin more than 100 documents, only the first 100 documents are pinned in the order they are specified in the ruleset.",
         "operationId": "query-rules-put-rule",
         "parameters": [
           {
             "in": "path",
             "name": "ruleset_id",
-            "description": "The unique identifier of the query ruleset containing the rule to be created or updated",
+            "description": "The unique identifier of the query ruleset containing the rule to be created or updated.",
             "required": true,
             "deprecated": false,
             "schema": {
@@ -14979,7 +14979,7 @@
           {
             "in": "path",
             "name": "rule_id",
-            "description": "The unique identifier of the query rule within the specified ruleset to be created or updated",
+            "description": "The unique identifier of the query rule within the specified ruleset to be created or updated.",
             "required": true,
             "deprecated": false,
             "schema": {
@@ -14998,6 +14998,7 @@
                     "$ref": "#/components/schemas/query_rules._types:QueryRuleType"
                   },
                   "criteria": {
+                    "description": "The criteria that must be met for the rule to be applied.\nIf multiple criteria are specified for a rule, all criteria must be met for the rule to be applied.",
                     "oneOf": [
                       {
                         "$ref": "#/components/schemas/query_rules._types:QueryRuleCriteria"
@@ -15054,7 +15055,7 @@
           "query_rules"
         ],
         "summary": "Delete a query rule",
-        "description": "Delete a query rule within a query ruleset.",
+        "description": "Delete a query rule within a query ruleset.\nThis is a destructive action that is only recoverable by re-adding the same rule with the create or update query rule API.",
         "operationId": "query-rules-delete-rule",
         "parameters": [
           {
@@ -15135,6 +15136,7 @@
           "query_rules"
         ],
         "summary": "Create or update a query ruleset",
+        "description": "There is a limit of 100 rules per ruleset.\nThis limit can be increased by using the `xpack.applications.rules.max_rules_per_ruleset` cluster setting.\n\nIMPORTANT: Due to limitations within pinned queries, you can only select documents using `ids` or `docs`, but cannot use both in single rule.\nIt is advised to use one or the other in query rulesets, to avoid errors.\nAdditionally, pinned queries have a maximum limit of 100 pinned hits.\nIf multiple matching rules pin more than 100 documents, only the first 100 documents are pinned in the order they are specified in the ruleset.",
         "externalDocs": {
           "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/search-using-query-rules.html"
         },
@@ -15143,7 +15145,7 @@
           {
             "in": "path",
             "name": "ruleset_id",
-            "description": "The unique identifier of the query ruleset to be created or updated",
+            "description": "The unique identifier of the query ruleset to be created or updated.",
             "required": true,
             "deprecated": false,
             "schema": {
@@ -15207,6 +15209,7 @@
           "query_rules"
         ],
         "summary": "Delete a query ruleset",
+        "description": "Remove a query ruleset and its associated data.\nThis is a destructive action that is not recoverable.",
         "operationId": "query-rules-delete-ruleset",
         "parameters": [
           {
@@ -15248,7 +15251,7 @@
           {
             "in": "query",
             "name": "from",
-            "description": "Starting offset (default: 0)",
+            "description": "The offset from the first result to fetch.",
             "deprecated": false,
             "schema": {
               "type": "number"
@@ -15258,7 +15261,7 @@
           {
             "in": "query",
             "name": "size",
-            "description": "specifies a max number of results to get",
+            "description": "The maximum number of results to retrieve.",
             "deprecated": false,
             "schema": {
               "type": "number"
@@ -15324,6 +15327,7 @@
                 "type": "object",
                 "properties": {
                   "match_criteria": {
+                    "description": "The match criteria to apply to rules in the given query ruleset.\nMatch criteria should match the keys defined in the `criteria.metadata` field of the rule.",
                     "type": "object",
                     "additionalProperties": {
                       "type": "object"
@@ -53383,6 +53387,7 @@
             "$ref": "#/components/schemas/query_rules._types:QueryRuleType"
           },
           "criteria": {
+            "description": "The criteria that must be met for the rule to be applied.\nIf multiple criteria are specified for a rule, all criteria must be met for the rule to be applied.",
             "oneOf": [
               {
                 "$ref": "#/components/schemas/query_rules._types:QueryRuleCriteria"
@@ -53423,9 +53428,11 @@
             "$ref": "#/components/schemas/query_rules._types:QueryRuleCriteriaType"
           },
           "metadata": {
+            "description": "The metadata field to match against.\nThis metadata will be used to match against `match_criteria` sent in the rule.\nIt is required for all criteria types except `always`.",
             "type": "string"
           },
           "values": {
+            "description": "The values to match against the `metadata` field.\nOnly one value must match for the criteria to be met.\nIt is required for all criteria types except `always`.",
             "type": "array",
             "items": {
               "type": "object"
@@ -53457,12 +53464,14 @@
         "type": "object",
         "properties": {
           "ids": {
+            "description": "The unique document IDs of the documents to apply the rule to.\nOnly one of `ids` or `docs` may be specified and at least one must be specified.",
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/_types:Id"
             }
           },
           "docs": {
+            "description": "The documents to apply the rule to.\nOnly one of `ids` or `docs` may be specified and at least one must be specified.\nThere is a maximum value of 100 documents in a rule.\nYou can specify the following attributes for each document:\n\n* `_index`: The index of the document to pin.\n* `_id`: The unique document ID.",
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/_types.query_dsl:PinnedDoc"
@@ -53477,7 +53486,7 @@
             "$ref": "#/components/schemas/_types:Id"
           },
           "rules": {
-            "description": "Rules associated with the query ruleset",
+            "description": "Rules associated with the query ruleset.",
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/query_rules._types:QueryRule"
@@ -53496,18 +53505,18 @@
             "$ref": "#/components/schemas/_types:Id"
           },
           "rule_total_count": {
-            "description": "The number of rules associated with this ruleset",
+            "description": "The number of rules associated with the ruleset.",
             "type": "number"
           },
           "rule_criteria_types_counts": {
-            "description": "A map of criteria type (e.g. exact) to the number of rules of that type",
+            "description": "A map of criteria type (for example, `exact`) to the number of rules of that type.\n\nNOTE: The counts in `rule_criteria_types_counts` may be larger than the value of `rule_total_count` because a rule may have multiple criteria.",
             "type": "object",
             "additionalProperties": {
               "type": "number"
             }
           },
           "rule_type_counts": {
-            "description": "A map of rule type (e.g. pinned) to the number of rules of that type",
+            "description": "A map of rule type (for example, `pinned`) to the number of rules of that type.",
             "type": "object",
             "additionalProperties": {
               "type": "number"
diff --git a/output/schema/schema.json b/output/schema/schema.json
index 2fe4176cc6..b0de7095eb 100644
--- a/output/schema/schema.json
+++ b/output/schema/schema.json
@@ -14018,9 +14018,15 @@
           "stability": "stable"
         }
       },
-      "description": "Delete a query rule.\nDelete a query rule within a query ruleset.",
-      "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/delete-query-rule.html",
+      "description": "Delete a query rule.\nDelete a query rule within a query ruleset.\nThis is a destructive action that is only recoverable by re-adding the same rule with the create or update query rule API.",
+      "docId": "query-rule-delete",
+      "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/delete-query-rule.html",
       "name": "query_rules.delete_rule",
+      "privileges": {
+        "cluster": [
+          "manage_search_query_rules"
+        ]
+      },
       "request": {
         "name": "Request",
         "namespace": "query_rules.delete_rule"
@@ -14053,9 +14059,15 @@
           "stability": "stable"
         }
       },
-      "description": "Delete a query ruleset.",
-      "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/delete-query-ruleset.html",
+      "description": "Delete a query ruleset.\nRemove a query ruleset and its associated data.\nThis is a destructive action that is not recoverable.",
+      "docId": "query-ruleset-delete",
+      "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/delete-query-ruleset.html",
       "name": "query_rules.delete_ruleset",
+      "privileges": {
+        "cluster": [
+          "manage_search_query_rules"
+        ]
+      },
       "request": {
         "name": "Request",
         "namespace": "query_rules.delete_ruleset"
@@ -14089,10 +14101,16 @@
         }
       },
       "description": "Get a query rule.\nGet details about a query rule within a query ruleset.",
-      "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/get-query-rule.html",
+      "docId": "query-rule-get",
+      "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-query-rule.html",
       "extDocId": "query-rule",
       "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-using-query-rules.html",
       "name": "query_rules.get_rule",
+      "privileges": {
+        "cluster": [
+          "manage_search_query_rules"
+        ]
+      },
       "request": {
         "name": "Request",
         "namespace": "query_rules.get_rule"
@@ -14126,8 +14144,14 @@
         }
       },
       "description": "Get a query ruleset.\nGet details about a query ruleset.",
-      "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/get-query-ruleset.html",
+      "docId": "query-ruleset-get",
+      "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-query-ruleset.html",
       "name": "query_rules.get_ruleset",
+      "privileges": {
+        "cluster": [
+          "manage_search_query_rules"
+        ]
+      },
       "request": {
         "name": "Request",
         "namespace": "query_rules.get_ruleset"
@@ -14161,8 +14185,14 @@
         }
       },
       "description": "Get all query rulesets.\nGet summarized information about the query rulesets.",
-      "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/list-query-rulesets.html",
+      "docId": "query-ruleset-list",
+      "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/list-query-rulesets.html",
       "name": "query_rules.list_rulesets",
+      "privileges": {
+        "cluster": [
+          "manage_search_query_rules"
+        ]
+      },
       "request": {
         "name": "Request",
         "namespace": "query_rules.list_rulesets"
@@ -14195,9 +14225,15 @@
           "stability": "stable"
         }
       },
-      "description": "Create or update a query rule.\nCreate or update a query rule within a query ruleset.",
-      "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/put-query-rule.html",
+      "description": "Create or update a query rule.\nCreate or update a query rule within a query ruleset.\n\nIMPORTANT: Due to limitations within pinned queries, you can only pin documents using ids or docs, but cannot use both in single rule.\nIt is advised to use one or the other in query rulesets, to avoid errors.\nAdditionally, pinned queries have a maximum limit of 100 pinned hits.\nIf multiple matching rules pin more than 100 documents, only the first 100 documents are pinned in the order they are specified in the ruleset.",
+      "docId": "query-rule-put",
+      "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/put-query-rule.html",
       "name": "query_rules.put_rule",
+      "privileges": {
+        "cluster": [
+          "manage_search_query_rules"
+        ]
+      },
       "request": {
         "name": "Request",
         "namespace": "query_rules.put_rule"
@@ -14233,11 +14269,17 @@
           "stability": "stable"
         }
       },
-      "description": "Create or update a query ruleset.",
-      "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/put-query-ruleset.html",
+      "description": "Create or update a query ruleset.\nThere is a limit of 100 rules per ruleset.\nThis limit can be increased by using the `xpack.applications.rules.max_rules_per_ruleset` cluster setting.\n\nIMPORTANT: Due to limitations within pinned queries, you can only select documents using `ids` or `docs`, but cannot use both in single rule.\nIt is advised to use one or the other in query rulesets, to avoid errors.\nAdditionally, pinned queries have a maximum limit of 100 pinned hits.\nIf multiple matching rules pin more than 100 documents, only the first 100 documents are pinned in the order they are specified in the ruleset.",
+      "docId": "query-ruleset-put",
+      "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/put-query-ruleset.html",
       "extDocId": "query-rule",
       "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-using-query-rules.html",
       "name": "query_rules.put_ruleset",
+      "privileges": {
+        "cluster": [
+          "manage_search_query_rules"
+        ]
+      },
       "request": {
         "name": "Request",
         "namespace": "query_rules.put_ruleset"
@@ -14274,8 +14316,14 @@
         }
       },
       "description": "Test a query ruleset.\nEvaluate match criteria against a query ruleset to identify the rules that would match that criteria.",
-      "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/test-query-ruleset.html",
+      "docId": "query-ruleset-test",
+      "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/test-query-ruleset.html",
       "name": "query_rules.test",
+      "privileges": {
+        "cluster": [
+          "manage_search_query_rules"
+        ]
+      },
       "request": {
         "name": "Request",
         "namespace": "query_rules.test"
@@ -185891,6 +185939,7 @@
       },
       "properties": [
         {
+          "description": "A unique identifier for the rule.",
           "name": "rule_id",
           "required": true,
           "type": {
@@ -185902,6 +185951,7 @@
           }
         },
         {
+          "description": "The type of rule.\n`pinned` will identify and pin specific documents to the top of search results.\n`exclude` will exclude specific documents from search results.",
           "name": "type",
           "required": true,
           "type": {
@@ -185913,6 +185963,7 @@
           }
         },
         {
+          "description": "The criteria that must be met for the rule to be applied.\nIf multiple criteria are specified for a rule, all criteria must be met for the rule to be applied.",
           "name": "criteria",
           "required": true,
           "type": {
@@ -185939,6 +185990,7 @@
           }
         },
         {
+          "description": "The actions to take when the rule is matched.\nThe format of this action depends on the rule type.",
           "name": "actions",
           "required": true,
           "type": {
@@ -185961,7 +186013,7 @@
           }
         }
       ],
-      "specLocation": "query_rules/_types/QueryRuleset.ts#L36-L42"
+      "specLocation": "query_rules/_types/QueryRuleset.ts#L36-L58"
     },
     {
       "kind": "interface",
@@ -185971,6 +186023,7 @@
       },
       "properties": [
         {
+          "description": "The unique document IDs of the documents to apply the rule to.\nOnly one of `ids` or `docs` may be specified and at least one must be specified.",
           "name": "ids",
           "required": false,
           "type": {
@@ -185985,6 +186038,7 @@
           }
         },
         {
+          "description": "The documents to apply the rule to.\nOnly one of `ids` or `docs` may be specified and at least one must be specified.\nThere is a maximum value of 100 documents in a rule.\nYou can specify the following attributes for each document:\n\n* `_index`: The index of the document to pin.\n* `_id`: The unique document ID.",
           "name": "docs",
           "required": false,
           "type": {
@@ -185999,7 +186053,7 @@
           }
         }
       ],
-      "specLocation": "query_rules/_types/QueryRuleset.ts#L70-L73"
+      "specLocation": "query_rules/_types/QueryRuleset.ts#L110-L126"
     },
     {
       "kind": "interface",
@@ -186009,6 +186063,7 @@
       },
       "properties": [
         {
+          "description": "The type of criteria. The following criteria types are supported:\n\n* `always`: Matches all queries, regardless of input.\n* `contains`: Matches that contain this value anywhere in the field meet the criteria defined by the rule. Only applicable for string values.\n* `exact`: Only exact matches meet the criteria defined by the rule. Applicable for string or numerical values.\n* `fuzzy`: Exact matches or matches within the allowed Levenshtein Edit Distance meet the criteria defined by the rule. Only applicable for string values.\n* `gt`: Matches with a value greater than this value meet the criteria defined by the rule. Only applicable for numerical values.\n* `gte`: Matches with a value greater than or equal to this value meet the criteria defined by the rule. Only applicable for numerical values.\n* `lt`: Matches with a value less than this value meet the criteria defined by the rule. Only applicable for numerical values.\n* `lte`: Matches with a value less than or equal to this value meet the criteria defined by the rule. Only applicable for numerical values.\n* `prefix`: Matches that start with this value meet the criteria defined by the rule. Only applicable for string values.\n* `suffix`: Matches that end with this value meet the criteria defined by the rule. Only applicable for string values.",
           "name": "type",
           "required": true,
           "type": {
@@ -186020,6 +186075,7 @@
           }
         },
         {
+          "description": "The metadata field to match against.\nThis metadata will be used to match against `match_criteria` sent in the rule.\nIt is required for all criteria types except `always`.",
           "name": "metadata",
           "required": false,
           "type": {
@@ -186031,6 +186087,7 @@
           }
         },
         {
+          "description": "The values to match against the `metadata` field.\nOnly one value must match for the criteria to be met.\nIt is required for all criteria types except `always`.",
           "name": "values",
           "required": false,
           "type": {
@@ -186041,7 +186098,7 @@
           }
         }
       ],
-      "specLocation": "query_rules/_types/QueryRuleset.ts#L49-L53"
+      "specLocation": "query_rules/_types/QueryRuleset.ts#L65-L93"
     },
     {
       "kind": "enum",
@@ -186087,7 +186144,7 @@
         "name": "QueryRuleCriteriaType",
         "namespace": "query_rules._types"
       },
-      "specLocation": "query_rules/_types/QueryRuleset.ts#L55-L68"
+      "specLocation": "query_rules/_types/QueryRuleset.ts#L95-L108"
     },
     {
       "kind": "enum",
@@ -186103,7 +186160,7 @@
         "name": "QueryRuleType",
         "namespace": "query_rules._types"
       },
-      "specLocation": "query_rules/_types/QueryRuleset.ts#L44-L47"
+      "specLocation": "query_rules/_types/QueryRuleset.ts#L60-L63"
     },
     {
       "kind": "interface",
@@ -186113,7 +186170,7 @@
       },
       "properties": [
         {
-          "description": "Query Ruleset unique identifier",
+          "description": "A unique identifier for the ruleset.",
           "name": "ruleset_id",
           "required": true,
           "type": {
@@ -186125,7 +186182,7 @@
           }
         },
         {
-          "description": "Rules associated with the query ruleset",
+          "description": "Rules associated with the query ruleset.",
           "name": "rules",
           "required": true,
           "type": {
@@ -186150,7 +186207,7 @@
       "body": {
         "kind": "no_body"
       },
-      "description": "Delete a query rule.\nDelete a query rule within a query ruleset.",
+      "description": "Delete a query rule.\nDelete a query rule within a query ruleset.\nThis is a destructive action that is only recoverable by re-adding the same rule with the create or update query rule API.",
       "inherits": {
         "type": {
           "name": "RequestBase",
@@ -186188,7 +186245,7 @@
         }
       ],
       "query": [],
-      "specLocation": "query_rules/delete_rule/QueryRuleDeleteRequest.ts#L22-L41"
+      "specLocation": "query_rules/delete_rule/QueryRuleDeleteRequest.ts#L22-L44"
     },
     {
       "kind": "response",
@@ -186216,7 +186273,7 @@
       "body": {
         "kind": "no_body"
       },
-      "description": "Delete a query ruleset.",
+      "description": "Delete a query ruleset.\nRemove a query ruleset and its associated data.\nThis is a destructive action that is not recoverable.",
       "inherits": {
         "type": {
           "name": "RequestBase",
@@ -186242,7 +186299,7 @@
         }
       ],
       "query": [],
-      "specLocation": "query_rules/delete_ruleset/QueryRulesetDeleteRequest.ts#L22-L35"
+      "specLocation": "query_rules/delete_ruleset/QueryRulesetDeleteRequest.ts#L22-L39"
     },
     {
       "kind": "response",
@@ -186308,7 +186365,7 @@
         }
       ],
       "query": [],
-      "specLocation": "query_rules/get_rule/QueryRuleGetRequest.ts#L22-L42"
+      "specLocation": "query_rules/get_rule/QueryRuleGetRequest.ts#L22-L44"
     },
     {
       "kind": "response",
@@ -186362,7 +186419,7 @@
         }
       ],
       "query": [],
-      "specLocation": "query_rules/get_ruleset/QueryRulesetGetRequest.ts#L22-L36"
+      "specLocation": "query_rules/get_ruleset/QueryRulesetGetRequest.ts#L22-L38"
     },
     {
       "kind": "response",
@@ -186390,7 +186447,7 @@
       },
       "properties": [
         {
-          "description": "Ruleset unique identifier",
+          "description": "A unique identifier for the ruleset.",
           "name": "ruleset_id",
           "required": true,
           "type": {
@@ -186402,7 +186459,7 @@
           }
         },
         {
-          "description": "The number of rules associated with this ruleset",
+          "description": "The number of rules associated with the ruleset.",
           "name": "rule_total_count",
           "required": true,
           "type": {
@@ -186414,7 +186471,7 @@
           }
         },
         {
-          "description": "A map of criteria type (e.g. exact) to the number of rules of that type",
+          "description": "A map of criteria type (for example, `exact`) to the number of rules of that type.\n\nNOTE: The counts in `rule_criteria_types_counts` may be larger than the value of `rule_total_count` because a rule may have multiple criteria.",
           "name": "rule_criteria_types_counts",
           "required": true,
           "type": {
@@ -186437,7 +186494,7 @@
           }
         },
         {
-          "description": "A map of rule type (e.g. pinned) to the number of rules of that type",
+          "description": "A map of rule type (for example, `pinned`) to the number of rules of that type.",
           "name": "rule_type_counts",
           "required": true,
           "type": {
@@ -186460,7 +186517,7 @@
           }
         }
       ],
-      "specLocation": "query_rules/list_rulesets/types.ts#L23-L42"
+      "specLocation": "query_rules/list_rulesets/types.ts#L23-L44"
     },
     {
       "kind": "request",
@@ -186484,9 +186541,10 @@
       "path": [],
       "query": [
         {
-          "description": "Starting offset (default: 0)",
+          "description": "The offset from the first result to fetch.",
           "name": "from",
           "required": false,
+          "serverDefault": 0,
           "type": {
             "kind": "instance_of",
             "type": {
@@ -186496,7 +186554,7 @@
           }
         },
         {
-          "description": "specifies a max number of results to get",
+          "description": "The maximum number of results to retrieve.",
           "name": "size",
           "required": false,
           "type": {
@@ -186508,7 +186566,7 @@
           }
         }
       ],
-      "specLocation": "query_rules/list_rulesets/QueryRulesetListRequest.ts#L22-L40"
+      "specLocation": "query_rules/list_rulesets/QueryRulesetListRequest.ts#L22-L43"
     },
     {
       "kind": "response",
@@ -186557,6 +186615,7 @@
         "kind": "properties",
         "properties": [
           {
+            "description": "The type of rule.",
             "name": "type",
             "required": true,
             "type": {
@@ -186568,6 +186627,7 @@
             }
           },
           {
+            "description": "The criteria that must be met for the rule to be applied.\nIf multiple criteria are specified for a rule, all criteria must be met for the rule to be applied.",
             "name": "criteria",
             "required": true,
             "type": {
@@ -186594,6 +186654,7 @@
             }
           },
           {
+            "description": "The actions to take when the rule is matched.\nThe format of this action depends on the rule type.",
             "name": "actions",
             "required": true,
             "type": {
@@ -186617,7 +186678,7 @@
           }
         ]
       },
-      "description": "Create or update a query rule.\nCreate or update a query rule within a query ruleset.",
+      "description": "Create or update a query rule.\nCreate or update a query rule within a query ruleset.\n\nIMPORTANT: Due to limitations within pinned queries, you can only pin documents using ids or docs, but cannot use both in single rule.\nIt is advised to use one or the other in query rulesets, to avoid errors.\nAdditionally, pinned queries have a maximum limit of 100 pinned hits.\nIf multiple matching rules pin more than 100 documents, only the first 100 documents are pinned in the order they are specified in the ruleset.",
       "inherits": {
         "type": {
           "name": "RequestBase",
@@ -186630,7 +186691,7 @@
       },
       "path": [
         {
-          "description": "The unique identifier of the query ruleset containing the rule to be created or updated",
+          "description": "The unique identifier of the query ruleset containing the rule to be created or updated.",
           "name": "ruleset_id",
           "required": true,
           "type": {
@@ -186642,7 +186703,7 @@
           }
         },
         {
-          "description": "The unique identifier of the query rule within the specified ruleset to be created or updated",
+          "description": "The unique identifier of the query rule within the specified ruleset to be created or updated.",
           "name": "rule_id",
           "required": true,
           "type": {
@@ -186655,7 +186716,7 @@
         }
       ],
       "query": [],
-      "specLocation": "query_rules/put_rule/QueryRulePutRequest.ts#L28-L57"
+      "specLocation": "query_rules/put_rule/QueryRulePutRequest.ts#L28-L73"
     },
     {
       "kind": "response",
@@ -186717,7 +186778,7 @@
           }
         ]
       },
-      "description": "Create or update a query ruleset.",
+      "description": "Create or update a query ruleset.\nThere is a limit of 100 rules per ruleset.\nThis limit can be increased by using the `xpack.applications.rules.max_rules_per_ruleset` cluster setting.\n\nIMPORTANT: Due to limitations within pinned queries, you can only select documents using `ids` or `docs`, but cannot use both in single rule.\nIt is advised to use one or the other in query rulesets, to avoid errors.\nAdditionally, pinned queries have a maximum limit of 100 pinned hits.\nIf multiple matching rules pin more than 100 documents, only the first 100 documents are pinned in the order they are specified in the ruleset.",
       "inherits": {
         "type": {
           "name": "RequestBase",
@@ -186730,7 +186791,7 @@
       },
       "path": [
         {
-          "description": "The unique identifier of the query ruleset to be created or updated",
+          "description": "The unique identifier of the query ruleset to be created or updated.",
           "name": "ruleset_id",
           "required": true,
           "type": {
@@ -186743,7 +186804,7 @@
         }
       ],
       "query": [],
-      "specLocation": "query_rules/put_ruleset/QueryRulesetPutRequest.ts#L23-L44"
+      "specLocation": "query_rules/put_ruleset/QueryRulesetPutRequest.ts#L23-L53"
     },
     {
       "kind": "response",
@@ -186812,6 +186873,7 @@
         "kind": "properties",
         "properties": [
           {
+            "description": "The match criteria to apply to rules in the given query ruleset.\nMatch criteria should match the keys defined in the `criteria.metadata` field of the rule.",
             "name": "match_criteria",
             "required": true,
             "type": {
@@ -186857,7 +186919,7 @@
         }
       ],
       "query": [],
-      "specLocation": "query_rules/test/QueryRulesetTestRequest.ts#L24-L45"
+      "specLocation": "query_rules/test/QueryRulesetTestRequest.ts#L24-L51"
     },
     {
       "kind": "response",
diff --git a/specification/_doc_ids/table.csv b/specification/_doc_ids/table.csv
index 563224d35c..907a170207 100644
--- a/specification/_doc_ids/table.csv
+++ b/specification/_doc_ids/table.csv
@@ -455,6 +455,14 @@ query-dsl-wildcard-query,https://www.elastic.co/guide/en/elasticsearch/reference
 query-dsl-wrapper-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-wrapper-query.html
 query-dsl,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl.html
 query-rule,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-using-query-rules.html
+query-rule-delete,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/delete-query-rule.html
+query-rule-get,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-query-rule.html
+query-rule-put,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/put-query-rule.html
+query-ruleset-delete,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/delete-query-ruleset.html
+query-ruleset-get,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-query-ruleset.html
+query-ruleset-list,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/list-query-rulesets.html
+query-ruleset-put,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/put-query-ruleset.html
+query-ruleset-test,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/test-query-ruleset.html
 realtime,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/docs-get.html#realtime
 redact-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/redact-processor.html
 regexp-syntax,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/regexp-syntax.html
diff --git a/specification/query_rules/_types/QueryRuleset.ts b/specification/query_rules/_types/QueryRuleset.ts
index b995d0dafc..ca48c50a28 100644
--- a/specification/query_rules/_types/QueryRuleset.ts
+++ b/specification/query_rules/_types/QueryRuleset.ts
@@ -24,19 +24,35 @@ import { PinnedDoc } from '../../_types/query_dsl/specialized'
 
 export class QueryRuleset {
   /**
-   * Query Ruleset unique identifier
+   * A unique identifier for the ruleset.
    */
   ruleset_id: Id
   /**
-   * Rules associated with the query ruleset
+   * Rules associated with the query ruleset.
    */
   rules: QueryRule[]
 }
 
 export class QueryRule {
+  /**
+   * A unique identifier for the rule.
+   */
   rule_id: Id
+  /**
+   * The type of rule.
+   * `pinned` will identify and pin specific documents to the top of search results.
+   * `exclude` will exclude specific documents from search results.
+   */
   type: QueryRuleType
+  /**
+   * The criteria that must be met for the rule to be applied.
+   * If multiple criteria are specified for a rule, all criteria must be met for the rule to be applied.
+   */
   criteria: QueryRuleCriteria | QueryRuleCriteria[]
+  /**
+   * The actions to take when the rule is matched.
+   * The format of this action depends on the rule type.
+   */
   actions: QueryRuleActions
   priority?: integer
 }
@@ -47,8 +63,32 @@ export enum QueryRuleType {
 }
 
 export class QueryRuleCriteria {
+  /**
+   * The type of criteria. The following criteria types are supported:
+   *
+   * * `always`: Matches all queries, regardless of input.
+   * * `contains`: Matches that contain this value anywhere in the field meet the criteria defined by the rule. Only applicable for string values.
+   * * `exact`: Only exact matches meet the criteria defined by the rule. Applicable for string or numerical values.
+   * * `fuzzy`: Exact matches or matches within the allowed Levenshtein Edit Distance meet the criteria defined by the rule. Only applicable for string values.
+   * * `gt`: Matches with a value greater than this value meet the criteria defined by the rule. Only applicable for numerical values.
+   * * `gte`: Matches with a value greater than or equal to this value meet the criteria defined by the rule. Only applicable for numerical values.
+   * * `lt`: Matches with a value less than this value meet the criteria defined by the rule. Only applicable for numerical values.
+   * * `lte`: Matches with a value less than or equal to this value meet the criteria defined by the rule. Only applicable for numerical values.
+   * * `prefix`: Matches that start with this value meet the criteria defined by the rule. Only applicable for string values.
+   * * `suffix`: Matches that end with this value meet the criteria defined by the rule. Only applicable for string values.
+   */
   type: QueryRuleCriteriaType
+  /**
+   * The metadata field to match against.
+   * This metadata will be used to match against `match_criteria` sent in the rule.
+   * It is required for all criteria types except `always`.
+   */
   metadata?: string
+  /**
+   * The values to match against the `metadata` field.
+   * Only one value must match for the criteria to be met.
+   * It is required for all criteria types except `always`.
+   */
   values?: UserDefinedValue[]
 }
 
@@ -68,6 +108,19 @@ export enum QueryRuleCriteriaType {
 }
 
 export class QueryRuleActions {
+  /**
+   * The unique document IDs of the documents to apply the rule to.
+   * Only one of `ids` or `docs` may be specified and at least one must be specified.
+   */
   ids?: Id[]
+  /**
+   * The documents to apply the rule to.
+   * Only one of `ids` or `docs` may be specified and at least one must be specified.
+   * There is a maximum value of 100 documents in a rule.
+   * You can specify the following attributes for each document:
+   *
+   * * `_index`: The index of the document to pin.
+   * * `_id`: The unique document ID.
+   */
   docs?: PinnedDoc[]
 }
diff --git a/specification/query_rules/delete_rule/QueryRuleDeleteRequest.ts b/specification/query_rules/delete_rule/QueryRuleDeleteRequest.ts
index df745da4ab..7604dab5a9 100644
--- a/specification/query_rules/delete_rule/QueryRuleDeleteRequest.ts
+++ b/specification/query_rules/delete_rule/QueryRuleDeleteRequest.ts
@@ -22,9 +22,12 @@ import { Id } from '@_types/common'
 /**
  * Delete a query rule.
  * Delete a query rule within a query ruleset.
+ * This is a destructive action that is only recoverable by re-adding the same rule with the create or update query rule API.
  * @rest_spec_name query_rules.delete_rule
  * @availability stack since=8.15.0 stability=stable
  * @availability serverless stability=stable visibility=public
+ * @cluster_privileges manage_search_query_rules
+ * @doc_id query-rule-delete
  */
 export interface Request extends RequestBase {
   path_parts: {
diff --git a/specification/query_rules/delete_ruleset/QueryRulesetDeleteRequest.ts b/specification/query_rules/delete_ruleset/QueryRulesetDeleteRequest.ts
index 3698895120..50e8b7666e 100644
--- a/specification/query_rules/delete_ruleset/QueryRulesetDeleteRequest.ts
+++ b/specification/query_rules/delete_ruleset/QueryRulesetDeleteRequest.ts
@@ -21,9 +21,13 @@ import { Id } from '@_types/common'
 
 /**
  * Delete a query ruleset.
+ * Remove a query ruleset and its associated data.
+ * This is a destructive action that is not recoverable.
  * @rest_spec_name query_rules.delete_ruleset
  * @availability stack since=8.10.0 stability=stable
  * @availability serverless stability=stable visibility=public
+ * @cluster_privileges manage_search_query_rules
+ * @doc_id query-ruleset-delete
  */
 export interface Request extends RequestBase {
   path_parts: {
diff --git a/specification/query_rules/get_rule/QueryRuleGetRequest.ts b/specification/query_rules/get_rule/QueryRuleGetRequest.ts
index de16f7ff86..c650758134 100644
--- a/specification/query_rules/get_rule/QueryRuleGetRequest.ts
+++ b/specification/query_rules/get_rule/QueryRuleGetRequest.ts
@@ -25,6 +25,8 @@ import { Id } from '@_types/common'
  * @rest_spec_name query_rules.get_rule
  * @availability stack since=8.15.0 stability=stable
  * @availability serverless stability=stable visibility=public
+ * @cluster_privileges manage_search_query_rules
+ * @doc_id query-rule-get
  * @ext_doc_id query-rule
  */
 export interface Request extends RequestBase {
diff --git a/specification/query_rules/get_rule/QueryRuleGetResponseExample1.yaml b/specification/query_rules/get_rule/QueryRuleGetResponseExample1.yaml
new file mode 100644
index 0000000000..aea10dc43d
--- /dev/null
+++ b/specification/query_rules/get_rule/QueryRuleGetResponseExample1.yaml
@@ -0,0 +1,17 @@
+# summary:
+description: A successful response from `GET _query_rules/my-ruleset/_rule/my-rule1`.
+# type: response
+# response_code: ''
+value:
+  rule_id: my-rule1
+  type: pinned
+  criteria:
+    - type: contains
+      metadata: query_string
+      values:
+        - pugs
+        - puggles
+  actions:
+    ids:
+      - id1
+      - id2
diff --git a/specification/query_rules/get_ruleset/QueryRulesetGetRequest.ts b/specification/query_rules/get_ruleset/QueryRulesetGetRequest.ts
index bbc3118e70..5f650908e0 100644
--- a/specification/query_rules/get_ruleset/QueryRulesetGetRequest.ts
+++ b/specification/query_rules/get_ruleset/QueryRulesetGetRequest.ts
@@ -25,6 +25,8 @@ import { Id } from '@_types/common'
  * @rest_spec_name query_rules.get_ruleset
  * @availability stack since=8.10.0 stability=stable
  * @availability serverless stability=stable visibility=public
+ * @cluster_privileges manage_search_query_rules
+ * @doc_id query-ruleset-get
  */
 export interface Request extends RequestBase {
   path_parts: {
diff --git a/specification/query_rules/get_ruleset/QueryRulesetGetResponseExample1.yaml b/specification/query_rules/get_ruleset/QueryRulesetGetResponseExample1.yaml
new file mode 100644
index 0000000000..dbb772266e
--- /dev/null
+++ b/specification/query_rules/get_ruleset/QueryRulesetGetResponseExample1.yaml
@@ -0,0 +1,21 @@
+# summary:
+description: A successful response from `GET _query_rules/my-ruleset/`.
+# type: response
+# response_code: ''
+value:
+  "{\n    \"ruleset_id\": \"my-ruleset\",\n    \"rules\": [\n        {\n    \
+  \        \"rule_id\": \"my-rule1\",\n            \"type\": \"pinned\",\n       \
+  \     \"criteria\": [\n                {\n                    \"type\": \"contains\"\
+  ,\n                    \"metadata\": \"query_string\",\n                    \"values\"\
+  : [ \"pugs\", \"puggles\" ]\n                }\n            ],\n            \"actions\"\
+  : {\n                \"ids\": [\n                    \"id1\",\n                \
+  \    \"id2\"\n                ]\n            }\n        },\n        {\n        \
+  \    \"rule_id\": \"my-rule2\",\n            \"type\": \"pinned\",\n           \
+  \ \"criteria\": [\n                {\n                    \"type\": \"fuzzy\",\n\
+  \                    \"metadata\": \"query_string\",\n                    \"values\"\
+  : [ \"rescue dogs\" ]\n                }\n            ],\n            \"actions\"\
+  : {\n                \"docs\": [\n                    {\n                      \
+  \  \"_index\": \"index1\",\n                        \"_id\": \"id3\"\n         \
+  \           },\n                    {\n                        \"_index\": \"index2\"\
+  ,\n                        \"_id\": \"id4\"\n                    }\n           \
+  \     ]\n            }\n        }\n    ]\n}"
diff --git a/specification/query_rules/list_rulesets/QueryRulesetListRequest.ts b/specification/query_rules/list_rulesets/QueryRulesetListRequest.ts
index f98ee4a6b5..fa573c44bb 100644
--- a/specification/query_rules/list_rulesets/QueryRulesetListRequest.ts
+++ b/specification/query_rules/list_rulesets/QueryRulesetListRequest.ts
@@ -25,15 +25,18 @@ import { integer } from '@_types/Numeric'
  * @rest_spec_name query_rules.list_rulesets
  * @availability stack since=8.10.0 stability=stable
  * @availability serverless stability=stable visibility=public
+ * @cluster_privileges manage_search_query_rules
+ * @doc_id query-ruleset-list
  */
 export interface Request extends RequestBase {
   query_parameters: {
     /**
-     * Starting offset (default: 0)
+     * The offset from the first result to fetch.
+     * @server_default 0
      */
     from?: integer
     /**
-     * specifies a max number of results to get
+     * The maximum number of results to retrieve.
      */
     size?: integer
   }
diff --git a/specification/query_rules/list_rulesets/QueryRulesetListResponseExample1.yaml b/specification/query_rules/list_rulesets/QueryRulesetListResponseExample1.yaml
new file mode 100644
index 0000000000..1162cea1d8
--- /dev/null
+++ b/specification/query_rules/list_rulesets/QueryRulesetListResponseExample1.yaml
@@ -0,0 +1,14 @@
+# summary:
+description: A successful response from `GET _query_rules/?from=0&size=3`.
+# type: response
+# response_code: ''
+value:
+  "{\n    \"count\": 3,\n    \"results\": [\n        {\n            \"ruleset_id\"\
+  : \"ruleset-1\",\n            \"rule_total_count\": 1,\n            \"rule_criteria_types_counts\"\
+  : {\n                \"exact\": 1\n            }\n        },\n        {\n      \
+  \      \"ruleset_id\": \"ruleset-2\",\n            \"rule_total_count\": 2,\n  \
+  \          \"rule_criteria_types_counts\": {\n                \"exact\": 1,\n  \
+  \              \"fuzzy\": 1\n            }\n        },\n        {\n            \"\
+  ruleset_id\": \"ruleset-3\",\n            \"rule_total_count\": 3,\n           \
+  \ \"rule_criteria_types_counts\": {\n                \"exact\": 1,\n           \
+  \     \"fuzzy\": 2\n            }\n        }\n    ]\n}"
diff --git a/specification/query_rules/list_rulesets/types.ts b/specification/query_rules/list_rulesets/types.ts
index 1441eb6af6..7270ed7406 100644
--- a/specification/query_rules/list_rulesets/types.ts
+++ b/specification/query_rules/list_rulesets/types.ts
@@ -22,21 +22,23 @@ import { integer } from '@_types/Numeric'
 
 export class QueryRulesetListItem {
   /**
-   * Ruleset unique identifier
+   * A unique identifier for the ruleset.
    */
   ruleset_id: Id
   /**
-   * The number of rules associated with this ruleset
+   * The number of rules associated with the ruleset.
    */
   rule_total_count: integer
 
   /**
-   * A map of criteria type (e.g. exact) to the number of rules of that type
+   * A map of criteria type (for example, `exact`) to the number of rules of that type.
+   *
+   * NOTE: The counts in `rule_criteria_types_counts` may be larger than the value of `rule_total_count` because a rule may have multiple criteria.
    */
   rule_criteria_types_counts: Dictionary<string, integer>
 
   /**
-   * A map of rule type (e.g. pinned) to the number of rules of that type
+   * A map of rule type (for example, `pinned`) to the number of rules of that type.
    */
   rule_type_counts: Dictionary<string, integer>
 }
diff --git a/specification/query_rules/put_rule/QueryRulePutRequest.ts b/specification/query_rules/put_rule/QueryRulePutRequest.ts
index e3c1f5aefe..853f2f7c9e 100644
--- a/specification/query_rules/put_rule/QueryRulePutRequest.ts
+++ b/specification/query_rules/put_rule/QueryRulePutRequest.ts
@@ -28,29 +28,45 @@ import {
 /**
  * Create or update a query rule.
  * Create or update a query rule within a query ruleset.
+ *
+ * IMPORTANT: Due to limitations within pinned queries, you can only pin documents using ids or docs, but cannot use both in single rule.
+ * It is advised to use one or the other in query rulesets, to avoid errors.
+ * Additionally, pinned queries have a maximum limit of 100 pinned hits.
+ * If multiple matching rules pin more than 100 documents, only the first 100 documents are pinned in the order they are specified in the ruleset.
  * @rest_spec_name query_rules.put_rule
  * @availability stack since=8.15.0 stability=stable
  * @availability serverless stability=stable visibility=public
+ * @cluster_privileges manage_search_query_rules
+ * @doc_id query-rule-put
  */
 export interface Request extends RequestBase {
   path_parts: {
     /**
-     * The unique identifier of the query ruleset containing the rule to be created or updated
+     * The unique identifier of the query ruleset containing the rule to be created or updated.
      */
     ruleset_id: Id
 
     /**
-     * The unique identifier of the query rule within the specified ruleset to be created or updated
+     * The unique identifier of the query rule within the specified ruleset to be created or updated.
      */
     rule_id: Id
   }
   /**
-   * The query rule information
+   * The query rule information.
    */
   /** @codegen_name query_rule */
   body: {
+    /** The type of rule. */
     type: QueryRuleType
+    /**
+     * The criteria that must be met for the rule to be applied.
+     * If multiple criteria are specified for a rule, all criteria must be met for the rule to be applied.
+     */
     criteria: QueryRuleCriteria | QueryRuleCriteria[]
+    /**
+     * The actions to take when the rule is matched.
+     * The format of this action depends on the rule type.
+     */
     actions: QueryRuleActions
     priority?: integer
   }
diff --git a/specification/query_rules/put_rule/QueryRulePutRequestExample1.yaml b/specification/query_rules/put_rule/QueryRulePutRequestExample1.yaml
new file mode 100644
index 0000000000..ab774fede5
--- /dev/null
+++ b/specification/query_rules/put_rule/QueryRulePutRequestExample1.yaml
@@ -0,0 +1,9 @@
+# summary:
+# method_request: POST _query_rules/my-ruleset/_test
+description: >
+  Run `POST _query_rules/my-ruleset/_test` to test a ruleset.
+  Provide the match criteria that you want to test against.
+# type: request
+value:
+  match_criteria:
+    query_string: puggles
diff --git a/specification/query_rules/put_ruleset/QueryRulesetPutRequest.ts b/specification/query_rules/put_ruleset/QueryRulesetPutRequest.ts
index 06d244fe1c..7ff40b9b87 100644
--- a/specification/query_rules/put_ruleset/QueryRulesetPutRequest.ts
+++ b/specification/query_rules/put_ruleset/QueryRulesetPutRequest.ts
@@ -22,15 +22,24 @@ import { QueryRule } from '../_types/QueryRuleset'
 
 /**
  * Create or update a query ruleset.
+ * There is a limit of 100 rules per ruleset.
+ * This limit can be increased by using the `xpack.applications.rules.max_rules_per_ruleset` cluster setting.
+ *
+ * IMPORTANT: Due to limitations within pinned queries, you can only select documents using `ids` or `docs`, but cannot use both in single rule.
+ * It is advised to use one or the other in query rulesets, to avoid errors.
+ * Additionally, pinned queries have a maximum limit of 100 pinned hits.
+ * If multiple matching rules pin more than 100 documents, only the first 100 documents are pinned in the order they are specified in the ruleset.
  * @rest_spec_name query_rules.put_ruleset
  * @availability stack since=8.10.0 stability=stable
  * @availability serverless stability=stable visibility=public
+ * @cluster_privileges manage_search_query_rules
+ * @doc_id query-ruleset-put
  * @ext_doc_id query-rule
  */
 export interface Request extends RequestBase {
   path_parts: {
     /**
-     * The unique identifier of the query ruleset to be created or updated
+     * The unique identifier of the query ruleset to be created or updated.
      */
     ruleset_id: Id
   }
diff --git a/specification/query_rules/put_ruleset/QueryRulesetPutRequestExample1.yaml b/specification/query_rules/put_ruleset/QueryRulesetPutRequestExample1.yaml
new file mode 100644
index 0000000000..2aa19c71a0
--- /dev/null
+++ b/specification/query_rules/put_ruleset/QueryRulesetPutRequestExample1.yaml
@@ -0,0 +1,27 @@
+# summary:
+# method_request: PUT _query_rules/my-ruleset
+description: >
+  Run `PUT _query_rules/my-ruleset` to create a new query ruleset.
+  Two rules are associated with `my-ruleset`.
+  `my-rule1` will pin documents with IDs `id1` and `id2` when `user_query` contains `pugs` or `puggles` and `user_country` exactly matches `us`.
+  `my-rule2` will exclude documents from different specified indices with IDs `id3` and `id4` when the `query_string` fuzzily matches `rescue dogs`.
+# type: request
+value:
+  "{\n    \"rules\": [\n        {\n            \"rule_id\": \"my-rule1\",\n \
+  \           \"type\": \"pinned\",\n            \"criteria\": [\n               \
+  \ {\n                    \"type\": \"contains\",\n                    \"metadata\"\
+  : \"user_query\",\n                    \"values\": [ \"pugs\", \"puggles\" ]\n \
+  \               },\n                {\n                    \"type\": \"exact\",\n\
+  \                    \"metadata\": \"user_country\",\n                    \"values\"\
+  : [ \"us\" ]\n                }\n            ],\n            \"actions\": {\n  \
+  \              \"ids\": [\n                    \"id1\",\n                    \"\
+  id2\"\n                ]\n            }\n        },\n        {\n            \"rule_id\"\
+  : \"my-rule2\",\n            \"type\": \"pinned\",\n            \"criteria\": [\n\
+  \                {\n                    \"type\": \"fuzzy\",\n                 \
+  \   \"metadata\": \"user_query\",\n                    \"values\": [ \"rescue dogs\"\
+  \ ]\n                }\n            ],\n            \"actions\": {\n           \
+  \     \"docs\": [\n                    {\n                        \"_index\": \"\
+  index1\",\n                        \"_id\": \"id3\"\n                    },\n  \
+  \                  {\n                        \"_index\": \"index2\",\n        \
+  \                \"_id\": \"id4\"\n                    }\n                ]\n  \
+  \          }\n        }\n    ]\n}"
diff --git a/specification/query_rules/test/QueryRulesetTestRequest.ts b/specification/query_rules/test/QueryRulesetTestRequest.ts
index 6ce634de10..194759a455 100644
--- a/specification/query_rules/test/QueryRulesetTestRequest.ts
+++ b/specification/query_rules/test/QueryRulesetTestRequest.ts
@@ -27,6 +27,8 @@ import { Id } from '@_types/common'
  * @rest_spec_name query_rules.test
  * @availability stack since=8.10.0 stability=stable
  * @availability serverless stability=stable visibility=public
+ * @cluster_privileges manage_search_query_rules
+ * @doc_id query-ruleset-test
  */
 export interface Request extends RequestBase {
   path_parts: {
@@ -40,6 +42,10 @@ export interface Request extends RequestBase {
    */
   /** @codegen_name match_criteria */
   body: {
+    /**
+     * The match criteria to apply to rules in the given query ruleset.
+     * Match criteria should match the keys defined in the `criteria.metadata` field of the rule.
+     */
     match_criteria: Dictionary<string, UserDefinedValue>
   }
 }
diff --git a/specification/query_rules/test/QueryRulesetTestRequestExample1.yaml b/specification/query_rules/test/QueryRulesetTestRequestExample1.yaml
new file mode 100644
index 0000000000..2aa19c71a0
--- /dev/null
+++ b/specification/query_rules/test/QueryRulesetTestRequestExample1.yaml
@@ -0,0 +1,27 @@
+# summary:
+# method_request: PUT _query_rules/my-ruleset
+description: >
+  Run `PUT _query_rules/my-ruleset` to create a new query ruleset.
+  Two rules are associated with `my-ruleset`.
+  `my-rule1` will pin documents with IDs `id1` and `id2` when `user_query` contains `pugs` or `puggles` and `user_country` exactly matches `us`.
+  `my-rule2` will exclude documents from different specified indices with IDs `id3` and `id4` when the `query_string` fuzzily matches `rescue dogs`.
+# type: request
+value:
+  "{\n    \"rules\": [\n        {\n            \"rule_id\": \"my-rule1\",\n \
+  \           \"type\": \"pinned\",\n            \"criteria\": [\n               \
+  \ {\n                    \"type\": \"contains\",\n                    \"metadata\"\
+  : \"user_query\",\n                    \"values\": [ \"pugs\", \"puggles\" ]\n \
+  \               },\n                {\n                    \"type\": \"exact\",\n\
+  \                    \"metadata\": \"user_country\",\n                    \"values\"\
+  : [ \"us\" ]\n                }\n            ],\n            \"actions\": {\n  \
+  \              \"ids\": [\n                    \"id1\",\n                    \"\
+  id2\"\n                ]\n            }\n        },\n        {\n            \"rule_id\"\
+  : \"my-rule2\",\n            \"type\": \"pinned\",\n            \"criteria\": [\n\
+  \                {\n                    \"type\": \"fuzzy\",\n                 \
+  \   \"metadata\": \"user_query\",\n                    \"values\": [ \"rescue dogs\"\
+  \ ]\n                }\n            ],\n            \"actions\": {\n           \
+  \     \"docs\": [\n                    {\n                        \"_index\": \"\
+  index1\",\n                        \"_id\": \"id3\"\n                    },\n  \
+  \                  {\n                        \"_index\": \"index2\",\n        \
+  \                \"_id\": \"id4\"\n                    }\n                ]\n  \
+  \          }\n        }\n    ]\n}"
diff --git a/specification/query_rules/test/QueryRulesetTestResponseExample1.yaml b/specification/query_rules/test/QueryRulesetTestResponseExample1.yaml
new file mode 100644
index 0000000000..4a6f26543f
--- /dev/null
+++ b/specification/query_rules/test/QueryRulesetTestResponseExample1.yaml
@@ -0,0 +1,9 @@
+# summary:
+description: A successful response from `POST _query_rules/my-ruleset/_test`.
+# type: response
+# response_code: ''
+value:
+  total_matched_rules: 1
+  matched_rules:
+    - ruleset_id: my-ruleset
+      rule_id: my-rule1