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

The description discloses rich behavioral detail beyond the minimal annotations: note input is always exited even on error, success only means command acceptance (kOK), can_undo is not verification, and Dorico's overwrite mode can replace existing music rather than push it along. These are exactly the kinds of caveats that prevent an agent from misinterpreting results.

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 action and then organized into Returns and Note sections. It is longer than average, but nearly every sentence adds essential caveats or guidance; only minor redundancy exists around verification, so it earns a strong score rather than a perfect one.

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 tool with a small schema, providing output schema, and meaningful behavioral caveats, the description covers everything an agent needs: what the tool does, what repeated calls do, how overwrite mode affects results, how to verify placement, and what success does and does not mean. It also anticipates the can_undo misconception.

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 100%, so the schema already fully documents notes, as_chord, and duration with examples, defaults, and allowed values. The description adds little parameter-specific meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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 opening sentence states a specific verb and resource: 'Input notes at the caret, then leave note-input mode cleanly.' It clearly distinguishes itself from sequence-oriented siblings by explicitly directing users to write_score / render_to_dorico for a sequence of notes or chords, and clarifies that repeated add_notes calls do not chain.

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 gives explicit when-to-use guidance: use for a single insertion at the caret, use write_score / render_to_dorico for sequences over time. It also warns that repeated calls stack on the same beat, and provides practical direction to read displaces_existing and get_status beforehand, which is far beyond a vague 'use when adding notes.'

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

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

Annotations are minimal, so the description carries the behavioral burden. It discloses that note-input mode is always exited even on failure, that success means Dorico accepted the command rather than the rest being effective, that calls do not chain, and that can_undo is set merely by entering note input. No contradiction with annotations.

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 well-structured with a front-loaded summary, a Returns section, and a Note section. There is minor redundancy between the first and second paragraphs, but the additional detail about failure behavior, result fields, and non-chaining justifies the length.

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?

The description covers the tool's side effects, acceptance semantics, alternatives, required navigation, and common pitfall with can_undo. With an output schema present and annotations available, nothing essential is missing for an agent to call this tool correctly.

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 parameter `duration` is fully documented in the input schema with accepted values and a default, so 100% schema coverage means the description does not need to repeat parameter details. The description adds behavioral context about the caret advancing by that duration, but this is not required for parameter understanding.

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: 'Input one rest at the caret, then leave note-input mode cleanly.' It clearly distinguishes from related tools by emphasizing a single rest and directing passage-level work to write_score.

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?

Usage context is explicit: one rest at the current caret, and for a passage the description directs the agent to put rest events in a ScoreSpec and use write_score instead. It also tells the agent to use goto_bar first and warns not to read can_undo as evidence.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds valuable behavioral detail: the analysis is entirely offline and does not involve Dorico, the return value is a result dictionary with key estimate, confidence, and Roman numerals, and key estimation relies on pitch distribution with a caveat for short or chromatic excerpts. This goes well beyond what annotations convey.

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 purpose, then uses short labeled sections for returns and notes. Every sentence adds information: offline behavior, output contents, a limitation, and sibling routing. There is no filler or repetition of schema details.

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 single-parameter, read-only analysis tool with a rich output schema, the description is complete. It covers the operation, the execution context, the result shape, a known limitation, and alternatives. The agent has everything needed to decide when to call it and what to expect.

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 100% and there is only one parameter. The schema already explains the score parameter thoroughly as a ScoreSpec object and even points to score_schema for the exact shape. The description merely refers to 'ScoreSpec,' so it adds no new parameter meaning beyond the 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?

The description opens with a specific verb and resource: 'Estimate the key of a ScoreSpec and name its chords in Roman numerals.' This clearly identifies the operation, the input, and the output. It also positions the tool against siblings by saying 'This answers what the harmony is,' which helps distinguish it from related analysis tools.

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 gives explicit when-to-use guidance: it answers what the harmony is, and it names the alternatives for related questions (check_voice_leading for voice movement, check_counterpoint for strict two-part writing, suggest_next_chord for what could come next). It also clarifies that the tool works offline and on music never in a project, giving clear context for when this tool is appropriate.

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

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

Annotations already establish read-only, idempotent, and non-destructive behavior, and the description reinforces this with 'Entirely offline and read-only.' It adds valuable behavioral detail beyond annotations: the strict rule set enforced, the refusal of unsupported species, and the result format with an empty list meaning success. These details let an agent predict tool behavior without calling it.

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 well organized: a one-sentence summary, a read-only/offline note, the rule list, return semantics, and caveats. Every sentence adds useful information, and the most important scoping facts are front-loaded. No filler or repetition.

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?

