set_status

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

With no annotations, the description carries the full burden and does disclose real behavior: the status is broadcast to everyone in the session, the status string is capped at 200 bytes, and the target defaults to the current session. It omits whether a call overwrites a previous status, whether an active session/join_session is required, and whether phase changes have side effects beyond visibility.

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?

Two short sentences, front-loaded with the verb and the controlled fields, with the example and byte limit placed after. Nothing is padding, though the parenthetical phase gloss is a bit garbled and costs some clarity.

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 three-parameter, one-required mutation tool with no annotations and no output schema, the description covers purpose, visibility, the size limit, and the default session scope. It still leaves unanswered whether joining a session is a prerequisite and what happens to a previously set status, which an agent would want before calling it.

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 only 33% (only 'session' is documented in-schema), so the description must compensate, and it does: it glosses the phase enum values and adds a constraint absent from the schema (status is a one-line string, max 200 bytes) plus a concrete example. The parenthetical '("waiting" for work or "working")' is slightly ambiguous about what 'waiting' means (idle vs awaiting a task), which keeps it from a 5.

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?

The description uses a specific verb ('Set') and names both resources it controls: the phase and a one-line status visible to the session. That is enough for an agent to distinguish it from read-oriented siblings such as session_info or session_events, though it never explicitly contrasts itself with them.

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 only implied: the phrase 'everyone in the session sees' hints that this is a broadcast of current activity, and the example suggests calling it when starting a task. There is no explicit statement of when to call it, when not to, or how it relates to alternatives like session_info.

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