document-reading-resolution-workflows

name	Document Reading & Resolution Workflows
description	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:

1. Explicit path given: read_document("/absolute/path/to/file.docx")
   → Skip resolve_document, go straight to the target tool

2. 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:

1. Extract friendly name and optional location hint
2. Call resolve_document(name, location)
3. Handle three possible outcomes:
   • status: "found" → Use resolved_path with target tool
   • status: "ambiguous" → Present candidates to user, ask which one
   • status: "not_found" → Explain search locations, suggest alternatives

Example dialogue:

User: "Read the budget document on my desktop"
Agent step 1: resolve_document(name="budget", location="desktop")
Agent step 2: Returns { status: "found", resolved_path: "/Users/me/Desktop/budget.docx", ... }
Agent step 3: read_document(path="/Users/me/Desktop/budget.docx")
Agent step 4: Presents content to user

Pattern 2: Location Hints Mapping

Parse user language for location keywords:

User Language	Location Param
"on my desktop"	"desktop"
"in my downloads" / "I just downloaded"	"downloads"
"in my documents" / "in my docs"	"documents"
"in current directory" / "in this folder" / "here"	"current"
"in /path/to/folder"	absolute/relative path as-is
No location mentioned	omit location param (tool searches all common locations)

Pattern 3: Intent-to-Tool Mapping

Once document is resolved, route to the right tool based on user intent:

User Intent	Tool Sequence	Agent Responsibility
"Read/open/show me X"	resolve → read_document	Present full text
"Summarize X"	resolve → read_document	Summarize content (LLM capability)
"Find/search for Y in X"	resolve → search_document	Show search results with context
"What's in X" / "Describe X"	resolve → read_document	High-level description (LLM capability)
"How large is X" / "When was X modified"	resolve → get_document_metadata	Extract and present metadata
"What docs are on my desktop"	list_documents	No resolution needed; direct listing
"Create a diagram from X"	resolve → read_document	Parse content, generate diagram (LLM capability)
"Extract X from Y" (e.g., table data)	resolve → read_document	Parse and reformat (LLM capability)

Pattern 4: Ambiguous Match Handling

If resolve_document returns status: "ambiguous":

{
  status: "ambiguous",
  candidates: ["/path/to/report.docx", "/path/to/report_v2.docx"],
  message: "Multiple matches found..."
}

Agent action:

• Present candidates to user in readable format
• 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"

Example 5: Absolute Path (Skip Resolution)

User: "Read /etc/docs/my_file.docx"

Agent workflow:
1. Recognize: user provided absolute path
2. Skip resolve_document
3. read_document(path="/etc/docs/my_file.docx") directly

---

Anti-Patterns

❌ Calling read_document with a friendly name

// 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