# Configuring Agent Tools

<div id="early"><div class="note-border alert-important">
  <div class="alert alert-important" role="alert">
    <div><i class="far fa-exclamation-circle"></i></div>
    <div class="alert-text">
      <p><strong>Important</strong>: The functionality described on this page is only available to customers who have licensed Veeva AI.</p>
    </div>
  </div>
</div>

</div>
Agent tools are a capability that provides your Large Language Model (LLM) additional information from your Vault to help it execute an agent action. When executed, agent tools operate as extensions of [agent actions](/en/lr/950644/#configure-agent-action), allowing the action to interact with other areas of your Vault to provide relevant information to Veeva AI Chat users.

When assigning an agent tool to an agent action, you may include details on when and how to execute the tool in the [agent action's instructions](/en/lr/950644/#write-agent-action-instructions). In addition, you can configure the agent action to always use an assigned agent tool, or let your LLM decide when to employ the agent action. The _Description_ of the agent tool and _Input_ parameters can also help your LLM to understand how to use the agent tool without explicit mention in the instructions.

<div class="note-border alert-info">
  <div class="alert alert-info" role="alert">
    <div><i class="far fa-info-circle"></i></div>
    <div class="alert-text">
      <p><strong>Note</strong>: Ensure that the <em>Description</em> of the agent tool and <em>Input</em> parameters are clear and concise, as your LLM uses this information to understand the purpose of and how to execute the agent tool. If the <em>Description</em> is easy to understand, your LLM can invoke the agent tool without explicit direction in the agent action instructions.</p>
    </div>
  </div>
</div>



## VQL Query Agent Tool

The VQL Query agent tool allows an agent action to query Vault for specific data. For example, VernBio has created a custom _Document Quality Check_ agent action that checks document spelling and grammar. Also, they would like the agent action to check if company terms and acronyms used in documents exist in VernBio's glossary. To accomplish this behavior, they created an agent tool using the _VQL Query Tool Type_, which allows the agent action to query the VernBio _Glossary_ object for accepted terms and phrases. Now, when a user clicks _Document Quality Check_, it will not only provide spelling and grammar checks, but also check if company terms used in the document are available in the glossary.

### How to Configure a VQL Query Agent Tool

To configure a _VQL Query_ agent tool: 
1. Navigate to **Admin** > **Configuration** > **Tools**. 
2. Click **Create**. 
3. Select **VQL Query** as the **Tool Type**. 
4. Enter a **Label**. The API **Name** field value is populated based on the **Label** value. 
5. Set the **Status** to **Active** or **Inactive**. By default, new agent tools are created in the **Active** status. 
6. Enter a **Description**.
7. Under **Input**, click **Add**. This option is not available until you select the _Tool Type_.
8. Enter a **Property**. This value represents the attribute your LLM uses to execute the Agent Tool. For example, if you enter `SELECT id, name__v FROM documents WHERE TONAME(type__v) = 'promotional_piece__c'` in the **Query** field, you would enter `promotional_piece__c` as the _Property_.
9. Select **String**, **Integer**, or **Number** from the **Type** drop-down.
10. Enter a **Description** of the _Input_ parameter.
11. Click **Add**.
12. Enter your VQL statement in the **Query** field.
13. Click **Save**.

The _VQL Query_ agent tool is now created and you can [assign](/en/lr/950644/#add-agent-context-tool-to-action) it to an agent action.

### Best Practices {#best-practices}

Use the following best practices when configuring agent tools:

* Reference _Input_ parameters in the _Query_ field using the `${parameter_name}` format. Parameter names are case sensitive and must match the _Property_. For example, if you enter `SELECT id, name__v FROM documents WHERE TONAME(type__v) = ${promotional_piece__c}` in the _Query_ field, you must enter `${promotional_piece__c}` as the _Property_.
* Always include an `ORDER BY` clause when using a query that returns multiple records to ensure the LLM receives the most relevant data first within the 1,000 record limit.
* Your LLM uses the agent tool _Description_ to interpret and execute the agent tool within agent actions. Ensure the _Description_ is accurate and easy to understand to help the LLM when executing the agent tool.
* Use the `AS` clause to provide meaningful _Name_ values to fields and help the LLM accurately interpret the data. For example: `status__v AS current_approval_status`.
* Use the <a class="external-link " href="https://developer.veevavault.com/vql" target="_blank" rel="noopener">developer portal<i class="fa fa-external-link" aria-hidden="true"></i></a> to learn more about VQL syntax.

### Limits {#limits}

The following limits apply to configuring agent tools:

* The _VQL Query_ agent tool does not support `LIMIT`, `PAGESIZE`, or `PAGEOFFSET` VQL query clauses.
* The _VQL Query_ agent tool only supports object and document <a class="external-link " href="https://developer.veevavault.com/vql/#query-targets" target="_blank" rel="noopener">query targets<i class="fa fa-external-link" aria-hidden="true"></i></a>.
* You can add up to ten _Input_ parameters per agent tool.
* _VQL Query_ agent tools can return a maximum of 1,000 records. If the query returns over 1,000 records, only the first 1,000 are sent to the LLM. Subquery limits are determined by your Vault's `MAXROWS` configuration.
* The characters " ' () and \ are escaped if used in _Property_ values. The % and \* characters are not escaped when used in `LIKE` and `FIND` operators.
* The _Property_ field does not support lists and enumerations.
* When using multiple arguments in a `CONTAINS` operator, you must provide multiple individual tokens. For example: `WHERE CONTAINS(${PROD_1}, ${PROD_2})`.
* You must use search phrases in `FIND` VQL clauses as tokens. For example: `FIND( ${search_statement} )` is valid while `FIND( ${prod_1} AND ${prod_2}) `is invalid.

## JSON Response Agent Tool

The _JSON Response_ agent tool allows you to generate JSON structured data based on input schema. You can execute a custom agent action using a _JSON Response_ agent tool through either Vault Java SDK or Vault API to generate JSON formatted data. External programs, such as Java, can consume the data for processing purposes.

<div class="note-border alert-important">
  <div class="alert alert-important" role="alert">
    <div><i class="far fa-exclamation-circle"></i></div>
    <div class="alert-text">
      <p><strong>Important</strong>: When crafting a <em>Description</em> for the <em>JSON Response</em>, do not use language that suggests the agent tool <em>outputs</em> a JSON result. This language may cause errors when the agent action invokes the agent tool. Instead, the <em>Description</em> should mention the LLM provides the JSON response. For example, “Generate a JSON output based on the document” may return an error, while “Report the detected language, summary, and keywords for a given document based on its content” is a valid <em>Description</em>.</p>
    </div>
  </div>
</div>



The _JSON Response_ schema supports the following:

* Up to five levels of nesting
* 100 properties per _JSON Response_ agent tool
* Required parameters
* Types:
  * Object
  * Array
  * String
  * Number
  * Integer
  * Date
* Enum data type

The following is an example of the JSON input schema you can use in the _JSON Response_:

~~~ json
{
  "type": "object",
  "properties": {
    "document_id": {
      "type": "string",
      "description": "The document identifier, echoed from input."
    },
    "language": {
      "type": "string",
      "description": "Detected language of the document as an ISO 639-1 two-letter code (example: 'en', 'fr', 'de')."
    },
    "summary": {
      "type": "string",
      "description": "A concise summary of the document content, between two and five sentences."
    },
    "keywords": {
      "type": "string",
      "description": "Up to ten representative keywords extracted from the document and returned as a single comma-separated string (example: 'biology, syllabus, course, grading, schedule')."
    }
  },
  "required": ["document_id", "language", "summary", "keywords"]
}
~~~

### How to Configure a JSON Response Agent Tool

To configure a _JSON Response_ agent tool:

1. Navigate to **Admin** > **Configuration** > **Tools**.
2. Click **Create**.
3. Select **JSON Response** as the **Tool Type**.
4. Enter a **Label**. The API **Name** field value is populated based on the **Label** value.
5. Set the **Status** to **Active** or **Inactive**. By default, new agent tools are created in the **Active** status.
6. Enter a **Description**.
7. Under **Input**, enter the structured JSON input schema in the **JSON Response** field.
8. Click **Save**.

The _JSON Response_ agent tool is now created and you can [assign](/en/lr/950644/#add-agent-context-tool-to-action) it to an agent action.