update the chat prompt part and refine according to comments

ChenJieting · ChenJieting · commit ebbd11111e38 · 2024-05-07T17:10:40.000+08:00
diff --git a/articles/ai-studio/how-to/prompt-flow-tools/llm-tool.md b/articles/ai-studio/how-to/prompt-flow-tools/llm-tool.md
@@ -127,7 +127,7 @@ The output varies depending on the API you selected for inputs.
 
 Prepare a prompt as described in the [Prompt tool](prompt-tool.md#prerequisites) documentation. The LLM tool and Prompt tool both support [Jinja](https://jinja.palletsprojects.com/en/3.1.x/) templates. For more information and best practices, see [Prompt engineering techniques](../../../ai-services/openai/concepts/advanced-prompt-engineering.md).
 
-For example, for a chat prompt we offer a method to distinguish between different roles, such as "system," "user," "assistant." Each role can have "name" and "content" properties.
+For example, for a chat prompt we offer a method to distinguish between different roles in a chat prompt, such as "system", "user", "assistant" and "tool". The "system", "user", "assistant" roles can have "name" and "content" properties. The "tool" role, however, should have "tool_call_id" and "content" properties. For an example of a tool chat prompt, please refer to [Sample 3](#sample-3).
 
 ### Sample 1
 ```jinja
@@ -191,6 +191,67 @@ In LLM tool, the prompt is transformed to match the [openai messages](https://pl
 ]
 ```
 
+### Sample 3
+This sample illustrates how to write a tool chat prompt.
+```jinja
+# system:
+You are a helpful assistant.
+# user:
+What is the current weather like in Boston?
+# assistant:
+{# The assistant message with 'tool_calls' must be followed by messages with role 'tool'. #}
+## tool_calls:
+{{llm_output.tool_calls}}
+# tool:
+{#
+Messages with role 'tool' must be a response to a preceding message with 'tool_calls'.
+Additionally, 'tool_call_id's should match ids of assistant message 'tool_calls'.
+#}
+## tool_call_id:
+{{llm_output.tool_calls[0].id}}
+## content:
+{{tool-answer-of-last-question}}
+# user:
+{{question}}
+```
+
+In LLM tool, the prompt is transformed to match the [openai messages](https://platform.openai.com/docs/api-reference/chat/create#chat-create-messages) structure before sending to openai chat API.
+
+```
+[
+    {
+        "role": "system",
+        "content": "You are a helpful assistant."
+    },
+    {
+        "role": "user",
+        "content": "What is the current weather like in Boston?"
+    },
+    {
+        "role": "assistant",
+        "content": null,
+        "function_call": null,
+        "tool_calls": [
+            {
+                "id": "<tool-call-id-of-last-question>",
+                "type": "function",
+                "function": "<function-to-call-of-last-question>"
+            }
+        ]
+    },
+    {
+        "role": "tool",
+        "tool_call_id": "<tool-call-id-of-last-question>",
+        "content": "<tool-answer-of-last-question>"
+    }
+    ...
+    {
+        "role": "user",
+        "content": "<question>"
+    }
+]
+```
+
 ## Next steps
 
 - [Learn more about how to create a flow](../flow-develop.md)
diff --git a/articles/machine-learning/prompt-flow/tools-reference/llm-tool.md b/articles/machine-learning/prompt-flow/tools-reference/llm-tool.md
@@ -117,7 +117,7 @@ The following sections show various inputs.
 
 _To grasp the fundamentals of creating a chat prompt, begin with the [Write a prompt section](prompt-tool.md#write-a-prompt) for an introductory understanding of Jinja._
 
-We offer a method to distinguish between different roles in a chat prompt, such as "system," "user," "assistant." Each role can have "name" and "content" properties.
+We offer a method to distinguish between different roles in a chat prompt, such as "system", "user", "assistant" and "tool". The "system", "user", "assistant" roles can have "name" and "content" properties. The "tool" role, however, should have "tool_call_id" and "content" properties. For an example of a tool chat prompt, please refer to [Sample 3](#sample-3).
 
 ### Sample 1
 ```jinja
@@ -180,3 +180,64 @@ In LLM tool, the prompt is transformed to match the [openai messages](https://pl
     }
 ]
 ```
+
+### Sample 3
+This sample illustrates how to write a tool chat prompt.
+```jinja
+# system:
+You are a helpful assistant.
+# user:
+What is the current weather like in Boston?
+# assistant:
+{# The assistant message with 'tool_calls' must be followed by messages with role 'tool'. #}
+## tool_calls:
+{{llm_output.tool_calls}}
+# tool:
+{#
+Messages with role 'tool' must be a response to a preceding message with 'tool_calls'.
+Additionally, 'tool_call_id's should match ids of assistant message 'tool_calls'.
+#}
+## tool_call_id:
+{{llm_output.tool_calls[0].id}}
+## content:
+{{tool-answer-of-last-question}}
+# user:
+{{question}}
+```
+
+In LLM tool, the prompt is transformed to match the [openai messages](https://platform.openai.com/docs/api-reference/chat/create#chat-create-messages) structure before sending to openai chat API.
+
+```
+[
+    {
+        "role": "system",
+        "content": "You are a helpful assistant."
+    },
+    {
+        "role": "user",
+        "content": "What is the current weather like in Boston?"
+    },
+    {
+        "role": "assistant",
+        "content": null,
+        "function_call": null,
+        "tool_calls": [
+            {
+                "id": "<tool-call-id-of-last-question>",
+                "type": "function",
+                "function": "<function-to-call-of-last-question>"
+            }
+        ]
+    },
+    {
+        "role": "tool",
+        "tool_call_id": "<tool-call-id-of-last-question>",
+        "content": "<tool-answer-of-last-question>"
+    }
+    ...
+    {
+        "role": "user",
+        "content": "<question>"
+    }
+]
+```
diff --git a/articles/machine-learning/prompt-flow/tools-reference/overview.md b/articles/machine-learning/prompt-flow/tools-reference/overview.md
@@ -33,13 +33,11 @@ The following table shows an index of tools in prompt flow.
 | [Azure OpenAI GPT-4 Turbo with Vision](./azure-open-ai-gpt-4v-tool.md) | Use AzureOpenAI GPT-4 Turbo with Vision model deployment to analyze images and provide textual responses to questions about them. | Default | [promptflow-tools](https://pypi.org/project/promptflow-tools/) |
 | [OpenAI GPT-4V](./openai-gpt-4v-tool.md) | Use OpenAI GPT-4V to leverage vision ability. | Default | [promptflow-tools](https://pypi.org/project/promptflow-tools/) |
 | [Index Lookup](./index-lookup-tool.md)* | Search an Azure Machine Learning Vector Index for relevant results using one or more text queries. | Default | [promptflow-vectordb](https://pypi.org/project/promptflow-vectordb/) |
-| [Faiss Index Lookup](./faiss-index-lookup-tool.md)*<sup>1</sup> | Searches a vector-based query from the Faiss index file. | Default | [promptflow-vectordb](https://pypi.org/project/promptflow-vectordb/) |
-| [Vector DB Lookup](./vector-db-lookup-tool.md)*<sup>1</sup>| Searches a vector-based query from existing vector database. | Default | [promptflow-vectordb](https://pypi.org/project/promptflow-vectordb/) |
-| [Vector Index Lookup](./vector-index-lookup-tool.md)*<sup>1</sup> | Searches text or a vector-based query from Azure Machine Learning vector index. | Default | [promptflow-vectordb](https://pypi.org/project/promptflow-vectordb/) |
+| [Faiss Index Lookup](./faiss-index-lookup-tool.md)* | Searches a vector-based query from the Faiss index file. | Default | [promptflow-vectordb](https://pypi.org/project/promptflow-vectordb/) |
+| [Vector DB Lookup](./vector-db-lookup-tool.md)* | Searches a vector-based query from existing vector database. | Default | [promptflow-vectordb](https://pypi.org/project/promptflow-vectordb/) |
+| [Vector Index Lookup](./vector-index-lookup-tool.md)* | Searches text or a vector-based query from Azure Machine Learning vector index. | Default | [promptflow-vectordb](https://pypi.org/project/promptflow-vectordb/) |
 | [Azure AI Language tools](https://microsoft.github.io/promptflow/integrations/tools/azure-ai-language-tool.html)* | This collection of tools is a wrapper for various Azure AI Language APIs, which can help effectively understand and analyze documents and conversations. The capabilities currently supported include: Abstractive Summarization, Extractive Summarization, Conversation Summarization, Entity Recognition, Key Phrase Extraction, Language Detection, PII Entity Recognition, Conversational PII, Sentiment Analysis, Conversational Language Understanding, Translator. You can learn how to use them by the [Sample flows](https://github.com/microsoft/promptflow/tree/e4542f6ff5d223d9800a3687a7cfd62531a9607c/examples/flows/integrations/azure-ai-language). Support contact: taincidents@microsoft.com | Custom | [promptflow-azure-ai-language](https://pypi.org/project/promptflow-azure-ai-language/) |
 
-_<sup>1</sup> The Index Lookup tool replaces the three deprecated legacy index tools: Vector Index Lookup, Vector DB Lookup, and Faiss Index Lookup. If you have a flow that contains one of those tools, follow the [migration steps](./index-lookup-tool.md#how-to-migrate-from-legacy-tools-to-the-index-lookup-tool) to upgrade your flow._
-
 _*The asterisk marks indicate custom tools, which are created by the community that extend prompt flow's capabilities for specific use cases. They aren't officially maintained or endorsed by prompt flow team. When you encounter questions or issues for these tools, prioritize using the support contact if it's provided in the description._
 
 To discover more custom tools developed by the open-source community, see [More custom tools](https://microsoft.github.io/promptflow/integrations/tools/index.html). 
