Zoteus

Zotero data model (types & fields)

zotero_schema

Read-only

Get the Zotero data model to validate item types, fields, and creator types before creating or updating items. Avoid hardcoding item shapes with schema version and type-specific details.

Instructions

Return the Zotero data model so you never hardcode item shapes. With no arguments, returns the schema version and the list of all item type names. With item_type, returns the valid fields and creator types for that type (the "primary" creator type is listed first). Use this to validate an item before creating or updating it: notes, attachments, and annotations are item types too but bypass the normal field/creator model.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`item_type`	No	If set, return the fields & creator types for this item type.

Output Schema

TableJSON Schema

Name	Required	Description
`fields`	No	Valid field names for that item type.
`version`	Yes	Zotero schema version this answer came from.
`itemType`	No	The item type asked about.
`itemTypes`	No	Every item type name; returned when no item_type was given.
`creatorTypes`	No	Valid creator types for it, primary first.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv1.20.2Sep 16, 2026

removedInput schema / $schema

Removed value: -"http://json-schema.org/draft-07/schema#"

removedOutput schema / $schema

Removed value: -"http://json-schema.org/draft-07/schema#"

Changed1 schema field changedv1.20.0Sep 13, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": true,
+  "properties": {
+    "creatorTypes": {
+      "description": "Valid creator types for it, primary first.",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "fields": {
+      "description": "Valid field names for that item type.",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "itemType": {
+      "description": "The item type asked about.",
+      "type": "string"
+    },
+    "itemTypes": {
+      "description": "Every item type name; returned when no item_type was given.",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "version": {
+      "description": "Zotero schema version this answer came from.",
+      "type": "number"
+    }
+  },
+  "required": [
+    "version"
+  ],
+  "type": "object"
+}

First observedv1.0.4Jul 30, 2026

TDQS

A4.7/5.0

Behavior5/5

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

The description adds meaningful behavioral detail beyond the readOnlyHint/openWorldHint annotations: it specifies the no-argument return (schema version plus item type names), the item_type-argument return (fields and creator types), and the fact that the primary creator type is listed first. This gives the agent an accurate picture of what the tool will do before invoking it.

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

Conciseness5/5

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

The description is compact, front-loaded with the core purpose, and divides behavior into no-argument versus item_type cases in a clear, scannable way. Every sentence contributes useful information, and there is no redundant restatement of the name or title.

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?

Given the simple one-parameter optional interface, the annotations, and the presence of an output schema, the description covers everything an agent needs: what calling with no arguments returns, what passing item_type returns, when to use the tool, and an important caveat about special item types. No critical usage detail is missing.

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

Parameters3/5

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

The input schema already fully documents the single optional item_type parameter and its effect. The description adds some context around the returned fields and creator types, including the primary-creator ordering, but does not materially change the meaning of the parameter itself. With 100% schema coverage, a baseline of 3 is appropriate.

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?

The description states a specific action ('Return the Zotero data model') and clearly distinguishes the tool's role as a schema lookup for validation, not as an item search or mutation tool. It also differentiates the no-argument and item_type-argument behaviors, which are the two ways the tool is used.

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?

The description gives explicit guidance: 'Use this to validate an item before creating or updating it.' It also provides a useful exclusion by noting that notes, attachments, and annotations are item types but bypass the normal field/creator model, helping the agent know when not to rely on the standard schema.

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