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

Annotations already declare readOnly/idempotent/non-destructive/openWorld=false, so the safety profile is covered. The description adds real behavioral context beyond that: default ordering ('newest due first'), the hard cap ('limit is at most 50'), and a prompt-injection warning that CRM field values are untrusted data. Pagination/continuation behavior is still undisclosed.

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 tight sentences: what is listed, what can be filtered and how results are ordered/bounded, then the untrusted-content caution. Purpose and scope are front-loaded and no sentence is redundant.

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 9-parameter read tool with a nested linkedRecord object, no output schema, and near-zero schema documentation, the description supplies enough to call it correctly: filter semantics, default sort, and the limit ceiling. It stops short of describing return shape or how to page past the 50-item cap, which matters at this result limit.

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 only 11% (effectively just workspaceId), so the description must carry the load, and it does map most parameters to readable concepts: type, status, due window, linked record, 'mine', and the limit ceiling. It omits sortDirection's role (only its default effect is implied) and the multi-workspace requirement for workspaceId.

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 ('Lists tasks, calls, meetings and emails'), and the four-type enumeration crisply defines what an 'activity' is, which separates it from list_records. It adds a scope qualifier ('you may view'), but never names a sibling tool (get_activity, get_timeline, search) it should be preferred over, so it stops short of full sibling differentiation.

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 gives explicit context for use: it enumerates the available filter dimensions (type, status, due window, linked record, 'mine') and notes the 'mine' filter means assigned to you. It does not state when to prefer this over get_activity for a single item or search for cross-object queries, so no exclusions are offered.

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