Static source inference · medium confidence · evidence: Streamable HTTP
Current-spec patterns detected
Summary
This server presents significant definition quality gaps. While all 11 tools are registered and have basic descriptions, the implementation lacks comprehensive schema documentation, parameter descriptions are sparse, and error handling guidance is minimal. The tool definitions in server_old.py show basic docstrings but no structured input validation or output schema documentation. The codebase references tool functions from separate files (tools/basic/ and tools/academic/) but those implementations are not provided, making it impossible to verify actual parameter handling, validation, or error recovery patterns. Tools rely on string-based responses rather than structured outputs, which forces LLMs to parse free-form text. Based on the 549 production tool baseline (average description 194 chars, p90=392), most tools here fall below 150 chars with minimal actionable guidance.
Output schemas not documented. Tools return unstructured string responses (e.g., 'Found N images') rather than structured objects with typed fields. LLMs cannot predict which fields to extract or plan downstream tool calls without knowing the response structure.
Parameter descriptions are minimal or absent. 'file_path' and 'page' parameters appear across all tools but have one-line descriptions lacking format constraints, ranges, or examples of valid inputs.
Document output schemas for all tools. Example for extract_citations: '{citations: [{id: string, authors: string[], title: string, year: integer, venue: string}], total_count: integer, method: string}'. This enables LLMs to extract fields and chain downstream tools.
Expand parameter descriptions to 50+ characters with format and constraint details. Example: 'file_path (string, required): Absolute or relative path to a PDF file (e.g., /data/paper.pdf or ~/documents/study.pdf). File must exist and be readable. Returns error if not found.'
Add actionable error messages with recovery hints. When file not found, return: 'PDF file not found at path: /path/to/file.pdf. Ensure the path is correct and file is readable. Available tools to discover files: search_pdf_directory()'.
Implement pagination for list-returning tools. Add 'limit' (default 20, max 100) and 'offset' (default 0) parameters to detect_sections, extract_citations, extract_key_sections. Return {results: [...], total_count: integer, offset: integer, limit: integer}.
Constrain numeric parameters with explicit ranges. Example for dpi: 'dpi (integer, optional, default 150): Rendering resolution in dots per inch. Range: 72 - 600. Lower values (72 - 150) are faster; higher values (300 - 600) are better for OCR.'
Add input validation and type checking. Per pattern:constrained-input, validate file_path exists, page is positive integer, dpi is in range. Return: 'Invalid page number: 0. Valid range for this PDF: 1 - 42 pages.'
Implement dry-run for any file modifications or side effects. If future tools write output files, add a 'dry_run' parameter and return what would happen without actually doing it.
No error handling or recovery guidance. Tools raise ValueError on missing files but do not guide the LLM on what to do next (e.g., 'Try verifying the file path' or 'Available tools: list_pdf_files'). Per pattern:recovery-guide, error responses must be actionable.
Tool implementation files not visible in provided source. Tool_registry.py imports from tools/basic/ and tools/academic/ but actual implementations are not shown. This prevents verification of parameter handling, validation logic, and return value structure. Per HARD SCORING RULE: tools whose actual definitions are inferred rather than directly visible are capped at 50.
Optional parameters lack clear defaults and constraints. 'page', 'dpi', 'chunk_size' parameters are optional but no description clarifies what happens if omitted. For 'dpi' (default 150), no range is specified, can it be 1, 10000, or must it stay within 72-600? Unconstrained numbers let LLMs pass absurd values.
No pagination support. Tools like extract_citations likely return long lists but accept no limit or offset parameters. Per pattern:paginated-result, tools returning lists must support pagination to avoid context window exhaustion.
Tool descriptions under 50 chars violate baseline minimums. 'Get PDF metadata and document information' (48 chars) and 'Render a PDF page as an image' (31 chars) lack actionable context.
get_metadatarender_pageextract_abstract
Provide tool selection guidance in descriptions. Example for extract_academic_text vs extract_key_sections: 'Use extract_academic_text for raw, complete text extraction with formatting preserved. Use extract_key_sections for a curated summary of abstract, intro, methodology, results, and conclusion, optimized for agent reasoning.'
Add return examples to parameter descriptions to anchor LLM expectations. Example: 'page (integer, optional): PDF page number to process (1-indexed). E.g., page=3 processes the third page. If omitted, processes entire document.' Note: Examples should be generic (page numbers, not specific IDs).
Include per-tool error classification (retryable vs user-fixable vs fatal). Tools should raise/return structured errors: {error_code: 'file_not_found|invalid_page|permission_denied|timeout', message: '...', retryable: boolean, next_steps: string}.