list_folders

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

With no annotations, the description carries the full disclosure burden. It usefully reveals two behavioral traits: the return shape is a flat array and paths are already resolved. However, it does not mention ordering, whether deleted or hidden folders are included, or what fields accompany each folder. It is helpful but not fully transparent.

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?

Two compact sentences, each earning its place: the first defines the core behavior and output shape, and the second gives actionable downstream usage. Information is front-loaded and there is no filler or repetition of schema data.

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, read-only listing tool with no output schema, the description is complete enough for an agent to call it correctly. It states what the tool returns, how the result is structured, and how the result should be used in related operations. Nothing essential 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?

This tool has zero parameters, and the schema already covers that fully, so the baseline is 4. The description adds relevant context by explaining how returned folder ids should be used with create_folder/update_folder, though it does not need to explain any parameters of this tool itself.

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 states a specific verb and resource: "List all folders (flat array)". It also clarifies the key distinguishing behavior—"full path already resolved—no need to walk parent_id yourself"—so the tool is immediately distinguishable from related tree-walking or graph tools. This is a precise, unambiguous purpose statement.

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 contextual guidance for when this tool is useful: you get complete folder paths without manually traversing parent_id. It also tells you how to use the result, saying to pass a folder's id as parent_id to create_folder/update_folder. It does not explicitly name alternatives or exclusions, but the intended context is clear.

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