Agents user guide

Last updated Jul 29, 2025

Building effective agent tools

Agents use tools as follows:

Tool selection: The agent selects a tool based on the name, description, and context provided in the system prompt.
Tool execution: The agent supplies input arguments, using the tool's defined input schema and any example usage in the prompt to infer format and values.
Output interpretation: After execution, the agent interprets the output using context and examples from the prompt.

If not given enough context, agents may incorrectly infer how to supply arguments to or interpret the results from a tool. You can improve reliability by applying several design strategies across tool configuration, usage examples, and guardrails.

Converting existing automations to be used as tools

You can use existing workflows as tools by publishing them as processes or importing them into your Studio Web solution. Review the input and output arguments to ensure they use supported types. Unsupported argument types may prevent the agent from calling the process.

Writing effective tool descriptions

Including the following details in tool descriptions can help both the agent and other developers use the tool effectively in agentic processes:

What does the tool do?
What side effects does the tool have?
Does the tool modify its environment?
Might the tool perform destructive updates to a system of record?
Does calling the tool repeatedly have any additional effect?
Does calling the tool allow for the agent to interact with other agents, users, or systems in an unstructured way? This could introduce additional risk and may necessitate a corresponding increase in oversight.

Descriptions should remain concise but informative, written in plain language that supports agent reasoning.

Providing example usage in a system prompt

Including an example in the system prompt that demonstrates how to use the tool and interpret its output can significantly improve tool accuracy.

For example, an Agent wants to use an RPA workflow to check the status of an invoice in an internal system. In the system prompt of the agent, you can give the following example usage:

Example Usage of ValidateInvoiceStatus Tool

Input:
{
  "InvoiceNumber": "INV-2024-1837" // the unique invoice identifier
}

Output:
{
  "IsValid": true, // boolean indicating if the invoice exists
  "PaymentStatus": "Paid", // payment status of the invoice
  "DueDate": "2025-06-30" // when payment is due (if unpaid)
}

Interpreting the Results:
Result Condition	Agent Interpretation
IsValid = true, PaymentStatus = Paid	"Invoice INV-2024-1837 is valid and has already been paid."
IsValid = true, PaymentStatus = Unpaid	"Invoice INV-2024-1837 is valid but unpaid. It is due by June 30, 2025."
IsValid = false	"There's not a valid invoice with number INV-2024-1837 in the system."Example Usage of ValidateInvoiceStatus Tool

Input:
{
  "InvoiceNumber": "INV-2024-1837" // the unique invoice identifier
}

Output:
{
  "IsValid": true, // boolean indicating if the invoice exists
  "PaymentStatus": "Paid", // payment status of the invoice
  "DueDate": "2025-06-30" // when payment is due (if unpaid)
}

Interpreting the Results:
Result Condition	Agent Interpretation
IsValid = true, PaymentStatus = Paid	"Invoice INV-2024-1837 is valid and has already been paid."
IsValid = true, PaymentStatus = Unpaid	"Invoice INV-2024-1837 is valid but unpaid. It is due by June 30, 2025."
IsValid = false	"There's not a valid invoice with number INV-2024-1837 in the system."

Using guardrails for additional oversight

Tool guardrails allow you to enforce policies on the input provided to and the output received from agent tools, allowing a human to review the tool use, blocking it entirely, and more. Read more about tool guardrails.

Using connectors in workflows

You can add many Integration Service connector activities directly as a tool for your agent. To use connectors and activities that are not yet supported directly: