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

Annotations already flag destructiveHint=true, idempotentHint=false and openWorldHint=true, so the description's job is to add context—and it does: the status persists until expiry or until someone else changes it, and it changes chat routing. That persistence/overwrite semantics is exactly the behavior an agent needs to reason about the non-idempotent, destructive hints. It does not, however, say what happens to already-assigned chats or whether the call returns anything.

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 short sentences, front-loaded with the action and the value examples, then the expiry rules. The sentence about the status staying in effect is slightly redundant with the ttl/valid_until framing but still carries the distinct point that others can override it.

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 4-parameter mutation with annotations covering the risk profile and full schema coverage on parameters, this is nearly complete—it explains timing, exclusivity, persistence and side effects. The remaining gap is what happens to in-flight chat assignment and whether anything is returned, which matters mildly given there is no output 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 the baseline is 3; the description earns above baseline by adding the mutual-exclusivity constraint ("give exactly one of the two") that the schema does not encode—there is no oneOf in the input schema. It also cross-references chaport_list_operators for valid status names and operator ids, which the schema descriptions only partially do.

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+resource ("Set an operator's status") with concrete value examples (online, away, offline) and even names the endpoint POST /operators/{operatorId}/status. No sibling tool performs status changes, so the agent can distinguish it immediately from list/get/update tools in the same family.

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?

Usage is implied rather than stated: the description explains the effect ("Changes who gets new chats") and the exactly-one-of rule for the two timing parameters, but never says when an agent should prefer this over, say, sending a message or leaving the operator untouched. Since no true alternative exists in the sibling set, the implicit guidance is probably sufficient, but it is not explicit.

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