list_folders

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

With no annotations provided, the description must carry the full burden. It explicitly discloses that it returns the full list, not a page, and explains the rationale (small folder list). It also clarifies potential confusion about duplicate names by emphasizing path vs folder_id. While it does not state 'read-only' explicitly, 'List' strongly implies it, and there is no indication of side effects. This is above average for a simple read operation.

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 four sentences, front-loaded with the primary function. It provides essential context in clear paragraphs. There is a slight redundancy in the last sentence ('Returns everything rather than a page' and 'the whole point is to see the shape of the archive...'), but overall it is tight and efficient.

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 parameterless list tool without an output schema, the description covers everything an agent needs: what is returned (full path, note count), how to interpret data (path vs folder_id), and that it returns all items non-paginated. It also explains the purpose of the archive shape, making it complete for correct invocation.

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?

The tool has zero parameters, so the baseline is 4 per the rubric. The description adds context about the output fields (path, note count, folder_id) that would be useful for downstream tool usage, though it does not need to explain parameters since none exist.

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 clearly states the verb and resource: 'List every Apple Notes folder, with its full path and how many notes it holds.' It goes beyond a simple statement by explaining the purpose of the output (folder_ids, path disambiguation) and explicitly contrasts with siblings that operate on notes. An agent can immediately distinguish this from list_notes or search_notes.

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 a strong usage hint: 'This is where folder_ids come from' and explains that folder_id is what other tools take, implying this is the entry point for folder references. It also explains the non-paginated behavior ('Returns everything rather than a page'). However, it does not explicitly mention alternatives or 'when not to use', but given the unique purpose, the guidance is sufficient.

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