list_routine_folders

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

With no annotations provided, the description carries the burden of disclosing behavioral traits. It mentions that Hevy enforces a max pageSize of 10, but this is already encoded in the schema (pageSize maximum: 10) and adds no new information. The description does not state whether this is a read-only operation, what the return format looks like, whether pagination uses page numbers, or any authentication requirements. Thus, beyond the schema, it provides minimal transparent behavioral context.

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 brief and front-loaded, with the primary purpose stated in the first sentence. The second sentence about Hevy enforcement is concise and adds a small piece of context, though it is redundant with schema. No filler or verbose phrasing is present, so the description is efficiently written.

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?

This is a list operation with two optional parameters and no output schema, so the description should at least indicate what the tool returns (e.g., a list of routine folders) and any pagination behavior. It does neither. Additionally, no usage context is provided, leaving the tool incomplete for an agent to confidently invoke without resorting to guessing or other tools.

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 input schema has two parameters (page, pageSize) with 0% description coverage, so the description must compensate by explaining their meaning. However, the description only repeats the pageSize max via 'Hevy enforces a max pageSize of 10' and does not explain what page or pageSize represent, how pagination works, or how to combine them. Since the description adds no semantic value beyond the schema, it fails to meet the compensation requirement.

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 'List routine folders' clearly states the action (list) and resource (routine folders), making the tool's purpose obvious. It is distinct from sibling tools like get_routine_folder or create_routine_folder, though it doesn't explicitly differentiate itself from other list tools such as list_routines. The name itself already provides strong clarity, earning a 4.

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 no guidance on when to use this tool versus alternatives. It does not mention list_routines, get_routine_folder, or any other sibling, nor does it state any exclusions or preferred scenarios. The only extra sentence about max pageSize is a constraint, not usage context, so the description fails to help the agent decide when to invoke this tool.

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