list_todos

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

No annotations are provided, so the description carries the full burden, and it discloses real behavior: result ordering, that 'all' includes full completion history, and that history grows without bound. It does not state whether results are paginated or what fields are returned, which keeps it from a top score for an unannotated tool.

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 ordering behavior is front-loaded in the first clause, followed by the parameter modes, with no filler sentences. The whitespace and line break inside the quoted description are slightly awkward but do not impair comprehension.

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 one-parameter list tool with no output schema, the description covers what matters: ordering, scope per mode, and the fact that history is unbounded. Return shape is left implicit, which is acceptable for a simple listing endpoint but is the remaining gap.

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 0% – the single parameter is an untyped anyOf string/null with no enum – so the description must compensate entirely, and it does: it names the default (all) and defines all three modes, including the non-obvious semantics of 'today' (unfinished plus items completed today). The schema would otherwise leave the valid value set unknowable.

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 ('列出待办') and goes further by specifying the ordering: incomplete items first, newest on top. It doesn't explicitly distinguish itself from sibling list tools such as list_habits or list_countdowns, but those cover clearly different resources, so an agent can identify the tool.

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?

It gives concrete guidance for selecting the 'only' mode – notably 'use open when you just want to find work to do' and explaining that 'today' matches what is visible on the phone page. It lacks any when-not guidance or tool-level alternative routing, but there is no sibling that lists todos, so that gap is minor.

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