Set how the bot looks in rooms

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

With no annotations, the description carries the full burden and does so convincingly: persistence across restarts, that a name change restarts the bot, that new pictures apply only to rooms joined from now on, and that a name change is refused mid-room. Missing only what the call returns and how clear_picture interacts with picture_path.

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?

Four tight sentences, front-loaded with the core effect and then the constraints. The final environment-variable sentence is dense but genuinely load-bearing; the only minor cost is the run-on feel of the first sentence.

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 mutation tool with zero annotations and no output schema, the description covers persistence, restart side effects, the room precondition, file constraints, and restart-time overrides. Minor gaps remain around zero-argument calls and argument conflict handling.

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, but the description adds real information beyond the schema: accepted image formats, the 256 KB limit, and the environment-variable precedence that governs these fields. clear_picture's semantics are still only conveyed by the schema, keeping it below 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 names the exact verb and both resources it mutates — the bot's display name and its avatar picture — plus the accepted file formats and size ceiling. Nothing else in the sibling list touches bot appearance, so an agent can distinguish it immediately without opening the schema.

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?

It supplies a real precondition (the change is refused while the bot is in a room) and routes the agent to end_meeting first, and it flags that GIFOS_BOT_NAME / GIFOS_BOT_PICTURE override these values at next start. That covers when-not and precedence well, though it doesn't discuss calling it with no arguments or the relationship between picture_path and clear_picture.

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