agent_workload

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.