---
dimensions:
  type:
    primary: reference
    detail: core
  level: beginner
standard_title: Tool
language: en
title: Tool Return
description: This document provides a detailed introduction to the data structure
  and usage of Tools in Dify plugins. It covers how to return different types of messages
  (image URLs, links, text, files, JSON), how to create variable and streaming variable
  messages, and how to define tool output variable schemas for reference in workflows.
---

Before reading the detailed interface documentation, please make sure you have a general understanding of the tool integration process for Dify plugins.

### Data Structure

#### Message Return

Dify supports various message types such as `text`, `links`, `images`, `file BLOBs`, and `JSON`. You can return different types of messages through the following interfaces.

By default, a tool's output in a `workflow` includes three fixed variables: `files`, `text`, and `json`. You can use the methods below to return data for these three variables.

For example, you can use `create_image_message` to return an image, but tools also support custom output variables, making it more convenient to reference these variables in a `workflow`.

#### **Image URL**

Simply pass the image URL, and Dify will automatically download the image through the link and return it to the user.

```python
    def create_image_message(self, image: str) -> ToolInvokeMessage:
        pass
```

#### **Link**

If you need to return a link, use the following interface.

```python
    def create_link_message(self, link: str) -> ToolInvokeMessage:
        pass
```

#### **Text**

If you need to return a text message, use the following interface.

```python
    def create_text_message(self, text: str) -> ToolInvokeMessage:
        pass
```

**File**

If you need to return the raw data of a file, such as images, audio, video, PPT, Word, Excel, etc., you can use the following interface.

* `blob` The raw data of the file, in bytes type.
* `meta` The metadata of the file. If developers need a specific file type, please specify `mime_type`, otherwise Dify will use `octet/stream` as the default type.

```python
    def create_blob_message(self, blob: bytes, meta: dict = None) -> ToolInvokeMessage:
        pass
```

#### **JSON**

If you need to return a formatted JSON, you can use the following interface. This is typically used for data transmission between nodes in a workflow. In agent mode, most large models can also read and understand JSON.

* `object` A Python dictionary object that will be automatically serialized to JSON.

```python
    def create_json_message(self, json: dict) -> ToolInvokeMessage:
        pass
```

#### **Variable**

For non-streaming output variables, you can use the following interface to return them. If you create multiple instances, the latter will override the former.

```python
    def create_variable_message(self, variable_name: str, variable_value: Any) -> ToolInvokeMessage:
        pass
```

#### **Streaming Variable**

If you want to output text with a "typewriter" effect, you can use streaming variables to output text. If you use an `answer` node in a `chatflow` application and reference this variable, the text will be output with a "typewriter" effect. However, currently this method only supports string type data.

```python
    def create_stream_variable_message(
        self, variable_name: str, variable_value: str
    ) -> ToolInvokeMessage:
```

#### Returning Custom Variables

If you want to reference a tool's output variables in a `workflow` application, it's necessary to define in advance which variables might be output. Dify plugins support output variable definitions in [`json_schema`](https://json-schema.org/) format. Here's a simple example:

```yaml
identity:
  author: author
  name: tool
  label:
    en_US: label
    zh_Hans: 标签
    ja_JP: ラベル
    pt_BR: etiqueta
description:
  human:
    en_US: description
    zh_Hans: 描述
    ja_JP: 説明
    pt_BR: descrição
  llm: description
output_schema:
  type: object
  properties:
    name:
      type: string
```

The example code above defines a simple tool and specifies an `output_schema` for it, which includes a `name` field that can be referenced in a `workflow`. However, please note that you still need to return a variable in the tool's implementation code to actually use it, otherwise you will get a `None` return result.

{/*
Contributing Section
DO NOT edit this section!
It will be automatically generated by the script.
*/}

---

[Edit this page](https://github.com/langgenius/dify-docs/edit/main/plugin-dev-en/0411-tool.mdx) | [Report an issue](https://github.com/langgenius/dify-docs/issues/new?template=docs.yml)