Shape a tool response

Shape a tool response to control the information an AI assistant receives after a tool runs.

Workday and other APIs can return large responses containing technical fields, IDs, nested objects, and information the assistant doesn't need. Shaping the response lets you return only the information the assistant needs to continue the conversation.

For example, after submitting a time-off request, the assistant might only need:

• Confirmation ID
• Start date
• End date
• Status
• Time-off type

The employee doesn't need to see the complete Workday response.

Working and final responses

When response reshaping is enabled, a tool can use two response formats:

The process is:

API response → Filter → Enrich → Reshape → Final response

Filtering and enrichment are optional.

If response reshaping isn't enabled, you configure a single response structure for the tool.

When to shape a response

Shape a response when the API returns more information than the assistant needs or when the response needs to be transformed into a more useful structure.

For example, a Workday response might contain technical fields and nested references. You can reshape it into:

• confirmationId
• startDate
• endDate
• status
• timeOffTypeName

A smaller, clearly named response helps the assistant provide a focused answer and makes the tool easier to reuse in conversations and workflows.

Shape a response

1. Open the tool in Agent Tools.
2. Select Refine.
3. Open Response.
4. Decide whether you need response reshaping.

Use a simple response

If the API response already contains the information the assistant needs:

1. Leave Response reshaping disabled.
2. Define the fields the assistant should receive.
3. Give fields clear, descriptive names.
4. Mark fields as lists when the API can return multiple items.

Use a simple response when the API already returns a suitable structure.

Use response reshaping

Enable Response reshaping when you need to transform the API response before the assistant receives it.

You can:

• Remove fields the assistant doesn't need.
• Rename fields.
• Combine information from multiple fields.
• Create a simpler structure for the assistant.
• Filter or enrich the working response before transforming it.

Define the response fields

Only include information the assistant needs to answer the user or continue the workflow.

For example:

Use clear names such as status instead of technical API field names.

For a list response, mark the relevant field as List of items.

Filter a response

Use Response filtering when an API returns a list but the assistant only needs some of the items.

For example, you might filter a list to return only active plans.

Filtering runs before response reshaping.

Enrich a response

Use Response enrichment when you need to call another tool to add information to the working response.

You can enrich:

• Once — Make one additional call for the response.
• Per item — Make an additional call for each item in a list.

For example, a Workday operation might return a leave type ID. An enrichment can use that ID to retrieve the corresponding leave type name.

Fields used as enrichment targets must already exist in the working response.

Reshape the response

When response reshaping is enabled:

1. Define the Working response.
2. Add any required filtering or enrichment.
3. Create a transform expression that converts the working response into the final response.
4. Define the Final response to match the result of the transformation.

Applaud uses JSONata for response transformation.

Use the expression editor and field picker to select the fields available in the working response rather than relying on guessed field paths.

Test the response

Test the tool after configuring the response.

1. Open Test.
2. Run the tool with representative inputs.
3. Review the Response and Run trace.
4. Check the filtering, enrichment, and reshaping steps if they're enabled.
5. Confirm that the final response contains only the information the assistant needs.
6. Make any required changes and test again.
7. Save the tool.

If the test result contains a useful response structure, you can use Use test result shape as a starting point and then remove any fields the assistant doesn't need.

Example: Request time off

A Workday time-off request might return a large response containing technical information about the transaction.

Instead of passing the complete response to the assistant, shape it into:

The assistant can then use those fields to respond:

Your annual leave from 15 Aug to 16 Aug was submitted. Your request is pending approval. Reference: ABC-123.

Best practices

• Return only the information the assistant needs.
• Use clear, human-readable field names.
• Remove technical fields that don't contribute to the conversation.
• Filter lists when the assistant only needs a subset of the results.
• Use enrichment only when additional information is required.
• Keep the final response as small and predictable as possible.
• Test the final response with realistic data before activating the tool.