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?
| The tool wants |
Signals |
Prefix |
| A locator it fetches itself |
Name contains url, uri, link, path, href or attachment; description says "URL", "link" or "reference" and never offers to accept inline content |
url |
| The bytes, inline |
Description mentions "content", "base64", "encoded", "file data", RFC 2397, or a URI accepting a data: scheme |
data |
| The text itself, inline |
Description asks for "text" or "string content" and does not ask for a URI or encoded bytes |
text |
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
| Tool parameter |
Its description |
Value to send |
target_url |
"The URL to navigate to." |
file:url::https://example.com/page |
attachment_urls (array) |
"A list of full URLs for each attachment related to the tool call." |
["file:url::files/bucket/report.pdf"] |
doc_url on an MCP tool, schema has "dial_url": true |
"Path of the document to index." |
file:url::files/bucket/report.pdf |
doc_url on an MCP tool, no dial_url flag |
"Path of the document to index." |
file:data::files/bucket/report.pdf — the server cannot fetch a DIAL path |
image_data |
"The base64 encoded contents of the image file." |
file:data::files/images/chart.png |
uri |
"Convert a resource described by an http:, https:, file: or data: URI to markdown." |
file:data::files/uploads/report.docx |
documents (array) |
"List of base64-encoded file contents." |
["file:data::files/a.pdf", "file:data::files/b.pdf"] |
script_content |
"The text content of the python script." |
file:text::files/scripts/main.py |
input_file, after a failed data call |
"Pass the base64-encoded file data for processing." |
file:base64::files/uploads/document.pdf |
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.
1---2name: tool-call-file-parameter-formatting3description: Formats file and URL parameters for tool calls. You must analyze the target tool's parameter names and descriptions to choose the correct format (data URI, base64, text, or URL ref).4---56# File Parameter Formatting78Every file or URL you pass to a tool must be written as `file:{prefix}::{path_or_url}` — prefix one of9`url`, `data`, `text`, `base64`; path either a DIAL path (`files/bucket/report.pdf`) or an external URL10(`https://example.com/report.pdf`). A raw path with no `file:...::` form is not processed. The same form11is used for a single string parameter and for each element of an array parameter.1213## Step 1 — what does the parameter want?1415Read the parameter's **name and description in the tool definition** and answer: **does the tool want the16file's bytes, or a locator it resolves itself?**1718| The tool wants | Signals | Prefix |19|---|---|---|20| A locator it fetches itself | Name contains `url`, `uri`, `link`, `path`, `href` or `attachment`; description says "URL", "link" or "reference" and never offers to accept inline content | `url` |21| The bytes, inline | Description mentions "content", "base64", "encoded", "file data", RFC 2397, or a URI accepting a `data:` scheme | `data` |22| The text itself, inline | Description asks for "text" or "string content" and does **not** ask for a URI or encoded bytes | `text` |2324Hints in the tool's own name or description count too (`base64_image_processor`, "reads their text content25directly"). The description wins over the name: a parameter called `uri` whose description accepts `http:`,26`https:`, `file:` **or** `data:` URIs wants content, so use `data`.2728## Step 2 — if it wants a locator, can the receiver resolve it?2930A reference is only useful if the tool receiving it can actually fetch the file. `file:url::` is passed31through verbatim, with no credentials attached, so a **DIAL path handed to a tool that lives outside DIAL32arrives as a meaningless relative string**. Check the receiver before settling on `url`:3334- **An external `https://` URL** — anyone can fetch it. Use `url`, whatever the tool is.35- **A DIAL path to a DIAL deployment tool** (including `attachment_urls`) — the deployment is inside DIAL36 and resolves the path itself. Use `url`.37- **A DIAL path to an MCP or REST tool** — the server is off-platform. It can only resolve the path if the38 parameter is marked `"dial_url": true` in the schema (QuickApps grants that server access to the file39 first) or the description says it accepts DIAL paths. Use `url` then. **Otherwise inline the bytes with40 `data`** — a reference the server cannot fetch usually fails silently rather than returning a usable error.4142When you cannot tell, prefer `url` for an external URL and `data` for a DIAL path going off-platform.4344## `attachment_urls` is always a reference4546`attachment_urls` accepts **only** `file:url::` — a DIAL path (`file:url::files/bucket/report.pdf`) or an47external URL (`file:url::https://example.com/report.pdf`). The receiving deployment resolves it itself, so48step 2 is already satisfied; this holds for a file the user just uploaded — pass its path, never its bytes.49`file:data::`, `file:base64::` and `file:text::` are not valid here and will be rejected.5051## When someone names a prefix for you5253A prefix asked for in a message — "use `file:data::`", "send it as base64", a pasted literal `data:` URI —54does not by itself override the parameter definition. Re-run steps 1 and 2; if the request conflicts with55what they imply, send what they imply and say in one line what you sent instead.5657The exception is a request that carries **information you could not read off the definition** — most often58reach: "our MCP server has no access to DIAL storage", "that endpoint can't resolve `files/` paths". The59schema rarely states this, so take it at face value and inline. What you must not do is inline bytes into a60reference-only parameter on an unexplained request: the tool cannot resolve a `data:` URI, and the rejected61payload stays in the conversation.6263## Fallbacks6465- A `file:data::` call that fails (MCP error, rejection, or the tool cannot consume a data URI) — retry the66 same call **once** with `file:base64::` (plain base64, no `data:` envelope). Do not retry `data` blindly.67- A `file:url::` DIAL path that comes back empty, not-found, or with the tool reporting it could not read68 the file — the server likely cannot reach DIAL. Retry once with `file:data::`.69- An external `https://` URL that fails because external fetching is disabled — for `file:data::`,70 `file:base64::` and `file:text::`, ask the user to upload the file to DIAL and re-issue the call with the71 `files/...` path. For `attachment_urls`, the same `file:url::` call may still succeed: the URL is72 forwarded and the deployment fetches it itself.7374## Examples7576| Tool parameter | Its description | Value to send |77|---|---|---|78| `target_url` | "The URL to navigate to." | `file:url::https://example.com/page` |79| `attachment_urls` (array) | "A list of full URLs for each attachment related to the tool call." | `["file:url::files/bucket/report.pdf"]` |80| `doc_url` on an MCP tool, schema has `"dial_url": true` | "Path of the document to index." | `file:url::files/bucket/report.pdf` |81| `doc_url` on an MCP tool, no `dial_url` flag | "Path of the document to index." | `file:data::files/bucket/report.pdf` — the server cannot fetch a DIAL path |82| `image_data` | "The base64 encoded contents of the image file." | `file:data::files/images/chart.png` |83| `uri` | "Convert a resource described by an http:, https:, file: or data: URI to markdown." | `file:data::files/uploads/report.docx` |84| `documents` (array) | "List of base64-encoded file contents." | `["file:data::files/a.pdf", "file:data::files/b.pdf"]` |85| `script_content` | "The text content of the python script." | `file:text::files/scripts/main.py` |86| `input_file`, after a failed `data` call | "Pass the base64-encoded file data for processing." | `file:base64::files/uploads/document.pdf` |8788## Common mistakes8990- ❌ Reaching for `data` before deciding whether the parameter wants content at all.91- ❌ Inlining a file into a parameter that names a URL or an attachment reference.92- ❌ Sending a DIAL path as `file:url::` to an off-platform tool that has no way to fetch it.93- ❌ Mapping a parameter named `uri` to `url` when its description accepts `data:` URIs.94- ❌ Sending `base64` on the first attempt, or retrying `data` after it already failed.95- ❌ Sending a raw path (`files/doc.pdf`) without the `file:...::` form.
epam