Static source inference · medium confidence · detected: Logging
Deprecated protocol patterns detected
Summary
The server exposes 22 tools with basic JSON Schema definitions, but exhibits significant quality gaps. Most tool descriptions are extremely terse (10-30 characters), well below the production baseline of 194 chars. Parameter descriptions are minimal or absent for complex operations. Error handling is not evident in the visible tool definitions. The server lacks tool annotations (destructiveHint, readOnlyHint) despite having several destructive tools (delete_document, clear_documents, delete_entity, delete_relation). Schema completeness is uneven, some tools lack input examples or output documentation. The codebase shows evidence of incomplete development (investigation scripts in archive/, minimal_server.py with stub implementations). No security validation rules are visible in the tool definitions.
Descriptions are critically short (10-40 chars, well below 194-char baseline). E.g., 'Scan documents in LightRAG', 'Clear all documents from LightRAG', 'Get available labels in the knowledge graph'. These lack WHEN to use, prerequisites, or dependencies.
Expand ALL tool descriptions to 50 - 200 chars. Include WHAT the tool does, WHEN to use it instead of similar tools, and any prerequisites. Example: 'Delete a specific document from LightRAG by its ID. Use after get_documents() to find the document_id. This is irreversible, call with caution.'
Add tool annotations (destructiveHint, readOnlyHint, idempotentHint) for all 22 tools in the server registration code. Mark delete_*, clear_*, and update_* operations as destructiveHint: true. This allows clients to warn users before executing.
Document output schemas for all tools. For get_documents, return a schema like {type: object, properties: {documents: {type: array, items: {type: object, properties: {id: string, title: string, status: string}}}, total: integer}}. For query_text, document that it returns {type: object, properties: {results: array, query: string, mode: string}}.
Add parameter validation rules inline. For get_documents_paginated, add minimum/maximum to the schema: 'page' {minimum: 1}, 'page_size' {minimum: 1, maximum: 100}. For update_entity, describe the expected structure of 'properties': 'A JSON object with entity metadata keys (e.g., {label: string, description: string})'.
Implement recovery guidance in error responses. If update_entity(entity_id='nonexistent', properties={...}) fails, return 'Entity ID not found. Call check_entity_exists("entity_name") to verify the entity exists, or call get_knowledge_graph() to browse available entities.'
Remove or archive testing scripts in archive/ and merge only working tool definitions into a single source-of-truth server.py. Add a CHANGELOG or TODO comment documenting why upload_document, get_documents, and entity operations had test failures and how they were fixed.
Spec posture evidence
Inferred effective spec: <=2025-11-25.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
Output schemas are not documented in any tool definition. Tools like get_knowledge_graph, get_documents, query_text_stream return complex nested objects, but the response structure is never declared. LLMs cannot plan downstream tool calls without knowing output fields.
No error handling guidance visible. If upload_document fails with a file not found, or update_entity fails because entity_id does not exist, the error response likely includes raw exception traces rather than actionable recovery steps (e.g., 'Entity not found. Try check_entity_exists() first.').
Parameter descriptions are missing or minimal. update_entity accepts a 'properties' param (object) with no description of its structure. update_relation accepts 'updated_data' (object) with no schema. Agents cannot infer the correct structure.
get_documents_paginated requires 'page' (1-indexed) and 'page_size' (1-100) but the input schema has no 'minimum', 'maximum', or pattern constraints to prevent invalid values. An agent could pass page=0 or page_size=999 and fail.
Tool definitions exist in archive/ testing scripts (minimal_server.py, investigate_failing_tools.py) alongside production code in src/. Evidence of incomplete development, investigation scripts show the team found test failures (upload_document, get_documents, get_documents_paginated, entity operations) but did not document root causes or fixes in the tool definitions.
No permission checks or scope declarations visible. Destructive tools like clear_documents and delete_document lack any guard against accidental or malicious invocation. No audit trail hints or permission requirement documentation.
No rate limiting or timeout documentation. Tools that call external LightRAG services (e.g., query_text_stream) offer no guidance on timeout behavior or retry strategy if the service hangs.
Add permission/scope declarations. Declare which tools require read vs write access: insert_text, insert_texts, upload_document, update_entity, update_relation require write:lightrag. delete_*, clear_* require write:lightrag + a confirmation step.
Implement a dry-run or confirm_before_execute pattern for irreversible operations. Before clear_documents() or delete_entity(id), return a confirmation request: {input_required: 'Confirm deletion of entity "[entity_name]". Type YES to proceed.'}
Add per-tool error classification guidance. Document which errors are retryable (network timeout, rate limit) vs user-fixable (invalid entity_id) vs fatal (API key expired). Return structured error objects with error_code, message, and suggested next_step.
Consolidate duplicate/similar tool names. If query_text and query_text_stream do almost the same thing, clarify the difference in descriptions: 'Use query_text for simple JSON responses; use query_text_stream if the response is large and you need streaming results.' Consider merging with a 'stream' boolean parameter.