Skip to main content

​
Tools Overview

Linkly AI exposes three tools to AI assistants via MCP (Model Context Protocol), forming a progressive document access workflow: 
search → outline → read

search

Search documents and find relevant results

outline

View document outlines to understand structure

read

Read document content for detailed information
These three tools work together to enable AI assistants to efficiently retrieve contextual information from your local documents. Searches indexed local documents and returns a list of the most relevant results.

​
Parameters

ParameterTypeRequiredDefaultDescription
querystringYes—Search keywords or phrase
limitnumberNo20Maximum number of results (1-50)
doc_typesstring[]NoAllFilter by document type, e.g. ["pdf", "md", "docx"]
output_formatstringNomarkdownSet to json for structured JSON output
If the vector model is still downloading, search will automatically fall back to keyword-only mode without affecting usability.

​
Response Fields

Each search result contains the following information:
FieldDescription
doc_idUnique document identifier for subsequent outline/read calls
titleDocument title
pathFile path
relevanceRelevance score (0-1)
word_countDocument word count
total_linesTotal number of lines in the document
has_outlineWhether an outline is available
modified_atLast modified time
keywordsExtracted keyword list
snippetMatching content snippet

​
Usage Examples

# CLI method
linkly search "project management best practices" --limit 10

# Filter by document type
linkly search "quarterly report" --type pdf,docx --json

​
Outline

Retrieves the structured outline and metadata of one or more documents, helping to quickly understand document structure and locate target sections.

​
Parameters

ParameterTypeRequiredDefaultDescription
doc_idsstring[]Yes—List of document IDs (from search results)
expandstring[]NoAutoNode IDs to expand (e.g. ["2", "3.1"]); omit to automatically show all levels
output_formatstringNomarkdownSet to json for structured JSON output

​
When to Use Outline

ScenarioRecommendation
Long document (> 200 lines) with outlineView outline first, then read target sections
Short document (< 100 lines)Skip outline, read full text directly
Document with has_outline: falseSkip outline, read page by page
The outline feature works best with bookmarked PDFs, Markdown, and DOCX documents. It is especially effective when reading lengthy documents and books. Outline support for plain text and unbookmarked PDFs will be added in future iterations.

​
Usage Examples

# View a single document's outline
linkly outline abc123

# View multiple documents at once
linkly outline id1 id2 id3

# JSON format output
linkly outline abc123 --json

​
Read

Reads document content with line number positioning and pagination, suitable for reading specific parts of long documents. The Read tool behaves consistently with the Claude AI SDK, ensuring optimal results across various Agentic AI models.

​
Parameters

ParameterTypeRequiredDefaultDescription
doc_idstringYes—Document ID (from search results)
offsetnumberNo1Starting line number (from 1)
limitnumberNo200Number of lines to read (max 500)
output_formatstringNomarkdownSet to json for structured JSON output

​
Content Format

The Read tool returns content with line numbers for easy reference and positioning: 
  1	# Project Requirements Document
  2
  3	## 1. Project Background
  4
  5	This project aims to build an efficient knowledge management system...
  6	Target users are enterprise R&D teams and individual knowledge workers.

​
Pagination Strategy

For long documents, it is recommended to read in chunks: 
# Page 1: Lines 1-200
linkly read <DOC_ID> --offset 1 --limit 200

# Page 2: Lines 201-400
linkly read <DOC_ID> --offset 201 --limit 200

# Page 3: Lines 401-600
linkly read <DOC_ID> --offset 401 --limit 200
Combining with outlines yields even better results — use the outline to locate the line range of the target section, then use read to precisely retrieve the content within that range.

​
Usage Examples

# Read the beginning of a document
linkly read abc123

# Read a specific range
linkly read abc123 --offset 120 --limit 80

# JSON format (suitable for programmatic processing)
linkly read abc123 --json

​
Workflow Examples

​
Complete Workflow: CLI Method

The following example demonstrates how to perform a complete document retrieval via CLI: 
# Step 1: Search for relevant documents
linkly search "microservice architecture design" --limit 5

# Step 2: View the target document's outline (assuming doc_id is abc123)
linkly outline abc123

# Step 3: Read the section of interest (assuming the target is at lines 80-150)
linkly read abc123 --offset 80 --limit 70

​
Complete Workflow: MCP Method

When AI assistants call tools via the MCP protocol, the request format is as follows: 
// Step 1: Search
{
  "method": "tools/call",
  "params": {
    "name": "search",
    "arguments": {
      "query": "microservice architecture design",
      "limit": 5
    }
  }
}

// Step 2: View outline
{
  "method": "tools/call",
  "params": {
    "name": "outline",
    "arguments": {
      "doc_ids": ["abc123"]
    }
  }
}

// Step 3: Read content
{
  "method": "tools/call",
  "params": {
    "name": "read",
    "arguments": {
      "doc_id": "abc123",
      "offset": 80,
      "limit": 70
    }
  }
}

​
FAQ

Linkly AI currently supports the following formats:
FormatExtensionsOutline Support
Markdown.md, .mdxYes
Word.docxYes
PDF.pdfPartial
Plain Text.txtNo
HTML.html, .htmPartial
If a document has no available outline (has_outline: false), you can:
  1. Use the read tool directly to browse the document content page by page
  2. Read the beginning of the document first (default 200 lines) to get a general idea, then decide whether to continue reading
Recommended workflow:
  1. First use outline to understand the document structure (if an outline is available)
  2. Based on the line ranges in the outline, use the offset and limit parameters of read to precisely read target sections
  3. Read up to 500 lines at a time, and paginate by adjusting offset
The default port is 60606. If that port is occupied, the application will automatically try other ports. You can check the actual port in use in Linkly AI Desktop’s settings.
You can try:
  • Using more precise keywords
  • Using natural language descriptions (leveraging vector semantic matching)
  • Mixing keywords and synonyms, e.g. "authentication auth login sign-in"
  • Using --type to filter specific document types and narrow the search scope