BuildTools

Tool Description Overrides

Rewrite a tool's name or description so the model picks it correctly.

A tool’s description is what the model uses to decide whether to call it. The defaults Agent Handler ships are good starting points, but they’re written for the third-party API as it was named upstream - your “ticket” might be the third party’s “issue,” your “deal” might be their “opportunity,” your “customer” might be their “account.”

Description overrides let you rewrite a tool’s name or description per Tool Pack so the model sees your domain’s language, not the third party’s. They’re a small change with outsized impact on tool selection accuracy.

When to override

The default description is fine for most tools. Reach for an override when:

  • The model picks the wrong tool. Two tools have similar default descriptions and the model keeps confusing them.
  • Your domain has different terms. Your CRM is built around “opportunities” but the Connector exposes them as “deals.” Rewriting the description to use your term makes the model more likely to call the right thing.
  • You want to constrain behavior. “Use this tool only for high-priority tickets” - a usage hint in the description steers the model without code.
  • The default description is too long. Some defaults pull verbatim from third-party API docs and bloat the system prompt. Trimming saves tokens.

If the description is fine and the issue is that the model has too many tools to choose from, the right fix is a smaller Tool Pack, not an override.

Override from the dashboard

Open the Tool Pack at Tool Packs, click the Connector, then click the tool you want to override. The override editor shows the default name and description, with editable fields next to each.

Save and the override applies on the next tools/list call.

Override via the API

$curl -X POST https://ah-api.merge.dev/api/tool-packs/$TOOL_PACK_ID/tool-description-overrides \
>  -H "Authorization: Bearer $MERGE_AGENT_HANDLER_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "tool_name": "salesforce__create_opportunity",
>    "name_override": "create_deal",
>    "description_override": "Create a new sales deal in Salesforce. Use this when the user asks to log a new opportunity, deal, or pipeline entry."
>  }'

To remove an override, DELETE the same path. Tools without overrides fall back to the default.

Where overrides apply

Overrides are scoped to one Tool Pack. Two Tool Packs can show the same tool with different descriptions - useful when one pack serves a customer-support agent (tool description: “Look up a customer’s recent tickets”) and another serves a sales agent (same tool, different description: “Pull a contact’s open issues for context before a renewal call”).

Overrides don’t change the tool’s input schema or behavior. The third-party API still gets called the same way; only what the model sees changes. If you need to change the schema, see Tool Input Overrides.

What “good” overrides look like

A few patterns that work well:

  • Lead with the verb. “Create a Slack message in a channel,” not “This tool can be used to create a Slack message in a channel.”
  • Include the domain term. If your team says “ticket,” put “ticket” in the description even if the Connector is for Jira (where the term is “issue”).
  • Add a usage hint when needed. “Use this only for tickets in the ‘support’ project.” Hints disambiguate when two tools could both apply.
  • Keep it short. A one-sentence description usually beats a paragraph.

Test the override by asking your agent to do something the tool should handle. If it picks the right tool, the description works. If it doesn’t, refine the description and try again. The Playground is the tightest loop for this.

Next

Constrain what the model can produce with Tool Input Overrides.