ic_list_messages

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

Annotations declare readOnlyHint and openWorldHint, and the description goes well beyond them: per-section degradation on error, the fact that `limit` governs only the high-volume prism source, the read-tracking caveat, and an explicit untrusted-content warning. These are behavioral traits an agent cannot get from the structured fields.

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?

Dense but front-loaded: the source enumeration comes first, followed by error behavior, the limit scoping, the read caveat, and the safety warning. Every clause carries information, though the limit/read sentences could be tightened without loss.

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 takes on the burden of describing the return shape ('each section has its own count and items', error field isolation) and does so. For a three-source aggregator with open-world annotations, nothing essential is missing.

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 `limit` and `view` are already documented in the schema, and the description's limit statement largely duplicates it. `district` has no description in either place, and the description adds no new semantics for the enum. This lands at the baseline for partially-covered parameters.

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 ('List all parent-visible messages') and enumerates the exact three sources it aggregates (prism notifications, Messenger 2.0 inbox, portal userNotice). It distinguishes itself from the sibling ic_get_message by pointing at it for full HTML bodies, so an agent can route without opening 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?

Gives clear routing guidance: use ic_get_message for the full HTML body, and use this tool for the combined listing. The note on read-tracking behavior adds useful context. It does not explicitly enumerate when *not* to use it (e.g., for attachments or documents, which other siblings cover), so it stops short of full alternative coverage.

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