Add tools to custom agents

Note

This article describes features used in agents or agent flows powered by the standard harness.

Tools are building blocks that let your agent interact with external systems. Tools expand what your agent can do, and your agent can 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 perform tasks like:

• Send emails by 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 to agents

Note

If a tool you expect isn't available in the Add a tool pane, your organization's policies might restrict the tools available to you. Contact your administrator for help.

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

By using generative orchestration (active by default), your agent can automatically select the most appropriate tool or topic, or search across knowledge, to respond to a user. This orchestration mode creates a more dynamic and intelligent conversation experience.

In classic mode (generative orchestration turned off), 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.

You can use the following mechanisms to add tools to your agent:

• Connector: Connect to proprietary APIs and services by using Power Platform Connectors to pull in data or carry out actions.
  • Prebuilt connector: Choose from a selection of preset connections to thousands of popular APIs from both Microsoft and non-Microsoft services.
  • Custom connector: Define a connection to a custom service or system to enable custom tool options by using Power Platform Connectors. The connector needs view and share permissions for the organization for the agent to use the connector.
• Agent flow: Define an agent flow, including one or more actions to carry out.
• Prompt: Single turn model-based prompt that can reference knowledge you provide and generate code to analyze data.
• REST API: Define a connection to a REST API, and select one or more API endpoints and methods to add as tools.
• Model Context Protocol: Connect to an MCP server to access tools and resources.
• Computer use: 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.

You can also use the following mechanisms to add tool-like behavior to your agent:

• Azure Bot Service skills: Container for a set of related tools made available through the Azure Bot Service.
• Client tools: Send an event activity to the client so that the client carries out an action and returns a response.

Note

Skills in the context of the agents powered by the standard harness aren't the same as the skills used in coding agents. You can only add coding agent skills to agents powered by the GitHub Copilot harness.

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. Go to the Tools page for the agent.

3. Select Add a tool.

4. Select the type of tool you want to add from the list:

   • Agent flow
   • Prompt
   • Model Context Protocol
   • Computer use

   To show the full list, select See all. More options appear:

   • Rest API
   • Custom connector

   See all changes to See less.

   

   Note

   If your organization blocked a tool due to data policies, you can't select it. Learn more in Tools blocked by your organization's policies.

5. Perform the configuration steps specific to the type of tool you selected. For example, if you select Prompt, perform the following steps:

   • Define the prompt instructions
   • Select a model
   • Specify input parameters (by selecting + Add content)

   You can also get help by typing in the Prompt assistant field.

   As an alternative, you can use a pre-defined template to create a prompt by selecting prompt template.

6. Select Save to create the new tool.

7. Select Add and configure. The tool is added to your agent. The configuration page for your tool appears. View and make changes to your tool configuration here.

Your new tool appears on the Tools page for the agent.

Tools blocked by your organization's policies

Your organization can use governance policies to restrict which tools and connectors are available in Copilot Studio.

When a data policy blocks a tool, the tool appears disabled in the Add tool panel and you can't select it. Select the information icon next to the disabled tool to see why the tool isn't available.

The message identifies the policy restriction that prevents the tool from being used. If you need access to a blocked tool, contact your administrator.

Learn more in Configure data policies for agents.

View and make changes to your tool configuration

You can view and edit the configuration of your tool at any time. Go to the Tools page for your agent, and select the tool from the list of tools.

The configuration page for your tool opens. The details are displayed in three sections:

• Details
• Inputs
• Completion

For MCP servers connected as agent tools, the configuration page is different from other tool types. The Details section is similar, but instead of Inputs and Completion, there are Tools and Resources sections with information about available tools and resources for the MCP server. For more information, see View tools and resources in an existing MCP server.

Details

Use the Details section to configure basic details about your tool.

View and update the following information:

• Name: The name of the tool. This name appears in the list of tools for your agent. Choose a name that clearly indicates the tool's function.

