List Folders

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so 'It is read-only' restates structured data rather than adding value. Nothing is said about pagination behavior (the limit/cursor loop), whether folders are flat or hierarchical, or what identifiers are needed for later file/move calls — which is exactly the context this description sets up.

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 short sentences, with the workflow context front-loaded ahead of the safety note. The only waste is the trailing 'It is read-only,' which duplicates the annotations and could be dropped or replaced with genuinely new information.

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?

The tool is simple (0 required params, full schema coverage, output schema present, rich annotations), so most of the burden is already carried elsewhere and the description is minimally sufficient. Still, it omits pagination follow-through and the folder-identifier details an agent would want before chaining into a move/filing call, which the description itself invokes as the motivation.

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 100% and each parameter carries its own explanation (limit default/max, cursor source, mailbox_id scoping rule), so the schema does the work. The description adds no parameter meaning beyond that, which is the expected baseline of 3 when schema coverage is high.

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 pairs a specific verb ('inspect') with a specific resource ('mailbox folders'), making it obvious this is the folder-enumeration tool rather than a message or calendar tool. It never explicitly says 'lists/returns the folders available,' so it stops short of a 5, but the resource boundary against siblings is clear.

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?

'Use this to inspect mailbox folders before filing or moving messages' gives a real usage context tied to a prerequisite workflow. However, no alternative tool is named and there is no when-not-to-use guidance, so an agent must infer the boundaries itself.

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