epam/ai-dial-quickapps-backend/tool-call-file-parameter-formatting

File Parameter Formatting

Every file or URL you pass to a tool must be written as file:{prefix}::{path_or_url} — prefix one of url, data, text, base64; path either a DIAL path (files/bucket/report.pdf) or an external URL (https://example.com/report.pdf). A raw path with no file:...:: form is not processed. The same form is used for a single string parameter and for each element of an array parameter.

Step 1 — what does the parameter want?

Read the parameter's name and description in the tool definition and answer: does the tool want the file's bytes, or a locator it resolves itself?

Hints in the tool's own name or description count too (base64_image_processor, "reads their text content directly"). The description wins over the name: a parameter called uri whose description accepts http:, https:, file: or data: URIs wants content, so use data.

Step 2 — if it wants a locator, can the receiver resolve it?

A reference is only useful if the tool receiving it can actually fetch the file. file:url:: is passed through verbatim, with no credentials attached, so a DIAL path handed to a tool that lives outside DIAL arrives as a meaningless relative string. Check the receiver before settling on url:

• An external `https://` URL — anyone can fetch it. Use url, whatever the tool is.
• A DIAL path to a DIAL deployment tool (including attachment_urls) — the deployment is inside DIAL

and resolves the path itself. Use url.

• A DIAL path to an MCP or REST tool — the server is off-platform. It can only resolve the path if the

parameter is marked "dial_url": true in the schema (QuickApps grants that server access to the file first) or the description says it accepts DIAL paths. Use url then. Otherwise inline the bytes with `data` — a reference the server cannot fetch usually fails silently rather than returning a usable error.

When you cannot tell, prefer url for an external URL and data for a DIAL path going off-platform.

attachment_urls is always a reference

attachment_urls accepts only file:url:: — a DIAL path (file:url::files/bucket/report.pdf) or an external URL (file:url::https://example.com/report.pdf). The receiving deployment resolves it itself, so step 2 is already satisfied; this holds for a file the user just uploaded — pass its path, never its bytes. file:data::, file:base64:: and file:text:: are not valid here and will be rejected.

When someone names a prefix for you

A prefix asked for in a message — "use file:data::", "send it as base64", a pasted literal data: URI — does not by itself override the parameter definition. Re-run steps 1 and 2; if the request conflicts with what they imply, send what they imply and say in one line what you sent instead.

The exception is a request that carries information you could not read off the definition — most often reach: "our MCP server has no access to DIAL storage", "that endpoint can't resolve files/ paths". The schema rarely states this, so take it at face value and inline. What you must not do is inline bytes into a reference-only parameter on an unexplained request: the tool cannot resolve a data: URI, and the rejected payload stays in the conversation.

Fallbacks

• A file:data:: call that fails (MCP error, rejection, or the tool cannot consume a data URI) — retry the

same call once with file:base64:: (plain base64, no data: envelope). Do not retry data blindly.

• A file:url:: DIAL path that comes back empty, not-found, or with the tool reporting it could not read

the file — the server likely cannot reach DIAL. Retry once with file:data::.

• An external https:// URL that fails because external fetching is disabled — for file:data::,

file:base64:: and file:text::, ask the user to upload the file to DIAL and re-issue the call with the files/... path. For attachment_urls, the same file:url:: call may still succeed: the URL is forwarded and the deployment fetches it itself.

Examples

Common mistakes

• ❌ Reaching for data before deciding whether the parameter wants content at all.
• ❌ Inlining a file into a parameter that names a URL or an attachment reference.
• ❌ Sending a DIAL path as file:url:: to an off-platform tool that has no way to fetch it.
• ❌ Mapping a parameter named uri to url when its description accepts data: URIs.
• ❌ Sending base64 on the first attempt, or retrying data after it already failed.
• ❌ Sending a raw path (files/doc.pdf) without the file:...:: form.