tool-call-file-parameter-formatting

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 (base64, text, or URL ref).
metadata	{"version":"1.0"}

File Parameter Formatting

Purpose

Standardize file and URL inputs for tool calls using the file:{prefix}::{path_or_url} schema. You must determine the correct prefix by strictly analyzing the target tool's parameter definition.

Instructions

When a tool parameter requires a file or URL, follow this process:

1. Analyze Tool Parameter Definition

Inspect the Parameter Name and Parameter Description in the tool definition to determine the requirement:

• Requirement: Base64 Content
  • Clues: Description mentions "content," "base64," "encoded," "file data".
  • Action: Use base64 prefix.
• Requirement: Plain Text
  • Purpose: * Purpose: Use this mode to indicate the tool expects the actual text file content as the parameter. When a file is marked with the text prefix, the tool-call processor will read the file's contents and pass that text as the tool call parameter.
  • Clues: Description mentions "text", "string content".
  • Action: Use text prefix.
• Requirement: URL/Path Reference
  • Clues: Parameter name contains url, link, uri, or description says "pass the link" or "reference."
  • Action: Use url prefix.

2. Format the Value

Construct the string using the format: file:{prefix}::{path_or_url}

• Prefix: One of base64, text, or url (determined from step 1)
• Separator: Always use ::
• Path:
  • For system files: files/path/to/file.ext
  • For web resources: https://example.com/resource

Thinking Process

Before executing the tool call, perform this check:

1. Inspect Definition: "I am calling tool [tool_name]. The parameter [param_name] has the description: [description]."
2. Deduce Type: "Based on the name/description, this tool expects [raw content | text string | URL reference]."
3. Apply Format: "Therefore, I will use the [base64 | text | url] prefix."

Examples

Example 1: Visual Analysis Tool

• Tool Definition:
  • name: analyze_image
  • parameter: image_data
  • description: "The base64 encoded contents of the image file."
• Reasoning: Description explicitly asks for "encoded contents."
• Result: file:base64::files/images/chart.png

Example 2: Browser Tool

• Tool Definition:
  • name: web_browser
  • parameter: target_url
  • description: "The URL to navigate to."
• Reasoning: Parameter name is target_url and expects a navigation link.
• Result: file:url::https://google.com

Example 3: Code Reader

• Tool Definition:
  • name: read_script
  • parameter: script_content
  • description: "The text content of the python script."
• Reasoning: Description asks for "text content."
• Result: file:text::files/scripts/main.py

Example 4: Format Hint in Tool Name

• Tool Definition:
  • name: base64_image_processor
  • parameter: image_input
  • description: "Image to process."
• Reasoning: Tool name contains "base64," indicating it expects encoded content.
• Result: file:base64::files/photos/portrait.jpg

Example 5: Format Hint in Tool Description

• Tool Definition:
  • name: document_analyzer
  • description: "Analyzes documents by reading their text content directly."
  • parameter: document
  • description: "Document to analyze."
• Reasoning: Tool description mentions "reading text content directly," suggesting text mode optimization.
• Result: file:text::files/reports/annual_report.txt

Example 6: Format Hint in Argument Name

• Tool Definition:
  • name: fetch_resource
  • parameter: resource_url
  • description: "The resource to fetch."
• Reasoning: Parameter name ends with _url, indicating a URL reference is expected.
• Result: file:url::https://api.example.com/data.json

Example 7: Format Hint in Argument Description

• Tool Definition:
  • name: process_file
  • parameter: input_file
  • description: "Pass the base64-encoded file data for processing."
• Reasoning: Description explicitly states "base64-encoded file data."
• Result: file:base64::files/uploads/document.pdf

Example 8: Multi-file upload tool (array parameter, base64 content)

• Tool Definition:
  • name: batch_processor
  • parameter: documents (type: array of strings)
  • description: "List of base64-encoded file contents."
• Reasoning: Description asks for "base64-encoded file contents" for each element.
• Result: ["file:base64::files/doc1.pdf", "file:base64::files/doc2.pdf"]

Example 9: Multi-file upload tool (array parameter, URL references)

• Tool Definition:
• name: rag
  • parameter: attachment_urls (type: array of strings)
  • description: "List of URLs pointing to the files to be ingested."
• Reasoning: Name attachment_urls and description "URLs pointing to the files" indicate URL references for each element.
• Result: ["file:url::https://example.com/doc1.pdf", "file:url::https://example.com/doc2.pdf"]

Note: The file:{prefix}:: format works for both single string parameters and individual elements within array parameters.

Common Mistakes

• ❌ Ignoring the tool description and defaulting to url for local files.
• ❌ Passing file:base64::... to a tool that only asks for a URL string (parameter name url).
• ❌ Passing raw paths (files/doc.pdf) without the file:... schema.

External URL Fallback

External https:// URLs are valid file references — attachment_urls accepts them, and file:base64::https://... / file:text::https://... will inline external content. They may fail with a clear error when the operator has disabled external egress (EXTERNAL_URL_FETCH_ENABLED=false) or the per-app config has opted out (features.external_url_fetch.enabled: false). When that happens:

• For file:base64::https://... and file:text::https://..., retry by asking the user to upload the file to DIAL and re-issue the call with files/... instead.
• For deployment-tool attachment_urls, the same call may still succeed against a deployment that supports features.url_attachments (the URL is forwarded as a reference_url and the deployment fetches the bytes itself, never via QuickApps).