Optimized for Obsidian Vaults with smart upsert and document tracking capabilities, enabling agents to sync and reason over evolving Obsidian knowledge bases.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-lightrag Search the knowledge graph for articles about artificial intelligence"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol (MCP) server that enables AI assistants to interact with LightRAG knowledge graphs. Query documents, manage entities, and build semantic relationships through a standardized tool interface. Optimized for Obsidian Vaults: The built-in smart upsert and document tracking capabilities make it perfect for agents that need to sync and reason over evolving Obsidian knowledge bases.
Smart Updates: Intelligent upsert logic that detects changes in documents, skipping redundant uploads and re-indexing only when necessary
Knowledge Graph Queries: Perform semantic, keyword, or hybrid searches across your indexed documents
Document Ingestion: Add text, files, or entire directories to your knowledge base
Entity Management: Create, update, merge, and delete entities in the graph
Relationship Handling: Define and modify connections between entities
Robust Connectivity: Automatic retry with exponential backoff for reliable API communication
Flexible Configuration: Set options via environment variables or command-line arguments
Related MCP server: Obsidian MCP Server
# Clone the repository
git clone https://github.com/enriquecatala/mcp-lightrag.git
cd mcp-lightrag
# Install dependencies
uv syncStart your LightRAG server (must be running before the MCP server)
Launch the MCP server:
uv run mcp-lightrag --host localhost --port 9621Connect your AI assistant via the MCP protocol (stdio transport)
Option | Environment Variable | Default | Description |
|
|
| LightRAG API host |
|
|
| LightRAG API port |
|
| (none) | Optional API key |
| — |
| Logging verbosity |
To integrate this server with an MCP client (such as Claude Desktop), add the following configuration to your mcp-server-config.json key in your settings file. This configuration uses uv to run the server from the source directory.
{
"mcpServers": {
"mcp-lightrag": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/mcp-lightrag",
"run",
"mcp-lightrag",
"--host",
"localhost",
"--port",
"9621"
],
"env": {
"LIGHTRAG_API_KEY": "optional_api_key"
}
}
}
}Note: Replace
/absolute/path/to/mcp-lightragwith the actual full path to where you cloned this repository.
This server distinguishes itself with an intelligent Upsert Mechanism ideal for keeping in sync with Obsidian Vaults or other local knowledge bases:
New File → Uploads and indexes immediately.
Unchanged File → Detects identical content and skips (saving time and resources).
Modified File → Automatically removes the old version and indexes the new one. This allows agents to efficiently "watch" a folder and keep the RAG knowledge graph up-to-date without redundant processing.
query_knowledge_graph — Execute specialized RAG queries (mix, semantic, keyword, etc.) to answer questions based on your data.
ingest_text — Index raw text content directly into the graph.
ingest_file — Index a specific local file (absolute path required).
upload_and_index — Upload a file to the server for indexing (handles transfer).
ingest_batch — Recursively scan and index directories with pattern filtering.
upsert_document — Smart document upload: creates new, skips identical, or updates modified documents.
find_document — Search for a document by filename to check status and details.
get_latest_documents — Retrieve a paginated list of recently updated documents.
list_all_docs — List all documents in the system (warning: can be slow for large datasets).
check_indexing_status — Check if the background indexing pipeline is idle or busy.
create_entities — Manually insert new entities.
modify_entities — Update attributes of existing entities.
remove_entities — Delete specific entities.
unify_entities — Merge multiple entities into a single canonical entity.
connect_entities — Create or update relationships between entities.
purge_by_document — Delete a document and remove all its associated data from the graph.
get_graph_metadata — Explore the graph schema (available node labels and relationship types).
verify_server_health — Check if the LightRAG API is reachable and healthy.
# Install dev dependencies
uv sync --all-extras
# Run tests
uv run python -m pytest
# Lint code
uv run ruff check src/To publish a new version to PyPI:
Update the version in pyproject.toml.
Build the package:
uv run python -m buildUpload to PyPI (requires PyPI API token):
uv run twine upload dist/*If the LightRAG API evolves, you can regenerate the client using openapi-python-client. Ensure your LightRAG server is running (e.g., at http://localhost:9621), then run:
uv tool run openapi-python-client generate \
--url http://localhost:9621/openapi.json \
--output-path src/mcp_lightrag/client/light_rag_server_api_client \
--meta none \
--overwriteThis will update the client code in src/mcp_lightrag/client/light_rag_server_api_client based on the latest OpenAPI specification.
MIT
Check the current status of the document processing pipeline (idle or busy).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses return values (idle/busy), which is adequate for a simple read-only check. No annotations were provided, so description carries the burden and does so reasonably.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with front-loaded purpose. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and no output schema, the description is fairly complete. It would benefit from specifying the output format explicitly, but it is sufficient for understanding the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so baseline 4 applies. The description provides no additional parameter info, but none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool checks status of the document processing pipeline and lists the possible return values (idle or busy). It uses specific verb and resource, and there are no ambiguous siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. Given the simple nature, usage is implied, but explicit context iformation is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Define or update relationships between entities, including edge weights and descriptions.
| Name | Required | Description | Default |
|---|---|---|---|
| relations | Yes | List of relationship definitions. Required: 'source', 'target'. Optional: 'description', 'keywords', 'weight', 'type', 'edit_mode' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully convey behavioral traits. It only states the action (define/update) without disclosing mutability, idempotency, side effects, or required permissions. The lack of behavioral context is a significant gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no redundant words. It is front-loaded and efficient, achieving clarity without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the parameter (array of objects with multiple fields) and no output schema, the description is too minimal. It does not explain return values, error conditions, or constraints like entity existence. The tool's context within a knowledge graph is not leveraged for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so the schema already documents the 'relations' parameter well. The description adds 'including edge weights and descriptions,' which echoes optional fields but adds minimal new meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool defines or updates relationships between entities, explicitly distinguishing it from sibling tools focused on entities themselves (e.g., create_entities, modify_entities). The verb 'define or update' and resource 'relationships' are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like create_entities (for entities) or query_knowledge_graph (for querying). There is no mention of prerequisites, such as entities needing to exist before connecting them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manually insert specific entities into the knowledge graph.
| Name | Required | Description | Default |
|---|---|---|---|
| entities | Yes | List of entity dictionaries. Each must contain: 'name', 'type', 'description', 'source_id' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only states 'manually insert' but omits details like idempotency, duplicate handling, permissions, or return values.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words, front-loading the core purpose effectively.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's role in knowledge graph modification, the description lacks context on return values, error conditions, and behavior for duplicates or missing fields, making it insufficient for an agent to fully understand usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already describes the entities parameter. The description adds no additional meaning beyond the schema, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('manually insert') and resource ('specific entities into the knowledge graph'), distinguishing it from siblings like modify_entities and remove_entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as ingest_batch or upsert_document, leaving the agent without context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check if a document exists by its filename or path. Returns a dictionary with detailed status: 'id', 'status' (processed/failed/pending), 'created_at', 'updated_at', 'content_length', 'chunks_count', and 'error_msg' if any.
| Name | Required | Description | Default |
|---|---|---|---|
| filename | Yes | The name or path of the document file to find (e.g., 'report.pdf') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description partially covers behavioral traits by listing the return dictionary fields and status values. However, it does not explicitly state that the operation is read-only or idempotent, nor does it mention potential side effects or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences. The first sentence states the tool's purpose, and the second lists the return fields. No redundant information, and it is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description adequately covers the return structure. However, it lacks clarity on behavior when the document is not found (e.g., returns null or empty dictionary), which is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear parameter description. The description adds minimal extra meaning beyond the schema, only echoing 'filename or path'. Baseline of 3 is appropriate as the parameter is well-documented in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Check if exists' and the resource 'document by filename or path'. It distinguishes itself from sibling tools like 'list_all_docs' or 'purge_by_document' by focusing on existence check and returning detailed status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide guidance on when to use this tool versus alternatives. It lacks context such as prerequisites or when not to use it, like before ingestion to avoid duplicates.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve schema information about the knowledge graph, including available node labels and relationship types.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It accurately describes a read-only retrieval operation with no side effects, and specifies the returned information (node labels, relationship types). Absence of details on authentication or rate limits is acceptable for a simple read tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that immediately states the main action and output. It is efficient and contains no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, no output schema), the description is complete. It accurately captures the tool's purpose and output. No additional information is needed for an agent to select and invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the input schema is empty. The description adds value by defining the tool's output (schema information), which is not covered by the schema. This fully compensates for the lack of parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves schema information about the knowledge graph, specifically node labels and relationship types. It uses a specific verb ('Retrieve') and resource ('schema information'), and is distinct from sibling tools that handle entities, documents, or queries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for getting structural metadata but does not provide explicit guidance on when to use this tool versus alternatives, nor does it mention exclusions or prerequisites. With many sibling tools, a brief note on context would be beneficial.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a paginated list of the most recently updated documents. Useful for monitoring ingestion progress.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of documents to retrieve (10-100) | |
| status | No | Optional filter by status (e.g. 'processed', 'failed', 'pending') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions 'paginated list' and 'recently updated' implying an ordering by update time, but fails to specify the sorting direction (descending?), pagination mechanism (e.g., cursor or offset), or whether it is a read-only operation. For a tool with zero annotation coverage, these behavioral gaps are significant.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two short sentences. The first delivers the primary purpose immediately, and the second adds a usage hint. There is no redundant information or unnecessary detail. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 optional params, no output schema, no nested objects), the description covers the basic purpose and a typical use case. However, it omits essential details for a paginated tool: how to navigate pages (only a limit parameter, no page/offset/cursor), and what constitutes 'recently updated' (time window? last 24h?). This incomplete guidance hinders an agent's ability to use the tool effectively for pagination.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds some context by framing the parameters within 'most recently updated documents' but does not provide additional meaning beyond what the schema already states for 'limit' and 'status.' No extra enrichment is offered.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets 'a paginated list of the most recently updated documents,' specifying verb (Get), resource (list of documents), and a distinct qualifier (most recently updated). This distinguishes it from siblings like list_all_docs (which likely lists all without recency filter) and find_document (which is search-based).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly notes the tool is 'useful for monitoring ingestion progress,' providing a clear context of use. However, it does not mention when not to use it or any specific alternatives, which would strengthen the guidance. Still, the context is helpful and non-misleading.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recursively index all files in a directory that match specific patterns.
| Name | Required | Description | Default |
|---|---|---|---|
| directory_path | Yes | Absolute path to the directory to scan | |
| recursive | No | If True, scans subdirectories recursively | |
| max_depth | No | Maximum depth for recursive scanning | |
| include_patterns | No | List of glob patterns for files to include (e.g. ['*.txt', '*.md']) | |
| ignore_patterns | No | List of glob patterns for files to exclude |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. It lacks disclosure on side effects (e.g., overwriting, idempotency, indexing process, error behavior, or auth requirements).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with core action, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Five parameters, no output schema or annotations, yet description omits return value, failure modes, and behavioral nuance for a batch operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all parameters with 100% description coverage; the minimal description adds no extra semantic value beyond summarizing the tool's purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool recursively indexes files matching patterns in a directory, which distinguishes it from single-file siblings like ingest_file and ingest_text.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied usage for batch directory indexing but no explicit guidance on when to use this tool over alternatives or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Index a specific local file from the file system. The file must be accessible by the running server.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Absolute path to the local file to be indexed |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It lacks details on side effects, error behavior (e.g., if file is inaccessible), authentication needs, rate limits, or format support. The term 'index' is vague without explaining what processing occurs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences are highly concise and front-loaded with the core action. No superfluous words or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema and annotations, the description should explain typical outcomes (e.g., success return, errors). It omits info on file size limits, supported formats, and whether indexing is synchronous or asynchronous.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description for file_path. The tool description reinforces the local and accessible nature but adds minimal new information beyond the schema's parameter description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Index' and the resource 'a specific local file from the file system'. It distinguishes from siblings like ingest_batch (batched), ingest_text (text content), and upload_and_index (uploaded file) by specifying 'local file'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for local files accessible by the server but does not explicitly state when to use this tool over alternatives like upload_and_index or ingest_text. No exclusions or cross-references are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Index raw text content directly into the knowledge graph. Useful for small snippets or dynamic data.
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | The text content (string or list of strings) to be indexed |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It fails to mention whether the operation is synchronous, if it returns a result, or if it modifies state destructively. The description only states indexing without clarifying permissions, limits, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The first sentence states the primary purpose, and the second provides usage guidance. Information is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema), the description covers purpose, usage guidance, and parameter meaning. However, the lack of behavioral transparency (e.g., whether indexing is synchronous or destructive) is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the parameter description in the schema fully explains the content field. The tool description adds no additional meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('Index raw text content') and the target resource ('knowledge graph'), using specific verbs and nouns. It distinguishes from siblings like ingest_file and ingest_batch by emphasizing 'raw text' and 'directly'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use ('small snippets or dynamic data'), implying when not to use (large files or batch operations). This guidance contrasts with sibling tools like ingest_file and ingest_batch.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List ALL documents currently in the system. WARNING: Can be slow if there are many documents. Use get_latest_documents for better performance.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It warns about slowness, which is helpful, but does not disclose other behavioral traits such as permissions required, read-only nature, or return format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no wasted words. The warning is front-loaded, making the key trade-off clear immediately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (no params, no output schema) and lack of annotations, the description adequately covers purpose and usage but could improve by specifying what the returned list contains (e.g., document IDs or names).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so schema coverage is 100%. The baseline according to the rule for 0 parameters is 4. The description adds no further parameter info, but none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' with resource 'ALL documents', clearly defining the scope. It distinguishes from sibling tool get_latest_documents via a performance warning.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises when not to use this tool ('if there are many documents') and provides an alternative: 'Use get_latest_documents for better performance.' This is clear guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update the properties (type, description, source_id) of existing entities.
| Name | Required | Description | Default |
|---|---|---|---|
| entities | Yes | List of dictionaries with updated entity fields. Must include 'name'. Optional: 'type', 'description', 'source_id' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states that properties are updated but does not disclose whether the operation is idempotent, what happens if the entity does not exist, or what the return value is. No mention of permissions or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no redundancy or fluff. Every word contributes to the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is insufficient. It does not explain that entities must already exist, does not specify the response format, and provides no behavior details. The tool is simple, but more context is needed for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already documents the 'entities' parameter well (must include 'name', optional fields). The tool description adds minimal value by repeating the property list, but does not introduce new semantic information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Update' and the resource 'existing entities', and lists the specific properties (type, description, source_id) that can be modified. This distinguishes it from sibling tools like create_entities and remove_entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, such as unify_entities or connect_entities. There is no mention of prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove all entities and relationships associated with specific document IDs from the graph.
| Name | Required | Description | Default |
|---|---|---|---|
| doc_ids | Yes | List of document IDs (e.g., from find_document) to prune from the graph |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the full burden. It only states 'Remove all entities and relationships' but does not disclose whether the operation is reversible, whether documents are also deleted, or whether cascading effects occur. This lacks sufficient transparency for a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no superfluous words. However, it could benefit from additional structure, such as listing effects or usage notes. Still, it is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one parameter and no output schema. The description covers the core action but lacks crucial context (e.g., irreversibility, scope of removal) that would be expected given its destructive nature. It is minimally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with the parameter description already explaining its purpose. The tool's description repeats 'specific document IDs' without adding new meaning, so it meets the baseline but adds no extra value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Remove', the resource 'entities and relationships', and specifies 'associated with specific document IDs'. This distinguishes it from sibling tools like 'remove_entities' (which removes specific entities) and 'upsert_document' (document update).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as 'remove_entities' or 'modify_entities'. There is no mention of prerequisites, when-not-to-use, or recommended use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the knowledge graph for information using various strategies. Ideal for answering questions based on indexed data.
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | The question or search query to execute against the knowledge base | |
| search_mode | No | Search strategy to use: 'mix' (recommended for comprehensive results), 'semantic' (vector search), 'keyword' (exact match), 'global' (broad context), 'hybrid' (semantic + keyword), 'local' (specific context), 'naive' (simple) | mix |
| limit | No | Maximum number of result items/paragraphs to retrieve | |
| context_only | No | If True, returns only the raw context data without LLM generation | |
| prompt_only | No | If True, returns only the constructed LLM prompt without executing it to the LLM |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose all behaviors. It fails to state whether the tool is read-only, has side effects, requires authentication, or any rate limits. The description is vague about the output.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences. It front-loads the main purpose and adds a usage hint. No unnecessary words, though it could be slightly more structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 5 parameters, no output schema, and many sibling tools, the description is too minimal. It lacks information about output format, data scope, and expected behavior. The agent may not fully understand what the tool returns or how to interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents parameters. The description's mention of 'various strategies' adds no new meaning beyond the schema's detailed explanation of search_mode. It does not improve or worsen parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: searching the knowledge graph for information using various strategies. It is distinct from sibling tools like 'find_document', but does not explicitly differentiate itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says it's 'Ideal for answering questions based on indexed data,' providing a usage context. However, it gives no when-not-to-use instructions or comparisons with alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete one or more specific entities from the knowledge graph by name.
| Name | Required | Description | Default |
|---|---|---|---|
| names | Yes | List of entity names to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It states the action but does not explain side effects like cascading deletion of related edges, atomicity, reversibility, or error handling. This leaves significant ambiguity for the agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no waste, but it is too brief given the importance of deletion behavior. Conciseness is positive, but the lack of structure (e.g., no separation of purpose from behavior) reduces clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having only one parameter and no output schema, the description omits crucial context about deletion effects (e.g., impact on related entities, reversibility, error handling). It is not complete enough for an agent to confidently select and invoke this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameter is already well-documented. The description adds 'one or more specific' to imply multiplicity, but adds little beyond what the schema provides. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Delete', the resource 'entities from the knowledge graph', and the specific method 'by name'. It effectively distinguishes this tool from sibling tools like 'modify_entities' or 'unify_entities' by focusing on deletion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidelines are provided about when to use this tool versus alternatives. It does not mention prerequisites (e.g., entity must exist), exclusions (e.g., cannot delete entities with relationships), or context in which other tools might be preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Merge multiple source entities into a single target entity to resolve duplicates or synonyms.
| Name | Required | Description | Default |
|---|---|---|---|
| sources | Yes | List of entity names to be merged (will be removed) | |
| target | Yes | Name of the resolving entity (will function as the canonical entity) | |
| strategies | No | Strategy per field (e.g. {'description': 'concatenate'}). Options: keep_first, keep_last, concatenate |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided. The description mentions merging and the schema indicates sources will be removed, disclosing a key behavioral trait. However, it does not discuss irreversibility, relationship updates, or permissions, which would be valuable for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It is concise but could benefit from a bit more context without losing efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 3 parameters (including a nested object) and no output schema. The description does not cover return values, side effects (e.g., updates to relationships), or other behavioral context beyond the merge action, leaving gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already explains the parameters. The description adds no additional meaning beyond what the schema provides, resulting in a baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'merge', the resource 'entities', and the purpose 'resolve duplicates or synonyms'. It differentiates from sibling tools like 'connect_entities' or 'remove_entities'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for deduplication but does not provide explicit guidance on when to use this tool versus alternatives, nor does it list any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload a file to the LightRAG server's input directory and trigger indexing. Handles file transfer if the server is remote.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Local path to the file to upload and index |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description mentions file transfer handling for remote servers and indexing trigger, but lacks details on side effects (e.g., overwrite behavior), failure modes, or async nature. With no annotations, the description carries full burden and is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first defines core action, second adds conditional behavior. Every word provides value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Missing important context such as supported file types, size limits, indexing behavior synchronous/asynchronous, and error handling. Given the tool's involvement in uploading and indexing, more detail is needed for safe agentic use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter description 'Local path to the file to upload and index'. Tool description adds no additional detail beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool uploads a file to the server's input directory and triggers indexing, with handling for remote servers. This distinguishes it from siblings like ingest_file which likely assume file is already on server.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like ingest_file or upsert_document. The description implies it's for local files needing upload and indexing, but does not state conditions or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Intelligently upload a document: if it doesn't exist, creates it; if it exists and is identical (same content length), skips upload; if it exists but was modified, deletes the old version and re-uploads.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Local path to the document file to upsert |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses three behavioral cases (create, skip, delete-and-reupload) but lacks details on return format, error handling, authentication needs, or side effects like breaking references.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that front-loads the core action and explains logic. Could be slightly more structured with bullet points, but no waste. Efficient for length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, yet description explains no return values. Missing error conditions, prerequisites (e.g., file existence, server state), and handling of edge cases like concurrent modifications.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds context about the upsert logic but does not add new semantic meaning to 'file_path' beyond its schema description. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: intelligently upload a document with create, skip, or delete-and-reupload logic. It distinguishes itself from siblings like 'upload_and_index' and 'ingest_file' by specifying the upsert behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for updating documents with change detection but does not explicitly state when to use or when not to use this tool compared to alternatives. No direct guidance on exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check if the LightRAG server is reachable and healthy.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It fails to specify what constitutes 'healthy', the return format, or any side effects. A health check typically involves a network call, but this is not stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence of 8 words. It is maximally concise and front-loaded with the core purpose. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple health check with no parameters or output schema, the description is minimally adequate. However, it does not specify the return type or what 'healthy' means, which could be important for an agent to interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the input schema coverage is trivially 100%. According to the rubric, 0 parameters yields a baseline of 4. The description adds no parameter information, which is acceptable given the absence of parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'check' and the resource 'LightRAG server health'. It effectively distinguishes this tool from siblings like 'check_indexing_status', which checks indexing status rather than server health.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor does it specify any prerequisites or conditions for use. It simply states the action without contextual usage hints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Most tools have clearly distinct purposes, especially across document ingestion and entity management. However, some overlapping file-related tools (e.g., ingest_file vs upload_and_index) could cause slight confusion, and multiple document retrieval tools (find_document, get_latest_documents, list_all_docs) have overlapping but distinct use cases.
All tool names follow a consistent verb_noun pattern with underscore separators. The verbs are varied but appropriate for each action, and no mixed styles (e.g., camelCase) are present.
18 tools is a well-scoped number for a knowledge graph server. Each tool serves a specific function in document ingestion, entity management, querying, or monitoring, without unnecessary bloat.
The server covers document CRUD and entity management reasonably well, but lacks direct entity retrieval (only via query) and an explicit tool to delete a document record itself (only purge associated entities). These are notable gaps that may hinder agents in certain workflows.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Search and reason over your Obsidian-style Markdown vault, right from ChatGPT.
Connect AI assistants to your GitHub-hosted Obsidian vault to seamlessly access, search, and analy…
Personal wiki and memory layer for AI assistants. Persistent, structured memory across sessions.
Persistent memory and knowledge graph for AI assistants — keyword + vector + graph search.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/enriquecatala/mcp-lightrag'
If you have feedback or need assistance with the MCP directory API, please join our Discord server