Add tools to custom agents

Tools are the building blocks that enable your agent to interact with external systems. Tools expand the functionality of your agent, allowing it to perform various actions in response to user requests or autonomous triggers. Each tool represents a specific capability that your agent can perform. For example, you can equip your agent with tools that do things like:

• Send emails using the Office 365 Outlook connector
• Check the current weather conditions and forecasts
• Read and write data from Dataverse
• Read and post messages to Teams

Mechanisms for adding tools

You can extend the capabilities of your custom agent by adding one or more tools. Tools can be used by your agent to respond to users automatically, using generative orchestration. You can also call tools explicitly from within a topic.

In classic mode (generative orchestration disabled), an agent can only use topics to respond to the user. However, you can still design your agent to call tools explicitly from within topics.

If you turn on generative orchestration, your agent can automatically select the most appropriate tool or topic, or search across knowledge, to respond to a user. This creates a more dynamic and intelligent conversation experience.

There are several mechanisms available to you to add tools to your agent:

• Prebuilt connector: Choose from a selection of preset connections to thousands of popular APIs from both Microsoft and third-party services.
• Custom connector: Define a connection to a custom service or system to enable custom tool options using Power Platform Connectors.
• Agent flow: Define an agent flow, including one or more actions to be carried out by the flow.
• Prompt: Single turn model-based prompt that can reference knowledge you provide.
• REST API connection: Define a connection to a REST API, and select one or more API endpoints and methods to add as tools.
• Model Context Protocol (MCP) tool: Connect to an MCP server to access tools.
• Computer use (preview) agent: Lets your agent interact with any system that has a graphical user interface, for websites and desktop apps, selecting buttons, choosing menus, and entering text into fields on the screen.

When we talk about tool in this article and this section of the documentation, we mean one of the mechanisms in this group. These tool types can be added to your agent and configured in similar ways.

Be aware that there are two other mechanisms you can use to add tool-like behavior to your agent:

• Skills: Container for a set of related tools.
• Client tool: Send an Event activity to the client so that the client carries out an action and returns a response.

For more information on skills and client actions, see the links in the Related content section.

Create and add a new tool at agent level

Creating new tools directly within Copilot Studio streamlines the development process and ensures proper integration with your agent. Tools added to an agent are available for automatic orchestration throughout your agent's conversations.

1. Open your agent by choosing Agents in the left hand navigation pane and selecting your agent from the list.

2. Select Tools to open the Tools tab for the agent.

3. Select Add a tool.

4. In the Add tool pane, select New tool.

5. You are presented with a list of ways to add a new tool:

   • Prompt: Create AI-powered text generation and analysis tools
   • Agent flow: Build multi-step processes with conditional logic
   • Computer use: Enable GUI automation for legacy systems
   • Custom connector: Connect to proprietary APIs and services
   • REST API: Direct integration with web services

   Select the type of tool you want to add.

6. You are taken through configuration steps specific to the type of tool you selected. For example, if you selected Prompt, you are taken through a series of steps to configure the prompt:

   • Define the prompt template and instructions
   • Specify input parameters
   • Configure knowledge sources
   • Set response format and constraints

7. Test your tool configuration using the preview panel to ensure it works as expected.

8. Once you have completed the configuration steps, select Save to create the new tool.

9. When it is done, select Add to agent to add the tool to your agent. You are returned to the Tools tab for the agent. You can see the new tool in the list of tools.

View and make changes to your tool configuration

You can view and edit the configuration of your tool at any time. To do this, go to the Tools tab for your agent, and select the tool from the list of tools.

The Tool details page opens, showing the configuration of your tool. The details are displayed in three sections:

• Details
• Inputs
• Completion (Tools for MCP connectors)

Details

The Details section lets you configure basic details about your tool.

Here, you can view and update:

• Name: The name of the tool. This is the name that appears in the list of tools for your agent. Choose descriptive names that clearly indicate the tool's function.

• Description: A description of the tool. When using generative orchestration, this description is used to help the agent determine when to use the tool. Write clear, specific descriptions including what the tool does and when it should be used.

• Additional details:

  • Allow agent to decide dynamically when to use the tool: When the checkbox is selected, the agent can use generative orchestration to determine when to use the tool. If this option is not selected, the agent will only use the tool when it is explicitly called from a topic. (By default, this option is selected when generative orchestration is enabled.)
  • Ask the end user before running: In the end user chat experience, ask the agent for confirmation before running the tool. This option is set to No by default.
  • Authentication: Select whether to use user authentication or copilot author authentication for the tool. By default, this is set to user authentication.
  • Description: Optionally, you can add a description of the tool that is shown to the user when the tool is run. This description lets the user know what they are being asked to authenticate.

