message_status

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

With no annotations, the description carries the full load and does so: it discloses atomic all-or-nothing failure on any ineligible id, that the error does not identify the offending id, that results are deduplicated and returned in the requested order, and that recipient names are resolved as of send time. It also states the operation is non-mutating.

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, leading with the core verb and result shape before edge cases. It is a long multi-clause sentence, but nearly every clause conveys a distinct constraint; only the parenthetical about removed recipients is arguably over-detailed.

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?

No output schema exists, so the description must define the return value, and it does field by field, including the null case and the reason a person-addressed message stays unread. The failure mode and ordering guarantees complete what an agent needs to call and interpret it correctly.

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% and the single parameter is already documented, so the schema does the heavy lifting. The description still adds real meaning: the ids must come from send_message, the 1–200 bound is behavioral (not per-item), and a single invalid id fails the entire call.

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: report whether messages you sent have been read, with the exact return fields (id, to, read, readAt). It also scopes the inputs to ids returned by send_message, which separates it cleanly from read_inbox and read_conversation in the sibling list.

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 preconditions ('Requires register first') and eligibility bounds ('only messages sent under your name since you registered it, to an agent or person of your account'). It also clarifies 'Marks nothing read', implicitly contrasting with read_inbox, though it never names the alternative tool explicitly.

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