update_chat

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description does add one genuine behavioral fact beyond them — the settings are synchronisés sur tous mes appareils — but it never states whether omitted fields are left unchanged, which is the central behavioral question for a 6-field partial-update tool.

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?

A single front-loaded sentence listing the target resource first and the settable operations second, with no filler. It is appropriately sized; the only structural weakness is that a noun phrase rather than a verb leads, and the list is separated by colons/commas rather than tied to the parameter names.

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?

An output schema exists, so return values need not be explained, and annotations carry the safety profile, which lowers the burden. Still, for a 6-parameter mutation with 33% schema coverage, the description omits what chat refers to, what account controls, and whether this is a partial or full replacement update — an agent could call it correctly only by guessing.

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 33% (only mute and unread carry descriptions), so the description should compensate more than it does. It does name four of the six fields — archive, pin, mute, unread — which maps them to user-facing actions, but it says nothing about the required chat identifier or the account parameter, and adds no value semantics beyond the names.

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?

It names the resource (une discussion) and enumerates the operations available — archiver, épingler, mettre en sourdine, marquer comme lu/non lu — so an agent knows this is the chat-settings mutation, not a message or group operation. It does not, however, distinguish itself from the overlapping sibling mark_read, which also flips read/unread state.

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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives. The overlap with mark_read (and, for archived/pinned metadata, with list_chats filtering) is left entirely to inference, which is risky for an agent choosing between these siblings.

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