> ## Documentation Index
> Fetch the complete documentation index at: https://watermelon.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Designing Multi-Attribute Inputs for AI Actions

# Defining Attributes in Swagger

Each parameter defined in your **OpenAPI / Swagger schema** becomes an attribute that the Agent can fill.

These attributes can be defined in:

* **Query parameters**
* **Path parameters**
* **Request body fields**

Example mapping:

| API Parameter | Attribute (used by the Agent) | Required | Type   |
| ------------- | ----------------------------- | -------- | ------ |
| order\_number | order\_number                 | required | string |
| postal\_code  | postal\_code                  | required | string |
| email         | email                         | required | string |

The Agent reads these parameters from the schema and collects them from the user when needed.

***

# Example Swagger Definition

Below is an example OpenAPI specification defining attributes for an order lookup Action.

```yaml theme={null}
paths:
  /orders:
    get:
      summary: Retrieve order information
      description: Use this action when a user wants to check the status of their order.
      parameters:
        - name: order_number
          in: query
          required: true
          schema:
            type: string
          description: |
            The unique order number assigned when the order was placed.
            Ask the user for their order number if they want to check their order status.

        - name: email
          in: query
          required: true
          schema:
            type: string
          description: |
            The email address used when placing the order.
            Ask the user for this if it has not already been provided.
```

In this example:

* `order_number` and `email` automatically become **attributes**
* the Agent will request these values if they are missing
* once both values are available, the API call can be prepared.

***

# How the AI Uses Parameter Descriptions

The **description fields** in the Swagger schema are passed to the language model and used as instructions.

They help the Agent understand:

* when the Action should be used
* what the parameter represents
* how to ask the user for the value
* what format the value should have

### Poor Description

```text theme={null}
order_number: string
```

This provides almost no guidance for the Agent.

### Good Description

```text theme={null}
description: |
  The unique order number assigned when a customer places an order.
  Ask the user for this number if they want to check their order status.
```

This gives the Agent enough context to:

* recognize the correct user intent
* ask the correct follow-up question
* extract the value from the conversation.

***

# Required vs Optional Attributes

Swagger also defines whether an attribute is required.

### Required

If `required: true`, the Agent must collect the value before the Action can run.

### Optional

If a parameter is optional, the Agent will include it only if the user provides it.

Example API request:

```text theme={null}
/orders?order_number=123&email=jane@example.com
```

If both parameters are required, the Agent waits until **both values are known** before continuing.

***

# Handling Partial Inputs

The Agent automatically keeps track of which attributes are already known.

Behavior:

* If some required attributes are missing, the Agent asks only for those fields
* Users can provide information in any order
* The Agent maps each answer to the correct parameter

Example conversation flow:

User:

> I want to check my order.

Agent:

> Sure, could you provide your order number?

User:

> It's 12345.

Agent:

> Thanks. Can I also get the email address used for the order?

Once all required attributes are available, the Agent prepares the API request.

***

# Confirmation Before Execution

Even when all attributes are collected, the Agent will **not immediately execute the Action**.

Instead, the Agent asks the user to confirm the collected values.

Example:

> I found the following details: Order number: 12345 Email: [jane@example.com](mailto:jane@example.com)
>
> Is this correct?

The user can then:

* confirm the values
* correct any incorrect information

Example correction:

> That is not my email address. It should be [example@test.com](mailto:example@test.com).

After confirmation, the Action is executed.

<Tip>
  The wording of confirmation messages can be influenced through Domain Knowledge.
</Tip>

<Warning>
  The confirmation step is mandatory and cannot be disabled.
</Warning>

***

# Best Practices

To make Actions work reliably with AI Agents:

* Define **all attributes directly in the Swagger schema**
* Use **clear parameter names**
* Write **descriptive parameter descriptions**
* Indicate clearly whether parameters are **required**
* Include guidance in descriptions about **how the Agent should ask the user**

Well-structured API schemas allow the Agent to collect information naturally and execute Actions reliably.