• Description: A description of the tool. Generative orchestration relies on this description to determine when your agent should 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 you select this option, the agent can use generative orchestration to determine when to use the tool. If you don't select this option, the agent only uses the tool when it's 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 the user's (End user) or maker's (Maker-provided) credentials for the tool. By default, user authentication applies.
  • Description: Optionally, add a description of the tool the agent shows to the user when it wants to run the tool. This description lets the user know what they're being asked to authenticate.

Inputs

View and configure the inputs for your tool. Use the inputs to gather information from the user to fill the required inputs for the tool. The information is displayed as a table, with 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 the agent doesn't find an appropriate value, 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 appears to the user.
• Identify as: How the user's response is interpreted, for example as string of text or mapped to a predefined 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 extra 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 you override an input, the agent doesn't ask the user for a value.

Note

After you refresh a connector action, its output type can remain unresolved until you enter all required connector inputs. Enter the required values, save the topic, and then check the output variables again.

Completion

Select what you want to happen when the tool finishes 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. Use the variable picker to insert references to output variables from the tool. You can also use Power Fx formulas to format the response.

Under After running, select 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: AI crafts 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.

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 helps the agent identify when to use the tool. The tool description also helps the orchestrator use generative AI to generate questions, as needed, to collect inputs. Your agent can use questions to gather information to fill the inputs needed to use 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. The agent orchestrator handles input collection for you at runtime.

The agent considers 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

When using generative mode, by default, tools return their information back to the agent. With the tool response, 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.

Tip

When using generated questions from a tool, inform your users that AI generated some of the conversation.

For example, add an extra message in the Conversation Start system topic. This topic determines the message shown to your users when a new conversation starts.

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 that uses multiple nodes. Or, like in the following example, adding a single action (tool) 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 give it a name, such as Get weather.

3. Add appropriate Trigger phrases. To continue with the same weather example from the previous step, trigger phrases could include:

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

4. Select Add node (+) and then select Add a tool.

5. Select the tool from the available tools. Three tabs show different types of tools:

   • Basic tools
   • Connector
   • Tool

   Your Action node is now added to your topic.

6. Select Save.

MCP connector information

For the MCP connector, you can view the names and descriptions of the MCP tools and resources that the MCP connector makes available. The information for the tools and resources appears in a table, with one line for each tool.

Authentication considerations for tools

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

The agent runs tools in its runtime in the user context. You can't run tools unless authentication is enabled. The agent supports two types of authentication methods:

• End user credentials: The agent uses the user's credentials to authenticate with the service. This method ensures users only access data they're authorized to see.
• Maker-provided credentials: The agent uses the credentials of its author to authenticate with the service. Use this authentication mode for shared resources or when users shouldn't need individual access.

Test your tool

By using generative orchestration, the orchestrator selects your tool when it deems it relevant to a user query.

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

Turn a tool on or off in your agent

You can turn a tool on or off for your agent from the tool configuration page. Turning off a tool blocks the agent from using the tool, but the tool is still connected to the agent and can be turned back on later. When you add a tool to an agent, the tool is turned on by default.

To turn off a tool in an agent:

1. Go to your agent and select the Tools page for your agent.
2. Select the tool to go the tool configuration page.
3. At the top of the configuration page, turn off the tool by using the Enabled toggle.
4. Select Save to apply the change.

The tool still appears on the agent tools list, but is no longer turned on.

Delete a tool from your agent

Turning off a tool blocks the tool from use, but also gives you the flexibility to turn it back on later. You can also remove a tool more permanently from your agent. To delete a tool from your agent:

1. Go to your agent and select the Tools page for your agent.
2. Find the tool on the list of tools and hover over the tool name. Select the three dots (…).
3. Select Delete. A confirmation window appears.
4. Select Delete to remove the tool.

The tool disappears from the agent tools list.

Note

You can only delete tools from the agent tools page. You can’t delete tools from the main Copilot Studio Tools page.

Limitations on tools in agents

• When you use generative orchestration, the orchestrator supports up to 128 tools per agent. For best performance and results, limit the number of tools in your agent to 25 to 30.
• When you use multi-agent orchestration with child agents, each child agent has its own orchestration and can manage its own set of up to 128 tools.