docs: Update NSQL API for optional model field, sample_data default, and tools auto mode

Source: spiceai/spiceai#10715

Author: claudespice

website/docs/api/HTTP/post-nsql.api.mdx

@@ -59,7 +59,7 @@ When `stream` is true, the response is streamed as Server-Sent Events (SSE).
 
 <RequestSchema
   title={"Body"}
-  body={{"description":"Request body to generate an NSQL query","content":{"application/json":{"schema":{"type":"object","required":["query"],"properties":{"datasets":{"type":["array","null"],"items":{"type":"string"},"description":"Names of datasets to sample from when constructing model context; this is a sampling hint and does not restrict which tables queries can target. If omitted, all datasets are used."},"model":{"type":"string","description":"The name of the model to use for SQL generation. Default: \"nql\""},"query":{"type":"string","description":"The natural language query to be converted into SQL"},"sample_data_enabled":{"type":"boolean","description":"Whether sample data is included in the context for SQL generation. Default: true"},"stream":{"type":"boolean","description":"If true, streams the response instead of waiting for completion"}},"title":"Request"},"example":{"query":"Get the top 5 customers by total sales","model":"nql","stream":false,"sample_data_enabled":true,"datasets":["sales_data"]}}},"required":true}}
+  body={{"description":"Request body to generate an NSQL query","content":{"application/json":{"schema":{"type":"object","required":["query"],"properties":{"datasets":{"type":["array","null"],"items":{"type":"string"},"description":"Names of datasets to sample from when constructing model context; this is a sampling hint and does not restrict which tables queries can target. If omitted, all datasets are used."},"model":{"type":"string","description":"The name of the model to use for SQL generation. If omitted, Spice defaults to the only compatible LLM model configured in the Spicepod."},"query":{"type":"string","description":"The natural language query to be converted into SQL"},"sample_data_enabled":{"type":"boolean","description":"Whether sample data is included in the context for SQL generation. Default: false"},"stream":{"type":"boolean","description":"If true, streams the response instead of waiting for completion"},"prompt_cache_key":{"type":["string","null"],"description":"Stable prompt-cache key forwarded to the configured NSQL model for provider-specific cache handling."}},"title":"Request"},"example":{"query":"Get the top 5 customers by total sales","stream":false,"sample_data_enabled":false,"datasets":["sales_data"],"prompt_cache_key":"sales-dashboard"}}},"required":true}}
 >
 
 </RequestSchema>

website/docs/features/large-language-models/tools.md

@@ -21,7 +21,7 @@ The `tools` parameter on a model controls how tools are provided to the LLM:
 
 | Value | Description |
 | --- | --- |
-| `auto` | Automatically choose between direct tools and searchable registry discovery. When the number of available tools exceeds 20 and an embedding model is available, `auto` switches to registry-based discovery; otherwise it uses direct tools. |
+| `auto` | Automatically choose between direct tools and searchable registry discovery, excluding data sampling tools. When the number of available tools exceeds 20 and an embedding model is available, `auto` switches to registry-based discovery; otherwise it uses direct tools. |
 | `all` | Provide all built-in and Spicepod-configured tools directly to the LLM. |
 | `search_registry` | Use searchable registry discovery. The LLM receives `tool_search` and `tool_invoke` meta-tools instead of individual tool definitions. Requires an embedding model (see `tool_embedding_model`). |
 | `<tool1>, <tool2>, ...` | Provide only the named tools directly. |

website/public/openapi.json

@@ -984,12 +984,12 @@
               },
               "example": {
                 "query": "Get the top 5 customers by total sales",
-                "model": "nql",
                 "stream": false,
-                "sample_data_enabled": true,
+                "sample_data_enabled": false,
                 "datasets": [
                   "sales_data"
-                ]
+                ],
+                "prompt_cache_key": "sales-dashboard"
               }
             }
           },
@@ -1739,7 +1739,7 @@
           "Tools"
         ],
         "summary": "Run Tool",
-        "description": "The request body and JSON response formats match the tool’s specification.",
+        "description": "The request body and JSON response formats match the tool\u2019s specification.",
         "operationId": "post",
         "parameters": [
           {
@@ -4808,19 +4808,26 @@
           },
           "model": {
             "type": "string",
-            "description": "The name of the model to use for SQL generation. Default: \"nql\""
+            "description": "The name of the model to use for SQL generation. If omitted, Spice defaults to the only compatible LLM model configured in the Spicepod."
           },
           "query": {
             "type": "string",
             "description": "The natural language query to be converted into SQL"
           },
           "sample_data_enabled": {
             "type": "boolean",
-            "description": "Whether sample data is included in the context for SQL generation. Default: true"
+            "description": "Whether sample data is included in the context for SQL generation. Default: false"
           },
           "stream": {
             "type": "boolean",
             "description": "If true, streams the response instead of waiting for completion"
+          },
+          "prompt_cache_key": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Stable prompt-cache key forwarded to the configured NSQL model for provider-specific cache handling."
           }
         }
       },