tasks_list

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

No annotations are supplied, so the description bears the full burden. It usefully discloses the shape of the result (queues with pending/running counts, and the tasks within them), which is real behavioral value. However, it never states that this is a non-mutating read, says nothing about ordering or pagination beyond the limit parameter, and does not mention how many queues are returned or what happens with zero queues.

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?

It is a single sentence with no filler, and the primary resource (queues) is front-loaded ahead of the filtering behavior. The semicolon clause is slightly compressed to the point of feeling telegraphic, but nothing is wasted.

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?

With three optional, fully documented parameters and no output schema, the description does the one thing that matters most: it sketches the return contents (queues with counts, tasks within them) that the schema cannot express. Missing are read-only confirmation and any note about result volume, which for a list endpoint without an output schema would have been worth one extra clause.

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 description coverage is 100%, so the baseline is 3. The description reinforces the semantics of queue (scope to one queue) and state (restrict to one state), but adds no syntax, format, or defaulting detail beyond what the schema already documents. The one nuance it could have clarified — that limit is per queue rather than a global cap — is only in the schema, not the description.

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 names a concrete verb-resource pairing: it returns Cloud Tasks queues (with pending and running counts) plus the tasks inside them. That is more specific than the tool name alone and tells the agent the return payload includes aggregate counts as well as task entries. It does not explicitly contrast itself with siblings like tasks_stats or tasks_run, so it stops short of a 5.

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?

Usage is only implied: the clause 'with queue, only that queue's tasks, optionally in one state' conveys that the queue parameter narrows scope and state further filters. There is no explicit statement of when to call this instead of tasks_stats (counts only) or tasks_run (execution), which are the obvious alternatives in the sibling list.

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