# How to use the Pipelines tool

## Introduction

To handle the multiple steps required for FinnGen analyses, from data preparation to final output, we created streamlined analysis pipelines. By combining validation, parallel processing, and output generation into one workflow, we can easily manage complex GWAS, fine-mapping, and genetic correlation analyses across thousands of endpoints. We have made these workflows available to all users to make performing these analyses faster and easier. These analysis workflows are available in the **Pipelines tool**.

Analyses submitted in the Pipelines tool are run in Google Cloud and not on your local virtual machine and thus allows for larger and more parallelized analyses.

## Accessing the Pipelines tool

To open the Pipelines tool, simply open up the sandbox "start menu" by clicking **Applications** (usually in the top-left corner of the screen). From that menu, click **Sandbox** top open a second menu and then click **Pipelines**.

This will open the Pipelines page in the Firefox web browser with three boxes:

* FinnGen workflows
* User-defined workflows
* Submitted jobs

<figure><img src="/files/Kn1WCKMP1fu7JCwEKSgq" alt="A screenshot showing the front page of the Pipelines tool"><figcaption></figcaption></figure>

## Submitting an analysis

<figure><img src="/files/guffGRtpqVVuYJYxjAUE" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/EryYX5xKoBG5J8m1rD9Y" alt=""><figcaption></figcaption></figure>

