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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description usefully adds the aggregation grain and sort order (open-only, heaviest first), but says nothing about how "open" is determined, whether results are paginated, or how max_tickets truncates the data. Modest added value over the annotations.

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 short sentences, front-loaded with the grouping and ordering. The second sentence slightly restates the first ("heaviest load first" vs. "where work is piling up") rather than adding new information, but there is no meaningful bloat.

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?

An output schema exists, so return-value shape need not be described, and the tool is low complexity. However, for a tool whose only knob truncates the result set at a default of 1000, the silence on max_tickets and on what counts as an "open" ticket leaves real gaps.

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% for the single max_tickets parameter, and the description never mentions it. The default of 1000 and the effect of lowering it (truncation vs. filtering agents) are left entirely unexplained, so the description does not compensate for the schema gap.

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 names the resource (open tickets), the grouping dimension (assigned agent), and the ordering (heaviest load first), which lets an agent distinguish it from list-style siblings like find_tickets. It stops short of explicitly contrasting itself with backlog_health or reassign_tickets, but the verb-less noun phrase is still specific enough to identify the operation.

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?

"Shows where work is piling up" implies a capacity/triage use case, which is genuine but soft guidance. There is no statement of when to prefer this over backlog_health or find_tickets, nor any prerequisite or exclusion. Usage is inferred rather than stated.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: the exact four detection categories and the fact that 'unused' is measured over a 30-day window while 'stale' is measured against stale_days. It stops short of explaining result volume or the max_per_kind cap.

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 sentences, front-loaded with the action and target, followed by the detection list and the kind enumeration. Nothing is redundant and no sentence is 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?

An output schema exists, so return values need not be described. For a read-only, zero-required-parameter audit tool the description is nearly sufficient; the only substantive omission is any explanation of max_per_kind, which at 0% schema coverage is undocumented everywhere.

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%, so the description carries the burden. It does well on two of three parameters – enumerating valid kind values and tying stale_days to the 'not modified in stale_days' check – but max_per_kind is never mentioned in either the description or the schema, leaving its purpose and the 500 default undisclosed.

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 states a specific verb (audit) and resource (triggers, automations and macros) plus the goal ('looking for dead rules'), and enumerates the four problem classes it detects. No sibling tool overlaps this domain, so an agent can identify it unambiguously.

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 by the purpose – call it when you want to find dead automation rules – but there is no explicit when-to-use, when-not-to-use, or prerequisite statement. Since none of the sibling tools is a plausible alternative for this task, the lack of routing guidance is a minor but real gap.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, so the safety profile is covered structurally. The description adds the semantic definition of `stale_days` ('days without an update'), which is genuinely useful, but says nothing about result size, pagination, or scope limits beyond that.

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 tight sentences that front-load the output shape before the parameter gloss. 'X-ray' is a minor flourish but doesn't cost clarity; every clause carries information.

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, return values need no prose, and annotations cover the read-only safety profile. What remains is a partially documented second parameter, which is a small but real gap for a two-parameter analytical 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?

Schema description coverage is 0%, so the description bears the burden. It defines `stale_days` clearly but leaves `sample_size` (which presumably controls how many stalled tickets are returned) entirely unexplained in both schema and description. Partial compensation, hence a 3.

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 names a specific resource and output ('counts by status and priority, plus the most stalled tickets'), so an agent knows exactly what this tool produces. It does not, however, distinguish itself from analytical siblings like agent_workload or security_overview, so the sibling differentiation is left implicit.

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 by 'open backlog' and 'stalled tickets' — an agent can infer this is for backlog triage — but there is no explicit when-to-use/when-not statement or named alternative tool. Nothing misleads, but the agent must infer the routing itself.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description earns credit beyond that by disclosing a non-obvious behavioral detail: the phone must be the user's profile phone, not a ticket field, so the tool resolves the user first and then lists their tickets. It does not mention result limits or pagination 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 tight paragraphs: the search keys are front-loaded in the first sentence, then the interaction rules. Every sentence carries distinct information with no repetition of the name or 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?

An output schema exists, so return-value documentation is not needed, and the zero-required-parameter schema is offset by the explicit 'at least one' rule. The remaining gaps are minor: no note on capping/pagination with max_results or behavior when no matches are found.

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%, so the description carries the burden and does so well for the four filter parameters: it explains ticket_id exclusivity, the combinability of email/subject/phone, and the special semantics of phone. max_results (default 50) is not addressed at all, which leaves one of five parameters undocumented anywhere.

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 names a specific verb (find) and resource (tickets) and enumerates the exact search keys: ticket id, requester email, subject, phone. No sibling in the list is a ticket-search tool, and the one adjacent tool (find_user) is clearly distinct, so an agent can select this 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?

It states a hard precondition ('Provide at least one of the four') and spells out the selection rules: ticket_id is exclusive and suppresses the others, while email/subject/phone combine and are ANDed together. It gives no guidance on when to prefer this over other lookup paths or what happens when nothing matches, which keeps it short of a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the returned fields, but since an output schema exists that information is largely redundant and no pagination, result-limit, or empty-result behavior is disclosed.

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 tight sentences with the core capability front-loaded and no filler. The return-value sentence is somewhat redundant given the output schema, which 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?

