AITK v0-16-1 docs update (#8588)

* Initial changes

* updates based on feredback

* update link

* updated based on feedback

* Updated based on feedback

Author: ms-johnalex

docs/intelligentapps/agentbuilder.md

@@ -1,12 +1,12 @@
 ---
 ContentId: bd3d7555-3d84-4500-ae95-6dcd39641af0
-DateApproved: 06/16/2025
+DateApproved: 07/14/2025
 MetaDescription: Get Started with creating, iterating and optimizing your agents in AI Toolkit.
 ---
 # Build agents and prompts in AI Toolkit
 
 > [!NOTE]
-> Agent Builder was previously known as Prompt Builder. The name has been changed to better reflect the feature's capabilities and its focus on building agents.
+> Agent Builder was previously known as Prompt Builder. The updated name better reflects the feature's capabilities and its focus on building agents.
 
 Agent Builder in AI Toolkit streamlines the engineering workflow for building agents, including prompt engineering and integration with tools, such as MCP servers. It helps with common prompt engineering tasks:
 - Generate starter prompts
@@ -25,22 +25,22 @@ Agent Builder also enhances intelligent app's capabilities with tool use:
 
 To access Agent Builder, use either of these options:
 
-- In the AI Toolkit view, select **Agent (Prompt) Builder**
-- Select **Try in Agent (Prompt) Builder** from a model card in the model catalog
+- In the AI Toolkit view, select **Agent Builder**
+- Select **Try in Agent Builder** from a model card in the model catalog
 
 To test a prompt in Agent Builder, follow these steps:
 
 1. In **Models**, select a model from the dropdown list, or select **Browse models** to add another model from the model catalog.
 
-   ![Screenshot showing the model selection dropdown in Agent Builder.](./images/promptbuilder/select_models.png)
+   ![Screenshot showing the model selection dropdown in Agent Builder.](./images/promptbuilder/select-models.png)
 
 1. Enter a **User prompt** and optionally enter a **System prompt**.
 
    The *user prompt* is the input that you want to send to the model. The optional *system prompt* is used to provide instructions with relevant context to guide the model response.
 
    > [!TIP]
    > Describe your project idea using natural language to generate prompts automatically.
-   > ![Screenshot showing natural language prompt generation in Agent Builder.](./images/promptbuilder/generate_prompt_2.gif)
+   > ![Screenshot showing natural language prompt generation in Agent Builder.](./images/promptbuilder/generate-prompt-2.gif)
 
 3. Select **Run** to send the prompts to the model.
 
@@ -51,11 +51,11 @@ To test a prompt in Agent Builder, follow these steps:
 ## Use MCP servers
 MCP server is a tool that allows you to connect to external APIs and services, enabling your agent to perform actions beyond just generating text. For example, you can use an MCP server to access databases, call web services, or interact with other applications.
 
-You can use the agent builder to discover and configure featured MCP servers, connect to existing MCP servers or build a new MCP server from scaffold.
+Use the agent builder to discover and configure featured MCP servers, connect to existing MCP servers, or build a new MCP server from scaffold.
 
 > [!NOTE]
-> Using MCP servers may require either [Node](https://nodejs.org/en/download) or [Python](https://www.python.org/downloads/) environment. AI Toolkit will validate your environment to ensure that the required dependencies are installed.
-> After installing, please use the command `npm install -g npx` to install `npx`. If you prefer Python, we recommend using [`uv`](https://docs.astral.sh/uv/getting-started/installation/)
+> Using MCP servers might require either [Node](https://nodejs.org/en/download) or [Python](https://www.python.org/downloads/) environment. AI Toolkit validates your environment to ensure that the required dependencies are installed.
+> After installing, use the command `npm install -g npx` to install `npx`. If you prefer Python, we recommend using [`uv`](https://docs.astral.sh/uv/getting-started/installation/)
 
 ### Configure a featured MCP server
 AI Toolkit provides a list of featured MCP servers that you can use to connect to external APIs and services.
@@ -64,10 +64,10 @@ To configure an MCP server from featured selections, follow these steps:
 1. In the **Tools** section, select **+ MCP Server**, and then select **+ Add server** in the Quick Pick.
 2. Select **Use Featured MCP Servers** from the dropdown list.
 3. Choose an MCP server that meets your needs.
-   ![connect to MCP server](./images/promptbuilder/featured_server_2.png)
+   ![Screenshot showing the connect to MCP server interface in Agent Builder.](./images/promptbuilder/featured-server-2.png)
 4. Enter a name for the server.
 5. Select tools you want to use.
-   ![select_tools](./images/promptbuilder/select_tools.png)
+   ![Screenshot showing the select tools interface in Agent Builder.](./images/promptbuilder/select-tools.png)
 
 ### Use an existing MCP server
 > [!TIP]
@@ -82,23 +82,24 @@ To use an existing MCP server, follow these steps:
 4. Select tools from the MCP server if there are multiple tools available.
 5. Enter your prompts and select **Run** to test the connection.
 
-Here is an example of configuring the [Filesystem](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem) server in AI Toolkit:
+Here's an example of configuring the [Filesystem](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem) server in AI Toolkit:
+
 1. In the **Tools** section, select **+ MCP Server**, and then select **+ Add server** in the Quick Pick.
-2. Select **Connect to an Existing MCP Server**
-3. Select **Command (stdio)**
+1. Select **Connect to an Existing MCP Server**
+1. Select **Command (stdio)**
    > [!NOTE]
    > Some servers use the Python runtime and the `uvx` command. The process is the same as using the `npx` command.
-4. Navigate to the [Server instructions](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem#npx) and locate the `npx` section.
-5. Copy the `command` and `args` into the input box in AI Toolkit. For the Filesystem server example, it will be `npx -y @modelcontextprotocol/server-filesystem /Users/<username>/.aitk/examples`
-6. Input a name for the server.
-7. Optionally, enter additional environment variables.
-   Some servers might require additional environment variables such as API keys. In this case, AI Toolkit will fail at the stage of adding tools and a file `mcp.json` will open, where you can enter the required server details following the instructions provided by each server.
-   ![Modify args](./images/promptbuilder/modify_args.png)
-   Once completed the configuration:
-   1. Navigate back to **Tools** section and select **+ MCP Server**
-   2. Select the server you just configured from the dropdown list
-   3. Select tools you want to use.
-8. Select tools you want to use.
+1. Navigate to the [Server instructions](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem#npx) and locate the `npx` section.
+1. Copy the `command` and `args` into the input box in AI Toolkit. For the Filesystem server example, it's `npx -y @modelcontextprotocol/server-filesystem /Users/<username>/.aitk/examples`
+1. Input a name for the server.
+1. Optionally, enter extra environment variables.
+   Some servers might require extra environment variables such as API keys. In this case, AI Toolkit fails at the stage of adding tools and a file `mcp.json` opens, where you can enter the required server details following the instructions provided by each server.
+   ![Screenshot showing an example of a missing arg exception](./images/promptbuilder/modify-args.png)
+   After you complete the configuration:
+       1. Navigate back to **Tools** section and select **+ MCP Server**
+       1. Select the server you configured from the dropdown list
+
+1. Select the tools you want to use.
 
 ![connect to MCP server](./images/promptbuilder/mcp_existing.gif)
 
@@ -107,76 +108,76 @@ AI Toolkit also provides a scaffold to help you build a new MCP server. The scaf
 ### Build a new MCP server
 To build a new MCP server, follow these steps:
 1. In the **Tools** section, select **+ MCP Server**, and then select **+ Add server** in the quick pick.
-2. Select **Create a New MCP Server**
-3. Select a programming language from the dropdown list: **Python** or **TypeScript**
-4. Select a folder to create the new MCP server project in.
-5. Enter a name for the MCP server project.
+1. Select **Create a New MCP Server**
+1. Select a programming language from the dropdown list: **Python** or **TypeScript**
+1. Select a folder to create the new MCP server project in.
+1. Enter a name for the MCP server project.
 
-![scaffold mcp](./images/promptbuilder/scaffold_mcp.gif)
+![Animated GIF showing how to use the scaffold mcp](./images/promptbuilder/scaffold-mcp.gif)
 
 After you create the MCP server project, you can customize the implementation to suit your needs. The scaffold includes a basic implementation of the MCP protocol, which you can modify to add your own functionality.
 
-You can also use the agent builder to test the MCP server. The agent builder will send the prompts to the MCP server and display the response.
+You can also use the agent builder to test the MCP server. The agent builder sends the prompts to the MCP server and displays the response.
 
 Follow these steps to test the MCP server:
 
 > [!NOTE]
-> To run the MCP Server in your local dev machine, you will need: [Node.js](https://nodejs.org/) or Python installed on your machine.
+> To run the MCP Server in your local dev machine, you need: [Node.js](https://nodejs.org/) or Python installed on your machine.
 
 1. Open VS Code Debug panel. Select `Debug in Agent Builder` or press `F5` to start debugging the MCP server.
-2. Use AI Toolkit Agent Builder to test the server with the following prompt:
+1. Use AI Toolkit Agent Builder to test the server with the following prompt:
    1. System Prompt: You are a weather forecast professional that can tell weather information based on given location.
-3. The server will be automatically connected to Agent Builder.
-4. Select `Run` to test the server with the prompt.
+1. The server is automatically connected to Agent Builder.
+1. Select `Run` to test the server with the prompt.
 
-![debug mcp](./images/promptbuilder/mcp_debug.gif)
+![Animated GIF showing the debug mcp process](./images/promptbuilder/mcp-debug.gif)
 
 ## Use function calling
 
 Function calling connects your agent to external APIs and services.
 
-![Screenshot showing the Add Custom Function Tool dialog with options to add tools by example or upload schemas.](./images/promptbuilder/add_function_call.png)
+![Screenshot showing the Add Custom Function Tool dialog with options to add tools by example or upload schemas.](./images/promptbuilder/add-function-call.png)
 
 1. In **Tools**, select **Add Tool**, then **Custom Tool**.
-2. Choose how to add the tool:
+1. Choose how to add the tool:
    - **By Example**: Add from a JSON schema example
    - **Upload Existing Schema**: Upload a JSON schema file
-3. Enter the tool name and description, then select **Add**.
-4. Provide a mock response in the tool card.
+1. Enter the tool name and description, then select **Add**.
+1. Provide a mock response in the tool card.
 
-![Screenshot showing a function calling tool card with weather tool configuration.](./images/promptbuilder/function_call_card.png)
+![Screenshot showing a function calling tool card with weather tool configuration.](./images/promptbuilder/function-call-card.png)
 
-5. Run the agent with the function calling tool.
+1. Run the agent with the function calling tool.
 
 Use function calling tools in the **Evaluation** tab by entering mock responses for test cases.
 
-![Screenshot showing function calling tool usage in the evaluation tab.](./images/promptbuilder/function_call_eval.png)
+![Screenshot showing function calling tool usage in the evaluation tab.](./images/promptbuilder/function-call-eval.png)
 
 ## Structured output
 
 Structured output support helps you design prompts to deliver outputs in a structured, predictable format.
 
-![Use structured output](./images/promptbuilder/structured_output_2.gif)
+![Animated GIF showing how to use structured output](./images/promptbuilder/structured-output-2.gif)
 
 To test using structured output in Agent Builder, follow these steps:
 
 1. Select the **Structure output** from the left area, and select **json_schema**.
 
-2. Select **Prepare schema**, and then select **Select local file** to use your own schema, or select **Use an example** to use a predefined schema.
+1. Select **Prepare schema**, and then select **Select local file** to use your own schema, or select **Use an example** to use a predefined schema.
 
    If you proceed with an example, you can select a schema from the dropdown list.
 
-3. Select **Run** to send the prompts to the selected model.
+1. Select **Run** to send the prompts to the selected model.
 
-4. You can also edit the schema by selecting name of the schema.
+1. You can also edit the schema by selecting name of the schema.
 
-   ![edit schema](./images/promptbuilder/edit_schema_2.png)
+   ![Screenshot showing the edit schema dropdown in Agent Builder.](./images/promptbuilder/edit-schema-2.png)
 
 ## Integrate prompt engineering into your application
 
 After experimenting with models and prompts, you can get into coding right away with the automatically generated Python code.
 
-![view code](./images/promptbuilder/view_code_2.gif)
+![Animated GIF showing the generated Python code](./images/promptbuilder/view-code-2.gif)
 
 To view the Python code, follow these steps:
 

docs/intelligentapps/bulkrun.md

@@ -1,6 +1,6 @@
 ---
 ContentId: 1124d141-e893-4780-aba7-b6ca13628bc5
-DateApproved: 06/16/2025
+DateApproved: 07/14/2025
 MetaDescription: Run a set of prompts with variables or function calls with an imported or synthetically generated dataset towards the selected models and parameters.
 ---
 # Run multiple prompts in bulk
@@ -27,7 +27,7 @@ To start a bulk run in AI Toolkit, follow these steps:
 
 1. Select **Generate Data** to create a synthetic dataset.
 1. Choose the number of rows to generate and view or modify the data generation logic.
-    ![Screenshot showing Generate Data dialog in AI Toolkit.](./images/bulkrun/generate_data.png)
+    ![Screenshot showing Generate Data dialog in AI Toolkit.](./images/bulkrun/generate-data.png)
 1. Select **Generate** to create the dataset.
 
 > [!TIP]
@@ -37,7 +37,7 @@ To start a bulk run in AI Toolkit, follow these steps:
 
 ## Operate on dataset
 
-![Screenshot showing AI Toolkit interface with dataset operations and a table of evaluation results.](./images/bulkrun/dataset_operation.png)
+![Screenshot showing AI Toolkit interface with dataset operations and a table of evaluation results.](./images/bulkrun/dataset-operation.png)
 
 AI Toolkit provides several operations to manage and analyze your dataset during a bulk run:
 
@@ -55,11 +55,11 @@ AI Toolkit provides several operations to manage and analyze your dataset during
 
 AI Toolkit lets you evaluate the results of your bulk run directly in the dataset view.
 
-![Screenshot showing AI Toolkit interface in full screen mode with the Evaluation tab expanded. The dataset table displays multiple columns, including query prompts and AI responses, for detailed analysis.](./images/bulkrun/full_screen.png)
+![Screenshot showing AI Toolkit interface in full screen mode with the Evaluation tab expanded. The dataset table displays multiple columns, including query prompts and AI responses, for detailed analysis.](./images/bulkrun/full-screen.png)
 
 You can expand the **Evaluation** tab to full screen mode for a more detailed view of the results. Full screen mode provides the same functionality as the standard view, but with a larger display area for better visibility and analysis.
 
-![Screenshot showing detailed view of evaluation results with a modal dialog displaying a full conversation between user and assistant about weather queries.](./images/bulkrun/view_detail.png)
+![Screenshot showing detailed view of evaluation results with a modal dialog displaying a full conversation between user and assistant about weather queries.](./images/bulkrun/view-detail.png)
 
 Select **View Details** to see the full response for each query.
 
@@ -74,7 +74,7 @@ In the detail view, you can:
 
 ## Manage data columns
 
-![Screenshot showing AI Toolkit interface with dataset management options and column management controls.](./images/bulkrun/manage_columns.png)
+![Screenshot showing AI Toolkit interface with dataset management options and column management controls.](./images/bulkrun/manage-columns.png)
 
 With data column management, you can customize the dataset view to focus on the most relevant information for your bulk run analysis.