epam/tool-call-file-parameter-formatting

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," "read file," or the file type is code/markdown/logs.
  • 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).