For a one-parameter read-only search tool with annotations and an output schema, the description covers the essential scope. Only secondary details like result limits or search-syntax edge cases are absent.

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 0% and the single 'query' parameter has no schema description, so the description must carry the load. It does say the query accepts names, emails, or general Zendesk search syntax, which is meaningful, but it gives no syntax examples, quoting rules, or format constraints.

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?

States a specific verb and resource ('Find users') plus the searchable fields, and names the return shape. It is distinguishable from find_tickets, but it never explicitly contrasts itself with that sibling.

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 mention of 'name, email or any term of the Zendesk search syntax' implies how to use it, but there is no explicit when-to-use guidance, no exclusions, and no routing to siblings like find_tickets or whoami.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds only the shape of the returned data ('targets by priority and metric'), which is useful context but not rich 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?

A single front-loaded sentence with zero filler; every clause earns its place by stating the resource and the returned content.

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 no parameters, an output schema covering return values, and annotations covering the safety profile, the description supplies everything an agent needs to select and invoke the tool. Only the absence of explicit usage guidance keeps it short of perfect.

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?

The tool takes no parameters, so the baseline is 4. There is nothing further the description could reasonably add about parameter meaning.

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 names a specific verb ('List') and resource ('SLA policies') and summarizes the content returned ('targets by priority and metric'). It is clear, though it does not explicitly contrast itself with siblings, which is acceptable since none of the siblings touch SLA policies.

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?

There is no statement of when to call this tool versus alternatives, and no prerequisites or exclusions are mentioned. For a zero-argument read tool the usage is largely self-evident, but the description offers no guidance at all.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that results flag inactive and system fields, which is useful context, but says nothing about auth scope, rate limits, or pagination. With annotations carrying safety, a 3 fits the modest extra value.

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 tight sentences, front-loading what the tool returns and then the use case. No filler, though the second sentence is a soft hint rather than high-value content.

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?

An output schema exists, so return-format explanation is unnecessary, and read-only annotations cover the mutation question. The remaining gap is the include_inactive parameter and its default, which neither schema text nor description addresses.

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 single parameter include_inactive (default true) is never explained. The mention of 'inactive' gestures at the concept but does not clarify whether the toggle filters or merely annotates them, leaving the agent to infer behavior from a default it cannot see in the text.

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?

States a specific resource ('ticket fields') with an inventory/list action and adds what the output reveals (inactive vs system flags). It is distinguishable from siblings like list_sla_policies or find_tickets, though it does not explicitly name a competitor to avoid.

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?

'Useful before cleaning up forms' gives a use context, but there is no explicit when-to-use vs when-not, no prerequisites, and no named alternative. Usage is implied rather than directed.

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

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

The safety profile is already declared by annotations (readOnlyHint=true, destructiveHint=false, openWorldHint=true), and 'Read-only; it changes nothing' merely restates them. The description does add the inventory of what the report surfaces, but adds no permission requirements, scoping, or freshness/pagination behavior beyond that.

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 tight sentences: the first front-loads the payload inventory, the second disposes of the safety question. No filler, nothing repeated.

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?

An output schema exists, so return values need no explanation, and the description usefully previews report contents. For a one-parameter read-only tool this is nearly sufficient; only the identity/format of user_id is left unaddressed.

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%, so the description carries the full burden for the single user_id parameter, yet it never mentions it — an agent cannot tell whether it takes a numeric ID, an email, or a username from the description. 'An agent' implies the target but supplies no format or acceptance detail.

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?

