diff --git a/api-reference/inference-api/anthropic-transform.mdx b/api-reference/inference-api/anthropic-transform.mdx
index 11af35cc..1c7a2595 100644
--- a/api-reference/inference-api/anthropic-transform.mdx
+++ b/api-reference/inference-api/anthropic-transform.mdx
@@ -10,6 +10,11 @@
 - `stop` → mapped to `stop_sequences`
 - `max_completion_tokens` → mapped to `max_tokens`
 
+## Anthropic Sampling + Token Rules
+- For Anthropic models (across providers), `temperature` and `top_p` are direct mappings when sent individually.
+- If both `temperature` and `top_p` are sent together, Portkey keeps `temperature` and drops `top_p`.
+- If `max_tokens` is explicitly sent as `null`, Portkey falls back to `max_completion_tokens` (if present) or a safe default.
+
 ## Complex Transformations
 
 ### Messages Transformation
diff --git a/product/ai-gateway/messages-api.mdx b/product/ai-gateway/messages-api.mdx
index f27aef4d..cde8c2e3 100644
--- a/product/ai-gateway/messages-api.mdx
+++ b/product/ai-gateway/messages-api.mdx
@@ -302,6 +302,10 @@ curl https://api.portkey.ai/v1/messages \
 | `stop_sequences` | array | Stop strings. Translated to `stop` for adapter providers |
 | `stream` | boolean | Enable streaming responses |
 
+<Note>
+For Anthropic models (across all providers/routes), `temperature` and `top_p` are direct mappings when provided individually. If both are sent together, Portkey keeps `temperature` and drops `top_p` to match Anthropic constraints.
+</Note>
+
 ## Tool Use
 
 Define tools with `name`, `description`, and `input_schema`:
@@ -698,7 +702,7 @@ Parameters translated for adapter providers:
 | `tool_choice: {type: "any"}` | `"required"` | |
 | `tool_choice: {type: "tool", name: X}` | `{type: "function", function: {name: X}}` | |
 | `metadata.user_id` | `user` | |
-| `temperature`, `top_p`, `stream` | Direct pass-through | |
+| `temperature`, `top_p`, `stream` | Direct pass-through | For Anthropic models: if both `temperature` and `top_p` are present, Portkey drops `top_p`. |
 | `output_config.format` (`json_schema`) | `response_format` | Portkey extension; `json_object` not supported |
 | `output_config.effort` | `reasoning_effort` | Portkey extension for cross-provider reasoning |