> This page is for Tools.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.moveworks.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.moveworks.com/_mcp/server.

# Citations

# What are citations?

[Citations](/harness/agentic-reasoning-engine/reasoning-loops) enhance user trust by providing verifiable references to the data returned by AI agents. They consist of in-line verification links anchored to business objects (e.g., a `User` card or task record) displayed in the AI’s response. Citations are **highly recommended whenever plugins return data** to ensure transparency and reliability.

### Key Benefits

* **Trust**: Links to source systems allow users to verify information.
* **Clarity**: Business objects are presented clearly, often as cards or clickable references.

![](https://files.readme.io/8e1ee535519e460682f3e6a2cb3a30d375756072e2dc4a2480f954f2b1eb8be6-CleanShot_2024-12-11_at_17.58.142x.png)

![](https://files.readme.io/ed2c851ba71e90cb4c3b7bf56b3b0b8e39178f3c71340cc069a1a56229692535-CleanShot_2024-12-11_at_18.04.172x.png)

# Configuring Citations

Where you configure citations depends on whether your conversational process uses an **Action** or a **Compound Action**.

## Actions vs. Compound Actions

#### Actions (HTTP Actions)

When your conversational process calls an **Action** directly, configure citations in the **output mapper of the action activity** within the conversational process. The output mapper lets you add `id` and `friendly_id` fields to the action’s response data before it reaches the reasoning engine.

![](/_fern-img/5262145cc35a96a1b2f0897cad28ba3c9e051b840239aa1ec34279d061d170b7.webp)

This approach is configured per-conversational process, so the same action can have different citation mappings in different plugins.

#### Compound Actions

When your conversational process calls a **Compound Action**, configure citations in the **`return` statement of the compound action itself**. This is the recommended approach because it makes the citation logic reusable — any plugin that calls the compound action automatically gets properly cited results without additional configuration.

![](/_fern-img/a800565082a4c4149a6ecb9f3c56ea7e82b35dd5a4fa2d2ba9f8f0463e552573.webp)

Since the citation mapping lives inside the compound action, it stays consistent everywhere the compound action is used.

> **Tip**
>
> **When to use which approach?**
>
> * **Compound Actions** (recommended for reusability): Define citations in the compound action’s `return` statement. Any plugin that calls the compound action inherits the citation configuration automatically.
> * **Actions**: Define citations in the output mapper of the action activity within the conversational process. Use this when you need per-plugin control over citation formatting or when you’re calling an HTTP Action directly.

## Citation Object Schema

Each citation object must include:

* `id` **(Required)**: A unique, string-based identifier for the business object.
* `friendly_id`**(Optional)**: A human-readable string to describe the object.

#### Best Practices:

* **Unique IDs**: Ensure the `id` is unique to avoid anchoring to unintended parts of the Assistant's response (e.g., avoid generic IDs like "1" that may appear elsewhere, such as in "1 hour").
* **Single Object per Citation**: Each citation should represent one business object to prevent confusion.

## Returning a Single Object

Use the `result` key to return a single citation object.

#### Example:

**`Compound Action`**

```yaml Compound Action
steps:
  - action:
      action_name: get_company_info
      output_key: action_result
      input_args:
        company_id: data.company_id
  - return:
      output_mapper:
        result:
          MERGE():
            - data.action_result
            - id: data.action_result.system_id
              friendly_id: data.action_result.name
```

Say the output of `action_result` was:

```json
{
  "system_id": "86b7657c-10b1-4a2e-b85c-be1f590dd89d",
  "name": "Pied Piper Inc.",
  "state": "California",
  "num_employees": 4000
}
```

To meet the citation schema it requires the `id` and `friendly_id` and using the `MERGE` function allows us to do that.

#### Output with Citation

```json
{
  "result": {
    "id": "86b7657c-10b1-4a2e-b85c-be1f590dd89d",
    "friendly_id": "Pied Piper Inc.",
    "system_id": "86b7657c-10b1-4a2e-b85c-be1f590dd89d",
    "name": "Pied Piper Inc.",
    "state": "California",
    "num_employees": 4000
  }
}
```

## Returning a List of Objects

Use the `results` key to return multiple citation objects, processed with the `MAP` function to apply the citation schema to each item.

#### Example

**`Compound Action`**

```yaml Compound Action
steps:
  - action:
      action_name: get_company_list
      output_key: action_result
      input_args:
        region: data.region
  - return:
      output_mapper:
        results:
          MAP():
            converter:
              MERGE():
                - item
                - id: item.system_id
                  friendly_id: item.name
            items: data.action_result.list_of_records
```

#### Output without Citation

```json
{
  "list_of_records": [
    {
      "system_id": "86b7657c-10b1-4a2e-b85c-be1f590dd89d",
      "name": "Pied Piper Inc.",
      "state": "California",
      "num_employees": 4000
    },
    {
      "system_id": "df2cdf0f-0dff-4c82-a142-787661ef67b1",
      "name": "Dunder Mifflin",
      "state": "New York",
      "num_employees": 8500
    }
  ]
}
```

#### Output with Citation

```json
{
  "results": [
    {
      "id": "86b7657c-10b1-4a2e-b85c-be1f590dd89d",
      "friendly_id": "Pied Piper Inc.",
      "system_id": "86b7657c-10b1-4a2e-b85c-be1f590dd89d",
      "name": "Pied Piper Inc.",
      "state": "California",
      "num_employees": 4000
    },
    {
      "id": "df2cdf0f-0dff-4c82-a142-787661ef67b1",
      "friendly_id": "Dunder Mifflin",
      "system_id": "df2cdf0f-0dff-4c82-a142-787661ef67b1",
      "name": "Dunder Mifflin",
      "state": "New York",
      "num_employees": 8500
    }
  ]
}
```

# Troubleshooting

## Citation Not Appearing

* **Incorrect Schema**: Ensure each citation object includes a string-based `id`. If the schema is invalid, data under `result` or `results` will be removed from the response. Verify using the [DSL and Mapper Playground](/api-reference/configuration-languages/dsl-and-mapper-playground).
* **ID Not in Response**: The AI anchors citations to verbatim instances of `id` or `friendly_id` in its response. If the ID (e.g., `TOP_10_COMPANY_PALO_ALTO`) appears elsewhere (e.g., "View the top 10 companies in Palo Alto"), the citation may fail. Add instructions in the Plugin Result Instructions or plugin description to include the `id` or `friendly_id` verbatim.

#### Example Fix

```yaml
plugin_description: "Always include the task title ({data.task_info.title}) in the response."
```

## Citation Anchoring to Wrong Item

* **Non-Unique IDs**: If the id or friendly_id is not unique (e.g., id: "1" appears in "1 hour" in the response), the citation may anchor incorrectly. Use specific, unique IDs (e.g., TASK-17431) to avoid conflicts.

#### Example Fix in Output Mapper

```yaml
result:
	id: data.action_result.system_id  # Use unique ID like "TASK-17431"
  friendly_id: data.action_result.name
```

# Best Practices

* **Unique Identifiers**: Choose id values that are unlikely to appear in the AI’s natural language response (e.g., UUIDs or prefixed IDs like `TASK-123`).
* **Clear Friendly IDs**: Use `friendly_id` values that are human-readable and descriptive (e.g., "Write Product Requirements" instead of "Task 1").
* `Single Object per Citation`: Avoid creating multiple citations for the same business object to prevent user confusion.