zotero_cite_stub

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

With no annotations, the description carries the full burden of behavioral disclosure. It transparently states that the tool errors on nonexistent keys, validates all keys against the user's Zotero library, and describes the exact stub output format with examples. It doesn't cover potential side effects or return value structure, but for a generation tool, the disclosed behavior is sufficient. The validation warning is a valuable behavioral disclosure not evident from the name or schema.

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

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

The description is front-loaded with a clear purpose statement, followed by a structured list of stub formats, and closes with an important usage note. Each example in the list is compact and necessary because the stub syntax is the core knowledge required to invoke the tool correctly. Though it is longer than a typical description, every line contributes to usability; only a slight reduction could be made by trimming examples, but the detail is justified.

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

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

Given no output schema and no annotations, the description compensates by providing a comprehensive picture: what the tool does, when to use it, how to construct stubs, what validation behavior to expect, and how it fits into the larger document processing workflow. It even includes the specific stub format for bibliography. This level of detail ensures the agent can select and invoke the tool correctly without additional context. The only minor omission is an explicit statement about the return type, but the stub examples strongly imply the output.

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

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

The input schema already provides 100% parameter coverage with descriptions. The description adds semantic depth by showing concrete usage of each parameter through stub format examples (e.g., 'p=42' for locator, 'prefix=see%20|suffix=%2C%20emphasis%20added' for prefix/suffix, 'suppress-author' for narrative citations). This goes beyond the schema definitions, helping the agent map parameters to the actual stub syntax. The bibliography placeholder example clarifies the purpose of bibliography and bibliographyStyle parameters.

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

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

The description opens with 'Generate validated citation stubs for use in documents,' a specific verb+resource pairing that clearly differentiates from siblings like zotero_cite or zotero_process_docx. It further distinguishes itself by emphasizing validation of real Zotero items and the exact stub format. This leaves no ambiguity about the tool's core function.

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

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

The description provides clear workflow guidance: use stubs in .docx documents then run zotero_process_docx. The 'IMPORTANT: Always call this tool to get stubs instead of writing them by hand' gives a strong directive, and the validation rationale prevents hallucinated references. It doesn't explicitly state when NOT to use this tool versus alternatives like zotero_cite, but the overall context implies a staged workflow, earning a 4 rather than a 5.

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