midi_session

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

With no annotations, the description carries full responsibility for behavioral disclosure. It lists commands like 'undo' and 'redo' which imply state changes, but it does not explain side effects, persistence semantics, error behavior, or any side effects beyond naming the actions. The behavior is largely opaque.

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 very short and to the point, listing commands in a compact format. It is front-loaded with 'Session:' which sets the context. The structure is somewhat unstructured as a free-form string, but it contains no fluff and every word contributes to the set of examples.

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 having only one parameter and no output schema, the description is still too minimal. It does not explain what the tool returns, whether commands are executed sequentially, what 'checkpoint' does, or what constitutes valid input. For a session management tool, the description lacks essential operational context.

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?

The single 'action' parameter has no schema description and no enum, but the description partially compensates by providing concrete example values (e.g., 'new "Title"', 'open ./file'). This gives the agent some sense of expected syntax, though the format is ambiguous (mixing quotes, spaces, and version strings) and not all actions are equally explained.

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 implies session management through a list of example commands ('new', 'open', 'save', etc.), but it never explicitly states the tool's purpose as a verb+resource (e.g., 'Manage MIDI sessions'). It is more of a usage hint than a clear functional definition, and it does not explicitly distinguish itself from sibling tools like 'midi' or 'midi_query'.

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?

No guidance is provided on when to use this tool versus alternatives. The sibling tools are not mentioned, and there is no description of scenarios suitable for session operations. The examples imply actions, but no context or exclusion criteria are given.

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