docs: simplify API endpoint descriptions

Co-authored-by: aider (openai/andrew/openrouter/deepseek/deepseek-chat-v3.1) <aider@aider.chat>

src/modes/server/api/item.rs

@@ -16,17 +16,17 @@ use crate::modes::server::common::{AppState, ApiResponse, ItemInfo, TagsQuery, L
     path = "/api/item/",
     operation_id = "list_items",
     summary = "List stored items",
-    description = "Retrieve a paginated list of stored items with their metadata and tags. Items can be filtered by tags and sorted by creation time. Each item includes comprehensive metadata extracted during storage such as file type, encoding, size, and custom tags for organization.",
+    description = "Get paginated items with metadata and tags. Filter by tags, sort by creation time.",
     responses(
-        (status = 200, description = "Successfully retrieved paginated list of items with metadata and tags", body = ItemInfoListResponse),
+        (status = 200, description = "Items retrieved", body = ItemInfoListResponse),
-        (status = 401, description = "Unauthorized - Invalid or missing authentication credentials"),
+        (status = 401, description = "Unauthorized"),
-        (status = 500, description = "Internal server error - Failed to retrieve items from database")
+        (status = 500, description = "Internal server error")
     ),
     params(
-        ("tags" = Option<String>, Query, description = "Comma-separated list of tags to filter by (e.g., 'important,work'). Only items that have ALL specified tags will be returned."),
+        ("tags" = Option<String>, Query, description = "Comma-separated tags to filter"),
-        ("order" = Option<String>, Query, description = "Sort order for results: 'newest' (default, most recent first) or 'oldest' (oldest first)"),
+        ("order" = Option<String>, Query, description = "Sort order: 'newest' or 'oldest'"),
-        ("start" = Option<u64>, Query, description = "Starting index for pagination (default: 0). Use this to skip items for pagination."),
+        ("start" = Option<u64>, Query, description = "Pagination start index"),
-        ("count" = Option<u64>, Query, description = "Maximum number of items to return in this request (default: 100, maximum: 1000)")
+        ("count" = Option<u64>, Query, description = "Number of items to return")
     ),
     security(
         ("bearerAuth" = [])
@@ -103,16 +103,16 @@ pub async fn handle_list_items(
     path = "/api/item/",
     operation_id = "post_item",
     summary = "Store new item",
-    description = "Create a new item by uploading content. The content will be automatically compressed, analyzed for metadata (file type, encoding, etc.), and stored with a unique identifier. Binary detection is performed automatically, and various metadata plugins extract information like line counts, file types, and system information.",
+    description = "Upload content to store as a new item. Content is compressed, analyzed for metadata, and stored.",
     responses(
-        (status = 201, description = "Successfully created new item with generated metadata and unique ID", body = ItemInfoResponse),
+        (status = 201, description = "Item created", body = ItemInfoResponse),
-        (status = 400, description = "Bad request - Invalid input data or malformed content"),
+        (status = 400, description = "Bad request"),
-        (status = 401, description = "Unauthorized - Invalid or missing authentication credentials"),
+        (status = 401, description = "Unauthorized"),
-        (status = 500, description = "Internal server error - Failed to create item due to storage or processing error")
+        (status = 500, description = "Internal server error")
     ),
     request_body(
         content = String,
-        description = "Raw content to store as a new item. Can be text or binary data.",
+        description = "Content to store",
         content_type = "application/octet-stream"
     ),
     security(
@@ -143,19 +143,19 @@ pub async fn handle_post_item(
     path = "/api/item/latest/content",
     operation_id = "get_item_latest_content",
     summary = "Download latest item content",
-    description = "Download the raw content of the most recently stored item. The content is automatically decompressed and returned with the appropriate MIME type header for proper browser handling. If tags are specified, returns the latest item matching ALL the given tags. If allow_binary is false and the content is detected as binary, a 400 error is returned. Supports offset and length parameters for partial content retrieval.",
+    description = "Get raw content of the most recent item. Filter by tags. Binary content can be restricted.",
     responses(
-        (status = 200, description = "Successfully retrieved latest item raw content with appropriate Content-Type header set based on detected MIME type"),
+        (status = 200, description = "Content retrieved"),
-        (status = 400, description = "Bad request - Content is binary but allow_binary is false"),
+        (status = 400, description = "Binary content not allowed"),
-        (status = 401, description = "Unauthorized - Invalid or missing authentication credentials"),
+        (status = 401, description = "Unauthorized"),
-        (status = 404, description = "Item not found - No items exist in the database or no items match the specified tag criteria"),
+        (status = 404, description = "Item not found"),
-        (status = 500, description = "Internal server error - Failed to retrieve item content due to decompression or filesystem error")
+        (status = 500, description = "Internal server error")
     ),
     params(
-        ("tags" = Option<String>, Query, description = "Comma-separated list of tags to filter by (e.g., 'important,work'). If specified, returns the latest item that has ALL the specified tags."),
+        ("tags" = Option<String>, Query, description = "Tags to filter latest item"),
-        ("allow_binary" = Option<bool>, Query, description = "Whether to allow binary content to be returned (default: true). When false, returns 400 for binary files."),
+        ("allow_binary" = Option<bool>, Query, description = "Allow binary content"),
-        ("offset" = Option<u64>, Query, description = "Byte offset from the start of the file to begin reading (default: 0)"),
+        ("offset" = Option<u64>, Query, description = "Byte offset to start reading"),
-        ("length" = Option<u64>, Query, description = "Maximum number of bytes to return, starting at offset (default: 0 for unlimited)")
+        ("length" = Option<u64>, Query, description = "Number of bytes to read")
     ),
     security(
         ("bearerAuth" = [])
@@ -205,19 +205,19 @@ pub async fn handle_get_item_latest_content(
     path = "/api/item/{item_id}/content",
     operation_id = "get_item_content",
     summary = "Download item content",
-    description = "Download the raw content of a specific item by its ID. The content is automatically decompressed and returned with the appropriate MIME type header for proper browser handling. This endpoint is ideal for downloading files or viewing content directly in the browser. If allow_binary is false and the content is detected as binary, a 400 error is returned. Supports offset and length parameters for partial content retrieval.",
+    description = "Get raw content of a specific item by ID. Binary content can be restricted.",
     responses(
-        (status = 200, description = "Successfully retrieved item raw content with appropriate Content-Type header set based on detected MIME type"),
+        (status = 200, description = "Content retrieved"),
-        (status = 400, description = "Bad request - Invalid item ID (must be a positive integer) or content is binary but allow_binary is false"),
+        (status = 400, description = "Invalid ID or binary not allowed"),
-        (status = 401, description = "Unauthorized - Invalid or missing authentication credentials"),
+        (status = 401, description = "Unauthorized"),
-        (status = 404, description = "Item not found - No item exists with the specified ID"),
+        (status = 404, description = "Item not found"),
-        (status = 500, description = "Internal server error - Failed to retrieve item content due to decompression or filesystem error")
+        (status = 500, description = "Internal server error")
     ),
     params(
-        ("item_id" = i64, Path, description = "Unique identifier of the item to retrieve content for (must be a positive integer)"),
+        ("item_id" = i64, Path, description = "Item ID"),
-        ("allow_binary" = Option<bool>, Query, description = "Whether to allow binary content to be returned (default: true). When false, returns 400 for binary files."),
+        ("allow_binary" = Option<bool>, Query, description = "Allow binary content"),
-        ("offset" = Option<u64>, Query, description = "Byte offset from the start of the file to begin reading (default: 0)"),
+        ("offset" = Option<u64>, Query, description = "Byte offset to start reading"),
-        ("length" = Option<u64>, Query, description = "Maximum number of bytes to return, starting at offset (default: 0 for unlimited)")
+        ("length" = Option<u64>, Query, description = "Number of bytes to read")
     ),
     security(
         ("bearerAuth" = [])
@@ -318,15 +318,15 @@ async fn stream_item_content_response_with_metadata(
     path = "/api/item/latest/meta",
     operation_id = "get_item_latest_meta",
     summary = "Get latest item metadata",
-    description = "Retrieve comprehensive metadata for the most recently stored item. Metadata includes automatically extracted information such as file type, MIME type, encoding, line counts, file size, system information (user, hostname, etc.), and cryptographic hashes. If tags are specified, returns metadata for the latest item matching ALL the given tags.",
+    description = "Retrieve metadata for the most recent item. Filter by tags.",
     responses(
-        (status = 200, description = "Successfully retrieved latest item metadata as key-value pairs including file type, encoding, size, and system information", body = MetadataResponse),
+        (status = 200, description = "Metadata retrieved", body = MetadataResponse),
-        (status = 401, description = "Unauthorized - Invalid or missing authentication credentials"),
+        (status = 401, description = "Unauthorized"),
-        (status = 404, description = "Item not found - No items exist in the database or no items match the specified tag criteria"),
+        (status = 404, description = "Item not found"),
-        (status = 500, description = "Internal server error - Failed to retrieve item metadata from database")
+        (status = 500, description = "Internal server error")
     ),
     params(
-        ("tags" = Option<String>, Query, description = "Comma-separated list of tags to filter by (e.g., 'important,work'). If specified, returns metadata for the latest item that has ALL the specified tags.")
+        ("tags" = Option<String>, Query, description = "Tags to filter latest item")
     ),
     security(
         ("bearerAuth" = [])
@@ -376,16 +376,16 @@ pub async fn handle_get_item_latest_meta(
     path = "/api/item/{item_id}/meta",
     operation_id = "get_item_meta",
     summary = "Get item metadata",
-    description = "Retrieve comprehensive metadata for a specific item by its ID. Metadata includes automatically extracted information such as file type, MIME type, encoding, line counts, file size, system information (user, hostname, process ID, etc.), cryptographic hashes (SHA256, MD5), and performance metrics (read time, read rate).",
+    description = "Retrieve metadata for a specific item by ID.",
     responses(
-        (status = 200, description = "Successfully retrieved item metadata as key-value pairs including file type, encoding, size, and system information", body = MetadataResponse),
+        (status = 200, description = "Metadata retrieved", body = MetadataResponse),
-        (status = 400, description = "Bad request - Invalid item ID (must be a positive integer)"),
+        (status = 400, description = "Invalid ID"),
-        (status = 401, description = "Unauthorized - Invalid or missing authentication credentials"),
+        (status = 401, description = "Unauthorized"),
-        (status = 404, description = "Item not found - No item exists with the specified ID"),
+        (status = 404, description = "Item not found"),
-        (status = 500, description = "Internal server error - Failed to retrieve item metadata from database")
+        (status = 500, description = "Internal server error")
     ),
     params(
-        ("item_id" = i64, Path, description = "Unique identifier of the item to retrieve metadata for (must be a positive integer)")
+        ("item_id" = i64, Path, description = "Item ID")
     ),
     security(
         ("bearerAuth" = [])

src/modes/server/api/mcp.rs

@@ -15,12 +15,12 @@ use crate::modes::server::mcp::KeepMcpServer;
     get,
     path = "/mcp/sse",
     operation_id = "mcp_sse",
-    summary = "Model Context Protocol SSE endpoint",
+    summary = "MCP SSE endpoint",
-    description = "Server-Sent Events endpoint for Model Context Protocol communication. This endpoint allows AI tools and clients to interact with Keep's functionality through the standardized MCP protocol. Supports saving items, retrieving content, searching by tags and metadata, and listing stored items.",
+    description = "Server-Sent Events for Model Context Protocol. Enables AI tools to interact with Keep's storage and retrieval functions.",
     responses(
-        (status = 200, description = "SSE stream established for MCP communication"),
+        (status = 200, description = "SSE stream established"),
-        (status = 401, description = "Unauthorized - Invalid or missing authentication credentials"),
+        (status = 401, description = "Unauthorized"),
-        (status = 500, description = "Internal server error - Failed to establish MCP connection")
+        (status = 500, description = "Internal server error")
     ),
     security(
         ("bearerAuth" = [])

src/modes/server/api/status.rs

@@ -15,11 +15,11 @@ use crate::compression_engine::CompressionType;
     path = "/api/status",
     operation_id = "status",
     summary = "Get system status",
-    description = "Retrieve comprehensive system status information including database configuration, data storage paths, supported compression engines, available metadata plugins, and system capabilities. This endpoint is useful for health checks and system diagnostics.",
+    description = "Retrieve system status including database info, storage paths, compression engines, and metadata plugins.",
     responses(
-        (status = 200, description = "Successfully retrieved complete system status including database path, data directory, supported plugins, and system information", body = StatusInfoResponse),
+        (status = 200, description = "System status retrieved", body = StatusInfoResponse),
-        (status = 401, description = "Unauthorized - Invalid or missing authentication credentials"),
+        (status = 401, description = "Unauthorized"),
-        (status = 500, description = "Internal server error - Failed to retrieve status information due to system error")
+        (status = 500, description = "Internal server error")
     ),
     security(
         ("bearerAuth" = [])