count_work_items

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

With no annotations, the description carries full burden and does well: it explains grouping behavior, supported group_by values, the requirement for sub_group_by, and the return format including key types (UUIDs, strings, ISO dates, 'None'). This is thorough behavioral disclosure.

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 well-organized with clear sections (overview, usage, Args, Returns). Every sentence adds value, and the structure makes it easy to scan. Length is appropriate for the tool's complexity.

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?

Despite having an output schema, the description explicitly documents return fields and their formatting, covering edge cases like 'None' for unset values and UUID vs string keys. This makes the tool fully understandable without external references.

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 only 33%, but the description fully compensates by explaining pql filters with examples, listing all supported group_by values, and noting that sub_group_by requires group_by. It adds substantial meaning beyond the sparse schema.

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?

Description clearly states the tool counts work items across the workspace with optional grouping, using a specific verb (count) and resource (work items). It distinguishes from siblings like list_work_items by emphasizing aggregation without fetching full payloads.

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?

Explicitly instructs to use for analytics questions like 'how many urgent items?' and 'distribution by state?' and notes the benefit of not fetching full work item payloads, implying a contrast with list/search tools. This provides clear when-to-use guidance.

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