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

Beyond the annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false), the description discloses concrete behaviors: it returns a paginated JSON array, then a line with the total match count and whether more pages remain. It also explains that `include_body` and `include_instructions` are withheld for trashed notes, and that `include_instructions` defaults to `include_body` — useful nuance not visible in the schema alone.

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 long, but it is front-loaded with the core purpose and use-case distinction, then moves into parameter details. Each sentence adds information (pagination, onboarding fallback, combos), and the example at the end aids comprehension. A few repetitions exist (e.g., the note about being withheld for trashed notes appears twice), but overall it's dense and structured, not flabby.

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 13 parameters (0 required), full schema coverage, and no output schema, the description compensates thoroughly: it explains the output shape (array + total-count line), pagination mechanics, when to use include_body to avoid extra calls, and the empty-result onboarding path. Nothing an agent needs to call this tool 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 100%, so the schema already documents every parameter and its meaning. The description adds value beyond that by explaining interactions (e.g., `container_id` can combine with `team_id`), the default of `include_instructions`, the `include_body` trade-off, and a concrete example (`{container_id: 5, tags: ['ruby']}`). This is more than a baseline 3, though it doesn't radically change any single param's semantics.

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 ('List and browse') and a clear resource ('the user's saved notes'), then enumerates what those notes are. It explicitly distinguishes itself from the sibling tool `search` ('Use search instead when hunting for a topic or keyword; use this to enumerate a folder, tag, or scope'), so an agent can immediately tell them apart.

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 when-to-use guidance: it names the alternative (`search`) and the condition that selects it (topic/keyword hunting vs. enumeration). It also tells the agent what to do when the result is empty (call `me` and follow onboarding.next_action), which is a clear usage directive beyond mere selection.

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