Designing the Tool Set

Treat Tools Like Database Permissions

Every tool you assign expands what the agent can do — and what it can do wrong. Treat tool selection like granting database permissions: give the minimum set required for the workflow, nothing more. The agent that has access to ten tools has ten ways to surprise you. The agent with three tools has three.

This matters more than people expect. The default impulse when building an agent is to give it everything that might possibly be useful, on the theory that more capability is better. In practice, more tools means more wrong tool calls, more wasted tokens evaluating irrelevant options, and more ways for an agent to drift outside its intended scope.

Pair Every Write With A Read

If you give an agent zendesk_update_ticket_status, also give it zendesk_get_ticket so it can confirm the ticket state before acting. Writes without reads are how agents end up changing the wrong thing — they have no way to verify what they are operating on.

This sounds obvious. It is also one of the most common configuration mistakes we see: a triage agent assigned zendesk_update_ticket_priority but not zendesk_get_ticket, then asked to "decide priority based on ticket content" — except it cannot read the ticket. The model improvises something plausible, gets it wrong, and the priority is set to whatever its first guess was.

Avoid Optional Capabilities

If you are not sure whether the agent needs a tool, leave it out. You can always add tools later; you can never undo a wrong action that already happened. The cost of an extra tool toggle is small. The cost of an agent making an unauthorised change is large.

A useful self-check before enabling a tool: "Can I name a specific scenario in this agent's workflow where this tool will be called?" If you cannot, do not assign it.

Use The Dedicated Tool Over The Generic One

Where a connector offers both a dedicated tool (zendesk_update_ticket_priority) and a more generic tool that could do the same job (zendesk_update_ticket_fields), prefer the dedicated one. Three reasons:

• Confirmation messages are clearer. "Change ticket #123 priority to high?" tells the human reviewer exactly what is happening. "Update 1 field on ticket #123?" does not.
• Permissions are narrower. Granting update_ticket_priority grants exactly the ability to change priority. Granting a generic field-update tool grants the ability to change anything that fits in the field schema.
• Validation is tighter. Dedicated tools enforce per-field enums (priority must be one of four values). Generic tools rely on schema lookups that can drift.

Confirmation-Required Tools Are Not Optional

Write tools default to requiring confirmation in chat for a reason. The confirmation gate is the last line of defense — a human reviews the action before it ships. Do not enable an autonomous trigger on a write-heavy agent until you have run the same agent in chat mode and watched the confirmation gates fire.

When the trigger fires autonomously, the confirmation gate is bypassed (autonomous mode auto-approves). That is the point of autonomy. But it also means the chat-mode testing is the only safety net against bad writes — use it.

Tool Sets For The Three Common Roles

Most agents fall into one of three patterns. Tool sets that consistently work well for each:

Triage Agent

Reads incoming tickets and sets metadata. No customer-facing writes.

• zendesk_get_ticket — read the ticket
• zendesk_get_ticket_custom_fields — read existing custom field values
• zendesk_get_ticket_fields — schema lookup before custom field updates
• zendesk_update_ticket_priority — set priority
• zendesk_update_ticket_type — set type
• zendesk_update_ticket_tags — add/remove tags
• zendesk_update_ticket_fields — set custom fields (only if you actually use them)
• zendesk_add_internal_note — leave a note about why you set what you set

Reply Agent

Drafts customer-facing replies. The smallest possible write surface, with the highest-stakes write.

• zendesk_get_ticket — read the ticket
• zendesk_search_articles — find relevant help centre articles (or search_knowledge for non-Zendesk knowledge bases)
• zendesk_read_attachment — read images and document attachments if relevant
• zendesk_add_public_reply — post the reply (swap to zendesk_add_internal_note during the testing phase)

Routing Agent

Looks at incoming tickets and assigns them to the right group or agent.

• zendesk_get_ticket — read the ticket
• zendesk_search_users — resolve agent names to user IDs
• zendesk_list_groups — resolve group names to IDs
• zendesk_assign_ticket — assign to an agent, a group, or both
• zendesk_add_internal_note — explain the routing decision

Notice what is not on these lists: tools that do not directly serve the role's purpose. A triage agent does not get zendesk_add_public_reply — its job is metadata, not customer communication. A reply agent does not get zendesk_update_ticket_status — closing or reopening tickets is a separate decision that warrants a separate agent.

Custom Tools And Knowledge Tools

Custom tools (HTTP API tools you defined) and knowledge tools (search_knowledge, get_document) follow the same principles. Assign only the ones the workflow actually uses. If you have ten custom tools defined at the org level but a particular agent only needs three of them, assign three.

One note on knowledge tools: they are added automatically when you assign a searchable data source (large CSV, PDF, DOCX). They are not added for live connector sources (Google Docs, Notion, Confluence) — those use the connector's own read tool instead. So check what got added when you add a source, and prune anything you do not need.

The Trim-Aggressively Heuristic

When you finish configuring an agent, look at the tool list and ask: "Which of these would I be uncomfortable seeing the agent call right now?" Remove those. Repeat until the answer is "none of them."

This is the single highest-leverage thing you can do for agent reliability. An over-permissive agent is the bug you cannot easily debug — failures look like the agent doing something weird, when actually it is doing exactly what you let it do.