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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, so safety is covered. The description adds real behavioral context beyond that: the result set is bounded by the API key's permissions and duty status is reported per team with dutyMode/onDutyTime. It stops short of stating pagination or rate-limit behavior.

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 compact sentences plus the endpoint. The primary action and scope lead, the returned fields follow, and the practical motivation (needing user ids) closes it. No filler.

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?

No output schema exists, so the description carries the return-value burden, and it does so by enumerating the returned fields including the nested duty per-team shape. Combined with parameterless input and clear read-only annotations, an agent has everything needed to call and interpret this tool.

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?

With zero parameters there is nothing for the description to disambiguate, so the baseline is 4. The description does note that filtering is by the key's access scope rather than by any argument, which usefully explains why no filter parameters exist.

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?

Specific verb (List) plus resource (SIGNL4 users), the access scope (the key can access), and the exact fields returned (name, e-mail, contact addresses, activation state, duty status per team). This distinguishes it from signl4_get_user (single user) and signl4_list_team_users (team-scoped), so an agent can pick it without opening a schema.

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?

It supplies a concrete reason to call it – 'User ids are needed to acknowledge/close/annotate alerts' – which links it to the ack/close/annotate siblings. It does not, however, state when to prefer signl4_list_team_users over this tool when team scoping is the goal, so the routing guidance is good but not exhaustive.

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