Inputs

Here, you can view and configure the inputs for your tool. The inputs are used to gather information from the user to fill the required inputs for the tool. The information is displayed as a table, one line for each input.

By default, the Fill using column value for each input is set to Dynamically fill with AI. The agent tries to extract the value from available context — for example, from the user's message. If no appropriate value is found, it generates a question to ask the user for a value. Select Customize to access more fine-grained customizations for input collection and filling:

• Display name and Description: How the input will be presented to the user.
• Identify as: How the user's response will be interpreted, for example as string of text or mapped to a pre-defined entity.
• Retry logic: If the agent doesn't identify an entity in the user's statement, it can ask the question again.
• Input validation: Configure additional validation behavior on the user's input beyond the default for the entity type.

You can also choose to override an input with an explicit value instead of letting the agent extract it. To set an override, set Fill using to Custom value, and enter a value, select a variable, or use a Power FX formula. If an input is overridden, the agent won't ask the user for a value.

Completion

Here, you can select what you want to happen when the tool is done running.

You can have the agent automatically generate a contextual response for a user, based on their query and the result of the tool.

Alternatively, you can choose to author a specific, formatted response for your tool to return. You can insert references to output variables from the tool using the variable picker. You can also use Power Fx formulas to format the response.

Under After running, select one of a few different options for how the tool should respond to the user after the tool runs:

• Don't respond (default): The agent incorporates the tool output into its response
• Write the response with generative AI: Let AI craft a contextual response using the tool outputs
• Send specific response: Author a templated response with variable insertion
• Send an adaptive card: Create rich, interactive responses with buttons and actions

You can also configure which output variables to make available to the agent and other tools.

Tool selection and input collection

When you define a tool in Copilot Studio, you also provide information that describes its purpose. This information allows the agent to identify when to use the tool and also use generative AI to generate questions. These questions are used to gather information to fill the inputs needed to perform the tool. As a result, you don't need to manually author question nodes to gather all inputs needed, such as inputs in a flow. Input collection is handled for you at runtime.

The agent uses several factors to determine tool selection:

• The tool's name and description
• The current conversation context
• User intent derived from their message
• Available inputs and outputs
• Previous tool usage in the conversation

By default, when using generative mode, tools return their information back to the agent, so that the agent can generate a contextual response to the user's query. Alternatively, you can instruct your tool to always respond immediately, either generating a message or authoring an explicit message.

Call an existing tool from within a topic

You can call a tool explicitly from within a topic. Depending on your use case, you might use your tool as part of a wider topic, which uses more nodes. Or, like in the weather example, adding a single action node to a topic might be all you need.

To call a tool from within a topic:

1. In Copilot Studio, go to the Topics page for the agent you want to edit.

2. Create a new topic, and name it Get weather.

3. Add the following Trigger phrases:

   • will it rain
   • today's forecast
   • get weather
   • what's the weather

4. Select Add node (+) and then select Add a tool. Select the tool from the available tools. There are three tabs showing different types of tools:

   • Basic tools
   • Connector
   • Tool

5. Your Action node is now added to your topic.

6. Select Save.

Tools (MCP connectors only)

Under Tools, you can view the names and descriptions of the tools that are available for the MCP connector. The tools are displayed in a table, one line for each tool. For each tool, you can see:

• Tool name and version
• Input and output parameters
• Estimated execution time
• Usage statistics

Authentication considerations for tools

Some tools require authentication to work correctly, such as Dynamic Prompt or others that call a Dataverse API. Proper authentication configuration ensures security while maintaining a smooth user experience.

Tools are always run in the agent's runtime in the user context and can't be run unless authentication is enabled. Two types of authentication methods are supported:

• User authentication: The agent uses the user's credentials to authenticate with the service. This ensures users only access data they're authorized to see.
• Copilot author authentication: The agent uses the credentials of the copilot author to authenticate with the service. Use this for shared resources or when users shouldn't need individual access.

Test your tool

If you enabled generative orchestration, your tool is selected by the orchestrator when the orchestrator deems it relevant to a user query.

Alternatively, you can call an existing tool from within a topic.

Your agent selects which tools your agent selected from the tools page.

Related content

• Use connectors
• Use prompts
• Use agent flows with your agent
• Model context protocol (MCP)
• Add tools from a REST API
• Use skills
• Client actions
• Computer use (preview)