How to handle natural language document requests—resolve friendly names to paths, then use appropriate tools for reading, searching, summarizing, or analyzing Word documents
How to handle natural language document requests—resolve friendly names to paths, then use appropriate tools for reading, searching, summarizing, or analyzing Word documents
domain
document-operations, natural-language-interfaces
confidence
low
source
manual
tools
[{"name":"resolve_document","description":"Resolves a friendly document name (e.g., 'foo') + optional location hint to an absolute path","when":"User mentions a document by friendly name (not absolute path). Call this FIRST before other document tools"},{"name":"read_document","description":"Reads full text content from a .docx file at a resolved path","when":"User asks to read, show, open, or view a document. Use after resolve_document"},{"name":"search_document","description":"Searches for text within a .docx file and returns matching lines with line numbers","when":"User asks to search/find/look for specific text within a document. Use after resolve_document"},{"name":"get_document_metadata","description":"Returns file metadata (size, creation date, modification date) for a .docx file","when":"User asks about document properties (size, when modified, when created). Use after resolve_document"},{"name":"list_documents","description":"Lists all .docx files in a directory","when":"User asks what documents are in a location (desktop, downloads, etc.)"}]
Context
During a session, users frequently ask about Word documents using natural language: "Read the architecture doc on my desktop", "Summarize the status report I just downloaded", "Search for 'Q1 results' in the financial spreadsheet."
These requests fall into two categories:
Explicit path given:read_document("/absolute/path/to/file.docx")
→ Skip resolve_document, go straight to the target tool
Friendly name + optional location:"read foo from my desktop"
→ Requires resolution first (via resolve_document), then composition with a target tool
This skill teaches agents how to recognize friendly-name requests, resolve them correctly, and compose the right tool sequence for each intent.
Patterns
Pattern 1: Resolve Then Act
Applies when: User mentions a document by friendly name (not absolute path)
Sequence:
Extract friendly name and optional location hint
Call resolve_document(name, location)
Handle three possible outcomes:
status: "found" → Use resolved_path with target tool
status: "ambiguous" → Present candidates to user, ask which one
Ask user to clarify which one (e.g., by filename, date, or location)
Optionally, call resolve_document again with more specific location or name hint
After user picks, proceed with target tool
Example:
Found 2 documents matching "report":
1. /Users/me/Desktop/report.docx (modified 2 days ago)
2. /Users/me/Downloads/report_final.docx (modified 1 hour ago)
Which one would you like me to read?
Pattern 5: Permission & Not-Found Errors
If resolve_document returns status: "not_found":
Agent action:
Explain what locations were searched
Suggest alternatives:
Offer to list documents in a specific location
Ask for absolute path
Ask user to check if file exists
Example: "I couldn't find 'budget.docx' in Desktop, Downloads, or Documents. Would you like me to list files in Downloads, or can you provide the full path?"
Examples
Example 1: Simple Read (No Ambiguity)
User: "Read the meeting notes on my desktop"
Agent workflow:
1. resolve_document(name="meeting notes", location="desktop")
→ { status: "found", resolved_path: "/Users/me/Desktop/meeting notes.docx" }
2. read_document(path="/Users/me/Desktop/meeting notes.docx")
→ Returns full text
3. Present text to user with formatting
Example 2: Search Request
User: "Search for 'Q1 budget' in the finance report I downloaded"
Agent workflow:
1. Recognize intent: search + location hint (downloads)
2. resolve_document(name="finance report", location="downloads")
→ { status: "found", resolved_path: "/Users/me/Downloads/finance_report.docx" }
3. search_document(path="/Users/me/Downloads/finance_report.docx", query="Q1 budget")
→ Returns matching lines with line numbers
4. Present results: "Found 3 matches..."
Example 3: Ambiguous Match Resolution
User: "Summarize the status report"
Agent workflow:
1. resolve_document(name="status report", location=undefined)
→ { status: "ambiguous", candidates: [
"/Users/me/Desktop/status_report_2024.docx",
"/Users/me/Downloads/status_report_draft.docx"
]}
2. Ask user: "I found 2 documents. Which one?"
- Option A: /Desktop/status_report_2024.docx
- Option B: /Downloads/status_report_draft.docx
3. User picks A
4. read_document(path="/Users/me/Desktop/status_report_2024.docx")
→ Returns text
5. Agent summarizes
Example 4: Metadata Query
User: "When was the architecture document last modified?"
Agent workflow:
1. resolve_document(name="architecture document", location=undefined)
→ { status: "found", resolved_path: "/Users/me/Documents/architecture.docx" }
2. get_document_metadata(path="/Users/me/Documents/architecture.docx")
→ { modifiedAt: "2026-03-10T14:22:00Z", ... }
3. Present: "Last modified on March 10, 2026 at 2:22 PM"
// DON'T DO THIS
read_document(path="foo") // Will fail — "foo" is not a valid path
// DO THIS INSTEAD
resolve_document(name="foo") → read_document(path=resolved_path)
❌ Ignoring ambiguous matches
// DON'T DO THIS — silently pick first candidate
if (ambiguous) { use candidates[0] }
// DO THIS INSTEAD
if (ambiguous) { ask user to clarify }
❌ Not extracting location hints from user language
// DON'T DO THIS
resolve_document(name="budget report") // omits location hint even though user said "on my desktop"
// DO THIS INSTEAD
resolve_document(name="budget report", location="desktop")
❌ Calling list_documents without a clear purpose
// DON'T DO THIS — user didn't ask for a listing
resolve_document(name="X") fails → list all files on system
// DO THIS INSTEAD
If user wants to see available files, call list_documents with a specific location.
If resolve fails, offer to list that location.
❌ Chaining tools without waiting for resolution
// DON'T DO THIS — spawning all tools at once
resolve_document(...)
read_document(...) // May use wrong path if resolve is still pending
search_document(...)
// DO THIS INSTEAD
Wait for resolve_document result.
Then call the appropriate tool (read OR search OR metadata).
Checklist for Agents
When handling a document request:
Identify the intent: Read? Summarize? Search? Metadata?
Extract friendly name: What is the user calling the document?
Extract location hint: Desktop? Downloads? No hint?
Choose resolution strategy:
Absolute path given? Skip resolve_document
Friendly name? Use resolve_document
Handle resolution outcome:
Found? Proceed with target tool
Ambiguous? Present candidates, ask user
Not found? Explain search locations, offer alternatives
Call appropriate tool: read / search / metadata based on intent
Present results clearly: Full text, search results, or metadata summary
