open_message_log

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

Goes well beyond the annotations by disclosing side effects and failure modes: the listing is created empty if it does not exist, 'opened' only means the request was made, and nothing shows without an editor UI. It also explains what 'module_available' reports, which an agent could not infer from the schema.

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?

Front-loaded with the action and free of padding; the Returns block is warranted because there is no output schema. Slightly dense with clause-stacked sentences ('creating the listing empty when it does not exist yet and enabling message log display'), but every sentence carries information.

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?

Despite no output schema, the return fields are enumerated and their meaning explained, plus the no-UI caveat and data-vs-window distinction. There is no gap an agent would need to resolve before calling this tool.

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% and already documents log_name and its 'PIE' default, so the baseline is 3. The description adds real meaning about the parameter's side effect (the named listing is created empty when absent), earning a step above baseline.

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 ('Open or focus the editor Message Log window on one listing') and immediately bounds the scope ('PIE by default', 'no message is changed'). It is unambiguously distinguishable from the read/write siblings it names.

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?

Explicitly routes the agent to alternatives: read via get_message_log_entries, add via add_message_log_entry, empty via clear_message_log, and clarifies this tool operates on the window rather than the data. When-to-use and when-not-to-use are both stated.

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