A Flask-based server that provides paper search and retrieval functionality using the Elsevier API (Scopus)
Two tools with basic schemas and descriptions, but significant gaps in parameter documentation, output schema clarity, and error handling guidance. Both tools have action verbs (search, get) and non-empty descriptions (baseline: 194 chars avg; these are 150-160 chars). However, parameter descriptions are minimal or missing context. No output schemas documented. Error handling returns generic HTTP errors without recovery guidance. No tool annotations (readOnlyHint, idempotentHint). Schemas are present but lack depth, parameters have types but descriptions are sparse. This is typical community-server quality (C/D range).
Retrieve detailed metadata for a specific paper by its paper ID. Returns paper title, authors, abstract, publication date, journal name, and DOI.
Search for papers using a query string. Returns formatted search results with paper metadata including title, authors, publication date, and abstract.
Output schemas not documented. LLMs cannot plan downstream calls or extract fields without knowing response structure. search() returns formatted results with 'position', 'title', 'source', 'link', 'date', 'abstract' but this is inferred from code, not declared in tool definition.
Parameter descriptions lack actionable constraints. 'count' is described as 'Number of results to return (optional, defaults to configured default_count)' but does not specify min/max bounds. LLMs may pass absurd values (0, 10000) that break the API.
Error responses are generic HTTP errors (400, 404, 500) with minimal guidance. 'Query parameter q is required' is good, but 'Document not found' and generic 500 errors do not tell the LLM what to do next (retry? search first? ask user?).
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | F | 49 | <=2025-11-25 | v2 |
No tool annotations. Both tools are read-only (risk: READ_ONLY declared) but this is not reflected in tool definitions via readOnlyHint. LLMs cannot distinguish safe tools from destructive ones without explicit annotations.
get_paper parameter 'paper_id' description says 'path parameter' but does not explain what an EID is or how to obtain one. LLMs may not know that search() returns 'position' (EID) to pass to get_paper().