list_folder

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

Annotations already provide readOnlyHint=true and idempotentHint=true, so the read-only safety profile is covered. The description adds valuable context beyond those: the ambiguous-name-rejection behavior, the specific output format (tab-separated id/title/modified/snippet), sorted newest first, and the fact that subfolders come as full paths. It doesn't deeply describe depth or large-listing limits, but with strong annotations the added context is substantial, meriting a 4.

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?

Four sentences, all earning their place. Front-loaded with the core purpose, then schema-supplementing details on the parameter, output format, and sibling differentiation. Slightly dense with the tab-separated column enumeration, but every clause adds genuine value. No wasted words.

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?

There is an output schema, so return values need not be re-explained, but the description still covers the useful behavioral aspects: ordering, tab-separated field format, id reuse with read_note/edit_note, and the folder path semantics. For a single-parameter read-only listing tool with strong annotations and an output schema, this is complete.

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 fully compensate for the single folder parameter. It does: explains folder is 'a path (or a name, where unique) as shown by list_folders', notes ambiguity is rejected rather than guessed, and clarifies how subfolder values relate to descending. This adds meaning the bare schema property (title: Folder) entirely lacks. With 1 parameter and no enums, this is strong compensation.

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?

Description uses a specific verb+resource: 'List the notes and immediate subfolders inside folder'. It clearly distinguishes from siblings: list_folders (top-level listing), search_notes/search_note_text (text-based finding). The scope ('immediate subfolders', 'newest first') makes it unmistakable what this tool does and how it differs.

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?

Explicitly states when to use it: 'This is how to browse the library by structure, where search_notes/search_note_text find notes by their text.' This directly contrasts the structural-browsing use case against the text-search alternative, naming sibling tools. It also documents behavioral nuances (ambiguous names rejected, subfolders as full paths for re-descending).

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