list_notes

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

No annotations are provided, so the description carries the full disclosure burden. It does volunteer one behavioral fact — results come back in timeline order — and the verb 'Review' plus the tool name signal a read-only operation, but it never states whether resolved notes are excluded by default, whether results are scoped to one project, or whether there is any pagination.

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?

A single tight sentence with the ordering constraint placed up front and an inline example that makes 'notes' concrete. Nothing is wasted or padded.

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 two-parameter read tool with no output schema, the description covers what a note is and how results are ordered, which is a reasonable minimum. It falls short on the resolved/active distinction and on what a returned note looks like, both of which an agent needs to use the results correctly.

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 both parameters and does not. 'project' and 'include_resolved' are only inferable from their names; the description says nothing about whether project is an ID or a name, or that resolved notes are omitted unless include_resolved is set.

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 names the resource (notes) and adds a clarifying gloss — 'human feedback such as "cut this pause"' — plus a return ordering ('in timeline order'). That is more than the title/name alone conveys, though it never explicitly contrasts itself with the sibling mutations add_note and resolve_note.

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?

Reviewing existing human feedback implies the read-side use case against add_note/resolve_note, but the guidance is only implied. There is no explicit statement of when to prefer this over resolve_note, or when a caller should set include_resolved.

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