There are two ways to submit an analysis in the Pipelines tool. One is to use pre-built workflows made available to users, using **FinnGen workflows**, and the other is to create your own custom workflows, using **User-defined workflows**. For most users, there will be a pre-built workflow that will meet their needs, but more advanced users with knowledge of [WDL](https://openwdl.org/) (Workflow Descriptor Language; the coding language used to write the workflows) are able to create their own analysis workflows.

### FinnGen workflows

The simplest way to run an analysis in the cloud is to submit it using pre-built and centrally maintained workflows. These allow you to input your own curated FinnGen data into standard pipelines and, once completed, access the results. There are two types of workflows: <mark style="color:green;">**Green workflows**</mark> (a.k.a. "unmodifiable" workflows) and <mark style="color:red;">**Red workflows**</mark> (a.k.a. "modifiable" workflows).

<figure><img src="/files/oIwyOvVlYT8mdK8ExEh4" alt="A screenshot of the &#x22;FinnGen workflows&#x22; box on the Pipeline tools home page"><figcaption></figcaption></figure>

With <mark style="color:green;">**Green workflows**</mark>, you can choose the input data but cannot make any changes to how the specific analysis runs (i.e., the existing workflow .wdl cannot be edited). The advantage is that your results will be automatically copied to the green library and to the user-results PheWeb, with no download requested needed. **Note**: Green/Unmodifiable analysis workflows are only available for FinnGen release 12 (R12) and later.

With <mark style="color:red;">**Red workflows**</mark>, you can choose the input data and also make changes to how the specific analysis runs (by editing the existing workflow .wdl). As a consequence, the results cannot be automatically validated and thus copied to the green library or user-results PheWeb. A download request is required to access the results from outside of the sandbox environment.

#### <mark style="color:green;">Green workflows</mark>

Clicking on the <mark style="color:green;">Green workflows</mark> link takes you to a page listing the available green "unmodifiable" analysis workflows. The workflow **Name** indicates the analysis is performed and the FinnGen release that data that is used. For example, "UnmodifiableRegenieDF13" indicates that the workflow is the "unmodifiable" REGENIE (GWAS) workflow for release 13. If the workflow names are not clear, please refer to the **Description** for more details.

<figure><img src="/files/aMmNMcC4dZ3wUyOPc57M" alt="A screenshot of the Green workflows page, listing the available unmodifiable workflows"><figcaption></figcaption></figure>

The Green "unmodifiable" workflows currently available in the Pipelines tool are (click links for usage instructions):

* [Standard REGENIE GWAS](/working-in-the-sandbox/running-analyses-in-sandbox/how-to-run-genome-wide-association-studies-gwas/how-to-run-gwas-using-the-regenie-unmodifiable-pipeline.md)
* [Interaction REGENIE GWAS](/working-in-the-sandbox/running-analyses-in-sandbox/how-to-run-genome-wide-association-studies-gwas/how-to-run-an-interaction-gwas-using-the-regenie-unmodifiable-pipeline.md)
* [Finemapping of GWAS results](/working-in-the-sandbox/running-analyses-in-sandbox/how-to-run-finemapping-pipeline/unmodifiable-finemapping-pipeline.md)
* [Conditional analysis of GWAS results](/working-in-the-sandbox/running-analyses-in-sandbox/how-to-run-genome-wide-association-studies-gwas/conditional-analysis/unmodifiable-conditional-analysis-pipeline.md)
* [Conditional analysis of GWAS results using custom-define regions](/working-in-the-sandbox/running-analyses-in-sandbox/how-to-run-genome-wide-association-studies-gwas/conditional-analysis/unmodifiable-conditional-analysis-custom-regions-pipeline.md)
* [LDSC Genetic correlation](/working-in-the-sandbox/running-analyses-in-sandbox/how-to-run-ldsc-pipeline.md)
* [GATE survival GWAS](/working-in-the-sandbox/running-analyses-in-sandbox/how-to-run-genome-wide-association-studies-gwas/how-to-run-survival-analysis-using-gate-unmodifiable-pipeline.md)

Each Green "unmodifiable" workflow has a different set of input options, so please follow the relevant instructions for the specific workflow.

Browse the list of workflows until you find the one you are interested in, then click <mark style="background-color:$info;">Download</mark> or <mark style="background-color:blue;">Create</mark>. Downloading the analysis workflow allows you submit your analysis to the cloud using the terminal, but in this case the analysis results are not automatically copied to the green library or uploaded to the user-results PheWeb because we cannot ensure that the workflow has not been modified. Please refer to [How to submit a pipeline from the command line](/working-in-the-sandbox/running-analyses-in-sandbox/pipelines-tool-instructions/how-to-submit-a-pipeline-from-a-command-line.md) for more information.

Clicking <mark style="background-color:blue;">Create</mark> loads the page of your selected workflow, which shows the WDL code that performs the analysis and, below it, the Input JSON which contains the input options and is where you need to specify your input files and analysis options. To see all the input options, expand the Input JSON text box by clicking and dragging the triangular tab in the bottom-right corner of the box.

<figure><img src="/files/mfOdwVadg8BNtj7VNpyy" alt="Screenshot of an example green workflow page after clicking &#x22;Create&#x22; next to one of the workflows in the Green workflow list. It shows the WDL code used to run the analysis and, below that, the input json file where users&#x27; input files and options are entered"><figcaption></figcaption></figure>

The Pipelines tool won't check whether your input options are correct, but it will check that the syntax is correct (e.g., that you haven't accidentally deleted a necessary double-quote or comma symbol). The result of this check can be seen in the bottom-left of the Input JSON box. If the syntax is correct, it will display "JSON validity: <mark style="color:green;">valid</mark> <mark style="background-color:$success;">**✓**</mark>" and if incorrect will display "JSON validity: <mark style="color:red;">invalid</mark> <mark style="background-color:$danger;">**!**</mark> ". Do not submit your analysis if the check states that your Input JSON is <mark style="color:red;">invalid</mark>, as it will fail to run. Instead, carefully check your edits to find the mistake. The check will state that it is <mark style="color:green;">valid</mark> once you corrected the mistakes.

Once you have edited the text in the Input JSON section with your chosen options and the relevant paths to your desired input files, click <mark style="background-color:$success;">Submit</mark> to send the analysis to the cloud. If you don't wish to submit yet and plan to return later to finishing editing the input options, click <mark style="background-color:blue;">Save Draft</mark> to store the edits you have already made. In a similar fashion, the <mark style="background-color:blue;">Load Draft</mark> button can be used to load a previously saved draft.

