list_work_item_properties

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

With no annotations, the description carries the full burden of behavioral disclosure. It transparently explains the fallback scope resolution (workspace → project-flat → workspace), the result structure (id, display_name, property_type, options), and the PQL workflow. It does not mention pagination, rate limits, or auth requirements, but for a list operation the described behavior is unusually detailed.

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-structured and front-loaded, but somewhat long at approximately 300 words. It contains useful sections for scope resolution, result fields, and PQL workflow, each earning its place. However, it is more verbose than strictly necessary for a list operation, and the PQL workflow could be considered tangential to the tool's core purpose.

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?

Given the tool's complexity (three optional params, multiple scope behaviors, an output schema, and a sibling context), the description is remarkably complete. It covers all parameter combinations, provides the output fields, and even includes a practical workflow for composing PQL filters. The presence of an output schema reduces the need to elaborate return values, yet the description still adds valuable context on using the results.

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 0%, and the description fully compensates by explaining the effect of each parameter combination (no args, work_item_type_id only, project_id only, both). It also clarifies what each returned field means for downstream PQL usage, adding substantial meaning beyond the bare schema definitions.

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 opens with 'List custom work item properties,' a specific verb+resource combination that clearly distinguishes this tool from siblings like retrieve_work_item_property (single retrieval) and list_work_item_property_options (options for a property). It immediately conveys the tool's purpose without ambiguity.

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?

The description provides explicit scope resolution rules based on argument combinations and even recommends an efficient approach for PQL filtering ('prefer calling with NO args'). It gives clear context on when to use the tool and how to choose parameters, though it does not explicitly compare against alternative sibling tools like retrieve_work_item_property or list_work_item_property_options.

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