open_notebook_notes

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds real behavioral context by disclosing that results are titles only (not full note content) and how to paginate. It does not state the page size or what next_offset looks like on the final page, which keeps it from a 5.

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?

Three short sentences, zero waste, with the core action front-loaded and the alternative and pagination follow-ups in descending priority. Nothing could be cut 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?

An output schema exists, so return values need no explanation, and the description still flags the titles-only shape plus pagination. The only gap is page-size/limit behavior, which leaves the agent unable to reason about how many calls a full listing takes.

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 0%, so the description must carry the burden. It explains offset's pagination role (<next_offset>) but says nothing about limit (default 20) or notebook_id semantics, leaving two of three parameters undocumented anywhere except their bare 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?

Specific verb (List) + resource (notes) + scope (one notebook) + explicit return shape (titles only). It also implicitly distinguishes itself from open_notebook_note_get, so an agent can tell the list operation from the single-note fetch without opening either schema.

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?

"Read a note with open_notebook_note_get" routes the agent to the correct sibling when titles are not enough, and "Page with offset=<next_offset>" states the continuation procedure. There is no explicit when-not condition, but the main decision point is covered.

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