The tool checks a specialized music-theory concept, but the description covers scope, restrictions, failure modes, return value semantics, and alternatives. Combined with the rich input schema and output schema, an agent has everything needed to decide whether and how to invoke it correctly.

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%, so the schema already documents all three parameters with types and examples. The description reinforces the same-length and one-to-one pairing constraints, but those are also present in the schema. It does not add substantial new parameter-level meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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: 'Check a two-part first-species counterpoint against the classic rules.' This immediately distinguishes the tool from the sibling check_voice_leading by narrowing scope to two-part first-species counterpoint. The listed rules further clarify exactly what the tool checks.

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 gives explicit usage conditions: only first species is implemented, other species are refused, and the two lines must be the same length. It also names the alternative tool, check_voice_leading, and states when to use that instead ('for a chorale or a quartet'). This is exemplary guidance for an agent deciding between sibling tools.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description goes further by stating the tool is 'entirely offline and read-only,' that 'nothing in the score is changed,' and that 'findings are advice and nothing here rewrites the music.' It also discloses that common-practice rules mean intentionally broken passages are still reported. This adds meaningful behavioral context beyond the annotations without contradicting them.

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 well-structured with clear sections: a front-loaded purpose statement, an offline/read-only note, a concise Returns section, and a Note with rule-scope and alternative routing. Every sentence adds value; there is no filler or repetition of schema 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 a read-only analysis tool with a single well-documented parameter, an output schema, and annotations covering safety, the description is complete. It explains what the return value means, covers edge behavior (purposeful rule-breaking), and routes the agent to the correct sibling tools. Nothing needed for correct selection or invocation is missing.

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 100%, with the single 'score' parameter fully described as a ScoreSpec object and with a pointer to score_schema for exact shape. The tool description reinforces that the input is a ScoreSpec but does not add substantial parameter semantics beyond the schema. Baseline 3 is appropriate since the schema carries the descriptive load.

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: 'Audit a ScoreSpec for parallel fifths and octaves, overlaps and spacing.' It clearly identifies the tool's purpose and distinguishes it from related siblings like check_counterpoint and analyze_harmony by naming exactly what this tool checks.

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 explicit guidance on when to use this tool: for part-writing of any number of voices, with chorales or string quartets as natural inputs. It also gives two concrete alternatives: check_counterpoint for strict two-part species exercises and analyze_harmony for chordal analysis rather than voice movement. This is exemplary usage routing.

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

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

Although annotations already declare readOnlyHint and idempotentHint, the description adds critical behavioral context: the first connection triggers an authorization prompt that requires human action, and the token persists in AppData for later connections. This goes well beyond what annotations provide and helps the agent anticipate a potentially blocking interaction.

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 purpose and usage rule, then provides Returns and Note sections that each earn their place. The authorization caveat and get_status alternative are directly useful; there is no filler.

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 zero-parameter tool with annotations covering safety and idempotence, the description is complete. It explains the human-in-the-loop authorization behavior, token persistence, what the function returns, and when to use a sibling tool instead. The output schema already covers return values, so no additional detail is needed.

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 tool has zero parameters and the schema has 100% coverage with no required fields, so the baseline is 4. The description doesn't need to add parameter semantics because there are none to explain.

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 uses a specific verb and resource: 'Connect to Dorico Remote Control and return application status.' It clearly differentiates itself from get_status by explaining that get_status should be used afterwards to re-read the state without reconnecting.

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 explicitly says 'Call this before anything else here' and notes that every other Dorico tool needs the session this opens. It also provides an alternative: 'Use get_status afterwards to re-read the state without reconnecting,' and states that re-calling is safe on an open connection.

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

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

The annotations already mark the tool as destructive, and the description reinforces this by stating that a specified path is overwritten without confirmation. It also adds valuable behavioral context beyond annotations: entirely offline, no connection opened, Dorico need not be running, and musical elements survive the round trip.

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 well-structured and front-loaded with the core purpose; the offline behavior, return value, overwrite warning, and alternative tools each have a clear and compact section. No sentence is wasted, and the formatting makes the key warning and routing advice easy to scan.

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 annotations and output schema, the description is complete enough for an agent to call the tool safely: it covers destructive behavior, path handling, offline operation, return result shape, and how to get the file back into Dorico or produce a printable output. Nothing critical is missing.

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 100%, so the schema already documents both path and score thoroughly. The description adds little new parameter-level meaning beyond restating that a specified path is overwritten and that omission writes to a temporary file, which the schema also states. Baseline 3 is appropriate.

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 opening sentence states a specific verb and resource: 'Write a ScoreSpec to a MusicXML file on disk, without Dorico.' It also distinguishes this from export_pdf and write_score by naming them as alternatives with different purposes, so the agent can tell the tools apart immediately.

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 gives clear routing guidance: import_musicxml opens the file into Dorico later, write_score(method='musicxml') does both steps in one call, and export_pdf is for printable rather than interchange files. It also explains the offline/no-Dorico context, which is a strong signal for when this tool is the right choice.

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

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

