Creating and Managing Tool Instances

A tool instance is a tool installed in your organization, with its own name, settings and credentials. The Toolbox lists all of them. This article shows how to connect a new tool, open and edit an instance, attach it to Mates, and delete it. It is for the people who manage tools.

Connecting and managing tools needs tool-management rights: the Expert plan by default; your organization's plans may differ. Your role on each tool (Owner, Admin, User, List) then decides what you can do with it: see "Mastering Tool Authorizations".

Open the Toolbox

In the sidebar, open Mates & tools, then Toolbox. The page shows Tools ({count}), one card per instance, with the avatars of the Mates that use it. Use Search for a tool and the Category filter to find one.

Connect a new tool

Click Connect tool, then choose:

• Tool store: opens the Tools Store. Click Install on a tool. See "Discovering the Tool Store".
• Add custom tool: connects your own MCP server by its URL, or a REST API with Other custom tool paths > REST API. See "Deploying a Custom MCP Server in Your Organization" and "Master the REST API Tool".

After the install, the tool attachment dialog opens (next sections).

Open a tool instance

Click a card to open the tool page. The page has these tabs:

The menu (⋮) at the top right holds Edit, Manage Mates, Store Tool (opens the tool in the store) and Delete. Click the icon of the tool to upload a new one.

Edit a tool instance

1. Open the menu (⋮), on the card or on the tool page, and click Edit.
2. The tool instance editing dialog opens on its Settings tab.
3. Change what you need, then save.

The Settings tab holds the Name, Short description and Overview description, then the settings of this kind of tool: MCP server URL, Configuration, Authentication, OpenAPI Schema, Advanced settings or credential fields. The Documentation tab shows the store tool's guide.

Write names and descriptions for your colleagues and for the Mates: the Mate reads the description to decide when to use the tool. "Salesforce – Lead management (read-only)" says more than "Salesforce".

Today, only the tool Owner can save changes to its settings. An Admin sees Edit, but the save is refused, except for the shared OAuth connection of the tool.

Credentials

• Organization credentials (one value for everyone) are entered by an organization admin in the tool settings. The tool's Owners and Admins can read them again to review or correct them.
• Member credentials are entered by each member, the first time a Mate needs them. Only that member can read them, in Account > Connections.
• A saved OAuth client secret is never shown again. To change it, type a new one; leave the field empty to keep it.

See "Personal and shared tool authentication" for OAuth sign-in and shared accounts.

Attach a tool to Mates

From the tool side, you have three ways:

• the tool attachment dialog that opens right after an install,
• the Mates tab of the tool page, then Add a Mate,
• the menu (⋮), then Manage Mates.

In the dialog, click the card of each Mate to attach or detach, then click Save access. You need editor rights on a Mate to change its tools: "You need editor rights on this Mate to attach tools."

From the Mate side, open the Mate, then its Tools tab, then Add a tool.

A tool change takes effect at once. If the Mate has unpublished draft edits, the tool change also deploys them.

Delete a tool instance

1. Detach the tool from the Mates that use it: they lose the tool as soon as it is deleted.
2. Open the menu (⋮) and click Delete.
3. Confirm with Delete instance. The confirmation says that the instance and its saved credentials will be deleted.

Only the tool Owner can delete it. Deleting the instance does not revoke anything at the provider: revoke the key or the OAuth access there too.

Good to know

• Few tools per Mate. A Mate with three well-described tools chooses better than a Mate with twenty.
• Several instances of one tool are fine: one per team, account or environment. Give each a distinct name.
• Usage (calls, success rate, cost) is on the Tools page of Analytics, when your organization has Analytics.
• Review regularly: delete unused instances, check who is Owner or Admin, and rotate keys.
• A tool fails in chat? Open Tools called under the message to read the error. See "What a tool call looks like in a conversation".

Related articles

• Introduction to Tools
• Discovering the Tool Store
• Personal and shared tool authentication
• Mastering Tool Authorizations
• Master the REST API Tool
• Deploying a Custom MCP Server in Your Organization