States a specific resource (an agent's offboarding state) and enumerates exactly what is returned: assigned open tickets, groups, role, last login. The framing 'before deactivating them' plus 'read-only; it changes nothing' cleanly separates it from the mutating sibling set_user_status and the narrower find_user/agent_workload 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 phrase 'before deactivating them' gives a clear use context — run this prior to offboarding an agent. It does not name an alternative tool or state exclusions (e.g., when to prefer agent_workload or find_user instead), so it stops short of full routing guidance.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true, and idempotentHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing the dry-run default and what the non-destructive mode actually returns, which is exactly the kind of context an agent needs before a destructive bulk operation.

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 short sentences, front-loaded with the operation and followed by the mode switch. The hard line breaks split single sentences awkwardly, but there is no filler content.

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?

An output schema exists, so return values need not be explained, and the dry-run behavior is well covered. However, for a destructive bulk mutation it omits what qualifies as an 'open ticket,' what happens to tickets beyond max_tickets, and whether elevated permissions are required.

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%, so the description must carry the burden, and it only elaborates on dry_run (default true, report-only behavior, how to execute). The three other parameters — from_user_id, to_user_id, and max_tickets — receive no explanation of meaning or constraints, leaving half the surface documented only by self-evident names.

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 states a specific verb and resource ('reassign an agent's open tickets to another agent'), making it immediately distinguishable from read-only siblings like find_tickets and agent_workload. It does not, however, explicitly contrast itself with adjacent mutation tools such as offboarding_report or set_user_status.

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 explains the two execution modes (report-only vs. execute) and their trigger, which is genuine usage guidance for the tool itself. It gives no guidance on when this tool is appropriate versus siblings that also touch ticket ownership, and no prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds non-obvious context the annotations cannot: the data comes from the audit log and the tool is plan-gated to Enterprise, which is exactly the kind of entitlement constraint an agent needs before calling.

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?

Three short sentences, front-loaded with the resource and source, followed by parameter hints and the plan constraint. No filler, though the value enumeration is slightly list-like rather than integrated.

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?

An output schema exists, so return values need not be explained, and the Enterprise gate plus source is disclosed. The gaps are the undocumented `days` and `max_items` parameters and the absence of any default-behavior note (e.g., 7-day window), which matter for a tool whose schema has no descriptions at all.

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%, so the description must carry parameter meaning. It partially does: it enumerates accepted values for `action` (create, destroy, exported, login, update) and gives examples for `source_type`. But `days` and `max_items` are left completely undocumented, and the 'among others' phrasing makes the value lists non-exhaustive, so compensation is incomplete.

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 names a specific resource (recent configuration changes from the audit log), so an agent knows this is an audit-log query rather than a mutation. It does not differentiate itself from the sibling audit_business_rules, which is also audit-related, so it falls short of a 5.

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 states a hard prerequisite ('Requires the Enterprise plan'), which is genuine usage guidance. However, it never says when to prefer this tool over audit_business_rules or other siblings, and gives no when-not conditions.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the read-only nature and external-world reach are covered. The description adds the scope of what's returned, which is useful, but doesn't mention the unused-token threshold semantics or result size.

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?

One efficient sentence with the resource front-loaded and the three content categories enumerated. No padding, though a hint about usage context would have been worth the space.

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?

Output schema exists so return values need not be explained, and annotations cover safety. But with 0% param coverage, the description should clarify the unused_token_days parameter, and it offers no differentiation from sibling security tools — leaving gaps for a tool that overlaps several siblings.

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 single parameter unused_token_days only has a default of 90 in the schema with no explanation. The description alludes to 'unused' tokens but doesn't define the window or explain how this parameter controls it, leaving the core parameter undocumented.

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?

States a specific subject (account security overview) and enumerates the concrete contents: admin role holders, OAuth tokens including unused ones, and installed apps. It is distinguishable from siblings like whoami or recent_admin_changes, though it overlaps conceptually with offboarding_report.

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?

No guidance on when to use this versus the security-adjacent siblings (whoami, recent_admin_changes, offboarding_report). The agent must infer the appropriate context from the name alone.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the safety profile is partly covered. The description adds a genuinely important behavioral fact not in the annotations: dry_run defaults to true and only reports the proposed change against current state, which prevents accidental mutation. It still omits what an actual suspension does (active sessions, tokens, reversibility) and any permission requirements.

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 short sentences with zero filler; the capability statement is front-loaded and the dry_run caveat follows immediately. Every clause earns its place.

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?

An output schema exists, so return values need no explanation. For a destructive, four-parameter mutation tool the description covers the safe-preview mode and role vocabulary but leaves the mutation's side effects and authorization requirements unstated.

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%, so the description carries the burden and does explain two of four parameters well: the accepted role values (end-user, agent, admin) — critical since the schema declares no enum — and dry_run's default and effect. user_id and suspended are never described beyond what their names imply.

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 names a specific verb pair and resource: 'Suspend or reactivate a user, and/or change their role.' It even extends beyond the tool name set_user_status by revealing the role-change capability. However, it never references any sibling tool, so an agent gets no explicit routing signal versus find_user or offboarding_report.

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 by the operations described (suspend/reactivate/role change), and the dry_run default gives a safe-preview path, but there is no explicit when-to-use or when-not-to-use guidance and no named alternative among the twelve siblings.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description goes beyond that by disclosing what the tool reveals (account and role) and its role as a credential/auth verification step, which is genuine added context; only return-format details are absent, and an output schema exists anyway.

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 short sentences, zero filler, with the diagnostic purpose front-loaded before the usage instruction. Every clause earns its place.

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 zero-parameter read-only probe with full annotation coverage and an existing output schema, the description supplies everything an agent needs: what it does, what it returns conceptually, and that it should be called first.

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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. No parameter-level guidance is needed or missing.

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?

States a specific verb and resource: verify the Zendesk connection and report the account and role the server runs as. That is clear and unambiguous, and no sibling tool does anything comparable. It does not explicitly name a sibling to differentiate itself, which keeps it just short of a 5.

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?

"Use this first to confirm the credentials work" gives an explicit, actionable trigger: run it as the initial diagnostic before other calls. It does not describe when not to use it or name an alternative, but for a unique diagnostic tool no meaningful alternative exists.

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