> For the complete documentation index, see [llms.txt](https://comunity.gitbook.io/learning.comunitynexus/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://comunity.gitbook.io/learning.comunitynexus/26.2/toolkit-guides/intelligence/create-a-tool.md).

# Create a tool

A tool is what an agent can act with. An agent holding no tools can conduct a conversation and nothing more, which defeats most of the reason for having an agent.

## Before you start

* A provider. Until one exists, Tools shows only a prompt to create one. See [Set up a provider and deploy a model](/learning.comunitynexus/26.2/toolkit-guides/intelligence/set-up-a-provider-and-deploy-a-model.md).
* For a function tool, the endpoint it will call and any header that endpoint needs in order to authenticate.

## Create a tool

1. Open **Intelligence (Preview)**, then **Tools**.
2. Select **Add Tool**.
3. Complete the fields that apply to every tool.\ <br>

   <figure><img src="/files/KAsAwIYhZSGww1xdQNQt" alt=""><figcaption><p>Create Tool form</p></figcaption></figure>

| Field           | Description                                                                                              |
| --------------- | -------------------------------------------------------------------------------------------------------- |
| **Tool Name**   | Required. How the tool is identified in the Toolkit.                                                     |
| **Description** | Optional. Your own note on what the tool is for.                                                         |
| **Tool Type**   | What the tool reaches. Defaults to **Function**, and the configuration below it changes with the choice. |

4. Complete the configuration for the type you chose.
5. Leave **Enabled** on, so the tool is available to agents.
6. Select **View JSON** to check the definition, then **Create Tool**.

Existing tools are listed on the **Tools** tab, which carries a count, and **Search Tools** finds them by name, description or type.

## Function tools

A function tool gives the model a callable contract and an HTTP endpoint behind it. **Function Configuration** defines both, and everything in it is emitted into the tool definition.

| Field                                       | Description                                                                       |
| ------------------------------------------- | --------------------------------------------------------------------------------- |
| **Function Name**                           | Required. The name the model calls.                                               |
| **Function Description**                    | Required. What the function does. See below, because the model reads this.        |
| **Parameters**                              | Required. A JSON Schema describing the arguments the function takes.              |
| **Endpoint URL**                            | Required. The address called when the model invokes the function.                 |
| **HTTP Method**                             | The method used for that call. Defaults to **POST**.                              |
| **Auth Header Name**, **Auth Header Value** | Optional. A single header sent with the request, where the endpoint requires one. |

### The function description is what the model reads

A tool carries two descriptions, and they do different jobs. **Description**, at the top of the dialog, is optional and is your own note. **Function Description** is required and forms part of the callable contract, so it is what the model reads when deciding whether this function is the right one to call.

Write it as an instruction rather than a label: what the function does, and what it returns. Where the function changes data rather than only reading it, say so, because the model has to know that is within its power before it will consider it.

### Parameters define the arguments

Parameters is a JSON Schema, and it is prefilled with a template rather than a usable default. The template declares one required string called `input`, described as "Describe the input expected by the function."

Replace it with the arguments your endpoint actually takes. Each property's own description is read by the model in the same way the function description is, so it is worth writing them properly: they are how the model works out what to put in each argument.

## The tool definition

The dialog builds a single definition, saved as `toolDefinitionJson`. **View JSON** shows it before you commit, which is the quickest way to confirm the contract is what you intended.

{% hint style="warning" %}
An **Auth Header Value** forms part of that definition rather than being held as a separately managed secret. Prefer a scoped, rotatable credential over a long-lived one, and treat anyone who can read the tool definition as able to read the header.
{% endhint %}

## Other tool types

**Tool Type** determines what the tool reaches. Besides a function, a tool can point at project data, a search index, documents in SharePoint, or a capability exposed over the Model Context Protocol. The configuration below the field changes accordingly.

### Tools over project data

A tool over project data reaches OData entities through the data service, and you choose the entities it covers. One tool can carry several entities, so there is no need for a tool per entity. Group them by the job the agent has to do, and let one tool describe one job.

For each entity you choose which operations are exposed. Reading and creating are separate: an agent given read on faults can look at them, and an agent given create can log a fault on a user's behalf. Grant only what the role requires, since an agent that reports on user profiles has no reason to create them.

A tool over project data acts as a nominated user, and that user must hold access to the data the tool reaches. Table security governs an agent's reads and writes exactly as it governs any other caller.

{% hint style="warning" %}
Pass-through authentication, where the tool acts as the user who caused the agent to run, is not available. Choose the tool's user deliberately, because every call the tool makes carries that user's access rather than the access of whoever triggered the run.
{% endhint %}

## Test the tool

A tool can be run on its own, before any agent depends on it. Do this before attaching it, so that a failure in the agent is not first misdiagnosed as a problem with its instructions.

## Where to go next

* [Create an agent](/learning.comunitynexus/26.2/toolkit-guides/intelligence/create-an-agent.md): attach this tool to a role
* [Add knowledge to an agent](/learning.comunitynexus/26.2/toolkit-guides/intelligence/add-knowledge-to-an-agent.md): material an agent reasons against, as distinct from records it reads