Tools

The tools of a rest-api, dial-deployment, or internal Toolset define each tool: its function schema for the model, where calls go, how stages look, and what happens on failure. This reference lists the fields of every tool type and their shared settings. It is for app developers who write Quick App manifests. It assumes you know tool sets.

Tool types

`type`	Allowed in	What it calls
`restapi-tool`	`rest-api`	An HTTP endpoint
`deployment-tool`	`dial-deployment`	A DIAL model or application, with a function you define
`dial-deployment-simple`	`dial-deployment`	A DIAL model or application, as it is
`internal-tool`	`internal`	A tool built into the backend
`predefined-tool`	`rest-api`, `dial-deployment`, `internal`	A tool template, such as `dial_rag`

restapi-tool, deployment-tool, and internal-tool share these fields:

Field	Required	Default	Description
`open_ai_tool`	Yes	—	The function the model sees. See Function.
`enabled`	No	`true`	Whether the tool is used
`display`	No	—	See Display
`attachment`	No	—	See Attachments
`fallback_configuration`	No	Forward the error	See Fallback configuration

`restapi-tool`

Field	Required	Description
`rest_api_method_info`	Yes	`method_url` and `method_type` (`get`, `post`, `put`, or `delete`)
`response_as_attachment`	No	Turns the HTTP response into an attachment: `enabled` (default `false`), `content_types` (the response types to convert), and `include_body_as_content` (default `true`, keeps the body as text too)

Each parameter of a REST tool needs parameter_info: where the value goes, and under what key.

`parameter_info.type`	The value goes to
`query`	The query string
`url`	The `{key}` placeholder in `method_url`
`body`	The JSON body
`header`	An HTTP header

A parameter with "type": null and a const value is always sent, and the model never sees it.

{
  "type": "restapi-tool",
  "rest_api_method_info": { "method_url": "https://crm.example.com/api/v1/tickets/{ticket_id}", "method_type": "get" },
  "open_ai_tool": {
    "type": "function",
    "function": {
      "name": "lookup_ticket",
      "description": "Look up the status and details of a support ticket by its ID.",
      "parameters": {
        "type": "object",
        "properties": {
          "ticket_id": {
            "type": "string",
            "description": "The ticket ID, such as TICK-1234.",
            "parameter_info": { "type": "url", "key": "ticket_id" }
          },
          "format": { "type": null, "const": "json", "parameter_info": { "type": "query", "key": "format" } }
        },
        "required": ["ticket_id"]
      }
    }
  }
}

`deployment-tool`

Field	Required	Description
`deployment`	Yes	`deployment_id` and `parameters`. The parameters are the orchestrator's, plus `tools`: `static_function` tools the called deployment runs itself, such as web search.
`system_prompt`	No	A `custom` or `dial` system prompt for the call
`conversation_mode`	No	See Conversation mode
`propagate_annotations_to_choice`	No	Forwards the deployment's citation annotations to the answer. See DIAL deployments as tools.
`content_propagation`	No	`propagate_headers`: the headers sent to the deployment; default headers when unset. Its `propagate_history` is deprecated.

{
  "type": "deployment-tool",
  "deployment": {
    "deployment_id": "<GEMINI_MODEL_ID>",
    "parameters": {
      "reasoning_effort": "high",
      "tools": [{ "type": "static_function", "static_function": { "name": "web_search" } }]
    }
  },
  "open_ai_tool": {
    "type": "function",
    "function": {
      "name": "grounded_search",
      "description": "Answer a question with up-to-date facts from the web.",
      "parameters": {
        "type": "object",
        "properties": { "query": { "type": "string", "description": "The question to answer." } },
        "required": ["query"]
      }
    }
  }
}

Only static_function tools are accepted in deployment.parameters.tools. Their stages aren't shown inside the tool's stage.

`dial-deployment-simple`

Field	Required	Description
`deployment_id`	Yes	The DIAL model or application
`conversation_mode`	No	See Conversation mode
`propagate_annotations_to_choice`	No	Forwards the deployment's citation annotations to the answer

The tool's configuration comes from DIAL Core, so an override from a template doesn't apply to it.

`internal-tool`

