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

Annotations already cover the read-only/idempotent/non-destructive profile, yet the description adds real behavioral content: newest-first ordering, the 50-item ceiling, per-event field diffs and attachments, and the not_found-when-invisible error contract. It also carries an explicit prompt-injection warning about untrusted CRM field values, which annotations cannot express. The only gap is pagination behavior — with a 50 cap and no cursor/offset parameter, it is unclear how an agent retrieves older history.

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?

The functional contract is front-loaded in a single dense sentence, followed by a short safety note that earns its place by warning about untrusted content. No filler, though the second paragraph sits somewhat apart from the operational detail.

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, the description does the necessary work of describing the return shape (event types, field diffs, attachments, ordering) and the failure mode. Nothing critical is missing for a read tool, though the multi-workspace parameter constraint and pagination limits are only partially addressed.

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 only 25% (workspaceId is the sole documented property), so the description must carry more weight. It adds meaning for `limit` (cap of 50, ordering semantics) but says nothing about `id`, `objectType`, or the multi-workspace requirement for `workspaceId`, leaving the remaining parameters to name-inference alone.

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 (returns the change history of one record) and enumerates the payload contents (created/updated/deleted events with field diffs and attachments) plus ordering (newest first). This clearly separates it from get_record, list_records, and list_deleted_records without requiring the agent to open those schemas.

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?

Scopes usage to 'one record you may view' and names the not_found condition, which implies the visibility precondition. However, it never names an alternative tool or states when to prefer this over get_record, list_records, or get_record_lifecycle — the routing decision is left to inference.

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