List work cards

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered by structured data. The description adds the filtered-list semantics and the 'use before starting work' workflow context. The openWorldHint=false is slightly in tension with the description implying exhaustive results, but this is reasonable for a filter-based read 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?

Two tight sentences: the first enumerates the filter dimensions in a compact list, the second states usage context and the alternative tool. Zero waste, all information earns its place.

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 11-parameter read tool with an output schema and strong annotations, the description is complete enough. It explains the filter scope, provides usage timing, and names the alternative. No nested-object complexity or undocumented safety concerns. Could mention pagination behavior (limit/offset) but the schema documents those defaults clearly.

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%, with each parameter having a detailed description including enums for type, status, and priority. The description names the filter dimensions but adds little beyond the schema. Baseline 3 is appropriate since the schema carries the full burden of parameter documentation and does so well.

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 clearly states the verb (list) and resource (work cards) with explicit filter dimensions (status, area, type, priority, parent, claim). It distinguishes from sibling project_search by noting the full-text alternative, and name/title reinforce the same purpose without contradiction.

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 before starting work' provides clear contextual guidance for when to invoke this tool, and it explicitly names project_search as the alternative for full-text queries. It doesn't enumerate every sibling's differentiation, but the key alternative is called out, which is sufficient given the schema provides exhaustive filter options.

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