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

Annotations already cover safety (readOnly, idempotent, non-destructive), and the description adds genuinely new context: the response is a bare Long rather than an object, and the call requires the `notifications:read` API-key scope. It also pins the count to the current user in the active workspace, which the annotations cannot convey.

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 payload ('bare count ... a Long'), followed by the response-shape clarification and the scope requirement. Nothing is repeated or wasted.

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-required-param counter with no output schema, the description supplies the missing return-value information (single number, not an object), the auth requirement, and the targeting rule. An agent has everything needed to call and interpret it.

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 100% schema description coverage, the two params (account, workspace) are already fully documented and neither is required. The description's phrase 'active workspace' loosely ties to the workspace parameter but adds no syntax or override behavior beyond the schema, so the baseline applies.

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 ('Return the bare unread-notification count') plus scope ('current user in the active workspace') and return type ('a Long'). The emphasis on 'bare ... count, not an object' implicitly separates it from the list-style sibling pm_list_notifications without the agent needing to open the 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?

Usage is only implied: needing just a number rather than full notification records suggests when to pick this over pm_list_notifications, but no alternative is named and no when-not condition is given. Adequate but leaves the routing decision to inference.

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