Skip to main content
Glama
Sign In
Zoteus

Zoteus

by oscardvs
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

Record screening decisions on Zotero items

zotero_screen_items
DestructiveIdempotent

Record systematic-review screening decisions as Zotero tags on item batches, letting group libraries sync final or reviewer-specific include/exclude/maybe choices.

Instructions

Record systematic-review screening decisions as Zotero tags on a batch of items, so the whole group library sees them. Decisions are Zotero tags of the form screen//[:][@], e.g. "screen/title-abstract/exclude:wrong-population@alice"; stage is title-abstract or full-text, decision is include, exclude or maybe, a reason goes only on exclude, and a tag with no @reviewer is the final (consensus) decision. They sync to the whole group and stay readable in Zotero without Zoteus. Pass reviewer to record your own independent decision (dual screening); omit it to record the final decision, e.g. after resolving a disagreement. Each item gets exactly one tag for this stage and reviewer: a decision recorded earlier for the same stage and reviewer is replaced, and every other tag (the user's own, other stages, other reviewers) is left as it was. Writes go to the running Zotero desktop app (Zotero 10+) for every library it holds, otherwise to the cloud Web API (requires ZOTERO_API_KEY with write access). Read the queue and the tallies with zotero_review.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "stage": "<stage>",
      "decisions": "<decisions>"
    },
    "name": "zotero_screen_items"
  }
}

Input Schema

NameRequiredDescriptionDefault
stageYesScreening stage: "title-abstract" (first pass) or "full-text" (eligibility of the full report).
confirmNoRequired to tag more items in one call than the server's bulk-write threshold.
reviewerNoWho is screening, e.g. "alice". Slugged into the tag ("Alice B." becomes "alice-b"). Omit to record the final decision.
decisionsYesOne entry per item, at most 100 per call.
library_idNoNumeric id of the library to address, e.g. 5234875 for a group (zotero_groups lists the ids you can reach). Omit to use the configured default library; an id given without library_type is read as a group id.
library_typeNoWhich library to address: "user" (a personal library) or "group" (a shared group library). Omit to use the library this server is configured for. "group" on its own is refused: pass library_id with it.

Output Schema

NameRequiredDescriptionDefault
stageYesThe stage recorded.
failedNoOne entry per object the write could not land; absent or empty when all of them did.
targetNoWhere the write went: "local" (Zotero desktop local API), "desktop" (connector protocol) or "cloud" (Zotero Web API).
recordedYesThe items that now carry the decision.
reviewerNoThe reviewer slug, absent for final decisions.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv1.25.1

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare destructive/idempotent/openWorld, and the description earns that: it explains that each item gets exactly one tag per stage+reviewer, that an earlier decision for the same stage+reviewer is replaced while all other tags survive — which is precisely why the call is idempotent yet destructive. It further discloses the write path (running Zotero desktop 10+ for all libraries, otherwise Web API needing a write-scoped ZOTERO_API_KEY).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the action and the tag grammar, then the reviewer/consensus rule, then the replacement semantics and write path — a logical order. It is dense but a few clauses (restating stage/decision values already enumerated in the schema) could be trimmed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutating, batch, cross-library tool, the description covers tag format, per-item uniqueness, replacement scope, dual vs consensus screening, and the two write backends with auth requirements. An output schema exists, so return values need not be explained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: how `reviewer` is slugged into the tag, that a reason applies only to exclude, that a missing @reviewer means consensus, and that one tag per stage/reviewer is enforced. It does not add much on `confirm` or library addressing beyond what the schema already documents.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (record screening decisions), the resource (Zotero items, as tags), and the scope (batch, group-visible). It also names the exact tag encoding and routes the agent to zotero_review for reading, so it is distinguishable from siblings like zotero_manage_tags or zotero_review.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly distinguishes the two modes: pass `reviewer` for an independent dual-screening decision, omit it for the final consensus decision. It also names the alternative for the read side ("Read the queue and the tallies with zotero_review"), leaving nothing to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools