diff --git a/docs/painless/painless-contexts/painless-metric-agg-combine-context.asciidoc b/docs/painless/painless-contexts/painless-metric-agg-combine-context.asciidoc
index 31cb596ae8167..5cc9ad8ecbb93 100644
--- a/docs/painless/painless-contexts/painless-metric-agg-combine-context.asciidoc
+++ b/docs/painless/painless-contexts/painless-metric-agg-combine-context.asciidoc
@@ -12,7 +12,7 @@ optional as part of a full metric aggregation.
 `params` (`Map`, read-only)::
         User-defined parameters passed in as part of the query.
 
-`params['_agg']` (`Map`)::
+`state` (`Map`)::
         `Map` with values available from the prior map script.
 
 *Return*
diff --git a/docs/painless/painless-contexts/painless-metric-agg-init-context.asciidoc b/docs/painless/painless-contexts/painless-metric-agg-init-context.asciidoc
index 1503e3abb5891..8c0fddfa33961 100644
--- a/docs/painless/painless-contexts/painless-metric-agg-init-context.asciidoc
+++ b/docs/painless/painless-contexts/painless-metric-agg-init-context.asciidoc
@@ -12,13 +12,13 @@ full metric aggregation.
 `params` (`Map`, read-only)::
         User-defined parameters passed in as part of the query.
 
-`params['_agg']` (`Map`)::
+`state` (`Map`)::
         Empty `Map` used to add values for use in a
         <<painless-metric-agg-map-context, map script>>.
 
 *Side Effects*
 
-`params['_agg']` (`Map`)::
+`state` (`Map`)::
         Add values to this `Map` to for use in a map.  Additional values must
         be of the type `Map`, `List`, `String` or primitive.
 
diff --git a/docs/painless/painless-contexts/painless-metric-agg-map-context.asciidoc b/docs/painless/painless-contexts/painless-metric-agg-map-context.asciidoc
index 16016d1cf8171..a34308aa93887 100644
--- a/docs/painless/painless-contexts/painless-metric-agg-map-context.asciidoc
+++ b/docs/painless/painless-contexts/painless-metric-agg-map-context.asciidoc
@@ -13,10 +13,9 @@ part of a full metric aggregation.
 `params` (`Map`, read-only)::
         User-defined parameters passed in as part of the query.
 
-`params['_agg']` (`Map`)::
+`state` (`Map`)::
         `Map` used to add values for processing in a
-        <<painless-metric-agg-map-context, combine script>> or returned
-        directly.
+        <<painless-metric-agg-map-context, combine script>> or to be returned from the aggregation.
 
 `doc` (`Map`, read-only)::
         Contains the fields of the current document where each field is a
@@ -27,15 +26,16 @@ part of a full metric aggregation.
 
 *Side Effects*
 
-`params['_agg']` (`Map`)::
+`state` (`Map`)::
         Use this `Map` to add values for processing in a combine script.
         Additional values must be of the type `Map`, `List`, `String` or
-        primitive. If an initialization script is provided as part the
+        primitive. The same `state` `Map` is shared between all aggregated documents
+        on a given shard. If an initialization script is provided as part of the
         aggregation then values added from the initialization script are
-        available as well.  If no combine script is specified, values must be
-        directly stored in `_agg`. If no combine script and no
+        available.  If no combine script is specified, values must be
+        directly stored in `state` in a usable form. If no combine script and no
         <<painless-metric-agg-reduce-context, reduce script>> are specified, the
-        values are used as the result.
+        `state` values are used as the result.
 
 *Return*
 
diff --git a/docs/painless/painless-contexts/painless-metric-agg-reduce-context.asciidoc b/docs/painless/painless-contexts/painless-metric-agg-reduce-context.asciidoc
index b76e02b1b0499..b492207ef4468 100644
--- a/docs/painless/painless-contexts/painless-metric-agg-reduce-context.asciidoc
+++ b/docs/painless/painless-contexts/painless-metric-agg-reduce-context.asciidoc
@@ -14,7 +14,7 @@ specified) and is optional as part of a full metric aggregation.
 `params` (`Map`, read-only)::
         User-defined parameters passed in as part of the query.
 
-`params['_aggs']` (`Map`)::
+`states` (`Map`)::
         `Map` with values available from the prior combine script (or a map
         script if no combine script is specified).