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

Annotations already cover read-only/idempotent/non-destructive, and the description adds substantial context beyond them: the per-change field semantics (type, actor+alias, subject public id, why, mine), the caveat that viaBrowser events have no why by design, and the meaning and safe response to WORKSPACE_BUSY ('nothing was changed, retry'). That is real operational transparency.

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?

Core purpose is front-loaded in the first sentence, followed by field semantics and error handling in a sensible order. The parenthetical clauses (e.g. the viaBrowser explanation) are dense and slightly hard to parse but each carries unique 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?

For a stateful, cursor-advancing feed tool this covers the hard parts an agent needs: what each entry contains, the ack-or-replay advancement rule, and the WORKSPACE_BUSY recovery path. Return structure is covered by the output schema, so no return-value prose is needed.

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 100%, including descriptions for limit and deliveryToken, so the baseline is 3. The description corroborates deliveryToken's replay purpose but adds nothing the schema does not already say and never mentions limit or its 50-default behavior.

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 opening sentence gives a specific verb (Read), resource (workspace changes), and scope/ordering (bounded, authorized, oldest first). It distinguishes the read feed from the ack step conceptually, though it never names the sibling tool workspace_changes_ack, so the routing is left slightly 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?

It explains the two operating modes clearly: read a new page, or replay with deliveryToken, plus the requirement to acknowledge before advancing. It also gives an explicit retry instruction for WORKSPACE_BUSY. It stops short of naming when to call a different sibling instead.

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