Using tools in Plans: best practices

Companion to Plans and Skills best practices. That guide covers writing steps, sizing, and triggering. This one is about what steps do with tools once the Plan is running.

​

How tools and Plans work together

A Plan step is just an instruction. To make a step use a tool, name that tool in the step’s instructions, and the agent calls it as it works through the step. There’s no separate wiring between a step and a tool. The one prerequisite: the tool must be enabled on the same agent the Plan runs on. A Plan inherits its agent’s tools; it has no tool list of its own. If you name a tool whose connected service isn’t enabled on that agent, nothing happens. The agent might get stuck, reach for a differently named tool that seems similar, or say it’s calling a tool without actually running it. So enable the connected service on the agent, then refer to its tools in your steps.

​

Keep steps light: one or two tools each

This is the single biggest factor in whether a tool-using Plan finishes. One or two tools per step is the reliable zone. A step can name several tools and the agent will fire them in order, but the more you pack into one step, the less likely the Plan is to run all the way through. Three or more tool calls in a step is where reliability drops off sharply. A long Plan with many short steps is more effective than a short Plan with a few bulky, complex steps. Length costs far less than per-step load, so let a Plan be a step or two longer rather than cramming tools into each step. Watch big per-item steps. A step that loops an action over many items (revoking access to 30 systems, for example) can hit the agent’s per-turn limit and pause partway. See The per-turn tool limit below.

​

The per-turn tool limit

An agent caps how many tools it calls in a single turn, so a step that loops an action over many items can pause partway and ask the user before finishing them all, unless the request clearly reads as bulk work. When it pauses it stays on the same step rather than skipping ahead. Design for that check-in: make bulk intent explicit in how the Plan is triggered, or expect a mid-step pause. See Tool call limits for exactly how the budget works.

​

Give each tool a unique name

Make sure no two of an agent’s connected services expose a tool with the same name. When two connected tools share a name, the agent can’t tell them apart, and in some cases it fails to run at all. If you’re reusing a common action name like notify or send_update across services, give each a distinct name before attaching both to one agent. Prefixing with the service works well:

• slack_notify and email_notify rather than two tools both called notify
• crm_send_update and chat_send_update rather than two tools both called send_update

​

Showing widgets in a step

A widget renders in the chat when its tool runs as part of a step. Handy for a checklist, a confirmation card, or a picker at a specific point in the Plan. One caveat: if a step calls a widget-bound tool many times in a loop, the widget renders once per call and stacks up the chat. Reserve widgets for tools that a step calls once. For per-item bulk actions, use a tool without a widget, or summarize at the end.

​

When a tool fails

If a tool returns an error, the agent receives it and carries on. It sees what went wrong and responds, the same as outside a Plan. There’s no Plan-specific failure handling, so write your tools’ error messages to be clear and actionable, so the agent can recover or tell the user what happened.

​

Next steps