> For the complete documentation index, see [llms.txt](https://docs.ess-dive.lbl.gov/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ess-dive.lbl.gov/programmatic-tools/ess-dive-ai-assistant.md).

# ESS-DIVE AI Assistant

### What is the AI Assistant?

The AI Assistant is a tool that can help you search, download, and interpret ESS-DIVE data with the help of any AI model of your choosing. The assistant will help AI models properly fetch metadata, generate citations, look up reporting format data files on ESS-DIVE, [and more](#what-tasks-can-the-ai-assistant-help-you-with) through systems like Codex, Claude Code and VS Code. 

Figure 1 below demonstrates what it would be like to have the assistant find ESS-DIVE datasets by data type and summarize the search results.

We also have written [Skills](#skill) that can be used independent of our assistant to help AI model perform specific tasks related to ESS-DIVE.

<figure><img src="/files/FXy6TUXeCOcO5uDuDEDd" alt=""><figcaption><p>Figure 1. Example prompt in the AI-Assistant interface</p></figcaption></figure>

The program needs to be installed and connected to an AI Client, such as Goose, with an AI Agent, such as Gemini. The program allows you the flexibility to choose your preferred AI model to answer questions and perform tasks within your preferred AI client interface.&#x20;

:point\_right: To find the best starting point, check out our [Setup](#setup) section below. Otherwise, head over to [ESS-DIVE's GitHub Repository](https://github.com/ess-dive/essdive-mcp) to jump right in.

{% hint style="info" icon="timer" %}
The most basic set up through Goose takes around 20 minutes.&#x20;
{% endhint %}

{% hint style="success" icon="list-check" %}
**What will you need?**

:key: Access to an AI Agent API key

:computer: Client desktop app (e.g. Goose, VSCode)

:robot: Install AI Assistant&#x20;
{% endhint %}

<details>

<summary>Agent vs. Agent Client Terminology</summary>

**Agent:** An AI model capable of determining and executing goals and steps to take based on prompts.

**Agent Client:** The interface where you interact with an AI agent. E.g. Goose, Codex, Claude Code.

</details>

#### Why use ESS-DIVE's AI Assistant?

The type of tasks needed for interacting with data on ESS-DIVE are not natively supported in large language model (LLM) chat interfaces and would require a lot of assistance to complete a task. Once set up, the assistant can:

* Access data in consistent, predictable ways without guesswork
* Provide context from a variety of sources
* Work with variations
* Interpret results

#### What tasks can the AI Assistant help you with?

* Searching public ESS-DIVE datasets
* Fetching dataset metadata, version history, and sharing permissions
* Converting between ESS-DIVE dataset IDs and DOIs
* Generating consistent ESS-DIVE data citations with MCP/API access details, plus warning-backed Crossref fallback for non-ESS-DIVE DOIs
* Parsing File Level Metadata (FLMD) CSV content
* Searching with [Deep Dive API](/searching-and-accessing-data/search-with-deep-dive-api.md) to find information within [Reporting Format](/publish-data/review-cycle-and-criteria/reporting-format-requirements.md) files
* Looking up ESS-DIVE project acronyms, descriptions, and portal URLs
* Turning coordinates into map links

{% hint style="warning" %}
**Always make sure to cite your data!**
\
Datasets are valuable research contributions that should be cited to ensure that authors receive credit for producing and curating data. Always retain citations when using data from a published ESS-DIVE dataset.

The AI Assistant can help provide you with citations.
\\

\
Example prompt you can ask the AI: `Could you please dump the citations for these datasets to a
 TSV? Use ESS-DIVE format.`
{% endhint %}

### How does the AI Assistant work?

The AI Assistant is a combination between an **MCP** (Model Context Protocol), an **AI agent** (e.g. Chat GPT, Gemini) and **AI client** of your choice (e.g. Claude, Codex, Goose). An **MCP-Server** is a software that provides instructions, via **tools** and **skills**, to AI agents telling it how to accomplish tasks.&#x20;

The ESS-DIVE AI Assistant is an MCP-Server written by ESS-DIVE developers to instruct AI on the proper use of ESS-DIVE's APIs.
&#x20;When you install the AI Assistant, you are installing an MCP-Server.

The AI Assistant is not a web interface that you can interact with in your browser.

<figure><img src="/files/SDFHHow7zgkDeOAXzPSB" alt=""><figcaption><p>Figure 2: MCPs allow agents to interact with APIs, files, software tools, databases, and virtually any other data source or interface that traditional software can work with.</p></figcaption></figure>

{% columns %}
{% column %}

#### Tool

The MCP Server operates by having a collection of tools, or functions written in python, which tell the AI agent how to use ESS-DIVE's APIs and execute specific tasks. The tools are what enable the actions listed under "[What can the AI Assistant Help you With?](#what-can-the-ai-assistant-help-you-with)".&#x20;

AI agents will know when to use ESS-DIVE's tools based on the context within your prompt. It won't be necessary to specify which tool you want it to use.

{% endcolumn %}

{% column %}

#### Skill

Skills provide natural language instructions for accomplishing common tasks and are written in markdown following an open standard understood by most agent clients.&#x20;

Skills can be used with or without the MCP Server. Start off without Skills, then add them later if you want more predictable agent behavior for repeated tasks. Or the Skills can still be installed as reusable instruction documents outside of ESS-DIVE's MCP Server.

The MCP server provides the tools. A Skill helps the agent decide how and when to use them.
{% endcolumn %}
{% endcolumns %}

## Setup

The [GitHub Documentation](https://github.com/ess-dive/essdive-mcp/tree/main) provides multiple options and detailed instructions to set up your AI Assistant + Skills based on your preferences. Select which part of the setup documentation you would like to jump to:

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th><th data-hidden data-card-cover data-type="image">Cover image</th></tr></thead><tbody><tr><td><h4>Setup the MCP-Server in Goose</h4></td><td>The best option for those just starting out with AI Agents and Clients.</td><td><a href="https://github.com/ess-dive/essdive-mcp/blob/main/docs/GOOSE_SETUP.md">https://github.com/ess-dive/essdive-mcp/blob/main/docs/GOOSE_SETUP.md</a></td><td></td></tr><tr><td><h4>Connect the MCP-Server to a specific Client</h4></td><td>Select this setup option if you prefer to use a Client other than Goose. Common Clients include: VS Code with GitHub Copilot Chat, Claude Code, and Codex.</td><td><a href="https://github.com/ess-dive/essdive-mcp/blob/main/README.md#install-and-connect-to-a-client">https://github.com/ess-dive/essdive-mcp/blob/main/README.md#install-and-connect-to-a-client</a></td><td></td></tr><tr><td><h4>Install Skills</h4></td><td>See all Skills available for download and what they can do. <br><br>This is optional.</td><td><a href="https://github.com/ess-dive/essdive-mcp/blob/main/docs/SKILLS.md">https://github.com/ess-dive/essdive-mcp/blob/main/docs/SKILLS.md</a></td><td></td></tr><tr><td><h4>Example Queries</h4></td><td>Test these prompts to check that the AI Assistant is working.</td><td><a href="https://github.com/ess-dive/essdive-mcp/blob/main/README.md#first-queries-to-try">https://github.com/ess-dive/essdive-mcp/blob/main/README.md#first-queries-to-try</a></td><td></td></tr><tr><td><h4>Troubleshooting</h4></td><td>Find answers to common setup questions.</td><td><a href="https://github.com/ess-dive/essdive-mcp/blob/main/README.md#troubleshooting">https://github.com/ess-dive/essdive-mcp/blob/main/README.md#troubleshooting</a></td><td></td></tr><tr><td><h4>Tool-Level Examples</h4></td><td>If your client supports direct tool calling, these examples demonstrate how to reference our tools in prompts. </td><td><a href="https://github.com/ess-dive/essdive-mcp/blob/main/README.md#tool-level-examples">https://github.com/ess-dive/essdive-mcp/blob/main/README.md#tool-level-examples</a></td><td></td></tr></tbody></table>