Add missing CompletionsFinishReason comments. Update tool choice rela…

…ted models to use the work `choice` instead of selection, similar to OAI TypeSpec

specification/ai/ModelClient/models/chat_completions.tsp

@@ -102,7 +102,7 @@ alias ChatCompletionsOptions = {
   @doc("""
     If specified, the model will configure which of the provided tools it can use for the chat completions response.
     """)
-  toolChoice?: ChatCompletionsToolSelection;
+  toolChoice?: ChatCompletionsToolChoice;
 
   @doc("""
     If specified, the system will make a best effort to sample deterministically such that repeated requests with the
@@ -389,13 +389,11 @@ model ChatResponseMessage {
   toolCalls?: ChatCompletionsToolCall[];
 }
 
-// tool_choice: "auto" | "none" | "required" | {"type": "function", "function": {"name": string}}
-
 #suppress "@azure-tools/typespec-autorest/union-unsupported" "External API shape is defined in OpenAPI 3.0 as oneOf."
-alias ChatCompletionsToolSelection = ChatCompletionsToolSelectionPreset | ChatCompletionsNamedToolSelection;
+alias ChatCompletionsToolChoice = ChatCompletionsToolChoicePreset | ChatCompletionsNamedToolChoice;
 
 @doc("Represents a generic policy for how a chat completions tool may be selected.")
-union ChatCompletionsToolSelectionPreset {
+union ChatCompletionsToolChoicePreset {
   string,
 
   @doc("""
@@ -417,16 +415,16 @@ union ChatCompletionsToolSelectionPreset {
 }
 
 @doc("A tool selection of a specific, named function tool that will limit chat completions to using the named function.")
-model ChatCompletionsNamedToolSelection {
+model ChatCompletionsNamedToolChoice {
   @doc("The type of the tool. Currently, only `function` is supported.")
   type: "function";
 
   @doc("The function that should be called.")
-  function: ChatCompletionsFunctionToolSelection;
+  function: ChatCompletionsNamedToolChoiceFunction;
 }
 
 @doc("A tool selection of a specific, named function tool that will limit chat completions to using the named function.")
-model ChatCompletionsFunctionToolSelection {
+model ChatCompletionsNamedToolChoiceFunction {
   @doc("The name of the function that should be called.")
   name: string;
 }

specification/ai/ModelClient/models/common.tsp

@@ -10,13 +10,13 @@ namespace AI.Model;
 union EmbeddingInputType {
   string,
 
-  @doc("to do")
+  @doc("Indicates the input is a general text input.")
   text: "text",
 
-  @doc("to do")
+  @doc("Indicates the input represents a search query to find the most relevant documents in your vector database.")
   query: "query",
 
-  @doc("to do")
+  @doc("Indicates the input represents a document that is stored in a vector database.")
   document: "document",
 }