Even with annotations present, the description adds substantial behavioral context: the file is written next to the .dorico project, kOK does not guarantee file existence, commands run on the UI thread and can queue behind modal dialogs, and the all_layouts path is untested. It also discloses the tested version. This goes far beyond the annotations.

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 moderately long but every sentence contributes: core purpose first, then side-effect location, alternative exclusion, return semantics, asynchronous caveat, version testing, and unverified-path warning. Nothing is redundant or filler.

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 tool with one optional boolean parameter and an output schema, the description covers purpose, side effects, failure modes, testing status, and routing to the sibling export_musicxml. An agent has everything needed to decide when to call it and what to verify afterward.

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 already fully documents the single all_layouts parameter, including which underlying command each value triggers. The description adds valuable caveats about the all_layouts path being untested and the need to check the filesystem, which enriches the parameter's meaning beyond the 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?

The description states a specific verb and resource: 'Export the score to PDF unattended without opening a dialog.' It clearly distinguishes itself from File.Export and from export_musicxml by contrasting unattended PDF export with the modal dialog path and with interchange-format export.

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 explicitly explains when to use this tool: for unattended PDF export, not via File.Export, and not for interchange formats, which should use export_musicxml. It also warns that all_layouts is unverified, guiding the agent to prefer the verified current-layout path.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds valuable behavior: the status is an accumulated snapshot of pushed deltas, reading it costs nothing, and no command needs to be sent. It also clarifies the kOK acceptance-vs-effect protocol distinction.

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 primary purpose is front-loaded and each section adds meaningful context. The Returns and Note sections are slightly extended but every sentence contributes to correct usage, so it avoids unnecessary padding.

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 zero-parameter read-only snapshot tool with an output schema, the description is complete: it states what is returned, why it is cheap, when to use it, and what it is not for. There is no missing information an agent would need to invoke it correctly.

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 tool has no parameters, so the baseline is 4. The description adds no parameter-specific details, but none are needed since the input schema is empty and schema description coverage is 100%.

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 precise verb and resource: 'Return Dorico's current pushed application status snapshot.' It then specifies what the snapshot contains (mode, note input, selection, undo availability), which clearly distinguishes it from related tools like read_selection.

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 explicitly explains when to use this tool: to verify whether a command that returned kOK actually took effect. It also directs users to read_selection when they need properties of selected notes rather than application state, providing a clear alternative.

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

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

The annotations are all false/unspecified, so the description carries the disclosure burden. It is transparent about dead-reckoning, drift from reality, inability to detect drift, entering note input, and landing one bar short without the pickup flag. This fully reveals the tool's behavioral quirks.

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 long but every paragraph earns its place: caveat, usage routing, pickup trap, and performance characteristic. It is front-loaded with the core purpose and returns, then structured into clearly labeled notes. 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, the description is complete: it covers side effects, prerequisites for sequence usage, alternatives, failure modes, and the pickup edge case. An output schema exists for the return value, so the brief 'Returns' note plus schema is sufficient.

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%, so the baseline is 3; the description adds value by explaining why pickup matters, reinforcing that bars count from 1 while staves count from 0, and advising how to resolve pickup uncertainty. It does not deeply elaborate every parameter, but it goes beyond the schema where it matters most.

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 begins with a specific verb and resource ('Move the caret to a bar') and immediately clarifies that the position is guessed rather than read. It also distinguishes itself from navigate, which scrolls without touching the caret.

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 states when this is the right call: before add_notes or add_rest because it enters note input. It also names the alternative for pure scrolling ('use navigate') and warns about the pickup-bar situation with guidance to ask the user or check via read_score.

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

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

The description discloses important non-obvious behaviors: the import creates a new flow rather than joining the current one, Dorico may raise a player assignment prompt that waits for a person, and later commands may sit unexecuted in the queue while that prompt is open. These details go well beyond the annotations and help an agent anticipate blocking and side effects.

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 well-structured with a clear first sentence, a Returns section, and a Note section. It is longer than simplest definitions, but each section earns its place by covering return fields, behavioral caveats, and alternatives. The formatting makes the extra detail easy to scan.

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 single parameter, the presence of an output schema, and the annotation set, the description covers all important contextual aspects: behavior, return shape, blocking modal risk, queue effects, and alternative tools. Nothing critical for selecting or invoking the tool correctly is missing.

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?

There is only one parameter, path, and the schema already provides a full description: it is a filesystem path, Dorico reads it from disk, and it must be reachable by Dorico. The tool description does not add further parameter-specific meaning, but with 100% schema description coverage, the baseline of 3 is appropriate.

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 clearly states a specific action and resource: 'Import a MusicXML file into Dorico via the Remote Control API.' It also names the underlying mechanism, 'Dispatches File.Open with MusicXMLImportFilter,' and distinguishes the tool from write_score and export_musicxml by describing what each alternative does.

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 gives explicit routing guidance: use write_score(method="caret") to add music into an already-open flow, use export_musicxml to produce the file, and use write_score(method="musicxml") to do both steps in one call. It also warns about the modal dialog behavior and queued commands, giving the agent a clear context for when this tool is appropriate.

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

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

