DIAL Deep Research application properties

This reference covers per-instance applicationProperties in Deep Research 0.4.0 for platform engineers familiar with Core registration. Properties control sources, prompts, research limits, and reports. Deployment settings remain in the backend environment.

The backend validates properties on every request against ApplicationProperties. The same model supplies the live schema endpoint. A complete deployment-mode example is in Configure an application instance.

Research and report settings

Property	Default	Description
`max_research_iterations`	`5`	Positive integer. Maximum retrieval iterations before the graph proceeds to the report.
`max_research_graph_steps`	`500`	Positive integer. LangGraph super-step limit per graph execution. Exhaustion fails the turn; this is not the research-depth control.
`default_report_structure`	Four sections below	Non-empty ordered list of report sections. Names must be unique, with at least one protected section.
`max_report_words`	`2750`	Positive integer. Report word ceiling, excluding inline citations and the app-built References section. Reviews request rewrites within the version budget, rather than truncating text.
`max_report_versions`	`3`	Positive integer. Maximum drafts, including the first. The last allowed version is delivered without another review. `1` delivers the first draft unreviewed.
`references_section_name`	`References`	Non-empty heading for the section appended by the application.
`references_section_empty_text`	Text below	Non-empty text used when the report cites no source.
`max_pill_title_chars`	`null`	Optional integer, at least `10`. Shortens citation labels, including an ellipsis; the citation card retains the full name. `null` leaves labels whole.
`data_query_card_filter_max_line_chars`	`80`	Integer, at least `10`. Maximum length of each filter line on a data-query citation card, including its ellipsis.
`mcp_servers`	—	Required non-empty list of MCP connection objects; see MCP servers.
`prompts`	—	Required object containing client and agent names, plus optional client rules; see Prompts and client rules.

Defaults and semantics are defined in the root model. The default empty-reference text is:

This report cites no source: the research found no citable evidence.

Report section objects

Each default_report_structure entry contains:

Property	Default	Description
`name`	—	Required non-empty report heading.
`description`	—	Required non-empty content and formatting instructions, shared by the writer and reviewer.
`protected`	`false`	The prompt requires this section and its description to survive user instructions to remove or restyle it.

The default structure is:

Section	Protected	Content instructions
`Overview`	`true`	Research question, sources and approach, and a brief direct answer
`Key Findings`	`false`	Main findings, leading with the direct answer when supported
`Detailed Analysis`	`false`	Evidence, comparisons, disagreements, and findings resting on one source
`Conclusion`	`false`	What the findings answer and leave unanswered, without new facts

The full default instructions are in DEFAULT_REPORT_STRUCTURE. Report sections reject unknown fields. At least one must be protected, and no section may claim the appended References heading, compared after trimming and case folding. See structure validation.

MCP servers

Server names must be unique. Only generic_rag and statgpt are accepted, with at most one of each type. These constraints prevent citations from resolving an ID against the wrong server. Sources: supported types and server validation.

Common server fields

Property	Default	Description
`server_name`	—	Required non-empty internal connection name, also used in logs. Need not match the remote server name.
`server_type`	—	Required `generic_rag` for documents or `statgpt` for datasets.
`deployment_id`	`null`	DIAL Core deployment ID of the MCP application. Mutually exclusive with `connection`.
`connection`	`null`	Direct-mode `$env:{VAR}` reference to a JSON URL/key bundle. Mutually exclusive with `deployment_id`.
`tools_to_include`	`[]`	Tool names offered to the research agent. An empty list includes all tools.
`description`	`null`	Source description shown to the models. Required for Generic RAG unless `document_stats` is set. A supplied description must not be blank.
`references_table`	—	Required table title and columns for this server's cited sources; see Reference tables.

These fields are declared in MCPClientSettings and the reference-table field. tools_to_include filters agent tools; it does not prevent the application's own metadata, statistics, glossary, or citation calls.

Connection modes

Exactly one connection mode is required:

Mode	Configuration	Request behavior
Through DIAL Core	`"deployment_id": "<MCP_APPLICATION_ID>"`	Streamable HTTP at `<DIAL_URL>/v1/deployments/<MCP_APPLICATION_ID>/mcp`, using the forwarded request key and bearer token when present
Direct	`"connection": "$env:{RESEARCH_MCP_CONNECTION}"`	Streamable HTTP at the bundle's URL, using the bundle's key in the `api-key` header

In direct mode, the backend's environment variable contains:

{
  "url": "https://<MCP_HOST>/mcp",
  "api_key": "<MCP_API_KEY>"
}

The property must contain only the $env:{VAR} reference. Inline JSON and $env:{VAR|default} are rejected; unset variables and malformed bundles fail validation. The bundle allows only url and api_key; the URL must be HTTP(S) and the key non-empty. See placeholder and bundle validation, exclusive mode validation, and client construction.

Generic RAG fields

These fields belong only to a generic_rag server:

