This server has 16 tools with schemas present but significant quality gaps. All tools have descriptions (in Chinese), but they are brief (10-40 chars), leaving LLM context-selection decisions ambiguous. Input schemas exist and are well-formed JSON Schema with type declarations and descriptions, which is good. However, output schemas are entirely absent from the tool definitions, LLMs cannot see what fields to expect from any tool's return value. Tools use vague, generic names like 'convert_to_*' and 'process_arxiv_paper' that combine multiple concerns (search+download+parse+convert). Error handling is minimal, no recovery guidance, no actionable error messages, no categorization (retryable vs fatal). Parameter naming is inconsistent: some tools use `arxiv_id` while others reference paper metadata directly. The descriptions are translations to English from Chinese originals and lack the specificity needed for LLM tool selection (e.g., 'Parse PDF and return raw text content' does not explain WHEN to use parse_pdf_to_text vs parse_pdf_to_markdown). No tool declares permissions, audit trail requirements, or whether it modifies state (though risk tags are supplied externally). Tool composition is poor: batch_analyze_papers, process_arxiv_paper, and generate_unified_literature_review overlap significantly, it's unclear to an LLM which to call for a given intent.
No output schemas documented. LLMs cannot see what fields, types, or structure to expect from any tool's return value. This violates the tool-chain pattern, downstream tools cannot be selected if the LLM doesn't know what the current tool produces.
Tool descriptions are uniformly brief (20 - 45 chars) and lack context for LLM selection. Examples: 'Parse PDF and return raw text content', 'Download arXiv PDF file'. These do not explain WHEN to use the tool, what it returns, or how it differs from similar tools (parse_pdf_to_text vs parse_pdf_to_markdown are both present but descriptions do not clarify the distinction).
Expand tool descriptions to 80 - 150 characters. Explain WHAT (search arXiv), WHEN (need recent papers on a topic), and key DIFFERENCES from related tools. Example: 'Search arXiv for papers matching a query. Returns metadata (title, authors, date) but not PDF content. Use this to discover papers before calling download_arxiv_pdf.'
Split composite tools. Create a 'process_arxiv_paper' wrapper that calls search → download → parse → convert in sequence, but expose each step as a separate tool so agents can retry individual steps. Alternatively, document dependencies in the description: 'Requires download_arxiv_pdf to be called first with the same arxiv_id.'
Add error handling guidance to descriptions. Example for download_arxiv_pdf: 'Downloads the PDF. If the arxiv_id is invalid, returns error 'Paper not found'. If network times out, retry after 5 seconds. If arXiv is rate-limiting, wait 60 seconds.'
Implement a confirmation step for clear_workdir. Add a dry_run parameter (default true) that lists files to be deleted without actually deleting them. Require the agent to call with dry_run=false explicitly.
Tool names violate single-responsibility principle. 'process_arxiv_paper' does search + download + parse + convert in one call, an LLM cannot decompose this into steps or handle partial failure. Similarly, 'batch_analyze_papers' combines download, analysis, and optional wechat generation. Split composite tools so agents can compose them.
No error handling guidance. Tools do not document what errors can occur (network timeout, invalid arxiv_id, PDF parse failure, API rate limit), whether they are retryable, or what the LLM should do next. A bare exception provides no recovery path.
Destructive tool (clear_workdir) lacks confirmation or dry-run support. The tool deletes all files in the work directory with no recovery options. An agent should not be able to invoke this without explicit user confirmation.
Tool names use 'convert_to_*' and 'export_to_*' patterns that conflate input with output format. Examples: 'convert_to_wechat_article', 'convert_to_academic_review_enhanced'. These names do not clearly state the action (transform? generate? summarize?) or preconditions (must PDF already be parsed?).
Parameters lack detail on format, range, and validation. Examples: 'maxConcurrent' has no min/max; 'temperature' (0-1 range) is documented in description but not enforced; 'sources' enum is present but Notion export tools lack description of what 'database_id' and 'page_id' look like or how to find them.
Tool output includes opaque IDs (arxiv_id stored in database) but tool descriptions do not clarify how to retrieve or reference them. The 'export_to_notion_update' tool requires a 'page_id', there is no documented way for an LLM to discover what page_id values are valid or where they come from.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint). While external metadata labels tools as READ_ONLY, WRITE, or DESTRUCTIVE, the MCP tool definition itself does not carry this information. Agents cannot reason about safety without parsing external labels.
all
Rename tools to be more explicit about action and output. Examples: convert_to_wechat_article → generate_wechat_summary_from_pdf; convert_to_academic_review_enhanced → generate_enhanced_academic_review_from_pdf; process_arxiv_paper → search_download_and_analyze_arxiv_paper.
Add numeric constraints to parameter descriptions. Example: 'maxConcurrent (integer, 1 - 10, default 5): Maximum number of parallel downloads.' Add format hints: 'arxiv_id (string, format: YYYY.NNNNN or URL http://arxiv.org/abs/YYYY.NNNNN): The arXiv identifier.'
Document how to discover IDs for external services. For export_to_notion_full, add: 'database_id: Find this in the Notion URL after 'database/' or in the Share dialog. page_id: Find in the page URL or use list_notion_pages tool (if available).'
Add tool annotations to each tool definition in the MCP server code. Use readOnlyHint=true for search_* and parse_*, destructiveHint=true for clear_workdir, and idempotentHint=true for export_* tools that overwrite rather than append.
Implement pagination for search_academic_papers and batch tools. Add max_results_per_page (default 20, max 100) and return a next_cursor or page_number field so agents can iterate over large result sets without memory exhaustion.