> This page is for Agent Handler. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.merge.dev/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server. # Tool Packs > How Tool Packs work in Agent Handler: when to create one vs many, individual vs shared credential scope, tool selection, lifecycle. A Tool Pack is a named bundle of Connectors and the specific tools you want exposed to one agent surface. The Tool Pack ID is part of the MCP URL - it's how Agent Handler knows which tools the agent on the other end is allowed to see and call. > **Tool Packs and per-user tool access are separate** > > The Tool Pack decides access on its MCP URL: an agent can call every tool in the pack for any Connector the Registered User has authenticated. Per-user [tool access](/merge-agent-handler/administer/managing-tool-access) is not applied there; it governs the employee MCP URL and the Merge CLI. Most teams have more than one Tool Pack. The same Agent Handler organization might serve a customer-support agent (read-only Salesforce, Zendesk, Jira), a revenue-ops agent (write access to Salesforce and HubSpot), and an internal IT agent (Okta, Slack, GitHub). Different jobs, different packs, different blast radius. ## When to create one pack vs many Use one Tool Pack per agent surface. Reach for more than one when: * Different agent surfaces should see different tools. A support agent shouldn't have write access to your billing system. * Different customer tiers get different tools. Free-tier read-only; enterprise gets the full set. * Different environments need different scoping. A test pack with mocked Connectors, a production pack with the real ones. Tool Packs are cheap - every pack is one bounded surface area you can reason about, audit, and lock down. ## Creating a Tool Pack Packs have full CRUD over the API, and that is the path to reach for once packs are part of your deployment rather than a one-off: a pack per customer tier or per environment belongs in the code that provisions the rest of the tenant, not in a browser tab. **`cURL`** ```bash title="cURL" curl -X POST https://ah-api.merge.dev/api/v1/tool-packs/ \ -H "Authorization: Bearer $MERGE_AH_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Support agent", "description": "Read-only ticketing for the customer-support agent", "connectors": [ { "slug": "linear", "auth_scope": "INDIVIDUAL", "tool_names": ["get_issues", "get_issue"] } ] }' ``` **`Python`** ```python title="Python" import os import requests tool_pack = requests.post( "https://ah-api.merge.dev/api/v1/tool-packs/", headers={"Authorization": f"Bearer {os.environ['MERGE_AH_API_KEY']}"}, json={ "name": "Support agent", "description": "Read-only ticketing for the customer-support agent", "connectors": [ { "slug": "linear", "auth_scope": "INDIVIDUAL", "tool_names": ["get_issues", "get_issue"], } ], }, ).json() print(tool_pack["id"]) ``` The response carries the pack's `id`, which is the value the MCP URL needs: `/tool-packs//registered-users//mcp`. Omit `tool_names` on a connector to enable every tool it exposes, which is rarely what you want on a production pack. `connectors` is a full replacement on write, so a `PATCH` that sends one connector detaches the others; use the `/tool-packs/{id}/connectors/` sub-resource to add or remove one at a time. The [Tool Packs API reference](/merge-agent-handler/agent-handler/tool-packs/tool-packs-create) has the rest: list, retrieve, update, delete, and the connector-level endpoints. ### From the dashboard From the [Tool Packs dashboard](https://ah.merge.dev/tool-packs), click **Register new Tool Pack**, name it, and add Connectors. For each Connector, pick the specific tools you want the agent to see. Most Connectors expose 30–80 tools; you usually want a subset. The search box in that modal matches on Connector name and slug and on fully qualified tool names, so you can type a Connector like `salesforce` or jump straight to a specific tool like `google_drive__search`. It accepts either the underscore or hyphen form of the slug. A Connector that can't authenticate anyone until you register your own OAuth app is left out of the picker entirely, here and in SCIM group configuration. If a Connector you know exists doesn't come up in the search, that is usually why: set up its [Application Credentials](/merge-agent-handler/administer/application-credentials) and it appears. Save the pack and copy its ID from the URL. That ID goes into the MCP URL, exactly as it does over the API. ## Individual vs shared credential scope When you add a Connector to a Tool Pack, you pick the credential scope. | Scope | What it means | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Individual** | Each Registered User authenticates with their own credentials. One Salesforce token per Registered User. | | **Shared** | Registered Users in the same Group inherit one set of credentials. The Group is set by `origin_company_id` (or another grouping key) on the Registered User. | | **Organization** | One set of credentials serves every Registered User in your organization. Over the API this is `auth_scope: "ORGANIZATION"`. | **Pick Individual** when each end user has their own account in the third party - typical for B2B agents acting on a user's personal Salesforce, GitHub, Notion. Each user authenticates once; their token is theirs. **Pick Shared** when one set of credentials should serve a whole tenant - typical when a Company has a single Slack workspace and any of their users' agent calls should post as the Company. One person on the Company's IT team authenticates once; everyone else inherits. If you're unsure, pick Individual. Switching from Shared to Individual later is harmless; the reverse means re-authenticating every user. ## Tool descriptions and inputs Two ways to shape what the model sees per Tool Pack: * **Description overrides.** Rewrite a tool's description so the model picks it correctly. Useful when your domain has different terms than the third party - your "ticket" might be the third party's "issue." See [Tool Description Overrides](/merge-agent-handler/build/tools/tool-description-overrides). * **Input overrides.** Hide or constrain fields on a tool's input schema. Useful for forcing a project ID, hiding a paginator, narrowing an enum. See [Tool Input Overrides](/merge-agent-handler/build/tools/tool-input-overrides). Both apply at the tool-pack level, not org-wide. Different packs can show the same tool with different descriptions or different shapes. ## Editing a pack with active users Edits to a Tool Pack take effect on the next tool call - no token rotation, no re-authentication needed. Specifically: * **Adding a tool.** Existing Registered Users using this pack will see the new tool the next time the agent calls `tools/list`. Most clients refresh on a fixed cadence, so it can take a minute. * **Removing a tool.** The tool stops being callable immediately. If an agent tries to call it, the call returns `403 unauthorized_tool`. * **Changing description / input overrides.** Same as adding - picked up on the next `tools/list`. * **Changing credential scope (Individual ↔ Shared).** Existing credentials are not migrated. New users get the new scope; existing users keep what they had until they re-authenticate. * **Removing a Connector.** The Connector and all its tools stop being callable. Stored credentials are *not* deleted - if you re-add the Connector later, users don't have to re-authenticate. For high-volume packs, prefer adding new tools or making them configurable rather than removing tools mid-flight; mid-flight removals can break agent runs that picked the now-missing tool from a stale list. ## Security Gateway overrides per pack You can override [Security Gateway](/merge-agent-handler/secure/security-gateway) rules per Tool Pack. The org-level rule still exists; the override changes the action just for one pack. Common pattern: block credit card numbers org-wide, allow them on a payments-team pack that legitimately needs to read them. Configure overrides on the Tool Pack's **Rules** tab. ## Next Set up the identity Agent Handler attaches credentials to with [Registered Users](/merge-agent-handler/build/users/registered-users).