From 51448f2bfa7d7576bba656dc55ccd5bc560284f0 Mon Sep 17 00:00:00 2001
From: Rizel Scarlett <rizel@squareup.com>
Date: Sat, 2 Aug 2025 21:04:00 -0400
Subject: [PATCH] Add settings field documentation to recipe guides

- Added comprehensive settings section to recipe-reference.md with field descriptions, examples, and usage notes
- Enhanced settings section in recipes-tutorial.md with complete provider/model configuration examples
- Documents goose_provider, goose_model, and temperature settings for recipe-specific model configuration
---
 .../docs/guides/recipes/recipe-reference.md   | 38 +++++++++++++++++++
 .../docs/tutorials/recipes-tutorial.md        | 13 ++++++-
 2 files changed, 50 insertions(+), 1 deletion(-)

diff --git a/documentation/docs/guides/recipes/recipe-reference.md b/documentation/docs/guides/recipes/recipe-reference.md
index 89366be2b355..8ce47d4d96de 100644
--- a/documentation/docs/guides/recipes/recipe-reference.md
+++ b/documentation/docs/guides/recipes/recipe-reference.md
@@ -79,6 +79,7 @@ Goose automatically adds metadata fields to recipes saved from the Desktop app.
 | `prompt` | String | A template prompt that can include parameter substitutions; required in headless (non-interactive) mode |
 | `parameters` | Array | List of parameter definitions |
 | `extensions` | Array | List of extension configurations |
+| `settings` | Object | Configuration for model provider, model name, and other settings |
 | `sub_recipes` | Array | List of sub-recipes |
 | `response` | Object | Configuration for structured output validation |
 | `retry` | Object | Configuration for automated retry logic with success validation |
@@ -165,6 +166,38 @@ extensions:
     description: "For searching logs using Presidio"
 ```
 
+## Settings
+
+The `settings` field allows you to configure the AI model and provider settings for the recipe. This overrides the default configuration when the recipe is executed.
+
+### Settings Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `goose_provider` | String | (Optional) The AI provider to use (e.g., "anthropic", "openai") |
+| `goose_model` | String | (Optional) The specific model name to use |
+| `temperature` | Number | (Optional) The temperature setting for the model (typically 0.0-1.0) |
+
+### Example Settings Configuration
+
+```yaml
+settings:
+  goose_provider: "anthropic"
+  goose_model: "claude-3-5-sonnet-latest"
+  temperature: 0.7
+```
+
+```yaml
+settings:
+  goose_provider: "openai"
+  goose_model: "gpt-4o"
+  temperature: 0.3
+```
+
+:::note
+Settings specified in a recipe will override your default Goose configuration when that recipe is executed. If no settings are specified, Goose will use your configured defaults.
+:::
+
 ## Sub-Recipes
 
 The `sub_recipes` field specifies the [sub-recipes](/docs/guides/recipes/sub-recipes) that the main recipe calls to perform specific tasks. Each sub-recipe in the array has the following structure:
@@ -379,6 +412,11 @@ extensions:
     bundled: true
     description: "Query codesearch directly from goose"
 
+settings:
+  goose_provider: "anthropic"
+  goose_model: "claude-3-5-sonnet-latest"
+  temperature: 0.7
+
 retry:
   max_retries: 3
   timeout_seconds: 30
diff --git a/documentation/docs/tutorials/recipes-tutorial.md b/documentation/docs/tutorials/recipes-tutorial.md
index 6a3611e1fd13..7100420095e6 100644
--- a/documentation/docs/tutorials/recipes-tutorial.md
+++ b/documentation/docs/tutorials/recipes-tutorial.md
@@ -82,11 +82,22 @@ goose run --recipe trip.yaml --params destination=Africa --params duration=14
 
 By default, Goose uses the `temperature` and `model` you've already chosen, which usually works just fine. But sometimes you might want more control. For example, when performing a subjective task like planning a trip, it can help to turn up the `temperature` setting. Think of temperature like a creativity dial - the higher it is, the more varied and unexpected the results. If the first suggestion isn't quite right, the user can just run the recipe again to get a new one.
 
+You can also specify which AI provider and model to use for a specific recipe:
+
 ```yaml
 settings:
-    temperature: 0.8
+  goose_provider: "anthropic"
+  goose_model: "claude-3-5-sonnet-latest"
+  temperature: 0.8
 ```
 
+The available settings are:
+- `goose_provider`: The AI provider (e.g., "anthropic", "openai")
+- `goose_model`: The specific model name
+- `temperature`: Controls creativity/randomness (0.0-1.0, higher = more creative)
+
+These settings will override your default Goose configuration when this recipe runs.
+
 ## External Files
 
 Sometimes, you'll want to give the agent access to extra information without cramming all that data into the prompt. Instead of pasting everything in, you can keep the data in a separate file and point the recipe to it.