The annotations already declare readOnly, idempotent, and non-destructive behavior, so the description's added value is strong: it clarifies that the ranges are standard written ranges for a competent player, not instrument limits, and that professionals exceed them while beginners do not. It also explicitly states the operation is offline and read-only, reinforcing the safety profile with context.

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 well-structured and front-loaded: a one-paragraph summary of the tool's dual behavior, followed by concise 'Returns' and 'Note' sections. Every sentence contributes useful information, and the relationship to write_score is positioned at the end where it naturally supports usage decisions.

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 rich input schema, output schema, and thorough annotations, the description covers the remaining context needed: the two possible outcomes, the caveat about standard written ranges, and the link to write_score preflight. Nothing critical is missing for an agent to select and invoke the tool correctly.

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 already documents both parameters with examples and descriptions, so the baseline is 3. The description adds some behavioral color about 'without a pitch' versus 'with one,' but most parameter-level meaning is already present in the schema. It does not substantially extend the parameter documentation.

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 action ('Look up a standard instrument compass, or test one pitch against it'), clearly identifying both the resource and the two modes of the tool. It distinguishes itself from siblings like write_score by framing itself as a standalone range-check tool rather than a score-writing or transformation operation.

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 explicitly states when to use the tool ('Worth calling before write_score when writing for an instrument') and contrasts it with write_score, which runs the same check over a whole score. It also explains the conditional behavior depending on whether a pitch is supplied, giving the agent clear decision criteria.

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

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

The description goes beyond the annotations by disclosing exactly what side effects occur: it moves on-screen content via View.MoveViewportTo*, leaves the caret untouched, and makes no music changes. It also states the return behavior, including the redirect case for target='bar'.

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 well-structured with a front-loaded summary, a returns section, and a usage note. It is slightly longer than strictly necessary because the schema already covers parameter semantics, but every sentence adds meaningful behavioral or routing context.

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 2-parameter tool with 100% schema coverage, an output schema, and annotations, the description fully covers what the tool does, when to avoid it, what it returns, and how target='bar' is handled. Nothing essential is missing for an agent to invoke it correctly.

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 schema already fully describes both parameters, including the conditional behavior of 'bar' and the 'read only when target is bar' semantics. The description adds context by framing 'bar' as a redirect to goto_bar and explaining the rationale, which enriches the schema's documentation.

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: 'Scroll the score viewport to the start or end of the flow.' It clearly distinguishes navigate from goto_bar, stating that navigate only affects the viewport while leaving the caret in place.

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 explicitly instructs when not to use this tool: 'Use goto_bar instead to put the caret somewhere, which is what note entry needs.' It also explains that a target of 'bar' redirects to goto_bar rather than performing a partial viewport scroll, giving the agent clear decision criteria.

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

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

Annotations are all false or unhelpful, but the description discloses rich behavioral detail: the popover cannot be populated directly, the command stops after opening, it returns typing instructions, requires user interaction, and leaves the system in a state where later commands may be unsafe. This is far beyond minimal disclosure and directly informs invocation.

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 well-structured with a clear summary, return explanation, and a safety note. Every section earns its place, and the critical behavioral warning is separated and emphasized rather than buried.

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 interactive tool with no useful annotations, the description covers what the tool does, what it returns, what it cannot do, when not to use it, and what operational risks exist. The output schema exists, and the description appropriately explains return semantics rather than repeating schema structure.

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 100%, and each parameter already has a detailed description including counting conventions and defaults. The tool description adds some contextual color about the popover kind mapping to NoteInput.Create* commands, but it does not substantially add meaning beyond the schema for individual parameters, so the baseline of 3 is appropriate.

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: 'Open an input popover at the caret for manual text entry.' It clearly distinguishes itself from siblings by stating that unattended writes should go through write_score instead, so an agent can tell this interactive popover tool apart from the ScoreSpec-based tools.

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 explicitly tells when to use this tool versus alternatives: it is for manual, interactive entry, and it names write_score as the route for unattended writes, including which markings map to ScoreSpec fields. It also warns about the need for user interaction and about unsafe conditions while the popover waits, giving clear situational guidance.

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

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

Beyond the readOnly/destructive/idempotent hints, the description discloses the bounded side-effect surface ('no note, dynamic or layout changes'), the audible side effect ('It makes sound'), and the semantics of the Result dictionary ('reporting whether the transport command was accepted'). It even adds the important acceptance-vs-effect nuance around kOK, which is valuable for an agent.

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 core action and constraints are front-loaded, the Returns note is separated, and the following Note earns its place by explaining user-visible side effects and sibling routing. No redundancy or filler.

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-optional-parameter transport tool with an output schema, the description covers purpose, safety boundaries, return semantics, audible side effects, and alternatives. An agent has everything needed to invoke it correctly.

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 schema already fully documents both parameters with 100% coverage, so the description adds little parameter-level meaning; 'start, stop or rewind' merely restates the action enum. The baseline 3 applies because the description does not need to compensate for schema gaps.

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 action set ('Start, stop or rewind Dorico playback') and scopes the tool to 'Transport only', explicitly disclaiming note, dynamic, or layout changes. It further distinguishes itself by naming navigate and goto_bar as non-audible alternatives, so an agent can pick the right sibling without guessing.

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 explicitly names the alternatives: 'Use navigate to scroll the score without playing, and goto_bar to move the caret', and states that neither moves the playhead. It also gives a concrete reason to prefer playback — 'the one way to hear whether a write landed' — making the when-to-use decision explicit.

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

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

