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

With no annotations, the description carries the behavioral disclosure burden and does so thoroughly: it reveals that note-input mode is always exited even on error, that success only means kOK acceptance, and that the agent should verify actual placement via get_status, playback, or score inspection. It also warns about the stacking behavior on repeated calls.

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 caveat ('ONE insertion') and every section earns its place: purpose, sibling routing, argument details, and safety behavior. It is moderately long but densely informative with no fluff.

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 opertion scope, state behavior, error-mode cleanup, success semantics, and verification path, and points to alternatives. The only implicit context is that note-input mode must already be active, but the repeated references to entering and leaving note input mode make that clear enough for the agent to proceed 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 0%, so the description fully compensates. It explains notes format ('C4','E4','G4', letter + optional #/b + octave), lists all valid duration values, and defines as_chord as stacking notes into one chord instead of a sequences. This exceeds what the raw schema conveys.

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 action: 'Input notes at the caret' and explicitly limits it to 'ONE insertion at the current caret.' It differentiates itself from siblings by warning against using repeated add_notes calls for sequences and directing to write_score / render_to_dorico, so an agent can tell this tool apart.

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: for a sequence over time, use write_score / render_to_dorico, because repeated add_notes calls do not chain and will stack on the same beat. This directly answers when to use the tool vs. alternatives with no ambiguity.

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?

With no annotations provided, the description carries the full burden. It does disclose the return dictionary contents (success, duration, undo flag, mode), which is useful. However, it does not describe side effects on the document, whether the caret moves, error cases (e.g., no active caret), or undo behavior beyond the hint in the return value.

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 and well-organized into action, Args, and Returns sections. The primary action is front-loaded, and there is no filler. Slight formatting redundancy in the Args/Returns blocks could be tightened, but overall every 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?

The output schema provides return-value coverage, and the tool is low complexity (one optional param). However, with zero annotations,the description omits prerequisites suchas whether an active caret must already exist and failure behavior if absent.For a tool that mutates a score, this is adequate but leaves gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must carry parameter meaning, and it does: it enumerates all valid duration values (whole, half, quarter, eighth, sixteenth, 32nd, 64th). This adds real value beyond the schema, which only provides a title and default. A minor gap is the lack of guidance on handling invalid values.

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?

Clear verb+resource: 'Input a rest of the specified duration at the active caret position.' The resource (rest) is implicitly distinguished from sibling tools like add_notes, and the caret-position scope is specific. However, the verb 'Input' is slightly less idiomatic than 'Insert' or 'Add,' and the differentiation from siblings is implicit rather than 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?

No guidance is provided on when to use this tool versus alternatives (e.g., add_notes), nor are exclusions or prerequisites stated. The phrase 'at the active caret position' hints at context, but there are no actionable selection criteria for an agent deciding between 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It does state that analysis happens offline via music21 and that it returns key estimation details and Roman numeral sonority analyses, which is useful. It does not disclose whether the operation is strictly read-only, what happens for invalid or incomplete scores, or any latency or failure modes.

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 concise: two sentences, no filler, with the main purpose stated first and a brief summary of return values second. Every 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?

The input schema is richly documented and an output schema exists, so the description can be brief. It covers the core capability and high-level return content, but it lacks usage differentiation from sibling analysis tools like check_voice_leading or suggest_next_chord, and it does not caveat edge cases or side effects. This is minimally viable but not fully complete.

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 one required parameter, 'score', and although the top-level schema description coverage is 0%, the ScoreIn ref definition fully documents the accepted structure. The description itself does not explain the parameter or add meaning beyond the schema, but the parameter name plus the extensive nested schema make the intended input unambiguous enough for correct invocation.

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 names a specific operation and resource: analyzing harmonic structure and estimating key from a score, with the implementation context 'offline using music21'. It is clear about what the tool does and distinguishes it from siblings like check_voice_leading and suggest_next_chord by focusing on key estimation and Roman numeral sonority analysis, though it does not explicitly reference those alternatives.

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 implies this tool is used for harmonic and key analysis, and the 'offline' qualifier signals that it does not communicate with external apps such as Dorico. However, it gives no explicit when/when-not guidance, no alternatives, and no prerequisilities, so the agent has to infer when this is the right tool among several analysis siblings.

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?

With no annotations present, the description carries the full burden for behavioral disclosure. 'Analyze' indicates a read-only analysis operation and rules out mutation, but it does not describe what kind of result is returned, how rule violations are reported, or how invalid input is handled. The output schema may cover some of this, but the description itself adds little behavioral context beyond the core analysis action.

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 and front-loaded with the purpose sentence, followed by a tight Args list. Every line adds information; there is no fluff, repetition, or unnecessary background.

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 three-parameter checker with an output schema, the description is minimally sufficient: it states the domain, the input types, and the default species. It is not fully complete because it omits allowed species values and any guidance on how to choose between this tool and the closely related check_voice_leading / analyze_harmony tools.

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 0% description coverage, so the Args section must compensate. It usefully says the two array parameters contain 'scientific pitch names' and gives the default for species. However, 'Counterpoint species (default: 1)' does not clarify what integer values are valid, what species options exist, or how species affects the analysis. Partial but not complete.

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: 'Analyze two-part first-species counterpoint against standard rules.' This clearly identifies both the domain (counterpoint) and the scope (two-part first-species), which distinguishes it from nearby siblings like check_voice_leading and analyze_harmony.

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 phrase 'two-part first-species counterpoint' implies the intended use case, but the description never states when to choose this tool over alternatives such as check_voice_leading or analyze_harmony. No explicit exclusions or alternative routing are provided, so usage guidance is only implicit.

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?

No annotations are provided, so the description carries full behavioral burden. It discloses that the tool audits offline and returns a structured list, but it does not state whether the input score is modified, whether external connections like Dorico are involved, or what side effects may occur. For a tool with no annotation coverage, this is a significant gap.

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?

Two sentences with no waste: the first states the action and scope, the second states the return type. Purpose is front-loaded, making the tool easy to grasp quickly.

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 accepts a complex nested ScoreIn object and has no annotations, yet the description only covers the return type and offline nature. It does not explain what a valid score input looks like, what 'audit' implies for the input, or how this tool differs from check_counterpoint. Since an output schema exists, return structure need not be detailed, but input and selection guidance are 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 sole parameter 'score' has no top-level description in the tool description, and the description itself does not explain what score data should be passed. Although nested schema definitions describe ScoreIn, the schema description coverage is 0%, and the description does not compensate for that gap.

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?

Description states a clear verb ('Audit') and resource ('voice leading rules'), lists specific rule categories (parallels, overlaps, spacing), and notes it returns a structured list of issues. It doesn't explicitly differentiate from the sibling check_counterpoint, but the scope is specific and understandable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given on when to use this tool versus alternatives like check_counterpoint or analyze_harmony. The word 'offline' hints at execution context but there are no explicit when-to-use conditions, prerequisites, or exclusions.

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?

With no annotations provided, the description carries the full transparency burden. It discloses important behavioral traits: authorization prompt on first connection, token persistence in AppData, and automatic authentication on later runs. This is meaningful beyond the bare 'connect' semantics, though it could also mention what happens if already connected.

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 two short sentences with no filler. The first sentence immediately states the tool's purpose, and the second adds the key authorization detail. Every 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?

For a simple 0-parameter connection tool with an output schema, the description covers the essential setup behavior: authorization prompt and token persistence. It is slightly incomplete because it does not explicitly say this tool is a prerequisite for other Dorico Remote Control tools, which would help an agent sequence calls 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 there is no parameter semantics to explain. Per the baseline for 0-parameter tools, the description needs to compensate only for context, which it partially does by describing the connection flow. The empty schema means nothing is undocumented.

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: 'Connect to Dorico Remote Control and return application status.' It is clear about what the tool does. However, it does not explicitly distinguish itself from siblings like get_status, which may also report status, so it misses the top score for sibling differentiation.

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 no guidance about when to use this tool versus alternatives, nor does it state that this should be called before other Dorico operations. It only describes the connection and authorization behavior, which is useful context but not usage direction.

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?

With no annotations, the description carries the behavioral disclosure burden. It does well by stating the operation is offline, listing preserved score attributes, and clarifying the temp-file fallback when path is omitted. It does not mention overwrite behavior or return values, but the key behavioral traits are disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, each carrying distinct information: the core action, preserved attributes, and path behavior. The most important distinguishing facts are front-loaded, and 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 two-parameter tool, the description covers the critical operational details: offline execution, preservation guarantees, and default file location. It is slightly incomplete in not explaining the ScoreSpec structure or the output/return value, but the output schema mitigates that 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 0%, so the description must compensate. It explains the path parameter's omission behavior but gives no guidance on the 'score' parameter beyond calling it a 'ScoreSpec,' leaving the agent to rely entirely on the nested schema. Partial compensation is not enough for a required parameter.

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: 'Write a ScoreSpec to a MusicXML file offline.' It names the resource, the output format, and the execution mode, which clearly distinguishes it from sibling tools like import_musicxml (reverse direction) and export_pdf (different format).

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 word 'offline' implies it is for use when no Dorico connection is available, and the MusicXML format implies a distinct export target. However, it does not explicitly state when to prefer this over export_pdf or how it relates to import_musicxml, so the usage guidance is present but implicit.

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?

With no annotations, the description carries the full burden of behavioral disclosure, and it does this well. It reveals the underlying command, the output file location, the asynchronous/UI-thread caveat, and a concrete testing version. This goes beyond a generic 'export' statement and warns the agent about a non-obvious success semantics issue.

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 provides necessary command-level detail and a relevant caveat. Every sentence earns its place; the note about kOK and the UI thread is important and not extraneous.

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 no output schema declared, the description is complete: it specifies what command runs, where the file lands, how the parameter changes behavior, and what success does not guarantee. An agent has enough context to invoke this tool correctly and to interpret results cautiously.

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?

Although schema coverage is 0%, the description explicitly maps the single boolean parameter to behavior: current layout for ExportCurrentLayoutAsPDF and all layouts for ExportAllLayoutsAsPDF. This fully compensates for the schema-only title 'All Layouts' and gives an agent the information needed to set the parameter correctly.

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 ('Export the score to PDF'), a specific resource ('the score'), and a key mode ('unattended without opening a dialog'). It differentiates this tool from siblings like export_musicxml by naming the export format and the command it sends.

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 context for when to use the tool: when the user wants a PDF export without UI interaction. It also clarifies the two possible behaviors via current vs all layouts. It does not explicitly name alternative tools to avoid, but the format-specific wording makes the intended use clear.

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?

No annotations are provided, so the description carries the burden. It discloses that reads are 'selection-based' and reflect 'merged status deltas pushed by Dorico', which is useful behavioral context. However, it does not clarify what happens if no selection is active, whether the tool can fail (e.g., if disconnected), or what the output schema contains.

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 concise: two sentences that front-load the main purpose and then add relevant detail about what the snapshot contains. Every sentence adds value, and there is no fluff.

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 that there are no parameters and an output schema exists, the description is mostly complete. It explains what the tool returns and its selection-based nature. Minor gaps include lack of explicit error handling or connectivity mentions, but these are not critical for a zero-parameter getter with an output schema.

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 the schema is trivially complete (100% coverage). The description adds behavioral meaning by explaining what the state snapshot includes, which is beyond the schema's empty properties object. Since there are no parameters to document, the description effectively handles the default baseline.

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 resource ('Dorico's current pushed application status snapshot'), and elaborates on what the snapshot contains. It is clear but does not explicitly differentiate it from sibling tools like read_selection, though the mention of 'application status' distinguishes it from score-related 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 implies usage context by stating that reads are selection-based and reflect pushed status deltas, which hints at when this might be useful (e.g., checking active mode or undo availability). However, it does not explicitly state when to use this tool versus alternatives like read_selection or connect_to_dorico, nor does it provide exclusion 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?

With no annotations, the description carries the full behavioral burden, and it does well by disclosing that the position is assumed, not exact, and that the tool dead-reckons by rewinding to bar 1 and stepping forward. It does not fully disclose side effects such as entering note-input mode or disturbing the current selection, but the core behavioral quirk is clearly surfaced.

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?

Two sentences deliver the action, the return value, the API limitation, and the mechanism with no filler. The most important information is front-loaded, and every 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?

The description covers the main purpose and mechanism, and there is an output schema for the return shape. However, with no annotations, important contextual gaps remain: what happens to note-input mode, whether rewinding affects the visible score/selection, and whether staff indexing is zero-based are all unspecified.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description needed to add real meaning for bar, beat, and staff. It only says 'specified bar, staff, and beat' without explaining indexing, bounds, or units; the schema properties and defaults do most of the work, and the description barely compensates.

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 names a specific action (move the caret to a bar) and a specific resource (the bar/staff/beat position), and also states that it returns an assumed position. It clearly distinguishes this from generic navigation tools by explaining the dead-reckoning approach.

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 implies this tool is for when you need the caret's assumed position and need to move it via bar/staff/beat, since Dorico's API lacks direct coordinates. However, it does not explicitly say when to prefer this over sibling tools like 'navigate', nor does it give when-not-to-use 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?

No annotations are present, so the description carries the full disclosure burden. It reveals important behaviors: it dispatches File.Open, creates a new flow, may show player assignment confirmation prompts, and returns structured result fields including requires_confirmation. It could additionally note failure modes, but the core behavioral surface is well covered.

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 concise, front-loaded with the purpose, and includes a clear Args/Returns structure. Every sentence adds useful information: mechanism, side effects, alternatives, parameter meaning, and return shape.

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 tool with no annotations and no output schema, this description is complete. It explains the operation, its side effect, potential prompts, the alternative, the parameter, and the return contract. An agent has enough to call it correctly and interpret the result.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description compensates by documenting the sole parameter: 'path: Filesystem path to the MusicXML file.' This adds meaning beyond the bare schema property and is sufficient for correct invocation.

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 action ('Import a MusicXML file into Dorico'), the mechanism (Remote Control API, File.Open with MusicXMLImportFilter), and a key behavioral consequence (creates a new flow). It also distinguishes itself from write_score, so an agent can tell which tool to use.

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 explains that imports create a new flow and gives an explicit alternative: 'To add music into an existing sheet instead, use write_score(method="caret")'. This gives clear when-to-use and when-not-to-use 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?

There are no annotations, so the description carries the behavioral burden. 'Query'/'validate' and 'offine' convey a read-only, side-effect-free operation, but it does not disclose the return shape, error handling for unknown instruments, or whether validation returns a boolean versus a range.

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?

Two short purpose sentences are followed by a compact Args list. The purpose is front-loaded and every line contributes meaningful information, with no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter, one-required offline lookup, the description provides enough detail to invoke correctly: required instrument, optional pitch, and examples. The main gap is the absent return-value description, since there is no output schema to cover it, but this is minor for such a simple tool.

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 decription coverage is 0%, so the Args block is the only semantic documentation. It names both parameters, marks pitch optional, and provides concrete examples; however, it does not enumerate supported instrument names or fully specify pitch syntax beyond 'scientific pitch name'.

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 two specific actions, 'Query standard instrument ranges' and 'validate pitch playability', tied to a clear resource. The 'offine' qualifier and Arg examples make it unmistakably a standalone lookup utility, distinct from the score-editing/rendering 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 states the two use cases, range lookup and playability validation, and notes it works offline, giving an agent clear when-to-use context. It does not enumerate sibling alternatives or exclusions, but no sibling appears to compete with this range-lookup function.

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?

With no annotations, the description carries the burden of disclosing behavior, and it does so by explaining that target="start" and "end" move the visual viewport via View.MoveViewportTo* and that target="bar" redirects to goto_bar. It does not describe return values, but an output schema exists, so that omission is acceptable.

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 and front-loads the core purpose, with parameter details and a usage note in separate sections. The opening sentence is slightly awkward ('report bar navigation'), but the overall structure is efficient and scannable.

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 simple navigation tool, the description covers the main behaviors, parameter semantics, and the key alternative tool. The only minor gap is the ambiguous wording in the first sentence, but an agent can still understand what the tool does and when to call 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 input schema contains only titles with no descriptions, so the description fully compensates by explaining valid values for target ("start", "end", and "bar") and the conditional role of bar as a 1-indexed bar number only used when target="bar". This is exactly the kind of parameter-level meaning an agent needs.

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 identifies a clear action ('Scroll the score viewport') and a specific resource (score viewport), and it distinguishes this tool from goto_bar by noting that target="bar" redirects there. However, the phrase 'report bar navigation' is awkward and slightly obscures the third behavior, so it is not perfectly clear.

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 this tool versus goto_bar: use navigate for viewport movement, and use goto_bar to reposition the caret for note entry. It also explains that target="bar" redirects to goto_bar, giving clear 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?

With no annotations present, the description carries the full transparency burden. It discloses a key limitation (cannot populate fields remotely), explains that it positions the caret if requested, triggers a command, and returns instructions for manual input. This goes well beyond a generic 'opens a popover' statement, though it stops short of describing all UI side effects or prerequisites.

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 two tight paragraphs: the first states the primary action in one sentence, the second adds essential limitation and behavior. Every sentence earns its place, and the most 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?

For a simple three-parameter tool, the description covers the action, the API limitation, the underlying command trigger, and the nature of the returned instructions. The output schema can handle the return structure. Minor gaps remain around explicit staff/bar semantics, but the overall tool context is complete enough for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It does help by mapping kind to the supported popover types and implying bar relates to caret positioning, but it never explicitly explains the bar parameter or the staff parameter. The compensation is partial rather than complete.

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 ('Open') and a clearly defined resource ('input popover') with enumerated types (dynamic, tempo, key, time, clef) and location ('at the caret'). It is immediately distinguishable from sibling tools like set_key_signature or set_time_signature, which directly set values rather than opening a popover for manual input.

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 explains the workflow context: the Remote Control API can open popovers but cannot populate their fields, so this tool triggers the NoteInput.Create* command and returns manual-input instructions. This gives clear when-to-use context, though it does not explicitly mention alternatives or state when not to use this tool.

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?

With no annotations provided, the description carries the full behavioral burden. It adds the useful constraint that location is the 'Playhead origin for play,' implying it applies only to the 'play' action. However, it does not disclose side effects (e.g., whether stop preserves position, whether rewind halts playback, what happens if location is passed with stop/rewind) or describe any output behavior.

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 and front-loaded, with a one-sentence purpose statement followed by a clean Args block. Every element earns its place, and the parameter documentation is formatted for easy scanning by an agent. No filler or redundant restatement of the tool name.

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 simple two-parameter tool with an output schema, the parameter semantics are well covered. However, the absence of usage guidance and behavioral edge-case disclosure leaves gaps in the overall picture. The description is functionally adequate for calling the tool but not richly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and no enums are defined, so the description fully compensates by enumerating all valid values for both parameters. It also clarifies the conditional relationship between them (location is specifically 'for play'), which the schema entirely lacks. This is exactly the value the description should add.

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+resource statement, 'Control Dorico playback transport,' which clearly identifies the tool's function. The action parameter values ('play', 'stop', 'rewind') further reinforce the purpose. It doesn't explicitly name sibling alternatives, but the sibling list contains no other playback-related tool, so it is effectively distinct.

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 no guidance on when to use this tool versus alternatives or when not to use it. It documents what the parameters do but never states the intended invocation context, exclusions, or prerequisites. Usage must be inferred entirely from the tool name and the purpose sentence.

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?

No annotations are provided, so the description carries the full burden. It discloses that the read happens directly from the project ZIP archive and never requires launching Dorico, which is meaningful behavioral context. It does not mention failure modes or invalid files, but for a read-only operation this is adequate.

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?

Two tight sentences with no filler. The first sentence states the core purpose, and the second adds the valuable mechanism detail about ZIP extraction and the lack of a Dorico dependency.

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 one-parameter read tool with an output schema already present, the description covers the tool's purpose, input, and key behavioral constraint. It could add explicit path requirements or error behavior, but nothing critical is missing for an agent to select and invoke the tool.

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 provides only a bare path string with no description, so the description must compensate. It identifies the file as a saved .dorico project, making it clear the path should point to such a file. It does not specify path formats, but for a single obvious required parameter this is enough guidance.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: it reads metadata, flows, and player rosters from a saved .dorico file. The mention of extracting from the project ZIP archive and not requiring a running Dorico instance clearly distinguishes it from sibling tools that operate on a live session.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear usage context: use this tool when you have a saved .dorico file and do not want or need a running Dorico instance. It does not explicitly name alternatives or state when not to use it, so it stops short of a 5.

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

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

No annotations are provided, so the description carries the full behavioral transparency burden. It discloses that the operation is a read, that it processes the file measure by measure, and the high-level shape of the returned dictionary. However, it does not mention error behavior, format limitations, or path requirements beyond saying the file is MusicXML and existing.

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 and well-structured with clear Args and Returns sections. Every line adds useful information: the operation, the parameters, examples, and the return format. No filler or redundant 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 output schema is available and the parameter documentation is complete, the description provides sufficient context for an agent to invoke the tool correctly. It covers what is read, how to filter measures, and what kind of result 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?

The schema provides zero description coverage, but the description thoroughly documents both parameters. It explains 'path' as a filesystem path, and 'bars' with concrete filter examples ('8', '8-12', '8,10,12') plus the behavior when omitted. This fully compensates for the bare 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 clearly states the verb ('Read'), the resource ('existing MusicXML file'), and the mode ('measure by measure using music21'). It also describes the return dictionary, which helps disambiguate from write_score or import_musicxml, though it does not explicitly name sibling alternatives.

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 tells what the tool does but gives no explicit guidance on when to choose it over siblings like read_selection, read_project_info, or score_schema. There are no when-to-use/when-not-to-use conditions or alternative routing, so an agent must infer usage from the tool's name and basic purpose.

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?

With no annotations, the description carries the full transparency burden. It states that the tool reads properties and explicitly discloses the limitation that pitch and measure/beat positions are not exposed by Dorico's Remote API, which prevents false expectations. It does not describe behavior when no selection exists, but the read-only nature is clear and the main boundary is communicated.

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 concise and front-loaded: the first sentence states the core action and resource, and the following sentences add only high-value detail about what is inspected and what is not exposed. Every 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?

For a parameterless read tool with an output schema, the description is complete enough. It identifies the selection as the input context, lists the returned property categories, and warns about the key API limitation. An agent has sufficient information to decide whether this tool fits the need.

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 the default baseline is 4. There is nothing for the description to add regarding parameter meaning, and the schema is complete by virtue of having no properties.

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 ('Read') and resource ('active selection'), then enumerates the exact properties inspected: duration, dots, articulations, accidental, and event type. It also distinguishes itself from broader read tools by focusing on the selection, and clarifies what is not available.

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 intended use is implied clearly: use this when you need rhythmic and notation properties of the active selection. However, it does not explicitly name alternatives or state when to prefer another tool, such as read_score for pitch or broader score data. The exclusion of pitch and measure/beat positions is useful but framed as an API limitation rather than a usage guideline.

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?

With no annotations, the description carries the full burden. It usefully discloses dry-run behavior ('plan commands and return execution report without dispatching') and implies real runs dispatch commands. However, it does not mention side effects on the current document or caret, connection requirements, or whether the operation is 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 compact and front-loaded: a one-line purpose, a short Args block, and a brief Returns line. The phrase 'Score specification matching ScoreSpec schema' is slightly redundant, but no sentence 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?

Given no annotations, a complex ScoreSpec input, and a large sibling family, the description leaves important context implicit: what 'live caret path' means operationally, whether an active Dorico connection is required, and what the default dispatch actually changes. The dry-run and return summary make it minimally viable, but an agent would still need to infer key preconditions.

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?

Top-level schema coverage is 0%, so the description must compensate. It does: score is identified as a ScoreSpec, and dry_run is given a concrete behavioral consequence. The ScoreSpec/ScoreIn naming mismatch is not reconciled, but both parameters receive enough added meaning to invoke the 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 opening line names a specific action (render), a specific input (ScoreSpec), and a distinctive mechanism ('live caret path'). It does not distinguish itself from siblings like write_score or export_pdf, and 'ScoreSpec' is not formally defined, so it falls short of a 5.

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 Args block explains the two parameters but gives no guidance about when to prefer this tool over the many siblings such as write_score, add_notes, or export_pdf. No prerequisites, exclusions, or alternative conditions are stated.

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?

With no annotations, the description carries the burden of behavioral disclosure. It does disclose one important behavior: destroying commands require {"confirm": true}. It does not describe what happens if confirm is omitted, whether the command may fail silently, or how errors are returned.

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 concise, front-loads the core action, and uses a simple Args structure. Every sentence adds meaningful information and 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 two-parameter tool with an output schema, the core call contract is present. It is slightly incomplete because it does not explain where to find command IDs or how to handle authorization failures, which matter for a generic command dispatcher without annotations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must add meaning beyond the parameter types. It does: command_id is the exact command string from the catalog, and params is an optional dictionary with a confirm key to authorize destructive commands. Both parameters receive useful 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 names a specific action and resource: 'Dispatch any catalogued Dorico command ID with optional parameters.' It is clear about what the tool does, though it does not explicitly differentiate itself from siblings such as search_commands.

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 phrase 'any catalogued Dorico command ID' implies this is a generic dispatcher for commands that already exist in the catalog, and the confirm note indicates when authorization may be needed. However, it never says when to prefer this tool over search_commands or the other Dorico-specific tools, nor does it give explicit exclusions.

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?

No annotations are provided, so the description carries the full burden of disclosing behavior. It says 'Save the current project' but does not state whether this overwrites the existing file, whether it prompts for confirmation, or whether it modifies the state of the project in any irreversible way. The described behavior is minimal and leaves the agent guessing about 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 extremely short and to the point—one sentence with no filler. The parenthetical '(File.Save)' adds minor context but is not wasteful. It is concise, though it could be slightly more informative without losing brevity.

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 has no parameters and the description conveys the core action, it is minimally viable. However, since there are no annotations and no mention of side effects, output, or failure modes, an agent relying solely on this description might not fully understand the save operation's impact. The lack of usage guidance and behavioral disclosure makes it only partially complete.

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 input schema has no properties, so schema coverage is effectively complete. With no parameters to document, the description does not need to elaborate on parameter details. The baseline of 4 for a zero-parameter tool 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 'Save the current project' clearly states the action (save) and the resource (current project). It is distinct from sibling tools like export_pdf or write_score, which perform different operations. The parenthetical '(File.Save)' adds helpful context, though the phrasing is slightly terse.

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 no explicit guidance on when to use this tool versus alternatives. There are no mentions of exclusions, prerequisites, or related tools. Since 'save' has obvious meaning but sibling tools like export_pdf or write_score exist, more context on when saving is appropriate would improve the definition.

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?

No annotations are present, so the description carries the behavioral burden. It discloses what the return contains (minimal flat/nested examples, allowed enums, indexing rules) and a key parser behavior ('Unknown keys are rejected'). Strong for a read-only reference tool, though it does not mention side-effect status explicitly.

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?

Three purposeful sentences with no filler. The first states the purpose, the second justifies calling it, and the third delivers the exactness warning. The most 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?

For a zero-argument reference tool with an output schema, the description tells the agent why to call it, what the response will contain, and how to apply it. Nothing needed to invoke or use 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?

The tool has zero parameters, so the schema covers all input details and no compensation is needed. Baseline 4 is appropriate; no parameter-specific description is required.

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 ('Return') and a specific resource ('ScoreSpec input format') and names the consumer tools ('write_score/render_to_dorico'), which differentiates it from sibling score-editing tools. An agent can immediately see this is a format-reference tool, not a score mutation 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?

Explicitly tells the agent when to call it: 'Call this instead of guessing (or reading source)' and instructs it to 'match this shape exactly' before using ScoreSpec consumers. This is clear, actionable usage guidance with an explicit 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?

With no annotations provided, the description carries the burden of showing how this tool behaves. It usefully discloses case-insensitive substring matching, category filters, status filters, and the aggregate return shape (total matches, status counts, matching commands). It does not claim any side effects, and 'search' reasonably implies read-only behavior.

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 and well organized into Args and Returns. Every sentence adds functional value, and the most important purpose sentence comes first. No fluff or repeated schema-default 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?

The description covers purpose, filtering behavior, exact parameter meaning, and return structure, which is complete for a search tool. A minor gap is the lack of a prerequisite note (e.g., whether a connect to Dorico is required), but that is not critical for a catalog query and is inferable from the sibling tool set.

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 0% description coverage, so the description fully compensates by explaining every parameter: query semantics, category examples, status allowed values, and limit meaning. There is no dangling undocumented parameter, which is exactly what an agent needs.

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 identifies the action ('Search') and the resource ('the Dorico command catalog'), with a specific set of filters (query, category, status). It is unambiguous, though it does not explicitly differentiate itself from siblings such as run_command or read_project_info.

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 implies usage context: an agent should call this when it needs to discover or inspect commands from the Dorico catalog. However, it does not state when not to use it or how it compares to related tools like run_command, so the routing guidance remains implicit rather than 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?

With no annotations provided, the description carries the full behavioral burden. It transparently explains that the tool does not set key signatures and why (the Remote API cannot feed the interactive popover), which is strong disclosure for a stub-like tool. It does not explicitly state there are no side effects, but 'Report' strongly implies a non-mutating operation.

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 and front-loaded, with the core purpose stated in the first sentence. Every sentence earns its place: purpose, limitation rationale, and concrete alternatives.

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 simple reporting tool with an output schema, the description is nearly complete: it explains the limitation, names the relevant alternative tools, and provides invocation hints. The only meaningful gap is the semantics of the key parameter.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description does not explain the 'key' parameter's role, accepted values, or whether it is ignored. The agent can guess it represents the desired key signature, but the description does not confirm how it is used or what happens if it is omitted or invalid.

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 key signature limitation and suggest supported alternatives.' This clearly distinguishes the tool from siblings that actually set musical parameters, and it corrects the misleading impression created by the tool name.

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 the agent what to do instead: use open_popover(kind="key") or export_musicxml / write_score(method="musicxml"). This gives direct routing to alternatives and explains why this tool cannot perform the requested operation.

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?

No annotations are provided, so the description carries the full burden. It discloses that this tool only reports a limitation and does not actually set the signature, explains why, and gives supported workarounds. This prevents the agent from expecting a real mutation from a tool named set_time_signature.

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?

Approximately 45 words, three short blocks: purpose, underlying limitation, and concrete alternatives. Purpose is front-loaded and every sentence earns its place without 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?

The description gives purpose, reason, and alternatives, which is most of what an agent needs. The only notable gap is parameter guidance, but the single optional parameter with a self-explanatory title/default and the presence of an output schema keep this from being a major omission.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and the description never mentions the 'signature' parameter. The agent gets no guidance on what to pass or whether passing it affects the limitation report. The schema's title and default provide only minimal meaning, so the description fails to add needed semantics.

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?

Description clearly states a specific action: 'Report time signature limitation and suggest supported alternatives.' It explains the actual behavior and distinguishes it from sibling tools like set_key_signature and open_popover by explicitly naming alternatives.

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 tells the agent when not to attempt direct setting: 'Dorico requires time signatures to be entered via an interactive popover, which cannot receive text parameters over the Remote API.' It then names exact alternatives: open_popover(kind="time"), export_musicxml, and write_score(method="musicxml").

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?

No annotations are provided, so the description must carry the full behavioral burden. It does not mention what the output looks like, whether multiple suggestions are returned, how many chords are generated, or any constraints or side effects. The description only restates the basic operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very concise and well-structured. The first sentence states the purpose directly, and the Args section clearly maps each parameter to its meaning and example. No wasted words.

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?

There is no output schema, and the description does not describe the return value or how suggestions are presented. For a generative tool, knowing whether the result is a single chord, a ranked list, or a set of options is important. The description is minimally sufficient for parameter passing but incomplete for fully anticipating the tool's behavior.

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 provides only names and types, so the description adds meaningful semantics by explaining key as a tonal center and progression as prior Roman numeral chords, with concrete examples. It stops short of fully constraining allowed Roman numeral syntax, key formats, or progression length, but the basic call semantics are clear.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: suggesting functional harmonic continuations for a Roman numeral progression. It names the resource (harmonic continuation) and the action (suggest), but it does not explicitly distinguish itself from sibling tools like analyze_harmony or check_voice_leading.

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 implied: this is for continuing an existing Roman numeral progression. However, there is no explicit guidance on when to use this tool versus alternatives, nor any mention of exclusions or related 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?

No annotations are provided, so the description carries the full burden. It states the action (switch) which implies a state change, but doesn't disclose whether this affects the in-memory document, whether save/undo is needed, whether rendering is triggered, or what happens to playback state when switching modes. For a state-changing tool, this is a significant gap.

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 concise and front-loaded with the tool's purpose. The Args section is a bit redundant with the schema but the overall length is appropriate. No wasted words.

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 state-changing tool with no annotations and no output schema explanation, the description provides only the minimum: what the parameter values are. Missing completely are behavioral consequences of mode switching, when this tool is the right choice, and what the expected result of a successful invocation looks like.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It does enumerate the allowed values for 'mode' (write, engrave, play, print, setup), which is helpful, but it doesn't explain the semantics of each mode beyond their names. No context about what switching to each mode does or what constraints exist.

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 the verb and resource ('Switch Dorico's workspace window mode') which makes the basic purpose clear, but it doesn't distinguish this from siblings like navigate or connect_to_dorico in terms of scope. There's no mention that this is the correct tool for moving between Dorico's five 'modes' rather than for general navigation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided about when to use switch_mode versus the sibling tools (navigate, playback, get_status). The agent is left to infer that switching modes is distinct from navigation or playback operations, but this is never stated.

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 several important behavioral traits despite no annotations: the operation is selection-only (reads the current selection), it maps to specific catalogued NoteEdit commands, and the result carries registry_status that must be read before trusting the transposition. It stops short of detailing failure modes or how registry_status should be handled, but this is substantial transparency given zero 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 compact and highly informative, with each sentence earning its place: the operation statement, parameter meanings, the selection prerequisite, the command mapping, and the important caveat about registry_status. It is structured to front-load the core purpose and then layer practical usage 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?

Given the output schema exists and no annotations are present, the description covers the critical usage flow: select first, transpose, then check registry_status and the score. It does not fully document failure cases or the exact meaning of registry_status values, but for a tool of this complexity it is sufficiently complete for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, and it does: 'direction' is defined as up/down, 'chromatic' is explicitly explained as a semitone step, and 'octave' is explained with the precedence note. However, the description does not explain the exact format or validation of 'direction' beyond the two shown options, and enums are not specified in the schema, leaving minor ambiguity.

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 ('Transpose'), a specific resource ('current selection'), and the two directions, while 'chromatic' and 'octave' support clearly differentiate it from pitch-editing siblings like add_notes or run_command. It clearly identifies the underlying Dorico commands it maps to, so an agent knows exactly what operation it performs.

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: make a selection first, operates on whatever is selected, and direction is required. It gives no ambiguity about when to use this tool, and the selection prerequisite is stated directly.

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?

With no annotations, the description carries the behavioral burden and does disclose meaningful traits: caret means 'live caret entry', musicxml means 'full score export and import into a new flow', and preflight runs offline range and voice leading analysis before dispatching commands. It also states the return contains execution report, warnings, and caveats. It stops short of explicit side-effect and precondition disclosure, such as whether an active Dorico connection is required or whether caret mode mutates the current document, so it is not a 5.

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 docstring-style layout is front-loaded with a one-sentence purpose, then clean Args and Returns sections. Every line provides distinct call-relevant information, with 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?

The description covers main invocation decisions and return shape, and the output schema plus nested ScoreIn schema fill in structural detail. However, it omits important preconditions and failure context for a mutating tool: it does not mention requiring a Dorico connection, write mode, or what happens on partial failure. These gaps matter given there are no annotations and siblings like connect_to_dorico and switch_mode exist.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% at the top level, and the Args section compensates: method explicitly lists its two valid modes and what they do, preflight explains its conditional behavior, and score points to the ScoreSpec schema. It adds meaning beyond the bare schema without redundantly restating the nested ScoreSpec structure.

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 and resource: 'Render a ScoreSpec into Dorico via caret input or MusicXML import.' It clearly communicates what the tool does. However, it does not distinguish this from closely related siblings like render_to_dorico or import_musicxml, so the differentiation is left implicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given for when to prefer this tool over alternatives such as render_to_dorico, read_score, or import_musicxml. The method parameter describes two internal rendering strategies, but there is no tool-level usage context, preconditions, or exclusions.

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