version: "1.0.1" name: tool-call-file-parameter-formatting description: 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). metadata: version: "1.2"

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.