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

The description adds valuable behavioral context beyond the annotations: large backlogs are cleared asynchronously while the unread badge drops immediately. This discloses timing and eventual-consistency behavior that neither the idempotentHint nor destructiveHint conveys. Annotations are consistent with the description (it is a mutation, hence readOnlyHint=false, and it is idempotent). A small gap remains in not describing the return value or failure behavior, but the async disclosure is genuinely useful.

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 sentences with zero waste: the core action is front-loaded, the async behavior follows as essential nuance, and the routing to the sibling tool closes it out. Every sentence earns its place and the definition is appropriately short for a simple one-parameter tool.

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 low-complexity tool with one parameter, the description covers the operation, workspace scoping, async edge case, immediate badge effect, and the single-vs-all alternative. The only notable omission is the return value/confirmation behavior, especially given there is no output schema, but for a mark-as-read operation the effect is self-evident enough that this is a minor gap.

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 of explaining parameter meaning. The phrase 'in a workspace' clarifies that the single workspaceId parameter scopes the operation to a specific workspace, which partially compensates. However, the description does not explain where workspaceId comes from or that it is effectively required, though the parameter name is self-evident enough to keep this at an adequate level.

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: 'Mark all unread notifications in a workspace as read.' The word 'all' plus 'in a workspace' precisely scopes the operation, and it is clearly distinguished from the sibling campaignstack_mark_notification_read, which handles a single notification. No ambiguity remains about what this tool accomplishes.

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 description explicitly names the alternative tool ('use campaignstack_mark_notification_read instead') and the exact condition that selects it ('To mark a single notification read'). It also implies the intended use case for this tool — clearing all unread notifications at once — leaving no inference burden on the agent.

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