Import items by identifier or URL

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

Annotations declare readOnlyHint=false and openWorldHint=true, which the description supplements by explaining that saving requires a cloud key and that it can return multiple choices for by_url. It also notes the server dependency and that setup instructions appear if the server is unreachable, adding useful behavioral context 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 well-structured, starting with the overall purpose then detailing each action mode. It is informative but slightly lengthy; every sentence adds value. It could be slightly tighter, but it maintains clarity.

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 the tool's complexity (two modes, optional saving, external server dependency, no output schema), the description covers key operational aspects: identifier types, save behavior, collection association, and server requirement. It mentions multiple choices for by_url and setup instructions. Missing details like return value format or error states are minor gaps.

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 57% (parameters described: action, identifier, url, collection_key, save_to_library). The description adds meaning to action, identifier types, and the effect of save_to_library, and clarifies that collection_key is used during saving. However, it does not explain library_id and library_type, which lack schema descriptions.

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 resolves bibliographic metadata from identifiers or web pages and optionally saves them. It distinguishes two actions (by_identifier vs by_url) with specific identifier types, making the purpose unambiguous and distinct from sibling tools like search or create.

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 guides when to use each action (by_identifier for DOIs, ISBNs, etc.; by_url for scraping) and notes the save_to_library flag requires a cloud API key. It also mentions the dependency on a translation-server. However, it does not compare directly with sibling tools or state when NOT to use this tool.

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