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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description adds useful behavior beyond that — result ordering ('newest first'), the enrichment of contact-scoped results with role (source, target, assignee), and the underlying API surface (ActivityContact.get / Activity.get). It does not discuss pagination semantics, but the schema's offset description already points at next_offset.

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 with zero filler: result shape first, the contact_id branch second, the default branch and its filters last, with the API reference as a trailing footnote. Front-loaded and appropriately sized.

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 carries the burden of describing returns and does so (field list, ordering, role). For a 7-parameter read-only list tool this is close to complete; only pagination/result-size expectations are left entirely to the schema.

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%, so baseline would be 3; the description goes beyond it by explaining that contact_id switches the query to a contact-participation view and adds a returned role field, and that activity_type/status act as optional narrowing filters only in the non-contact case. That is genuine semantic value the schema's per-field descriptions do not convey.

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 the specific resource (activities: meetings, phone calls, e-mails, follow-ups) and what each record carries (type, subject, status, date, details), plus the ordering ('newest first'). The two-branch structure (with contact_id vs. without) makes it distinguishable from sibling list tools like civicrm_list_events or civicrm_list_cases.

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?

Explicitly describes the two usage modes: 'With contact_id: the activities that contact took part in, with their role ... Otherwise all activities, optionally of one type or status.' That is clear conditional guidance for choosing parameter combinations, but it names no alternative sibling tool (e.g., civicrm_query for arbitrary filters) and gives no exclusions.

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