What changed since you last looked

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

Even with readOnlyHint=true, the description adds valuable behavioral context: it reveals that user widget edits are included in the change stream, events are returned oldest-first with full details (actor, item id, fields), and omitting 'since' only returns the current position. This goes well beyond the structured 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?

Three dense sentences carry the entire behavioral contract without repetition. The most important concept ('what changed since you last looked') is front-loaded, and every clause adds necessary detail about marks, return ordering, and event contents.

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?

The description fully covers the tool's semantics: what events are returned, the meaning of 'since', how to continue paging via next_since, and the surprising inclusion of user widget edits. With an output schema present, there is no need to enumerate return fields, making this complete for the tool's complexity.

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 67%, so the description's burden is moderate. It enriches the 'since' parameter by explaining acceptable mark types (write ack seq, data_list version, next_since) and the consequence of omitting it. It does not elaborate on 'collection', but the overall context is sufficient; the extra mark semantics push this above baseline.

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 uses a specific verb ('returns') and clearly identifies the resource: a collection's event stream since a held ledger position. It distinguishes this from sibling tools by emphasizing that it includes edits made in the widget that never pass through the agent, which data_list and data_version do not cover.

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 provides clear when-to-use guidance by explaining how any existing mark (write ack seq, data_list version, or next_since) serves as the 'since' parameter. It does not explicitly state when NOT to use this tool or name an alternative for full collection snapshots, though it references data_list's version as a source, which implies its role.

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