Apply suggestions from code review

Apply suggestions from code review

Co-authored-by: Tom McCarthy <[email protected]>

Author: walmsles

Diff for: docs/utilities/idempotency.md

@@ -206,10 +206,10 @@ In this example, we have a Lambda handler that creates a payment for a user subs
 
 Imagine the function executes successfully, but the client never receives the response due to a connection issue. It is safe to retry in this instance, as the idempotent decorator will return a previously saved response.
 
-!!! warning "Making JSON APIs Idempotent"
-    To ensure JSON structured APIs are fully idempotent we must ensure the idempotent key is a valid JSON object.
+!!! warning "Idempotency for JSON payloads"
+    The payload extracted by the `event_key_jmespath` is treated as a string by default, so will be sensitive to differences in whitespace even when the JSON payload itself is identical.
 
-    To do this we can [customize the default behaviour](#customizing-the-default-behavior) with *event_key_jmespath* and the [JMESPath built-in function](/utilities/jmespath_functions) *powertools_json()*.
+    To alter this behaviour, we can use the [JMESPath built-in function](/utilities/jmespath_functions) *powertools_json()* to treat the payload as a JSON object rather than a string.
 
 === "payment.py"
 

Diff for: docs/utilities/jmespath_functions.md

@@ -3,7 +3,7 @@ title: JMESPath Functions
 description: Utility
 ---
 
-You might have events or responses that contain non-encoded JSON, where you need to decode so that you can access portions of the object or ensure the Powertools utility recieves a JSON object
+You might have events or responses that contain non-encoded JSON, where you need to decode so that you can access portions of the object or ensure the Powertools utility receives a JSON object. This is a common use case when using the [validation](/utilities/validation) or [idempotency](/utilities/idempotency) utilities.  
 
 ## Built-in JMESPath functions
 You can use our built-in JMESPath functions within your expressions to do exactly that to decode JSON Strings, base64, and uncompress gzip data.