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

No annotations are provided, so the description carries the full burden. It discloses the 50-item return cap, clarifies that only IDs are honored from the SELECT clause (batch-fetching full fields), and notes the search scope. This is meaningful behavioral disclosure beyond what's in the schema, though it doesn't mention auth requirements or read-only safety.

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 concise yet information-dense. It packs the core purpose, the query language reference, two concrete examples, a critical caveat about SELECT clause behavior, and the return cap into a compact paragraph with efficient formatting. No wasted words.

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 search tool with 100% schema coverage and no output schema, the description covers the essential aspects: what it searches, how to query, return limits, and the projection behavior. It could note whether results are sorted or how to handle pagination for more than 50 results, but for typical usage it's reasonably complete.

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 100%, so both parameters are documented. The description adds meaningful value beyond schemas: it explains the WIQL syntax, clarifies that SELECT columns beyond IDs are ignored, and provides real query examples. The maxResults parameter's behavior and cap are documented in both schema and 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 clearly states what the tool does: 'Search AzDO work items with WIQL (Work Item Query Language)' with specific verb+resource. It distinguishes itself from azdo_get_work_item by noting it returns the 'same projection,' and the sibling list shows it's unique as the search variant among azdo_create/get work item tools.

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 clear context for when to use this tool (searching with WIQL queries) and gives concrete WIQL examples to illustrate usage. It describes the return cap of 50 items but doesn't explicitly state when NOT to use it or contrast with another search alternative (though jira_search is a sibling for a different platform).

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