| name | script-lookup |
| description | Locate a specific FileMaker script in the `agent/xml_parsed/` folder, resolving to the matching pair of scripts from `scripts_sanitized` - human-readable version - and the Save a Copy as XML (SaXML) version. Use when the user says "review/refactor/optimize/open/show" a script, mentions "script ID", or asks about a specific script by name. |
Script Lookup
Locate a FileMaker script by ID or name, resolving to the paired human-readable and Save-As-XML files. Optimized for minimum tool calls.
Performance target: 4 tool calls for ID-based lookups, 5 for name-based.
Interpreting the user's request
Script ID extraction
Treat these as script IDs:
- "ID 123", "script 123", "script id: 123", "#123"
Script name extraction
If no ID is present, treat the remainder as a script name hint, e.g.:
- "review the new invoice for client script" → name hint: "new invoice for client"
Normalize name hints:
- Case-insensitive
- Remove the trailing word "script"
- Collapse repeated whitespace/punctuation
Lookup workflow
Step 1 — Index lookup (PARALLEL)
This is the critical optimization. agent/context/{solution}/scripts.index is a pipe-delimited file (ScriptName|ScriptID|FolderPath) covering every script in the solution. Use it as the primary lookup source — never start with filesystem traversal.
Run these in parallel (single message, multiple tool calls):
Tool call A — Grep the index:
- ID-based:
grep "|{id}|" agent/context/*/scripts.index — returns the exact match plus the solution name from the file path.
- Name-based:
grep -i "{name_hint}" agent/context/*/scripts.index — returns matching rows. If the user also mentions a solution name, include it in the grep path: agent/context/{solution_hint}*/scripts.index.
Tool call B — List sandbox:
ls agent/sandbox/ — check for any existing fmxmlsnippet files (in-progress work).
Step 2 — Resolve paths and read excerpt
From the index result, extract:
- Script name (column 1)
- Script ID (column 2)
- Folder path (column 3)
- Solution name (from the index file path:
agent/context/{solution}/scripts.index)
Multi-solution handling: If index results come from multiple solution paths, or the user mentions a specific solution, resolve to one. If ambiguous, use AskUserQuestion to ask which solution.
Derive file paths — the sanitized filename follows the pattern {ScriptName} - ID {ScriptID}.txt, nested inside a folder whose name starts with the folder path value from the index. Since the folder's own ID suffix isn't in the index, use a glob:
- Sanitized:
agent/xml_parsed/scripts_sanitized/{solution}/{FolderPath}*/{ScriptName} - ID {ScriptID}.txt
- Save-As-XML:
agent/xml_parsed/scripts/{solution}/{FolderPath}*/{ScriptName} - ID {ScriptID}.xml
For top-level scripts (empty folder path in index): files are directly in agent/xml_parsed/scripts_sanitized/{solution}/.
Sandbox match: From the sandbox listing (Step 1B), check if any file matches the script name (sandbox files don't include IDs — match by name).
Run in parallel:
Tool call A — Glob for sanitized file:
Use Bash: ls agent/xml_parsed/scripts_sanitized/"{solution}"/"{FolderPath}"*/*"ID {ScriptID}"* 2>/dev/null || ls agent/xml_parsed/scripts_sanitized/"{solution}"/*"ID {ScriptID}"* 2>/dev/null
Tool call B — Read first 20 lines of the sanitized script (for the excerpt). If you already know the exact path from the glob, read it directly. Otherwise, combine with tool call A by using a single Bash command that finds and reads:
file=$(find "agent/xml_parsed/scripts_sanitized/{solution}" -name "*ID {ScriptID}*" -type f | head -1) && head -20 "$file"
For name-based lookups where multiple index rows matched: pick the best candidate using the matching rules below, then resolve paths for that candidate.
Step 3 — Script match report + confirmation
Present the report and confirm in one response:
Selected script
- Name:
{script name}
- ID:
{id}
- Confidence: High/Medium/Low (why)
Paths found
- Sanitized (readable):
{path or "not found"}
- Save-As-XML (reference):
{path or "not found"}
- fmxmlsnippet (editable base):
{path in agent/sandbox, or "not found"}
Alternates (if any)
- Up to 3–5 other candidate scripts from the index results (name + ID)
Quick excerpt
- First few lines from
scripts_sanitized to confirm identity
Then use AskUserQuestion: "Is this the correct script? — {Script Name} (ID: {id}) in {solution}"
- Options:
yes — "Yes, proceed" / no — "No, that's not it — let me clarify"
Step 4 — Post-confirmation
If confirmed:
If declined:
- Ask for a corrected script name or ID.
- Re-run from Step 1.
Name-based matching rules
When the index grep returns multiple rows, rank candidates:
- Exact name match (case-insensitive) — highest confidence
- Contains match (all tokens from the hint present in the candidate name)
- Fuzzy match (most tokens match) — pick the best, include alternates in report
Pick the best candidate and continue. The confirmation step is the redirect gate — don't block on a separate disambiguation question unless confidence is truly Low across all candidates.
Fallback: no index available
If agent/context/ has no scripts.index files, fall back to filesystem search:
ls agent/xml_parsed/scripts_sanitized/ — determine solution subfolders.
- One subfolder → use automatically.
- Multiple →
AskUserQuestion to disambiguate.
- Search within the solution subfolder:
- ID:
find "agent/xml_parsed/scripts_sanitized/{solution}" -name "*ID {id}*" -type f
- Name:
find "agent/xml_parsed/scripts_sanitized/{solution}" -iname "*{hint}*" -type f
- Continue from Step 2 (resolve paths and read excerpt).
If agent/xml_parsed/ does not exist or is empty, report that explicitly and stop.
Mapping between sanitized and Save-As-XML variants
The sanitized and XML variants are a pair sharing the same name pattern: {ScriptName} - ID {ScriptID} with .txt vs .xml extension, in mirrored folder structures under scripts_sanitized/ vs scripts/.
When ID and name conflict, trust ID.
Handoff: when the user asked to "review" or "refactor"
If the user request is a review/refactor/optimization:
- Use this lookup to identify the correct script and its artifacts.
- Then follow the existing
script-review or script-refactor workflow:
- Prefer an existing fmxmlsnippet version in
agent/sandbox/ as the base.
- If none exists, translate from Save-As-XML using
agent/scripts/fm_xml_to_snippet.py.
Examples
Example 1 — ID-based lookup (fast path)
User: "Lets work on script 104"
Step 1 (parallel):
- Grep:
grep "|104|" agent/context/*/scripts.index → Quick Find Clients|104|Quick Find in Invoice Solution
- List:
ls agent/sandbox/ → check for existing "Quick Find Clients" file
Step 2 (parallel):
- Glob:
ls agent/xml_parsed/scripts_sanitized/"Invoice Solution"/"Quick Find"*/*"ID 104"*
- Read: first 20 lines of the matched sanitized file
Step 3: Report + confirm → "Is this the correct script? — Quick Find Clients (ID: 104) in Invoice Solution"
Step 4: On confirmation → convert to sandbox if no fmxmlsnippet exists.
Tool calls: 4 (2 parallel + 1 read/glob + 1 confirm) + 1 convert if needed.
Example 2 — Name-based lookup (fuzzy)
User: "Let's work on the invoices quick find for the invoice solution"
Step 1 (parallel):
- Grep:
grep -i "quick find" agent/context/"Invoice Solution"/scripts.index → multiple matches:
Quick Find Clients|104|Quick FindQuick Find Invoices|106|Quick FindQuick Find Products|108|Quick FindQuick Find Staff|110|Quick Find
- List:
ls agent/sandbox/
Best match: "Quick Find Invoices" (contains "invoices" token from hint).
Step 2: Resolve paths for ID 106, read excerpt.
Step 3: Report with alternates (104, 108, 110) + confirm.
Step 4: Convert on confirmation.
Tool calls: 5 (2 parallel + 1 resolve + 1 confirm + 1 convert).
Example 3 — Multiple solutions
User: "Review the New Invoice script"
Step 1:
- Grep:
grep -i "new invoice" agent/context/*/scripts.index → results from two solutions
Step 1.5: AskUserQuestion to disambiguate solution, then continue from Step 2.
Example 4 — Ambiguous name
User: "Show me the invoice script"
Step 1 (parallel):
- Grep:
grep -i "invoice" agent/context/*/scripts.index → many matches
- List:
ls agent/sandbox/
Pick best candidate, include alternates prominently. Confirmation step acts as redirect gate.
