diff --git a/docs/specification.md b/docs/specification.md
index 4accaad8b..8325b8e31 100644
--- a/docs/specification.md
+++ b/docs/specification.md
@@ -30811,7 +30811,7 @@ Provider credential keys follow the pattern `provider.<name>.<field>`. Each prov
 | `provider.google.api-key` | string | *(not set)* | `GOOGLE_API_KEY` | API key for Google AI models. Required when using Google-based actors. |
 | `provider.azure.endpoint` | string | *(not set)* | `AZURE_OPENAI_ENDPOINT` | Azure OpenAI endpoint URL. Required when using Azure-hosted OpenAI models. |
 | `provider.azure.api-key` | string | *(not set)* | `AZURE_OPENAI_API_KEY` | API key for Azure OpenAI. Required alongside `provider.azure.endpoint`. |
-| `provider.azure.api-version` | string | `2024-02-01` | `AZURE_OPENAI_API_VERSION` | Azure OpenAI API version string. |
+| `provider.azure.api-version` | string | `2024-05-01-preview` | `AZURE_OPENAI_API_VERSION` | Azure OpenAI API version string. The default `2024-05-01-preview` supports the latest features including structured outputs and tool calling improvements. Use a stable version (e.g., `2024-02-01`) for production deployments requiring API stability. |
 | `provider.google.gemini-api-key` | string | *(not set)* | `GEMINI_API_KEY` | API key for Google Gemini models. Required when using Gemini-based actors. The standard `GEMINI_API_KEY` environment variable is checked for compatibility with Google's tooling. |
 | `provider.huggingface.token` | string | *(not set)* | `HF_TOKEN` | Access token for Hugging Face Inference API. Required when using Hugging Face-hosted models. The standard `HF_TOKEN` environment variable is checked for compatibility with Hugging Face tooling. |
 | `provider.openrouter.api-key` | string | *(not set)* | `OPENROUTER_API_KEY` | API key for OpenRouter. Required when using OpenRouter as a provider. |