MusoKit music tools

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

The readOnlyHint and openWorldHint annotations already establish this as a safe, local, side-effect-free computation, so the description only needs to add output-behavior detail. It does add that results are broken out as straight/dotted/triplet note lengths, but it says nothing about which note values are returned or how the result is structured.

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?

A single dense sentence that front-loads the core transformation and appends the practical use cases; there is no filler and nothing redundant.

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, side-effect-free converter with readOnly annotations, the description covers the input domain, the nature of the output, and typical uses. The only gap is that the return shape (e.g., keys per note value) is unspecified and there is no output schema to fall back on.

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% for the single bpm parameter, so the description is the only source of parameter meaning. It indirectly identifies bpm as 'a tempo' but offers no unit clarification (BPM vs Hz) and never mentions the schema's 20-400 range, so it only partially compensates for the coverage 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?

The description states a precise transformation: tempo -> note lengths in milliseconds, with the three subdivision types named (straight, dotted, triplet). No sibling tool (capo_finder, chord_info, scale_info, transpose_chords) does timing conversion, so the agent can identify this tool's unique job immediately.

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

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

It gives concrete application contexts (setting delay, reverb pre-delay, LFO times), which tells the agent when this tool is the right pick. It stops short of any when-not-to-use or alternative-tool routing, but no plausible alternative exists among the 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds that it returns the top options plus a link to the capo calculator, which is mild behavioral value, but it says nothing about how many options, ordering criteria, or failure behavior for unparseable chords.

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 zero waste; the purpose and the return are both front-loaded and no sentence is redundant.

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, read-only, single-parameter tool with no output schema, the description covers purpose, input intent, and a rough sense of the return value. It is nearly complete, with only minor gaps around result count or error handling.

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?

Only one parameter, and schema description coverage is 100% with a concrete format example ("Bb Gm Eb F"). The description adds no further syntax or formatting guidance beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb and resource: finds the capo fret for a song's chords, with the rationale (easiest open chord shapes) and the return (top options and a calculator link). It is clearly distinct in intent from siblings like transpose_chords or chord_info, though it never explicitly names an alternative to contrast with.

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 opening clause 'For a song's chords' implies the usage context, but there is no statement of when to prefer this over transpose_chords or chord_info, and no prerequisites or exclusions. Usage is left to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond the annotations: the response contains notes, formula, fingering, free diagram image URLs and a listening link. It omits any error behavior for invalid symbols, 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?

A single sentence that front-loads the concrete outputs and then the extras (image URLs, listen link). It is dense but every clause earns its place; a slightly cleaner split of primary payload vs. extras would be ideal.

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

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

For a read-only, single-parameter lookup with no output schema, the description does the necessary work by describing what comes back, including media URLs that an agent would not otherwise anticipate. It still does not explain behavior on an invalid or unknown chord, leaving a minor gap.

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

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

Schema description coverage is 100% and the single chord parameter is documented with the same example symbols quoted in the description, so the schema already carries the semantics. The description adds no new syntax or format rules, so the baseline of 3 applies.

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 resource (a chord symbol) and enumerates the payload: notes, formula, guitar fingering, diagram image URLs and an audio link. An agent can distinguish it from scale_info and transpose_chords. The action verb is only implied (it reads as a noun phrase rather than 'returns X for Y'), which keeps it 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?

There is no when-to-use or when-not-to-use guidance and no routing to alternatives such as scale_info for scales or transpose_chords for changing key. Usage is only implied by the resource being a chord. Nothing tells the agent what to do for an unrecognized chord symbol.

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

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

Annotations already assert readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real context beyond that: the output is a link the user opens rather than an action performed here, and presets are applied "where possible" — clarifying that not every option maps to every tool.

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, zero filler; the return-value nature and the usage trigger are both front-loaded, and the examples are compact.

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?

No output schema, but the description explains what comes back (a ready-to-open link) and how options are applied. With annotations covering the safety profile, enum-heavy params documented in the schema, and only one required parameter, nothing essential is missing.

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

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

Schema description coverage is 80% and already labels bpm/beats/frequency/instrument as tool-specific, so baseline is 3. The description adds the presetting model (tool + its applicable options become pre-configured state), which helps an agent understand why options are conditional on the tool enum.

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+resource: returns a ready-to-open link to a MusoKit tool, with examples of preset behavior (tuner for an instrument, metronome at a tempo, tone at a frequency). It implicitly separates itself from the informational siblings (chord_info, scale_info, bpm_to_ms) but never names them explicitly.

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?

"Use when the user needs to actually tune, keep time or hear something" gives a clear triggering condition and implicitly contrasts with the lookup/calculation siblings, which only supply information rather than a usable tool. No explicit when-not or named alternatives.

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

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

Annotations only declare readOnlyHint and openWorldHint, leaving the return shape to the description — and the description fills that gap by disclosing that the result includes a listening link plus piano and guitar renderings. It is silent on behavior for unrecognized scale names or default scale handling, keeping it out of 5 territory.

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

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

Front-loads the core purpose in one sentence and appends the supported values compactly. The enumerated scale list is long but functional rather than padding, since no enum exists in the schema.

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

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

With no output schema, the description covers the return content (notes, step pattern, links), and both parameters are documented. Only error/fallback behavior for invalid scale input is unaddressed.

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

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

Schema coverage is 100% so the baseline is 3, but the schema has no enums and the description supplies the full set of accepted scale names, which is genuine meaning beyond the schema. The root format is left entirely to the schema.

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

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

States a specific resource (scale/mode notes and step pattern) and what accompanies it (audio link, piano/guitar visualization), which is unambiguous about what the tool returns. It does not explicitly contrast itself with chord_info or the other music siblings, so it stops 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?

There is no statement of when to reach for this tool versus sibling tools like chord_info or transpose_chords; the long scale list reads as parameter enumeration rather than usage guidance. Retrieval context is only weakly implied by the resource named.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safe-read profile is covered. The description adds genuinely non-redundant information: the call returns the new chords plus a link to a transposer, which matters because no output schema exists to convey that.

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 tightly written sentences with the core action front-loaded and the return behavior second. No filler, no restatement of the tool name or title.

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 read-only utility with full schema coverage and no output schema, the description covers the essentials, including the return shape. It stops short of clarifying the coupling between from_key and to_key or how conflicting semitones/key inputs are resolved, which would have removed the last ambiguity.

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

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

Schema description coverage is 100%, so every parameter is already documented (chords format, target key, original key as alternative to semitones, positive=up). The description only restates the semitone-vs-key duality already present in the schema, adding essentially no new parameter meaning.

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) and resource (chord progression) and enumerates both operating modes: by semitones or by key-to-key conversion. No sibling tool (chord_info, scale_info, capo_finder) overlaps this function, so the purpose is unambiguous without needing to name an alternative.

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 'either by semitones or from one key to another' implies the two calling modes but never states when to prefer one over the other, nor what happens if both are omitted or supplied together. Usage is inferable from the schema rather than spelled out.

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