Goes well beyond the annotations by disclosing that Dorico opens a modal confirmation dialog, that the tool triggers an export and waits for a file, and that the result is a snapshot which may be stale after edits. This is important behavioral context the agent would otherwise have no way to know.

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 purpose, followed by a clear returns section and a focused note. Every sentence earns its place, and the modal-dialog caveat is appropriately separated from the main purpose.

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?

Covers what the tool does, why it matters, what it returns, how the dialog interaction works, and how stale results should be handled. With a detailed input schema and output schema present, nothing an agent needs to call this correctly is missing.

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%, so the baseline is 3. The description mostly reinforces the schema's parameter meanings rather than adding new parameter-specific detail, though the note about the export dialog and one-key setup does enrich the context around `export_dir` and `trigger`.

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: 'Read the whole open score back by way of a MusicXML export.' It also distinguishes itself from selection-scoped reads by explaining that Remote API reads see only the selection, making this the only route to the full score contents.

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 positions the tool as the only way to access full-score contents, contrasting with selection-only reads. It also advises when to refresh the snapshot after edits, and the trigger parameter description gives a clear condition for when to use False after a timeout or manual export.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description adds meaningful behavioral context: it reads the .dorico file as a ZIP archive, runs entirely offline, does not require Dorico to be running, works on unopened projects, and reads only the project wrapper rather than musical content.

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, well-organized into Returns and Note sections, and concise overall. It loses a point for slightly repeating what the parameter schema already states, but every other sentence earns its place.

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 an existing output schema, the description need not spell out return values. It still explains the wrapper-vs-music distinction, offline behavior, and sibling alternatives, so an agent has sufficient context to select and invoke the tool correctly.

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 100% and the path parameter is already documented as a filesystem path that can point to any project on disk, not just the open one. The description repeats that idea and adds the 'offline' framing, but does not add new parameter-level detail beyond the 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?

The opening sentence names a specific verb ('Read'), a specific object ('metadata, flows, and player rosters'), and a specific resource ('saved .dorico file'). The note further distinguishes it from music-extraction and live-state siblings, so an agent can tell it apart from read_score, export_musicxml, get_status, and read_selection.

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 explicitly says to use export_musicxml + read_score for notes and rhythms, and identifies get_status/read_selection for the project open in Dorico. This provides clear when-to-use and when-not-to-use guidance with named alternatives.

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

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

The description reinforces the read-only and offline nature, consistent with the annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false). No side effects are hidden; the return type is mentioned as a structured dictionary.

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 efficient, with each sentence contributing either to purpose, usage guidance, or alternative comparisons. It is slightly verbose but not unnecessarily long.

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 output schema exists (not shown but indicated), the description provides sufficient context about return structure (dictionary), usage scenarios, and tool relationships, making it complete for an agent to decide when and how to use it.

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 schema already provides 100% coverage with descriptions for both parameters. The description adds a practical tip about using the bars filter to limit output, enhancing the schema without redundancy.

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 clearly states the tool reads an existing MusicXML file using music21, and distinguishes itself from siblings like read_selection and read_project_info by specifying 'existing MusicXML file' and 'measure by measure'.

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?

Provides explicit guidance on when to use this tool: use the bars filter for local questions, export from Dorico first to see current music, and contrasts with read_project_info and read_selection, leaving no ambiguity about alternatives.

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

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

Beyond the readOnly and idempotent annotations, the description discloses the empty-selection behavior (has_selection=False rather than an error), the API limitation about pitch and bar/beat position, and routes around that limitation. This gives the agent accurate expectations for edge cases.

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 well-structured with a clear purpose statement, a concise returns section, and a useful note about limitations. Every sentence contributes meaning, and the most important behavioral details are front-loaded.

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 zero-parameter read tool with an output schema and strong annotations, the description covers what the agent needs: what the tool reads, how to prepare the selection, what empty selections return, and where to go for unavailable data. Nothing essential is missing.

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 tool has zero parameters, so parameter semantics are largely moot. The baseline for zero-parameter tools is 4, and the description correctly focuses on behavior and return values instead of inventing parameter details.

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 clearly states the tool reads rhythmic and notation properties of the active selection, and lists concrete properties like duration, dots, articulations, accidental, and event type. This distinguishes it from sibling tools that read full scores or project information.

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 explicitly tells the agent to establish the selection first, either in Dorico or via goto_bar, and warns that this tool cannot change the selection. It also names specific alternatives for reading pitch data, which is not available here.

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

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