Once jobs have been submitted, you can see their status in the Pipelines tool - see [Submitted jobs](#submitted-jobs).

#### <mark style="color:red;">Red workflows</mark>

Clicking on the <mark style="color:red;">Red workflows</mark> link takes you to a page listing the available red "modifiable" analysis workflows. As with the Green workflows page, the workflow **Name** indicates the analysis is performed and the FinnGen release that data that is used. For example, "HLAassociatedDF13" indicates that the workflow is the "modifiable" HLA allele association (GWAS) workflow for release 13. If the workflow names are not clear, please refer to the **Description** for more details.

<figure><img src="/files/5Vf4jAgnGUNaORXWYDpr" alt="A screenshot of the Red workflows page, listing the available modifiable workflows"><figcaption></figcaption></figure>

The Red "modifiable" workflows currently available in the Pipelines tool include (click links for usage instructions):

* [Finemapping](/working-in-the-sandbox/running-analyses-in-sandbox/how-to-run-finemapping-pipeline/modifiable-finemapping-pipeline.md) (releases 7, 11 and 12)
* [Conditional analysis of GWAS results](/working-in-the-sandbox/which-tools-are-available/untitled/conditional-analysis-of-custom-gwas-analyses.md) (releases 10, 11 and 12)
* [Conditional analysis of GWAS results using custom-define regions](/working-in-the-sandbox/running-analyses-in-sandbox/how-to-run-genome-wide-association-studies-gwas/conditional-analysis/modifiable-conditional-analysis-custom-regions-pipeline.md) (release 12 only)
* [GATE survival GWAS](/working-in-the-sandbox/running-analyses-in-sandbox/how-to-run-genome-wide-association-studies-gwas/how-to-run-gwas-using-gate-survival-models.md) (releases 6, 10, 11 and 12)
* [HLA-allele only GWAS](/working-in-the-sandbox/running-analyses-in-sandbox/how-to-run-genome-wide-association-studies-gwas/how-to-run-gwas-on-imputed-hla-alleles-using-regenie.md) (release 13 only)
* [Polygenic Risk Score (PRS) calculator](https://docs.finngen.fi/working-in-the-sandbox/running-analyses-in-sandbox/how-to-run-prs) (releases 12 and 13)
* [Polygenic Risk Score weights generator](https://docs.finngen.fi/working-in-the-sandbox/running-analyses-in-sandbox/how-to-run-prs) (release 12 only)

Find the workflow you wish to use, then click <mark style="background-color:$info;">Download</mark> or <mark style="background-color:blue;">Create</mark>. Downloading the analysis workflow allows you submit your analysis using the terminal, but at the cost of analysis results not being automatically copied to the green library or uploaded to the user-results PheWeb. Please refer to [How to submit a pipeline from the command line](/working-in-the-sandbox/running-analyses-in-sandbox/pipelines-tool-instructions/how-to-submit-a-pipeline-from-a-command-line.md) for more information.

As with the Green workflows, clicking <mark style="background-color:blue;">Create</mark> loads the page of your selected workflow, which shows the WDL code that performs the analysis and, below it, the Input JSON where analysis input options and files are specified.

<figure><img src="/files/7GmcGo5jEC77e8goGSD4" alt="Screenshot of an example red workflow page after clicking &#x22;Create&#x22; next to one of the workflows in the Red workflow list. It shows the WDL code used to run the analysis, which can be edited"><figcaption></figcaption></figure>

Unlike with the Green "unmodifiable" workflow page, this time the WDL code can be edited to modify the analysis itself. Here, you can made your edits to the workflow to customise its behavior before submitting the analysis to the cloud. As you are making edits, the Pipelines tool will track whether the syntax is correct and will display a warning stating

> &#x20;<mark style="background-color:$warning;">**!**</mark> Unexpected WDL format. Please check your WDL!

if incorrect. If the warning is displayed, the red box beneath the warning will inform you of where the Pipelines tool thinks that the syntax is incorrect, which should help identify mistakes in the code.

Beneath the WDL code section is the Input JSON text box. This is where you can specify all the input files and input options needed for your specific analysis. To be able to see all the input options, you can expand the Input JSON text box by clicking and dragging the triangular tab in the bottom-right corner of the box.

<figure><img src="/files/CLAmoBtBSxwIn8HIsWvJ" alt=""><figcaption></figcaption></figure>

The Pipelines tool won't check whether your input options are correct, but (as with the WDL code) it will check that the syntax is correct but (unlike with the WDL code) cannot tell you where the mistake is. You can see the result of this check in the bottom-left of the Input JSON box, which will display "JSON validity: <mark style="color:green;">valid</mark> <mark style="background-color:$success;">**✓**</mark>" if correct and "JSON validity: <mark style="color:red;">invalid</mark> <mark style="background-color:$danger;">**!**</mark> " if incorrect. If the check returns <mark style="color:red;">invalid</mark>, carefully check your Input JSON and correct mistakes until the check once again states <mark style="color:green;">valid</mark>. Do not submit your analysis if the check states that your Input JSON is <mark style="color:red;">invalid</mark>, as it will fail to run.

Once you have made your desired edits to the WDL code and added your input file paths and optons to the Input JSON section, click <mark style="background-color:$success;">Submit</mark> to send the analysis to the cloud. If you don't wish to submit yet and plan to return later to finishing editing the input options, click <mark style="background-color:blue;">Save Draft</mark> to store the edits you have already made. In a similar fashion, the <mark style="background-color:blue;">Load Draft</mark> button can be used to load a previously saved draft.

Once jobs have been submitted, you can see their status in the Pipelines tool - see [Checking the status of submitted jobs](#checking-the-status-of-submitted-jobs).

#### <mark style="color:$info;">Edit draft</mark>

Clicking <mark style="color:$info;">Edit draft</mark> will open the WDL and Input JSON page of the last workflow that you saved the draft of (using the <mark style="background-color:blue;">Save Draft</mark> button). This can be either a <mark style="color:green;">Green</mark> or <mark style="color:red;">Red</mark> workflow, depending on which was the last draft workflow to be saved. Therefore, always double-check which workflow you are editing.

### User-defined workflows

If the pre-built Green and Red workflows are not suitable for your needs, then it is possible to create your own custom analysis workflows for running in the cloud. Analyses are written in [WDL](https://openwdl.org/) (Workflow Descriptor Language) and require you to specify a docker image which contains the operating system and software that the analysis will be run in. This option is typically for more advanced users due to the technical difficulty of writing a workflow in WDL. For a basic guide on creating your first WDL workflow, [click here](https://docs.openwdl.org/getting-started/quickstart.html).

<figure><img src="/files/FV8E8DSZOfPMJGeqKxos" alt="Screenshot of the &#x22;User-defined workflows&#x22; box on the Pipelines tool home page"><figcaption></figcaption></figure>

#### <mark style="color:red;">Create your own workflow</mark>

Clicking on the <mark style="color:red;">**Create your own workflow**</mark> link will load a page with two empty boxes:

* **WDL**: Here you put your analysis code, written in [WDL](https://openwdl.org/). You can either write your code from scratch or copy code from either your own existing WDL(s) or pre-existing WDLs. We recommend the creating your own workflow (in a .wdl file) elsewhere in the sandbox and then copy-pasting into the WDL box on this page.
* **Input JSON**: Here the input options and file paths can be specified as a .json format file. This is where you can put variables that will change between different runs of your custom analysis, so that you can avoid rewriting your WDL workflow for every analysis.

<figure><img src="/files/EozHtDS6K7jQBJ6N7CuU" alt="Screenshot of the &#x22;Create your own workflow&#x22; page. It shows the empty WDL code box where the user&#x27;s analysis code (written in WDL) can be entered. Below this is the empty Input JSON box where input files and options can be specified for passing to the workflow when submitted."><figcaption></figcaption></figure>

After filling in these two boxes, the Pipelines tool will check for the validity of both the WDL and input json syntax. If there is a syntax mistake, a warning message stating " <mark style="background-color:$warning;">**!**</mark> Unexpected WDL format. Please check your WDL!" will appear at the bottom of the WDL box, otherwise if the syntax is correct no message will be displayed. If the WDL syntax warning is displayed, the red box beneath the warning will inform you of where the Pipelines tool thinks that the syntax is incorrect, which should help identify mistakes in the code.

In the Input JSON, the Pipelines will also check that the syntax is correct but (unlike for the WDL code) cannot tell you where the mistake is. The result of this check is seen in the bottom-left of the Input JSON box, which will display "JSON validity: <mark style="color:green;">valid</mark> <mark style="background-color:$success;">**✓**</mark>" if correct and "JSON validity: <mark style="color:red;">invalid</mark> <mark style="background-color:$danger;">**!**</mark> " if incorrect. If the check returns <mark style="color:red;">invalid</mark>, carefully check your Input JSON and correct mistakes until the check once again states <mark style="color:green;">valid</mark>. Do not submit your analysis if the check states that your Input JSON is <mark style="color:red;">invalid</mark>, as it will fail to run.

**Note**: The Pipelines tool does not check the logic of your workflow and whether specified input files exist - it only checks whether your code and input options are consistent (e.g., that all variables declared in WDL are specified in the Input JSON.

Once you are satisfied that the WDL code and Input JSON are correct, click <mark style="background-color:$success;">Submit</mark> to send the analysis to the cloud. If you don't wish to submit yet and plan to return later to finishing editing the input options, click <mark style="background-color:blue;">Save Draft</mark> to store the edits you have already made. The <mark style="background-color:blue;">Load Draft</mark> button can be used to load a previously saved draft.

Once jobs have been submitted, you can see their status in the Pipelines tool - see [Checking the status of submitted jobs](#checking-the-status-of-submitted-jobs).

#### <mark style="color:$info;">Edit draft</mark>

Clicking <mark style="color:$info;">Edit draft</mark> will open the WDL and Input JSON page of the last workflow that you saved the draft of (using the <mark style="background-color:blue;">Save Draft</mark> button), allowing you to continue editing your draft analysis workflow before submitting it.

## Checking the status of submitted workflows

On the Pipelines tool main page, you are also able to find the status of your submitted jobs using the links in the **Submitted jobs** box. The links are:

* <mark style="color:$primary;">Show pipelines jobs</mark>: See a list of all jobs that you have run or are running, regardless of their status. You can also change the filters so that you can see analyses submitted by other users within the same sandbox.
* <mark style="color:$primary;">Running</mark>: See a list of your jobs that are currently running
* <mark style="color:$primary;">Succeeded</mark>: See a list of your jobs that have successfully completed
* <mark style="color:$primary;">Failed</mark>: See a list of your failed jobs

<figure><img src="/files/7O45cdXxyOSQVSCeKtZ0" alt="Screenshot of the &#x22;Submitted jobs&#x22; box on the Pipelines tool home page. It shows 4 options: &#x22;Show pipeline jobs&#x22;, &#x22;Running&#x22;, &#x22;Succeeded&#x22; and &#x22;Failed&#x22;"><figcaption></figcaption></figure>

Clicking <mark style="color:$primary;">**Show pipeline jobs**</mark> will load the "Recent jobs" page which contains a table of all recent jobs that you have submitted. Clicking the <mark style="color:$primary;">**Running**</mark>, <mark style="color:$primary;">**Succeeded**</mark> or <mark style="color:$primary;">**Failed**</mark> links will also bring you to the same page, but will filter the displayed jobs on the selected job status. The "Recent jobs" page displays a table of your "jobs" (submitted workflows) with the following details for each:

* **State**: one of "Submitted", "Running", "Succeeded" or "Failed". "Submitted" jobs are analyses that have not yet started
* **ID**: Cromwell ID (in UUID format). This is a random string that is generated when the workflow starts running and is a unique identifier for your submitted workflow. Jobs in "Submitted" state may not have yet been assigned an ID.
* **Name**: name of the workflow (e.g., "regenie\_unmod" for the green "unmodifiable" REGENIE GWAS workflow). This is defined in the WDL code (.wdl file) by the name given to the `workflow` function.
* **User**: First and second name of the user that submitted the workflow
* **Started At**: Date and time that the workflow analyses was submitted.
* **Ended At**: Date and time that the workflow analyses ended (i.e., entered "Succeeded" or "Failed" state). Jobs in "Submitted" and "Running" state will not have an entry in this field.

<figure><img src="/files/H1Vdz7PF2YTIvN8tmUr2" alt="Screenshot of the &#x22;Recent jobs&#x22; page, which is reached by clicking any of the links in the &#x22;Submitted jobs&#x22; box on the Pipelines home page. It shows the user&#x27;s recent submitted workflows, their &#x22;state&#x22; (&#x22;submitted&#x22;, &#x22;running&#x22;, &#x22;failed&#x22; or &#x22;succeeded&#x22;), submission ID, name and start/end date and time"><figcaption></figcaption></figure>

By default, only workflows that you submit in the past month will be displayed in this table. If you wish to see the status of all users' jobs within your sandbox, click the <mark style="background-color:$info;">All Jobs</mark> button above the table (default is <mark style="background-color:$info;">My Jobs</mark>) to the right of "Show only". Similarly, if you wish to see the status of workflows submitted more than a month ago, click either the <mark style="background-color:$info;">Last Year</mark> or <mark style="background-color:$info;">All Time</mark> buttons above the table and to the right of "started within" to see all workflows submitted in the past year or all workflows that have ever been submitted. For the purpose of speed, the "Recent jobs" table only shows 10 jobs at a time - you can browse through multiple pages using the pagination (page numbers) at the bottom right of the "Recent jobs" page.

The <mark style="background-color:$info;">Search</mark> <mark style="background-color:$success;">+</mark> box above the table allows you to search the list of jobs based on any attribute. For instance, typing "Failed" in the box will show jobs with the string Failed in *any* field. This allows you to search for specific IDs, workflow names and even dates and times (e.g., typing "17.04.26" will filter for jobs that either started or ended on that date).

### Detailed information about a submitted workflow

On the "Recent jobs" page, you can click on any job in the table to load the "Job details" page with detailed information on that job. There will be four tabs:

* **Info**: This is where basic information about the job is displayed, workflow output variable and file paths (under **Outputs**) if the job has "Succeeded" and (displayed in a red box) any errors the job has had so far (if still "Running") or had (if "Succeeded" or "Failed").
* **WDL**: The submitted WDL code and Input JSON text for this workflow.
* **Sub WDLs**: Submitted WDL code for any sub-WDLs provided when submitting the workflow (it can be advantageous to split WDL code into multiple modular scripts - some pre-built workflows use this feature). If no sub-WDLs used, then this tab will be blank.
* **Calls & Steps**: Similar to the **Info** tab, but with detailed information for specific tasks within the workflow. Tasks can be select by clicking <mark style="background-color:$info;">Select Call ▾</mark>, which opens a drop-down menu with the individual tasks. Clicking on any of these tasks in the drop-down menu will display information about that task, including status, start and end time and date, the docker image the task used and the paths of the standard output (stdout) and standard error (stderr) files. The standard output and error files can be useful for diagnostics if the code failed or produced unexpected output. If the workflow is still "Running" and hasn't reached a specific task or if the workflow failed before reaching a specific task, the task will not be displayed in the drop-down menu.

<figure><img src="/files/FYvd6YUfbKwzIg2iHC5L" alt="Job details for a failed job showing the &#x22;Info&#x22; tab with basic details such as job ID, name, start and end date and times and then a red box containing the errors that occurred when running the job"><figcaption></figcaption></figure>

At the bottom of the "Job details" page, you can find the <mark style="background-color:$success;">Download metadata (zip)</mark> and <mark style="background-color:blue;">Clone as new job</mark> buttons. Clicking <mark style="background-color:$success;">Download metadata (zip)</mark> will open a prompt to save a zip file, which contains the detailed Cromwell logs (in .json format) of the job. The "metadata" logs contained within this zip file, along with the error messages in the **Info** tab and the standard error and output files for specific tasks, are vital for identifying why a job failed. For more information on debugging job failures, please see [If your pipeline job fails](/working-in-the-sandbox/running-analyses-in-sandbox/pipelines-tool-instructions/if-your-pipeline-job-fails.md).

Clicking the <mark style="background-color:blue;">Clone as new job</mark> button will load the same page that you submitted your workflow from (<mark style="color:green;">**Green workflows**</mark> or <mark style="color:red;">**Red workflows**</mark> in **FinnGen workflows** or <mark style="color:red;">**Create your own workflow**</mark> in **User-defined workflows**) and fill the WDL and Input JSON boxes with the text of your submitted workflow. This allows you to make edits to WDL (if not a Green workflow) and Input JSON before resubmitting (e.g., in the case where your previous job failed due to a correctable issue).

## Related

* [Pipelines tool instructions](/working-in-the-sandbox/running-analyses-in-sandbox/pipelines-tool-instructions.md)
* [Running analyses in sandbox](/working-in-the-sandbox/running-analyses-in-sandbox.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.finngen.fi/working-in-the-sandbox/running-analyses-in-sandbox/pipelines-tool-instructions/how-to-use-the-pipelines-area.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.