From 8780a17f23b65c30c8ac58a9be6219fae13b7e18 Mon Sep 17 00:00:00 2001 From: Bruno Perez Date: Mon, 8 Jun 2026 16:13:42 +0200 Subject: [PATCH] docs: clarify that fewer parameters can be correct Newer reasoning models legitimately expose fewer parameters than their predecessors. Providers remove sampling controls (temperature, top_p, top_k) and fixed thinking budgets, so a smaller list is often right, not incomplete. Opus 4.7/4.8 and the GPT-5/o-series are examples already in the catalog. Document this in CONTRIBUTING.md and the schema convention so thin param lists aren't mistaken for incomplete entries. Sending a removed parameter returns an API error, so backfilling it would describe a request the model rejects. --- CONTRIBUTING.md | 22 ++++++++++++++++++++++ docs/model-parameters-schema.md | 16 ++++++++++++++++ 2 files changed, 38 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cd8c4c6..c4b0e04 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -114,6 +114,28 @@ params: thinking.type: enabled ``` +## Fewer parameters can be correct + +A model's parameter list is exactly what its API accepts today — not a superset of +what older models in the family accepted. Providers drop knobs on newer models, and +reasoning-focused releases in particular tend to remove sampling controls +(`temperature`, `top_p`, `top_k`) and fixed thinking budgets. So a newer model with +_fewer_ parameters than its predecessor is usually correct, not incomplete. + +Two examples already in the catalog: + +- **Anthropic Claude Opus 4.7 / 4.8** list four parameters where Opus 4.5 / 4.6 list + eight. `temperature`, `top_p`, `top_k`, and `thinking.budget_tokens` were removed: + extended thinking with a fixed budget is gone, so `thinking.type` no longer offers + `enabled` — only adaptive thinking remains. +- **OpenAI GPT-5 and the `o`-series** expose only `max_completion_tokens` and + `reasoning_effort` — sampling parameters don't apply to those models. + +Before reporting a model's parameters as incomplete, check the provider's current +API reference for that specific model. If the API no longer accepts a parameter, it +does not belong in the catalog — even if a sibling model still lists it. Adding it +back would describe a request the model rejects. + ## Removing parameters is blocked Once a parameter is published for a model, **it cannot be removed**. People using diff --git a/docs/model-parameters-schema.md b/docs/model-parameters-schema.md index 212c207..b6ac082 100644 --- a/docs/model-parameters-schema.md +++ b/docs/model-parameters-schema.md @@ -86,6 +86,22 @@ not belong in `params`: - pricing and rate limits - UI-only control metadata +A model's parameter list reflects what its API accepts today, not what earlier +models in the same family accepted. Providers routinely drop knobs on newer +models; reasoning-tuned releases in particular tend to remove sampling controls +(`temperature`, `top_p`, `top_k`) and fixed thinking budgets. A newer model that +exposes fewer parameters than its predecessor is expected, not a sign of an +incomplete entry. List exactly what the current API reference documents — do not +carry a parameter forward only because a sibling model still has it. + +For example, Anthropic's Claude Opus 4.7 and 4.8 drop `temperature`, `top_p`, +`top_k`, and `thinking.budget_tokens` (fixed-budget extended thinking is gone, so +`thinking.type` no longer offers `enabled` — only adaptive thinking remains). +Each lists four parameters where Opus 4.5 and 4.6 list eight. OpenAI's GPT-5 and +`o`-series reasoning models expose only `max_completion_tokens` and +`reasoning_effort` for the same reason. Sending a removed parameter returns an +API error, so listing it would describe a request the model rejects. + ## Applicability `applicability` controls whether a parameter is available for the current draft