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

Annotations already establish read-only, idempotent, non-destructive behavior, so the description correctly spends its words elsewhere: it discloses that results are paginated ('bounded pages') and that captured identity is 'self-reported, not verified' — a genuine data-trust caveat an agent could not infer from annotations or schema. It does not describe ordering or retention, but the added context is substantive.

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 with no padding, and the restrictive precondition is front-loaded where an agent will see it first. Slightly compressed to the point that the core purpose statement is missing, but nothing is 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?

With no output schema and no annotation gaps, the privacy and pagination warnings are the right content, but a 4-parameter cross-document tool still leaves the agent guessing how to scope a call (workspace_id vs documentId) and what an activity record contains. Adequate but with clear 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% across four parameters, so the description carries the full burden and mostly fails: 'bounded pages' hints at limit/cursor but never explains page size or cursor semantics, and the distinction between documentId and workspace_id — the key scoping choice — is unaddressed.

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 leans on the name and title to convey the action, characterizing the tool as 'cross-document detailed activity' rather than stating plainly that it returns activity records spanning documents in a workspace. The phrase does differentiate it from per-document siblings like get_document_activity, but the actual output (what an 'activity' item is) is never stated.

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?

'Only use on an explicit owner request' and 'Do not silently dump account-wide personal data' give an explicit precondition and an explicit prohibition, which is stronger guidance than most read tools. It stops short of naming the alternative (e.g. get_document_activity) for single-document lookups, but the 'cross-document' framing implies the boundary.

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