get_folderless_lists

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

No annotations are provided, so the description carries full burden. It discloses the key behavioral qualifier (folderless/directly in space) but does not reveal return format, pagination, ordering, or whether archived lists are included by default. The archived parameter hints at filtering but behavior isn't stated.

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?

A single sentence that is direct and wastes no words. It conveys purpose and scope efficiently. It's slightly under-specified but this is acceptable for a straightforward list-retrieval tool.

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 simple read tool with only 2 parameters and no output schema. The description covers the core scoping behavior adequately, but given no annotations, it could specify a bit more (default archived behavior, result form). It's minimally complete for a low-complexity tool.

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?

With only 50% schema description coverage, the description needs to compensate. It adds semantic value by explaining that the result set is scoped to a specific space (space_id context), and the 'not in any folder' qualifier gives meaning beyond the raw schema. However, the 'archived' parameter's semantics are left to the schema's minimal type info.

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 uses a specific verb+resource ('Get all lists') and adds a clear scope qualifier ('not in any folder, directly in a space'). This distinguishes it well from sibling tools like get_lists and get_folders, making the purpose clear and differentiated.

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?

While the description makes the scoping obvious (folderless lists in a space), it provides no explicit guidance on when to use this over alternatives like get_lists (which returns lists generally) or create_folderless_list. No exclusions or alternative tool mentions are given.

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