Designing Tools for Agents: The Difference Between a Tool an Agent Uses and One It Abuses

An AI Agent is only as competent as the tools you give it, and the quality of a tool is not measured by what it does when called correctly. It is measured by whether the agent calls it correctly in the first place, and what happens when it does not. Tool design is the new scripting craft on this platform, and it is subtle in ways that catch experienced developers off guard, because the consumer of your tool is not a human and not deterministic code. It is a language model making a judgment call.

What a "tool" is here. In AI Agent Studio, a tool is something the agent can invoke to get information or take action: a Now Assist skill, a platform action, a subflow, a script. The agent is handed a set of these and, at runtime, reasons about which one fits the situation. That last part is the whole ballgame. You are not writing a flow that calls step 1 then step 2. You are equipping a decision-maker and trusting it to choose.

The tool description is part of the prompt. This is the insight that reframes everything. The agent selects a tool primarily based on the tool's description. That description is not documentation for a human; it is input the model reasons over. A vague description ("handles requests") gives the agent nothing to discriminate on, so it guesses. A precise description ("Use this to reset a user's VPN credential when the user is verified and the device is managed; do not use for password resets") tells the agent exactly when this tool applies and when it does not. Write tool descriptions like you are writing the selection logic, because you are.

Input contracts prevent garbage calls. Each tool should have a tight input schema with clearly named, typed parameters and clear descriptions of each. When the schema is loose, the agent fills parameters with plausible-looking nonsense and the tool executes against bad input. When the schema is tight and well-described, the agent is constrained to supply the right things, and when it cannot, it knows to ask or escalate rather than fabricate. Treat every parameter description as another place you are steering the model.

Idempotency and reversibility are safety features. Because an agent may retry, loop, or misfire, design tools to be safe under repetition. An idempotent tool (calling it twice produces the same result as calling it once) protects you from duplicate actions when the agent retries. And classify your tools by reversibility: a read or a draft is safe to let the agent call freely; an irreversible action (deleting a record, sending an external notification, moving money) should be gated behind approval or confirmation. The reversibility of a tool should directly determine how much autonomy you grant around it.

Least privilege per tool. A tool runs with access. Scope that access to exactly what the tool needs and nothing more. If a lookup tool only needs read on one table, do not let it run with broad write. When (not if) an agent misuses a tool, least privilege is what bounds the damage. This is identical to the discipline you already apply to integration accounts; it just matters more now because the caller is non-deterministic.

Test tool selection, not just tool execution. Your unit test is no longer "does this skill produce the right output for this input." It is "given this ambiguous, realistic scenario, does the agent select the right tool, in the right order, with the right parameters?" Build scenarios specifically designed to tempt the agent into the wrong tool, and confirm it resists. If the agent keeps choosing the wrong tool, the fix is almost always in the descriptions, not the logic.

The mental shift: you are not building functions for code to call. You are building affordances for a reasoner to choose among. Design the descriptions and contracts so that the right choice is the obvious one.