Mark Relay Chat Read

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

Annotations already convey that the call is a mutation (readOnlyHint=false), idempotent (idempotentHint=true), and non-destructive. The description adds that read state is scoped to the Agent and to the visible chat, which is useful context beyond the schema. It does not describe side effects like unread-count updates, but the annotation set lowers the bar.

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?

One sentence, front-loaded with the action and object, and no filler. The phrase 'by the Agent' is mostly redundant with the tool title but not harmful. It earns a strong conciseness score despite semantic vagueness.

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 one-parameter, idempotent, non-destructive tool, the core operation is simple and annotations carry safety. However, the missing link between the described 'visible chat' and the required chat_id, plus the lack of any usage trigger, keeps it from being fully complete. It is minimally adequate rather than thorough.

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 0%, so the description should explain the chat_id parameter, but it never mentions chat_id or how the 'visible Relay Chat' maps to it. The single uuid parameter is self-naming, so an agent can guess, but the description adds no semantic value. This is a clear gap.

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?

Names a specific action (mark as read), a resource (Relay Chat), and an owner/scope (by the Agent), which distinguishes it from sibling tools like relay_list_chats or relay_send_message. The qualifier 'visible' is not defined, so it does not fully specify which chat beyond the required chat_id. Still clearly more than a tautology.

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?

Description provides no explicit when-to-use or when-not-to-use guidance, nor does it name an alternative or mention prerequisites such as the chat being open/visible. The need to mark read after viewing is only implied by the verb phrase. This leaves the agent to infer the trigger condition.

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