Skip to content
Swytchcode logo Swytchcode logo Swytchcode Docs docs

Manage Tools

Installing an integration makes its APIs available to your project, but it does not automatically allow your AI agent to use them.

Swytchcode uses a tool-based permission model. Before an AI agent can execute an API operation, the corresponding tool must be explicitly enabled in your project.

This gives you complete control over what your AI agent is allowed to do.

For example, you may want your agent to create GitHub issues and list pull requests, but never delete repositories. By only enabling the required tools, you define the execution surface of your project.

What is a tool?

A tool represents a single executable capability.

Depending on the integration, a tool can represent:

  • An API method
  • A predefined workflow
  • A higher-level operation composed of multiple API calls

Each tool has:

  • A unique canonical ID
  • Input parameters
  • Output schema
  • Authentication requirements
  • Documentation

Your AI agent discovers and executes tools instead of generating raw HTTP requests.

The tooling.json file

Every Swytchcode project contains a tooling.json file.

This file defines the tools that are available for execution inside your project.

Think of it as the project’s allow list.

If a tool is not present in tooling.json, it cannot be executed, even if the integration has been installed.

tooling.json


✓ github.pull_requests.list
✓ github.issues.create
✓ slack.messages.send


✗ github.repository.delete
✗ stripe.customer.delete

The CLI automatically updates this file as you add or remove tools.

In most cases, you won’t need to edit it manually.

Add tools

Use the add command to enable a tool.

Terminal window
swy add github.pull_requests.list

The CLI validates the tool, updates your project configuration, and makes it available for execution.

You can enable as many tools as your project requires.

Terminal window
swy add github.issues.create


swy add slack.messages.send


swy add stripe.customers.create

Only enabled tools become available to your AI agent.

swy add <canonical_id> is shorthand for swy add method <canonical_id> - the form used above. Two related variants cover the rest of the picture:

Terminal window
swy add method --all github   # enable every method from an integration at once
swy add workflow stripe.checkout   # install a published workflow, auto-fetching what it needs

If a workflow’s integrations later publish updates, swy sync will flag any enabled method whose definition has drifted so you know to re-run add and refresh it.

List enabled tools

To view every tool currently available in your project, use:

Terminal window
swy list

This displays all enabled methods and workflows.

Listing tools is useful when:

  • Verifying project configuration
  • Auditing available capabilities
  • Checking whether a tool has already been added

Discover tools

Sometimes you know what you want to accomplish, but not which tool to use.

The discover command searches installed integrations and returns relevant tools based on your intent.

For example:

Terminal window
swy discover "create a GitHub issue"

Instead of requiring you to remember exact tool names, Swytchcode helps you find the most appropriate match.

This is especially useful when working with large integrations that expose hundreds of methods.

Inspect a tool

Before executing a tool, you can inspect its documentation and schema.

Terminal window
swy info github.issues.create

The CLI displays useful information such as:

  • Description
  • Required inputs
  • Optional parameters
  • Authentication requirements
  • Expected response
  • Examples

Reviewing a tool before execution helps developers understand exactly what the API expects.

Plan an execution

Some tasks involve multiple API calls chained together as a workflow.

The plan command takes a workflow’s canonical ID and previews its ordered steps before you run it.

Terminal window
swy plan stripe.checkout

The CLI fetches the workflow definition from the registry and prints the ordered step list (step name, canonical ID, and integration for each step) without executing anything.

Planning improves transparency and helps developers review complex workflows before execution.

Understanding canonical IDs

Every tool has a unique identifier called a canonical ID.

Instead of referring to tools using natural language, Swytchcode uses canonical IDs to uniquely identify executable actions.

For example:

github.pull_requests.list


github.issues.create


stripe.customers.create


slack.messages.send

Canonical IDs are:

  • Unique
  • Stable
  • Predictable
  • Easy to reference in scripts and automation

Most CLI commands accept canonical IDs as input.

Methods and workflows

Swytchcode supports two kinds of tools.

Methods

A method represents a single API operation.

Examples include:

  • Create an issue
  • Send a message
  • Create a customer
  • List repositories

Methods generally map to one API endpoint.

Workflows

A workflow combines multiple methods into a reusable operation.

For example:

Onboard Customer


├── Create Customer
├── Create Subscription
├── Send Welcome Email
└── Notify Slack

Instead of executing each API call individually, your AI agent executes a single workflow.

Workflows simplify repetitive tasks and provide a higher level of abstraction.

Typical tool workflow

Most developers follow the same process when working with tools.

Install Integration
        │
        ▼
Discover Tool
        │
        ▼
Inspect Tool
        │
        ▼
Add Tool
        │
        ▼
Execute Tool

As your project grows, you’ll continue adding new tools while keeping the execution surface limited to only what your application requires.

Best practices

Enable only the tools your project needs.

Related pages

Authentication

Connect your Swytchcode account and securely manage provider credentials.

Projects

Initialize and configure Swytchcode projects.

Integrations

Discover, install, and manage API integrations.

Execute Tools

Execute tools, pass inputs, and preview requests.

Policy Rules

Define custom rules to control when and how tools are allowed to execute.

Runtime SDK overview

JavaScript and Python SDKs for tool execution.

Smaller tool sets improve discoverability, reduce unnecessary context for AI agents, and make project permissions easier to audit.

Prefer workflows for common multi-step tasks instead of repeatedly executing individual methods.

Review tool documentation with the info command before enabling unfamiliar tools.

Use canonical IDs consistently when writing scripts, automation, or documentation.

Now that you’ve enabled the tools your AI agents can execute, it’s time to understand how Swytchcode executes them safely and reliably.

What's Next?

Execution Pipeline

Learn how every request is validated, authenticated, protected by policies, and executed.

Policy Rules

Define custom rules to control when and how tools are allowed to execute.

Retries

Learn how Swytchcode automatically retries transient failures for reliable execution.

Idempotency

Prevent duplicate operations when retrying mutating API requests.

manifest.json

Configure execution behavior, including retries, timeouts, concurrency, and idempotency.