Loading ToolBench

Reading the current corpus…

ZotSeek MCP server · A · ToolBench

← Browse

ZotSeek

github.com/introfini/ZotSeek

Semantic Search for Zotero using local AI embeddings with MCP and REST endpoints

<=2025-11-25STREAMABLE_HTTP3 tools

83/100

Definition Quality87

Protocol Readiness72

SupportabilityNot measured-

Spec posture

Inferred effective spec <=2025-11-25·current baseline 2026-07-28

Static source inference · medium confidence · detected: Logging

Deprecated protocol patterns detected

Summary

ZotSeek provides 3 well-scoped read-only tools with clear names, detailed descriptions, and comprehensive input schemas. All tools start with action verbs (search, find, index) and have descriptions in the 150-350 character range. Input parameters are fully typed with constraints (enums, min/max bounds). Output schemas are partially documented through TypeScript interfaces visible in http-tools.ts. The main gap is the absence of explicit tool annotations (readOnlyHint, idempotentHint) in the registration code, though the tools themselves are demonstrably read-only. Error handling is implicit (relies on underlying search engines) but not explicitly documented per-tool. Overall, this is a solid B+ implementation with production-ready tool definitions.

Tools (3)

find_similarread onlysource verified87/100

Find papers semantically similar to a given Zotero item by item key, with optional library scoping and result limit

index_statusread onlysource verified85/100

Get the current indexing status including number of indexed papers, active model ID, readiness state, and model loading status

searchread onlysource verified90/100

Semantic search across Zotero library using hybrid, semantic, or keyword search modes with configurable parameters for similarity threshold, result count, and granularity

Issues (4)

MEDIUMtool-annotations ↗

Missing tool annotations (readOnlyHint, idempotentHint, destructiveHint) in MCP tool registration. While the code comments and interfaces clearly indicate all tools are read-only, the annotations are not visible in the source. This forces clients to infer safety from the tool name alone.

searchfind_similarindex_status

MEDIUMrecovery-guide ↗

Error handling guidance is not explicitly documented. The ToolResultItem and SearchToolArgs interfaces show input validation (clamping, enum checks in code), but error messages and recovery paths are not documented in tool descriptions. An LLM cannot predict what happens if query is empty, library_key is invalid, or min_similarity exceeds the valid range.

searchfind_similar

MEDIUMresponse-shaper ↗

Output schema for 'search' and 'find_similar' is inferred from ToolResultItem interface but not explicitly documented in tool descriptions. The description does not specify the structure of the returned results, pagination behavior, or whether results are sorted by score. LLMs benefit from explicit output schema documentation.

Recommendations

Add explicit tool annotations to the MCP registration. Each tool should declare readOnlyHint=true to signal to clients that no state is modified. This is especially important for 'search' and 'find_similar' which agents might call speculatively.
Document error handling per tool. For 'search': specify behavior if query is empty, min_similarity is out of range, or library_key does not exist. Example: 'If library_key does not exist, returns an empty result set; if query is empty, returns an error code with guidance to provide a non-empty query.'
Add explicit output schema to tool descriptions. For 'search': 'Returns an array of ToolResultItem objects sorted by score (descending), each with itemKey, title, authors, year, score, and optionally matchedChunk (snippet and page number). Maximum of max_results items returned.'
Clarify the granularity parameter. Update description to: 'papers returns whole-document matches (faster, broader context); passages returns individual chunk matches (slower, more precise for embedding-based ranking). Choose passages if the query targets specific claims within long papers.'
Add minimum input validation examples to descriptions. E.g., for 'search': 'query must be non-empty (1-500 characters); max_results between 1-100; min_similarity between 0.0-1.0.'
Document the library_key resolution behavior. Specify: 'Omit to search all indexed libraries. Provide 'user' for personal library or 'group:123' for a specific group library. Invalid library keys return an error with a list of available libraries.'

Spec posture evidence

Inferred effective spec: <=2025-11-25.

Relies on Logging (deprecated) - log to stderr or use OpenTelemetry

Score history

Overall score trend

First recorded score · v2 rubric

83/100

Scored	Grade	Overall	Spec posture	Rubric
2026-09-23	A	83	<=2025-11-25	v2