Property	Default	Description
`file_sharing_tool`	`null`	Required tool name, such as `get_citation_url`, that copies a cited document into the reader's DIAL storage and returns its URL.
`document_metadata_resource`	`null`	Required resource URI template, such as `documents://metadata/{document_ids}`. Must contain `{document_ids}` exactly once.
`document_title_key`	`null`	Required metadata key containing the publication title, such as `publication_title`. Set together with the metadata resource.
`document_stats`	`null`	Optional document statistics configuration, described below. Either this object, `description`, or both must be supplied.

The source declares these document citation fields, statistics field, and document description constraint.

The file-sharing tool is invoked by the application and is never offered to the research agent. A document lacking a usable title retains an ID/page label. See Generic RAG MCP for the tools and metadata resource.

document_stats contains:

Property	Default	Description
`list_documents_tool`	—	Required non-empty tool name. Called with `offset` and `limit`; expected result fields are `total_count` and `results`.
`document_date_key`	—	Required non-empty metadata key for publication dates. Non-ISO dates are ignored.
`document_type_key`	`null`	Optional non-empty metadata key for per-type statistics. Non-string values belong to no type.
`page_size`	`1000`	Positive integer number of documents requested per call.

Statistics are fetched at the start of every turn, for at most ten sequential pages. A listing failure or incomplete collection at that cap produces an unavailable-statistics notice to the models. It does not supply partial statistics. Source: DocumentStats and page cap and fetch behavior.

StatGPT fields

These fields belong only to a statgpt server:

Property	Default	Description
`list_datasets_tool`	`null`	Required tool name. Called without arguments for the complete catalogue, including dataset names and page addresses.
`client_meta_key`	`null`	Required exact key under MCP result `_meta`, such as `example.org/client`. Must match the dataset server's channel namespace.
`dataset_structure_tool`	`null`	Optional tool called with `{"dataset_id": "<ID>"}` for every listed dataset at the start of each turn.
`glossary`	`null`	Optional glossary tool and reference-table configuration, described below.

The dataset server must enable the client payload on both its data-query and dataset-list tools with the same namespace. The payload supplies data-explorer links for query and dataset citations. Source: dataset and glossary fields and client metadata.

Dataset structures join the catalogue in model context on every turn. The source describes this mode as intended for a channel with about ten datasets. Omitting dataset_structure_tool retains the catalogue without fetching every structure.

glossary contains:

Property	Default	Description
`list_terms_tool`	—	Required non-empty tool name, called without arguments.
`definitions_tool`	—	Required non-empty tool name, called with `{"terms": ["<TERM>"]}`. Must differ from `list_terms_tool`.
`max_terms_per_definitions_call`	—	Required positive integer. Must match the remote tool's allowed batch size.
`references_table`	—	Required reference table for cited glossary terms.

The application fetches configured glossary data at each turn's start, supplies terminology instructions, and lists cited terms in References. These automatic calls do not require the tools in tools_to_include. Source: GlossaryTools and glossary behavior.

Reference tables

Every server, and every configured glossary, must define a references_table object:

Property	Default	Description
`title`	—	Required non-empty table subheading.
`columns`	—	Required non-empty ordered list of column objects.
`columns[].heading`	—	Required non-empty column heading displayed to the reader.
`columns[].key`	—	Required non-empty field name read from a source metadata or glossary record.

The first column identifies the source. Missing values in that column fall back to the source ID or cited glossary term; other missing values leave empty cells. Dataset tables precede document tables, followed by cited glossary terms. Sources: table models, table order, and glossary table placement.

Prompts and client rules

Property	Default	Description
`prompts.client_name`	—	Required non-empty name of the organization using the application.
`prompts.agent_name`	—	Required non-empty name used by the agent to introduce itself.
`prompts.client_rules`	`[]`	Per-channel quality rules with unique names. Each step receives its corresponding instructions after the generic rules.

The prompts object rejects unknown fields. Source descriptions belong on each MCP server, not in prompts. Source: Prompts.

Each client_rules entry contains:

Property	Default	Description
`name`	—	Required non-blank, single-line rule name.
`research_agent`	`null`	Retrieval instructions: search, list, query, or read. The research agent does not write the report.
`research_review`	`null`	What counts as an evidence gap; requested next steps must be retrievals.
`report_writer`	`null`	Instructions for writing the report.
`report_review_blind`	`null`	Checks decidable from the draft, question, plan, and source descriptions without research findings. Content exclusions belong here.
`report_review_grounded`	`null`	Checks comparing the draft with research findings. Mutually exclusive with `report_review_blind` within a rule.

A rule must contain at least one instruction; supplied instructions must not be blank. Unknown rule fields are rejected. Source: QualityRule.

Example prompts object:

{
  "client_name": "Example organization",
  "agent_name": "Example Deep Research",
  "client_rules": [
    {
      "name": "Publication dates",
      "research_agent": "Retrieve publication_date metadata for the documents used as evidence.",
      "report_writer": "Identify the publication date when comparing findings from different reports.",
      "report_review_grounded": "Check that each stated publication date matches the retrieved metadata."
    }
  ]
}

Research and report settings​

Report section objects​

MCP servers​

Common server fields​

Connection modes​

Generic RAG fields​

StatGPT fields​

Reference tables​

Prompts and client rules​

Further reading​