Add Paper By Doi

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

Annotations already indicate this is a write operation (readOnlyHint=false) and non-destructive. The description adds valuable context that it 'Resolves metadata automatically via CrossRef' and optionally adds to a collection, revealing an external network dependency and side effect beyond the annotations.

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 concise and well-structured: an opening sentence with the main action, a brief elaboration on metadata resolution, and a clear Args list. No irrelevant information, and the most important details are front-loaded.

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?

For a relatively simple tool, the description covers the core purpose, the DOI resolution, and optional collection assignment. Since an output schema exists, return values are not required. It omits edge-case behavior like duplicate handling or network failures, but this is not essential for tool selection and invocation.

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 schema provides only parameter names and types, with 0% coverage. The description compensates fully by explaining each parameter: doi with an example and purpose, collection_id as an optional Zotero collection key. This gives the agent complete semantic understanding without needing external lookups.

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 clearly states the tool's function: 'Add a paper to your Zotero library by its DOI.' It specifies the verb (add), the resource (paper to Zotero library), and the method (by DOI), distinguishing it from sibling tools like add_paper_by_arxiv_id or add_book_by_isbn.

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 context for when to use the tool: when you have a DOI and want to add a paper to Zotero, with automatic metadata resolution via CrossRef. It does not explicitly mention alternatives or exclusions, such as pointing to add_papers_by_dois for batch operations, but the DOI-specific scope is unambiguous.

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