Defines the function of a tool built into the backend. The Python interpreter's template, py_interpreter, is an internal-tool whose function is internal_code_execution_python_interpreter. Use the template, through the py_interpreter predefined tool or Toolset, rather than writing the entry.

`predefined-tool`

Field	Required	Default	Description
`template_name`	Yes	—	The template: `dial_rag`, `web_search`, `image_generation`, or `py_interpreter`, or one added with `PREDEFINED_EXTRA_PATHS`
`enabled`	No	`true`	With `false`, the tool isn't loaded
`override`	No	—	A JSON Merge Patch applied to the template. It can't change `type`.

What each built-in template calls is in ChatHub.

Function

open_ai_tool follows the OpenAI tool format, with Quick Apps additions on each parameter.

Field	Required	Description
`type`	No	`function`
`function.name`	Yes	The name the model calls the tool by
`function.description`	Yes	When the model should use the tool, up to 1024 characters
`function.parameters`	Yes	`{ "type": "object", "properties": {...}, "required": [...] }`

A parameter takes type (string, number, integer, boolean, object, or array), description, and, as in JSON Schema, enum, items, properties, and required. Quick Apps adds:

Field	Description
`default`	The value used when the model sends none
`display`	How the parameter shows in the stage. See Display.
`parameter_info`	REST tools only: where the value goes

Display

display.stage on a tool sets its stage:

Field	Default	Description
`name`	The tool name	The stage title. `{argument}` placeholders show argument values.
`body`	—	The stage body, with the same placeholders
`defer_close`	`false`	Keeps the stage open until every parallel tool call finishes
`show`	`true`	Deprecated

display.stage on a parameter sets how the parameter shows in its tool's stage:

Field	Default	Description
`name`	The parameter name	The label shown
`ignore`	`false`	Leaves the parameter out of the stage
`ignore_parameter_name`	`false`	Shows the value without the label
`show_value_in_stage_title`	`false`	Adds the value to the stage title
`prefix`, `suffix`	—	Text before and after the value
`replaced_value_info`	—	Text shown instead of the value; `prefix` and `suffix` then don't apply
`format`	—	Wraps the value in a code block of this language. `""` gives a plain code block.
`order`	`0`	The parameter's position; lower comes first

{
  "display": { "stage": { "name": "Looking up ticket {ticket_id}" } }
}

Which stages appear at all is set by features.stage_display.

Attachments

attachment, on a tool or on an MCP-based or dial-app Toolset:

Field	Default	Description
`supported_types`	All types	The attachment MIME types the tool accepts, such as `image/png`
`propagate_types_to_choice`	`[]`	The MIME types of the tool's result attachments that appear in the answer
`media_type_substitution`	`{}`	Maps a result attachment's MIME type to another, for example for a custom visualizer

{
  "attachment": {
    "propagate_types_to_choice": ["image/png", "image/jpeg", "application/vnd.plotly.v1+json"],
    "media_type_substitution": { "application/json": "application/vnd.plotly.v1+json" }
  }
}

Fallback configuration

fallback_configuration, on a tool or on an MCP-based or dial-app Toolset. How strategies apply is in Fallbacks.

Field	Default	Description
`strategies`	`[{"type": "continue"}]`	The strategies, checked in order
`display_error_in_stage`	`true`	Shows the error text in the stage, instead of a generic notice. Timeouts always show it.

Strategy `type`	Fields	Effect
`continue`	`trigger_on`, `instructions`	Sends the error text to the model, with `instructions` appended, and continues
`hard_stop`	`trigger_on`	Ends the agent loop with a generic message
`retry`	—	Deprecated alias of `continue`
`stop`	—	Deprecated alias of `hard_stop`

trigger_on has type (contains or equals), value, and case_sensitive (default false). Without it, the strategy matches every error.

Conversation mode

conversation_mode, on deployment-tool, dial-deployment-simple, and the chat completion branch of dial-app:

Field	Default	Description
`resumable`	`false`	The tool gets an optional `session_id` argument. The first call's result carries the ID, and later calls that pass it continue the same subagent conversation.

Tool types​

restapi-tool​

deployment-tool​

dial-deployment-simple​

internal-tool​

predefined-tool​

Function​

Display​

Attachments​

Fallback configuration​

Conversation mode​

Further reading​