smart_add_paper

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

With no annotations provided, the description carries the burden of behavioral disclosure. It explicitly explains the non-destructive probe mode, the write mode, and the duplicate-handling behavior of attaching to an existing collection instead of creating a duplicate. It does not detail return values or error cases, but the critical behaviors are transparent.

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 compact and front-loaded with the primary purpose. The second sentence earns its place by explaining the crucial behavioral distinction between the two modes. There is no filler or redundant repetition of schema details.

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 the core decision an agent needs: when the tool will write, when it will not, and how duplicates are handled. Since there is no output schema, a bit more return-value detail for the probe mode would improve completeness, but the key usage context is well covered.

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?

Schema coverage is 100%, so the schema already documents all parameters. The description adds meaningful conditional semantics for collection_name (probe vs. actual write) and clarifies that tags are applied to newly created items, going beyond simple parameter names.

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 a specific action ('Add paper from DOI') on a specific resource and describes its main behaviors: duplicate checking and optional collection/tag assignment. The conditional dual-mode behavior further distinguishes it from sibling search-and-add tools, so an agent can tell this is the DOI-based add tool.

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 gives clear context for when the tool writes versus when it acts as a probe: without collection_name it is a dedup/metadata probe, and with collection_name it fetches from Crossref and writes to Zotero. It does not explicitly name sibling alternatives or state exclusions, but the conditional guidance is strong enough for correct selection.

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