neurolinker-mcp has 12 tools with clearly defined purposes and consistent naming conventions. All tools are properly named with action verbs (process, check, list, get, create, make). Descriptions are present and substantial, ranging from 100-600+ characters, generally exceeding the 10-character minimum. However, the server has significant gaps: (1) Input schemas are visible but parameter descriptions are minimal or missing in some cases; (2) Output schemas are NOT documented anywhere in the provided source; (3) No error handling guidance for recovery paths; (4) Parameters lack detailed constraints (enums, ranges, patterns); (5) Tool descriptions contain implementation details and instructions to the LLM rather than clean WHAT/WHEN/WHY guidance; (6) Batch operations (process_pdfs, get_documents_*) accept arrays but lack pagination/limit parameters despite returning potentially large result sets. The naming is strong and consistent across the toolkit, but parameter quality and output documentation are weak.
Get detailed status and results for a specific document within a processing request. Use when the user asks about one particular document. Always return status info; when processing is completed, also include the document_page_url (for opening results in the app UI). IMPORTANT: When status is "completed", ALWAYS include the document_page_url in user-facing messages, and NEVER mention the internal document_id.
Check the overall processing status of a job containing one or more PDF documents. When status is "completed": - Tell the user standard outputs are available (extracted text/markdown, structured JSON, extracted images, per-page summaries, high-level document summary, on-demand PDF generation). - Include the job_page_url so they can open results in the app UI. - If there is a single document or you are listing documents, you may also include its/their document_page_url(s). - NEVER expose internal identifiers (request_id, document_id) in user messages. Tip: Include job_page_url whenever available (even before completion) so the user can follow progress. Status meanings: - "pending": Just started, still in queue - "processing": Currently being processed - "partial": Some documents completed, others processing/failed - "completed": Processing finished, results available - "failed": Processing failed
Generate a new PDF based on one or more documents.
No output schemas documented. Tools return response.json() or error dicts, but the structure of successful responses is never declared. LLMs cannot plan downstream tool calls without knowing what fields to expect (e.g., does check_request_status return 'status', 'state', 'processing_state'?). Response structure must be documented as part of tool definition.
Parameter descriptions are minimal or missing. The input schemas show parameter names and types but lack descriptions explaining what each parameter controls. For example, document_ids and request_id have no descriptions. Per the rubric, every parameter requires a non-empty description explaining format, range, and allowed values.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | D | 54 | 2026-07-28+ | v2 |
| 2026-03-09 | F | 32 | - | v1 |
Get the extracted images from one or more documents. Use this tool when a user wants to download/view the images that were extracted from the PDF during processing. IMPORTANT: - In user-facing messages, include the download_url so they can access the files. - Do NOT expose internal document IDs.
Get the full JSON processing results file for a single or multiple documents. This tool retrieves the actual .json files that were saved to Firebase Storage at the end of the processing pipeline, containing the complete structured extraction results. Use when the user asks for something like JSON results structured data. IMPORTANT: - In user-facing messages, include the download_url so they can access the file. - Do NOT expose internal document IDs.
Get the extracted Markdown file for one or more documents. The markdown file represents the extraction output from the processing pipeline in a human-readable format with semantic structure preserved. IMPORTANT: - In user-facing messages, include the download_url so they can access the file. - Do NOT expose internal document IDs.
Get the per-page summaries for one or more documents. Summaries are short abstracts of the content of each page, generated during the processing pipeline. IMPORTANT: - In user-facing messages, include the download_url so they can access the file. - Do NOT expose internal document IDs.
Get the per-section summaries for one or more documents. Summaries are short abstracts of the content of each section, generated during the processing pipeline. IMPORTANT: - In user-facing messages, include the download_url so they can access the file. - Do NOT expose internal document IDs.
Get the high-level summary for one or more documents. This is a summary of the entire document generated during the processing pipeline. IMPORTANT: - In user-facing messages, include the download_url so they can access the file. - Do NOT expose internal document IDs.
Get an overview of all the requests in the system. Use this tool when a user wants to see what documents have been processed or are currently being processed. NEVER expose internal identifiers (request_id, document_id) in user messages.
Create a zip file containing results from one or more documents.
Start processing one or more PDF documents through the neurolinker pipeline. IMPORTANT: This is an ASYNC process that takes time. After calling this tool: 1. Immediately inform the user that processing has started 2. Tell them processing time varies with the size and complexity of the PDF 3. Tell them they can ask about overall request status or the document status to check progress - keep it natural and user-friendly 4. Do NOT wait or call other tools - let the user check back later 5. Only offer PDF creation AFTER processing is completed 6. NEVER mention request IDs or document IDs to the user Use this tool when a user wants to process PDF documents for analysis. Supports both local file paths and URLs.
Tool descriptions mix implementation details with LLM instructions. Descriptions like 'IMPORTANT: This is an ASYNC process...' and 'Do NOT wait or call other tools' are instructions to the LLM, not explanations of what the tool does. Separate WHAT/WHEN/WHY from how the LLM should use it. Descriptions should be neutral; LLM guidance belongs in system prompts, not tool descriptions.
No error handling guidance. Tools return errors as JSON dicts with an 'error' field, but there is no documentation of what errors are possible, whether they are retryable, or what the LLM should do next. Per the rubric, error responses should guide recovery: 'File not found. Verify the path or use list_processing_tasks() to get valid document IDs.'
Batch retrieval tools (get_documents_*) lack pagination parameters. These tools accept arrays of document_ids but provide no limit, offset, or page_size parameters. If an agent calls get_documents_json with 500 document IDs, the response could be enormous and exhaust the context window. Add limit and cursor/offset support per the paginated-result pattern.
create_pdf and make_zip have minimal descriptions (40 chars). 'Generate a new PDF based on one or more documents.' and 'Create a zip file containing results from one or more documents.' lack context on WHEN to use them vs other tools, what formats are supported, and what the output contains. Expand to 100-200 characters with actionable WHEN guidance.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint). The schema declares Risk fields (WRITE, READ_ONLY) in the source comments but these are not encoded as tool annotations in the MCP response. Per the current spec, use readOnlyHint=true for READ_ONLY tools and destructiveHint=true for WRITE tools so clients can warn before execution.
pdf_paths parameter in process_pdfs accepts array but has no description. The description is in the tool's docstring, not the parameter annotation. Parameters need inline descriptions. Also, the parameter accepts both file paths and URLs but the description mixes both cases, clarify the type and format per parameter.
Async processing requires multi-step user interaction (process → wait → check status → download), but there is no formal Multi Round-Trip Request (result 'input_required') pattern. Tool descriptions tell the LLM to wait and ask the user, but MCP supports structured user-input prompts. Consider using the input_required result type for cleaner UX.