Skip to main content
Manage the toolkits in your active environment.

​
Listing toolkits

Use the orchestrate tools list command to list all tools in your environment. You can also use the --verbose (-v) flag to get detailed information about each tool in JSON format.
BASH
orchestrate toolkits list -v
Exporting remote MCP toolkits with the ADK CLI enables you to package and distribute custom tool integrations for watsonx Orchestrate. This process ensures consistent agent workflows across environments and simplifies deployment for development, testing, or production. Use this capability when you need to share toolkits with other teams, migrate configurations, or maintain version control for your MCP integrations.

​
Exporting remote MCP toolkits using ADK CLI

Use the ADK CLI to export a remote MCP toolkit configuration for deployment or integration.
BASH
orchestrate toolkits export -n my-toolkit -o my-toolkit.zip

​
Updating toolkits

You can update Python toolkits and MCP toolkits in watsonx Orchestrate, but each type follows a different process.
Important: When you update a toolkit, all agents using tools from that toolkit must be redeployed to use the updated versions. Plan toolkit updates carefully to minimize disruption to production agents.

​
Updating Python toolkits

You can update a Python toolkit by importing it again with your updated specifications. When you import the toolkit, watsonx Orchestrate replaces the existing version so you can continue working with the latest changes. Update process:
  1. Make changes to your toolkit code
  2. Test changes locally
  3. Import the updated toolkit (replaces existing version)
  4. Test in draft environment
  5. Redeploy all agents that use the toolkit
  6. Publish agents to live environment
BASH
orchestrate toolkits add \
  --kind python \
  --name my-toolkit-name \
  --description "helps you talk to the manager" \
  --language python \
  --package <python-package-name> \
  --package_root <path-to-package-root> \
  --tier small

​
Updating local and remote MCP toolkits

Unlike Python toolkits, you cannot update an MCP toolkit in place. Instead, you must remove the existing toolkit and reimport it with the new specifications. Update process:
1

Delete the existing toolkit

BASH
orchestrate toolkits remove -n my-toolkit-name
2

Import the toolkit with the new specs

BASH
  orchestrate toolkits add \
      --kind mcp \
      --name my-toolkit-name \
      --description "helps you talk to the manager" \
      --package_root /path/to/folder \
      --command '["node", "dist/index.js", "--transport", "stdio"]' \
      --tools "*" \
      --app-id "my_app_id"
3

Redeploy all agents that use the toolkit

After reimporting the toolkit, you must redeploy all agents that use tools from this toolkit to ensure they use the updated version.
BASH
# Update agent configuration if needed
orchestrate agents import -f agent.yaml

# Publish to live environment
orchestrate agents publish -n my-agent
For more information, see Importing agents.
Migration consideration: If you’re frequently updating MCP toolkits and the remove/reimport process is disruptive, consider migrating to Python toolkits which support in-place updates. For guidance, see Migrating to Python toolkits.

​
Removing toolkits

Removing a toolkit will remove all tools provided by that toolkit. Before removing a toolkit, ensure no agents are using tools from it. Removal process:
  1. Identify all agents using the toolkit
  2. Update agents to remove toolkit tool references
  3. Redeploy updated agents
  4. Remove the toolkit
BASH
# Check which agents use the toolkit
orchestrate tools list | grep "my-toolkit-name:"

# After updating agents, remove the toolkit
orchestrate toolkits remove -n my-toolkit-name
Important: Removing a toolkit while agents still reference its tools will cause those agents to fail when they try to use the removed tools. Always update and redeploy agents before removing a toolkit.

​
Agent redeployment considerations

When you update or remove toolkits, you must redeploy affected agents: Why redeployment is required:
  • Agents cache tool definitions at deployment time
  • Updated toolkit tools won’t be available until agents are redeployed
  • Removed toolkit tools will cause errors if agents aren’t updated first
Best practices:
  1. Test in draft first: Update toolkits and test with agents in draft environment
  2. Update agents atomically: Update all related agents together to maintain consistency
  3. Use version control: Track toolkit and agent configurations in version control
  4. Plan maintenance windows: Schedule toolkit updates during low-traffic periods
  5. Monitor after deployment: Watch for errors after redeploying agents with updated toolkits
Redeployment workflow:
BASH
# 1. Update toolkit in draft
orchestrate env switch draft
orchestrate toolkits add --kind python --name my-toolkit --package_root ./my-toolkit

# 2. Test with agents in draft
orchestrate agents chat -n my-agent -m "test message"

# 3. Deploy to live
orchestrate env switch live
orchestrate toolkits add --kind python --name my-toolkit --package_root ./my-toolkit

# 4. Redeploy all affected agents
orchestrate agents publish -n agent1
orchestrate agents publish -n agent2
orchestrate agents publish -n agent3

# 5. Verify in live
orchestrate agents chat -n my-agent -m "test message"

​
Next steps