The description adds significant behavior beyond the annotations: dry_run true is a read that dispatches nothing and does not even require Dorico to be running, while dry_run false dispatches commands. It also discloses that this path skips the preflight checks and MusicXML handling that write_score adds, and explains the different return shapes for the two modes. The annotation readOnlyHint=false is consistent because the false mode writes/dispatches.

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 tightly organized with a lead sentence, a Returns section, and a Note section. Every sentence carries information: what the tool does, how it relates to write_score, what it returns, when to prefer the sibling, and the read-like behavior of dry_run. There is no filler or repetition that wastes the agent's attention.

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 output schema is present, the description does not need to enumerate return fields. It covers what the tool does, the two usage modes, the difference from write_score, when to choose each, and the connection/dispatch implications of dry_run. This is complete enough for an agent to select and invoke the tool correctly in both modes.

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 100%, so the baseline is 3, and the schema already provides strong descriptions for both 'score' and 'dry_run'. The tool description reinforces the dry_run semantics with 'plan it without sending' and 'nothing is dispatched', but it does not add meaningful new parameter-level information beyond what the schema already states.

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: 'Render a ScoreSpec through the caret path, or plan it without sending.' It clearly distinguishes this tool from write_score by calling it 'the lower half of write_score' and naming the two cases that matter, so an agent can separate it from its siblings without guessing.

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 Note explicitly says to 'Prefer write_score for ordinary composition' and gives exact reasons: it runs range and voice-leading checks and can take the MusicXML path. It then says to come here 'to inspect what would be sent, or when the caret path is specifically what is wanted.' This is exemplary when/when-not guidance with a named alternative.

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

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

The description goes well beyond the annotations: it explains registry_status semantics (verified, reachable, unavailable, broken, untested), cautions that kOK means acceptance rather than effect, and discloses the confirm flag requirement for destructive commands. It also warns that command_id is matched exactly with no case/spelling correction.

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 long but every sentence earns its place. It is front-loaded with the core purpose, then organizes Return behavior and safety notes into clear sections. No fluff or repetition of schema fields; it packs high-density operational guidance.

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 escape-hatch command dispatcher, the description covers command discovery, parameter semantics, destructive-command authorization, result trustworthiness, verification alternatives, and fallback logic. The presence of an output schema also relieves it of explaining return structure, and it still explains the key status field.

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?

Even though schema coverage is 100%, the description adds crucial meaning: params are command-specific and declared in the catalog, {'confirm': True} authorizes destructive commands, and command_id must match the catalog exactly. This is exactly the kind of contextual parameter guidance an agent needs beyond the raw 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?

The description opens with a specific verb and resource: 'Dispatch any catalogued Dorico command by ID, with optional parameters.' It clearly frames the tool as an escape hatch that reaches the entire catalogued command set, distinguishing it from the more specialized sibling tools.

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?

Usage guidance is explicit and actionable: 'Prefer a dedicated tool where one exists: write_score, transpose, switch_mode, playback and save all add validation or verification this does not.' It also directs the agent to search_commands for finding command IDs and parameters, and explains when this tool is the appropriate fallback.

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

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

Beyond the annotations, the description discloses that the tool overwrites the .dorico file in place, that acceptance (kOK) does not guarantee the file changed, and that the command has no effect on unsaved projects. This goes well beyond the destructiveHint annotation and gives the agent important behavioral expectations.

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 purpose and uses clear Returns and Note sections. It is slightly repetitive in places (e.g., restating 'in place' and 'overwrite'), but the overall structure is readable and each section contributes operational guidance.

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 zero-parameter save operation with an output schema present, the description covers all the essential context: the action, the precondition (already saved), the destructive effect, the acceptance caveat, and alternatives. Nothing an agent needs to call it correctly is missing.

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?

There are no parameters and the schema coverage is 100%, so no additional parameter documentation is needed. The description's zero-parameter nature makes this dimension trivially satisfied; a 4 is appropriate rather than 5 because there is no parameter semantics to add at all.

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 ('Save the open project over its existing file on disk') and clearly distinguishes it from export alternatives like export_pdf and export_musicxml. It is immediately obvious what the tool does and how it differs from siblings.

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 explicit when-to-use and when-not-to-use guidance, including the key limitation that it cannot save a project that has never been saved. It also names the alternatives to use for exports, giving the agent clear decision criteria.

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

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

