insert_notes

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses that the insertion is one undo step, returns a snapshot of all notes overlapping the inserted range with fresh indices, and explains the start-position chaining rule. This gives the agent important operational insight beyond the schema, though failure modes or permission requirements are not mentioned.

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 four sentences, each with a specific purpose: core action, note requirements and start behavior, undo step, and lyric conventions. It is front-loaded with the main purpose and then provides necessary detail without redundancy. No filler or tautology.

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?

Given the tool's complexity (nested notes array, optional start chaining, language-specific lyrics) and no output schema, the description covers the essential behaviors: what is inserted, how positioning works, lyric rules, undo grouping, and the return snapshot. It omits mention of the `group` parameter, but the schema explains its default and purpose. Overall, the description is complete enough for an agent to invoke the tool correctly without relying on external documentation.

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 input schema covers 100% of parameters, but the description adds significant meaning beyond the schema. It explains that omitting `start` chains notes sequentially and that the first note must have an explicit start, and it details lyric conventions (one kana per note, '-' for vowel extension, '+' for multi-syllable English). This enriches the `lyrics` and `start` parameters beyond their schema descriptions. The `group` parameter is not mentioned in the description, but its schema description is sufficiently clear.

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 opens with a specific verb and resource: "Insert notes into a track (1-based index) of the current Synthesizer V Studio project." This clearly distinguishes the tool from siblings like update_notes, delete_notes, and get_notes. It also gives the core action and context in one sentence.

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?

The description provides clear usage context: required note fields, the behavior of omitted start positions, and detailed lyric conventions (Japanese kana, '-' for vowel extension, '+' for English word continuation). While it doesn't explicitly name alternatives like update_notes, the guidance is specific and actionable for inserting notes. No exclusions are stated, but the context makes the use case clear.

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