zotero_add_from_file

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

With no annotations provided, the description fully discloses behavior: attempts DOI extraction, enriches metadata via CrossRef, falls back to filename/text guesses, explains the if_exists parameter logic, mentions PDF upload quota (300MB), states requirement for writable library, and notes that other extensions are rejected. No contradictions with annotations because none exist.

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 well-structured and front-loaded with the main action, then details metadata extraction, alternatives, parameter explanations, and conditions. While slightly lengthy, every sentence adds value for a complex tool. Minor room for conciseness without losing information.

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?

The description covers all contextual aspects: tool purpose, metadata extraction behavior, parameter details, edge cases (if_exists), prerequisites (writable library, quota), post-action (zotero_update_search_database), and an example. An output schema exists but the description does not need to explain return values per rules; it is complete for agent understanding.

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 has 0% description coverage, but the description compensates thoroughly: explains file_path requires absolute path and only .pdf/.epub, title is optional override, collections can be keys/names/paths, tags are optional, if_exists has three modes explained, and create_missing_collections is a boolean. Each parameter gets meaningful context beyond the schema types and defaults.

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 adds an item from a local .pdf or .epub file to the active Zotero library. It specifies metadata extraction via DOI or fallback, and explicitly distinguishes from sibling tools by naming zotero_add_by_doi and zotero_add_by_url as alternatives for different scenarios.

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 explicitly states when to use this tool (user has a file on disk but no DOI/URL) and when not to (use zotero_add_by_doi if DOI is available, zotero_add_by_url for online URLs). It also includes conditions like requiring a writable library and the need to run zotero_update_search_database afterwards.

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