design_live_note

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

With no annotations, the description carries the behavioral burden well: it says the entry appears in the Layout tab newest-first, that the user can see and stop the described action, and that empty text returns an error. It does not cover whether notes can be edited or deleted, but the key side effect and error behavior are disclosed.

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?

The description is front-loaded with the core instruction and timing, then adds useful UI context, calling convention, parameter definitions, and return behavior. Every sentence supports correct invocation, and the structure mirrors the agent's decision process.

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 two-parameter logging tool with no annotations, the definition is nearly complete: it explains purpose, timing, side effect, parameter meaning, return shape, and error condition. The main missing context is sibling differentiation among the live-view/session tools, which leaves some routing ambiguity.

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 0%, so the description must carry parameter meaning, and it does: section is defined as a short label such as placement, routing, rules, or a block name; text is defined as the decision plus its reason. Both parameters are required and both are explained with format guidance.

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 states a specific verb and resource: "Log a decision to the live view." It is clear what the tool does and when in the workflow it applies, but it does not explicitly distinguish itself from nearby siblings such as design_live_view or design_live_snapshot.

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 gives strong usage timing: call it BEFORE the step it describes, one decision per call, with a sentence or two explaining what will be done and why. It does not name alternate tools or state when not to use this one, so it stops short of full alternative routing.

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