Tools are Scripts

Summary

• Purpose: Explain the tool model and how to create tools
• Audience: Developers
• Prereqs: /docs

What Are Tools?

Tools are FileMaker scripts that extend the AI assistant's capabilities. When a user asks a question that requires data retrieval, record operations, or external API calls, the AI can automatically call your configured tools to perform these actions.

The relationship: Tool Name → FileMaker Script → AI Assistant

Each tool configuration maps a tool name (used by the AI) to a FileMaker script (that performs the actual work). Tools can retrieve data, create or update records, call external APIs, and more—all triggered naturally through chat conversations.

How Tools Work

The Execution Flow

1. User Query: User asks a question like "Find all customers in California"
2. AI Decision: The AI analyzes the query and decides which tool(s) to use based on tool descriptions
3. Script Execution: ProofChat calls your FileMaker script with parameters extracted from the query
4. Result Processing: The script returns data via Exit Script
5. Display: Results are displayed either:
   • Default (Text): Results are sent to the AI, which interprets them and crafts a natural language response
   • Component: Results are rendered directly using a predefined display component (table, chart, KPI card, etc.)

Built-in vs User-Created Tools

• Built-in Tools: System tools (like get_weather, query_database) that cannot be modified, only enabled/disabled
• User-Created Tools: Custom tools you configure yourself with full control over all settings

Script Requirements

Your FileMaker scripts that act as tools should:

• ✅ Receive parameters via script parameter (JSON format)
• ✅ Return results via Exit Script (JSON format)
• ✅ Handle errors appropriately (return error information in result)
• ✅ Keep layout stable (use card windows if navigation needed, close them when done)
• ✅ Return data matching component format (if using component display)

Scripts can perform typical FileMaker actions: create/update/delete records, navigate to layouts, open card windows, process data, and call external APIs via Insert from URL, etc.

Setting Up a FileMaker Script as a Tool

Follow these steps to create a new tool:

Step 1: Create Your FileMaker Script

Create a FileMaker script that:

• Receives parameters: Accepts JSON data via script parameter
• Performs the action: Does the work (search, create, update, etc.)
• Returns results: Uses Exit Script with JSON result
• Handles errors: Returns error information in a consistent format

Example Script Structure:

// FileMaker Script: HandleCustomerSearch
// Receives JSON parameter: {"query": "John", "limit": 10}

Set Variable [$param; Value: Get(ScriptParameter)]
Set Variable [$query; Value: JSONGetElement($param; "query")]
Set Variable [$limit; Value: JSONGetElement($param; "limit")]

// Perform find
Enter Find Mode []
Set Field [Customers::Name; "*" & $query & "*"]
Set Error Capture [On]
Perform Find []

// Build result JSON
Set Variable [$result; Value: JSONSetElement("{}";
  "success"; True;
  "count"; Get(FoundCount);
  "records"; JSONFromFile("...")
)]
Exit Script [$result]

Step 2: Configure Tool in Settings

1. Navigate to Settings → Tools (see Tools Configuration)
2. Click "Add Tool"
3. Fill in Basic Info:
   • Tool Name: search_customers
   • Description: "Searches for customer records by name. Use when users ask to find customers or look up contact information."
   • Script Name: HandleCustomerSearch
   • Enabled: ✓ (checked)

Step 3: Define Parameters

In the Parameters tab:

1. Click "Add Parameter"
2. Configure:
   • Name: query
   • Type: String
   • Description: "Search term for customer name"
   • Required: ✓
3. Add another parameter:
   • Name: limit
   • Type: Number
   • Description: "Maximum number of results to return"
   • Required: ✗ (optional)

Parameter Types:

• String: Text values
• Number: Numeric values
• Boolean: True/false values
• Object: Nested objects (use dot notation for nested properties)
• Array: Lists of values

Dot Notation for Nested Objects: Use dot notation to define nested parameter structures:

• contact.first_name → Creates nested object: { contact: { first_name: "..." } }
• user.profile.email → Creates deeper nesting: { user: { profile: { email: "..." } } }

When the AI calls your tool with nested parameters, they're passed to your FileMaker script as JSON in the script parameter.

Parameter Best Practices:

1. Use descriptive names that clearly indicate purpose
2. Provide clear descriptions for each parameter
3. Use dot notation for logically grouped data
4. Mark parameters required only when essential
5. Use enums for constrained string values
6. Test your tool after configuring parameters

Step 4: Choose Output Type

In the Output tab:

• For simple data: Choose "Default (Text Response)" - AI interprets and responds
• For structured data: Choose "Component Display" and select appropriate component (e.g., data-table)

If using a component, copy the expected format and ensure your script returns data in that exact structure. See Tool Components for available components and their expected formats.

Step 5: Test Tool Execution

1. Save the tool configuration
2. Open a chat session
3. Ask a question that should trigger your tool: "Find customers named John"
4. Verify:
   • Tool is called with correct parameters
   • Script executes successfully
   • Results display correctly

Use Cases

Data Retrieval

Example: "Find all customers in California"

• Tool: search_customers_by_state
• Parameters: { "state": "California" }
• Output: Component (Data Table)
• Script: Performs find, returns records as table data

Record Operations

Example: "Create a new invoice for customer ID 123"

• Tool: create_invoice
• Parameters: { "customer_id": "123", "amount": 1500.00 }
• Output: Default (Text Response) or FileMaker Record component
• Script: Creates record, returns confirmation

Data Analysis

Example: "Show sales summary by month"

• Tool: get_sales_summary
• Parameters: { "period": "monthly", "year": 2024 }
• Output: Component (Data Visualization or KPI Display)
• Script: Aggregates data, returns formatted summary

External API Calls

Example: "Get weather for New York"

• Tool: get_weather
• Parameters: { "location": "New York" }
• Output: Component (Key-Value Display)
• Script: Calls external API via Insert from URL, returns formatted data

FileMaker Navigation

Example: "Show me the details for customer John Doe"

• Tool: get_customer_record
• Parameters: { "name": "John Doe" }
• Output: Component (FileMaker Record)
• Script: Finds record, returns record ID with navigation link

When to Use Text vs Component Output

Use Default (Text) when:

• Results need AI interpretation and explanation
• Data format doesn't match available components
• You want conversational, natural language responses
• Simple success/error messages

How it works: Tool results are sent back to the AI model, which interprets them and crafts a natural language response. Example: A search tool returns raw data, and the AI explains "I found 5 customers matching your criteria..."

Use Component Display when:

• You want structured visualizations (tables, charts)
• Data fits a predefined component format
• Users need to interact with data (sort, filter, export)
• Quick visual feedback is important

How it works: Tool results are rendered directly using a predefined display component. No AI interpretation needed—the component displays the data immediately.

Tool Configuration Details

For detailed information about configuring tools in the Settings interface, see:

• Tools Configuration - UI reference for the Settings → Tools page
• Tool Components - Available display components and their expected formats

Related

• /docs/reference/settings/tools - UI reference for configuring tools
• /docs/reference/tool-components/ - Available display components
• /docs/integration/configuration-scripts/chat-tools - Advanced: Override tools per file via script