zotero_get_notes

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 explains the list vs search behavior, truncation behavior (including that truncate=False is list-mode only), raw_html return behavior, and the active-library scope. It also warns that query and item_key cannot be combined. It does not cover error cases or pagination, but for a read-only tool the disclosed behaviors are substantial and sufficient.

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 a single dense paragraph but is well organized: purpose first, then modes, then parameter explanations, then scope, then examples. Every sentence adds value, though it is a bit long. It is front-loaded with the core purpose and uses bold-like emphasis (capitals for LIST/SEARCH) to aid scanning.

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 tool with 5 optional parameters, no annotations, and an existing output schema, this description covers all needed semantics: param meanings, defaults, mode restrictions, scope, and usage examples. The output schema handles return structure, so nothing an agent needs to call it correctly is missing.

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 description coverage is 0%, so the description must explain every parameter. It does: limit (with default 20), query (search substring), item_key (child notes), truncate (shortening behavior and mode constraint), and raw_html (return original HTML, with use case). It even provides concrete examples demonstrating both list and search modes. This fully compensates for the lack of 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 opens with a specific verb and resource: 'Read notes from the active Zotero library.' It clearly distinguishes between listing and searching modes, and notes that it covers both note and annotation text. This makes it unmistakable what the tool does and how it differs from siblings like zotero_get_annotations or zotero_get_item_children.

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 explicit conditions for when to use list mode vs search mode (with or without query), and notes that query and item_key cannot be combined. It also explains when raw_html is appropriate (for editing and round-tripping via zotero_manage_note) and mentions scope changes via zotero_switch_library. It does not explicitly name alternative tools for annotation-only retrieval, but the guidance is otherwise clear and actionable.

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