swsd_my_queue

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered structurally. The description adds genuine context beyond that: per-row computed SLA risk levels, the client-side vs server-side split for filtering (assignee_email is client-side because SWSD ignores it server-side), and the mode switch when assigned_to_group is set. It does not discuss pagination limits or result-size behavior, which is a real gap for a queue 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?

Four sentences, front-loaded with the core purpose and defaults before the filter options. Each sentence carries information: default scope, default sort, output enrichment, and override mechanics. Slight redundancy with the schema descriptions keeps it from a 5.

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 an output schema present, the description need not explain return values, and it correctly spends its words on mode selection, defaults, and filter semantics. For a 10-parameter, zero-required tool it gives enough to call it correctly without reading the schema carefully. The main omission is any note on pagination behavior or the cost of client-side filtering on large result sets.

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%, and the schema already documents page, per_page caps, the enum for sort_by, the date/datetime union for updated_from, and the client-side note on assignee_email. The description largely restates these (states/priorities/sort_by options) rather than adding syntax or interaction rules the schema lacks; the one addition, mode defaulting when assigned_to_group is set, is also present in that parameter's own description. Baseline 3 is therefore appropriate.

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 a specific verb+resource framing ("Work-queue view for the authenticated user") and states the default result set: open incidents assigned to you, sorted by due_at ascending. It also distinguishes the tool's output shape (rows with a computed SLA risk level) from a plain list. It stops short of naming the closest siblings (swsd_list_incidents, swsd_list_my_incidents), so the differentiation is implicit rather than explicit.

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 implied through the description of default mode ("my" queue) and the two override paths (assignee_email for client-side filtering, assigned_to_group for server-side). However, there is no explicit statement of when to choose this over swsd_list_my_incidents or swsd_list_incidents, and no stated exclusions or prerequisites. An agent can infer the intent but must reason about which sibling to pick.

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