Annotations already mark the tool as read-only and idempotent. The description adds valuable behavioral context beyond that: unknown keys are rejected rather than ignored, and the result contains copyable examples, enum values, and indexing rules. This significantly helps the agent trust and correctly use the output.

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 compact, front-loaded with the core purpose, and clearly structured into use-case guidance and return-value details. Every sentence adds information and no space is wasted.

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 parameterless, read-only, idempotent tool with an output schema, the description is fully adequate. It explains when to call it, what it does, a critical parser behavior, and the contents of the returned example. Nothing essential is missing for an agent to invoke it correctly.

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 tool has zero parameters, so parameter semantics are not applicable; the baseline for a parameterless tool is 4. The description instead explains what the returned result contains, which is the relevant semantic information for a no-input tool.

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 ('Return') and a specific resource ('ScoreSpec input format') and names the downstream tools that consume it (write_score/render_to_dorico). This cleanly differentiates the tool from all data-retrieval or editing siblings.

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 explicitly instructs to call this instead of guessing or reading source, which tells the agent when to use this tool and removes ambiguity. It also implies the tool is a prerequisite for write_score/render_to_dorico, providing clear contextual guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful context beyond those annotations: the search is entirely offline, Dorico need not be running, and the return shape includes total matches, per-status counts, and matching commands. This gives the agent a clear model of side effects and environment requirements.

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 purpose, then uses short labeled sections for offline behavior, return value, and usage guidance. Every sentence adds value: the offline note prevents false assumptions about needing Dorico, the return description clarifies output semantics, and the 'prefer a dedicated tool' line prevents misuse. It is longer than a one-liner but not bloated.

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?

The description is complete for a search tool of this complexity. It explains the environment constraint, the return value, the trust model for status, and the relationship to run_command and sibling tools. The input schema covers parameter semantics, and the output schema is present, so the description does not need to repeat structured details.

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%, so the schema already documents all four parameters well. The description adds extra meaning by explaining that status indicates how far to trust a command and that only 'verified' rows have been observed to work, which directly informs how an agent should use the status parameter. It also reinforces that an empty query with a limit is a way to browse categories, matching the schema's description.

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: 'Search the Dorico command catalog by query, category, or status.' It clearly distinguishes this tool from siblings by explaining its role as the lookup mechanism for command IDs before using run_command, rather than a command-execution or music-editing tool.

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 gives explicit guidance on when to use this tool: to find a command ID, understand its required inputs, and check status trust before invoking run_command. It also explicitly warns to prefer dedicated sibling tools where they exist, naming write_score, transpose, playback, and save as alternatives, which is strong routing guidance.

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

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

Discloses that it writes nothing and always reports failure, going beyond the readOnlyHint and idempotentHint annotations. It also explains why the limitation exists, which helps the agent understand that this is an intentional capability gap rather than an error.

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?

Every sentence earns its place: the primary behavior is front-loaded, the reason is explained, return semantics are stated, and the note cleanly separates the two practical alternatives. No redundant filler.

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 deliberately failing tool with a single parameter, an output schema, and read-only annotations, the description is complete. It covers behavior, reason, return value, and the exact alternative tools to use, leaving no operational 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 coverage is 100% and the parameter is well described there. The description adds useful context by explaining that the key value is simply reported back so the caller can carry it to an alternative, and that nothing is written from it.

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: it reports that a key signature cannot be set and explains what to use instead. This clearly distinguishes it from a normal setter like set_time_signature or write_score by making its failure behavior explicit.

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?

Provides explicit guidance on when to use this tool versus alternatives: open_popover for a person at the keyboard, and write_score or export_musicxml for unattended writes. It also references set_time_signature to group related limitation-based tools.

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

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

Even though annotations already declare readOnlyHint, idempotentHint, and destructiveHint, the description adds crucial behavioral context: it 'writes nothing and always reports failure' and explains why a silent no-op would be misleading. This is exactly the kind of non-obvious behavior an agent needs to understand.

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 well-structured with a front-loaded summary, a returns line, and a note section. Every sentence earns its place by explaining the limitation, the failure behavior, or the alternatives. No filler or repeated schema content.

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 unusual behavior—always failing on purpose—the description fully covers what the tool does, why it does it, what the caller gets back, and what to use instead. The presence of an output schema and full parameter coverage means no essential context is missing.

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 schema already covers the single parameter with a clear description, so the baseline is 3. The tool description adds extra value by explaining that the signature is 'reported back in the answer so the caller can carry it to one of the alternatives' and emphasizing that 'nothing is written from it.'

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: 'Report that a time signature cannot be set here, and what to use instead.' It clearly distinguishes this from siblings like set_key_signature by framing it as a deliberate failure-reporting tool rather than an actual setting operation.

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 explicitly names alternatives and gives conditions for choosing them: open_popover(kind='time') for interactive use, and write_score(method='musicxml') or export_musicxml for unattended writes. This gives an agent concrete routing guidance rather than leaving usage to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, and the description adds meaningful behavioral context beyond those: 'Entirely offline', 'reasons about numerals as symbols and never touches a score or Dorico', and 'common-practice function... what usually follows rather than what must.' This tells the agent the tool is heuristic, symbolic, and side-effect-free in operational terms, not just via hints.

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 well-structured with a lead sentence, a Returns block, and a Note block. It is efficient and front-loaded. Minor redundancy exists: 'read-only' and 'Nothing is written anywhere' both restate what annotations already convey, but this is not harmful given the safety-critical nature of read-only assurances.

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?

