改段・改ページを入れる/外す

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

With no annotations, the description carries the full burden: it discloses that existing breaks on the measure are replaced (an overwrite/destructive trait), that the operation runs through the headless MuseScore API, and that it produces a new version rather than mutating in place. It also warns that 1-based measure indices can diverge from displayed numbering. It does not mention error conditions (bad score_id, measure out of range) or whether score_save is still needed.

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 purpose, then the kind table, then replacement/new-version behavior, then the numbering caveat — a sensible order with no filler sentences. The trailing parenthetical on measure numbering is long and nested, slightly hurting scanability, but each clause conveys operational 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?

For an unannotated mutation tool with no output schema, the description covers what changes (breaks replaced), the side effect (new version created), the execution environment (headless API), and the indexing convention with a way to verify it. Remaining gaps — failure modes and whether the result must be saved via score_save — are minor but real.

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 only 33% (only score_id is documented in the schema), so the description must compensate, and it does: every kind enum value is defined in prose, and measures is explained as 1-based sequential ordering from the top of the score, including the pickup/anacrusis and skipped-number caveat plus the layout_inspect cross-reference. This adds real meaning beyond the integer-array schema.

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 and resource: insert a break at the end of the specified measures, with 'none' explicitly removing it. The five kind values (line/page/section/nobreak/none) make the scope unambiguous, and the title reinforces the insert/remove duality. An agent can distinguish this from layout_set_stretch or layout_fit_pages purely from the description.

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 enumeration of kind values effectively tells the agent which mode to pick for each intent (line break, page break, section break, keep measures together, remove break). It also points to layout_inspect's measures[].index / no for resolving numbering, which is a concrete usage prerequisite. It never states when *not* to use it versus the other layout_* siblings, so it stops just short of a 5.

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