With an output schema present, the description need not detail return fields, yet it still summarizes the return shape. It covers operational context (offline, non-Dorico), limitations (common-practice heuristics), and integration with relevant siblings. For a two-parameter tool, this is comprehensive and leaves no critical gap.

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 100%, so the schema already documents both key and progression with examples and case conventions. The description adds no extra parameter-level semantics beyond restating that it takes numerals rather than notes. Baseline 3 is appropriate since the schema carries the full burden.

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: 'Suggest functional continuations for a Roman numeral progression.' This clearly distinguishes it from sibling tools like analyze_harmony (which extracts numerals) and write_score (which materializes music). The purpose is unambiguous and not a tautology.

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 gives explicit workflow guidance: 'This takes numerals, not notes. To get numerals out of actual music, run analyze_harmony first and feed its reading in here.' It also names write_score as the way to hear a candidate. These are concrete when-to-use and how-to-chain instructions with sibling tools.

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

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

While the idempotentHint annotation is present, the description adds concrete behavioral detail: it changes only the window, doesn't affect notes, playback position, or selection, and reports whether the switch was accepted. It also clarifies that the mode change is not read-only in the annotation sense but is still non-destructive.

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 well-organized with a clear first sentence, explicit side-effect statement, return mention, and practical note. Every section adds distinct value and important information is front-loaded.

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?

The tool is conceptually simple with one parameter, an output schema, and annotations. The description fully covers purpose, side effects, prerequisites, and exclusions relative to sibling tools. Nothing an agent needs to call it correctly is missing.

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% with a detailed mode parameter description listing all five values and their meanings. The description adds value by tying those modes to practical workflow context (e.g., write mode is needed before note-entry tools), which helps the agent pick the right mode value.

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 ('Switch') and resource ('Dorico's five workspace modes') and immediately distinguishes the tool from navigation tools by explicitly saying this is not navigation. An agent can understand exactly what mode switching accomplishes.

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 gives explicit when-to-use guidance: switch to write mode before note-entry tools if needed, and explicitly contrasts with navigate and goto_bar for scrolling and caret movement. This is ideal routing guidance.

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

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

The annotations only provide minimal hints (readOnly=false, destructive=false, idempotent=false). The description adds critical behavior: it modifies the score in place, is relative and repeatable, is a no-op with no selection, and tells the agent to verify via registry_status and the score/playback.

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 structured clearly: purpose first, then returns, then when/when-not, then behavior and parameters. It is longer than minimal, but each section carries useful guidance; only the 'Maps to CommandNote.Pitch...' line is mildly internal and less essential.

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 tool with selection-dependent, relative, repeatable behavior and no rich annotations, the description covers the preconditions, failure mode, parameter behavior, and verification steps. Since an output schema exists, not explaining the return dictionary in detail is acceptable.

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 schema has 100% coverage and already fully documents direction, chromatic, and octave semantics, including the override behavior. The description essentially restates these facts ('direction sets shift orientation', 'octave=True overrides chromatic') without adding meaning beyond the schema, so a baseline 3 is appropriate.

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 'Transpose currently selected notes up or down in the score,' a specific verb plus resource. It also differentiates from siblings by stating what the tool is not for: entry music (write_score/add_notes) and key signature changes (set_key_signature).

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?

An explicit 'When to use' block says to shift selected notes by semitone, diatonic step, or octave intervals, and a 'When NOT to use' block names the alternative tools. It also explains the no-selection case and directs the agent to make a selection or use goto_bar.

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

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

Annotations are sparse (only safe/write flags), so the description carries the burden. It discloses that kOK means accepted rather than effective, that the caret path restarts at the start of the flow, that musicxml imports as a new flow, and that unknown keys are refused rather than ignored. No contradiction with annotations.

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 long but every section earns its place: headline purpose, sibling differentiation, return summary, method decision rule, preconditions, and a subtle caret navigation behavior. It is structured with Returns and Note sections, making the density navigable.

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 complex write tool with no meaningful annotations, the description covers when to use it, how to choose the method, what side effects each method has, what preconditions exist, and how to interpret the return. Nothing an agent needs to call it correctly is missing.

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%, so the schema already documents score, method, and preflight. The description adds meaning beyond it: method choice tradeoffs, that preflight warns rather than blocks, and that score_schema should be called first because strict parsing rejects unknown keys. This is useful but not radically more than the schema already states.

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 first sentence names a specific verb ('Render') and resource ('ScoreSpec into Dorico') and immediately distinguishes the two entry paths, caret and MusicXML. It further contrasts with add_notes/add_rest by explaining they do not chain, so an agent can tell this tool apart from its closest siblings.

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 says this is the tool to reach for whenever more than a single beat is needed, and why add_notes/add_rest are unsuitable. It also gives a decision rule between caret and musicxml, including limitations (key/time signatures) and side effects (new flow), plus prerequisites like switch_mode and score_schema.

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