Guitar learning tools from Fretwork: name a chord from its frets, see open and barre chord shapes, transpose songs, find capo positions, show scales on the fretboard, find a song's key, find public-domain songs for the chords you know, check your level and build a daily practice plan. Read-only, no sign-in.
Scored across 9 tools
Most tools have clearly distinct input/output purposes: identifying chords, finding chord shapes, scales, keys, songs, and practice plans are well separated. There is some overlap between find_capo and transpose_chords, both of which suggest capo positions, and find_key partially overlaps get_scale by recommending scales.
The set mostly follows a verb_noun convention such as find_capo, get_scale, identify_chord, make_practice_plan, and transpose_chords. The main deviation is guitar_level_check, which is noun-oriented rather than verb_noun, but it remains readable.
Nine tools is a good scope for a guitar-learning and theory assistant. Each tool covers a distinct practical task and the set does not feel padded or thin.
The surface covers core guitar workflows: chord identification and shapes, scales, keys, transposition, capo placement, song discovery, level assessment, and practice planning. Minor gaps exist around rhythm/strumming resources, tuning, or saving/progress tracking, but agents can work around them for most stated tasks.
Works out where to put a capo. Give the key you want to sound in (for example to match a singer or a recording) and, optionally, the open-chord key you want to play shapes in. Returns the capo fret, or the easy options if no shape key is given.
| Name | Required | Description | Default |
|---|---|---|---|
| shape_key | No | Optional. The key whose open chord shapes you want to play, e.g. "G" or "Em". | |
| sounding_key | Yes | The key the music should sound in, e.g. "Bb", "F# minor". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this a read-only, idempotent, closed-world operation, so the safety profile is covered. The description adds genuine behavioral context by describing the return shape: a capo fret, or a set of easy options when no shape key is supplied — valuable given there is no output schema.
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 with zero filler: purpose first, input guidance second, return behavior last. No sentence is redundant with the title or 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?
For a two-parameter, read-only lookup with no output schema, the description supplies both the input expectation and the return behavior. Only a minor gap remains in not stating whether the returned easy options are ranked or formatted in a specific way.
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 would be 3, but the description goes beyond the schema by explaining the consequence of omitting shape_key (you get a range of easy options instead of a single fret) and by giving interpretive framing for both keys.
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 ("works out where to put a capo") and immediately ties it to the two inputs, so an agent can distinguish it from siblings like find_key or transpose_chords without opening the schema.
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 situations for use (to match a singer or a recording) and explains the conditional case for the optional shape_key, including what happens when it is omitted. It stops short of explicitly naming which sibling tool to use instead when the agent wants an alternative approach, but the context is otherwise unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Works out the most likely key of a song from its chord progression, gives each chord its Roman numeral, lists the other chords that belong to the key, and suggests which scale to solo with.
| Name | Required | Description | Default |
|---|---|---|---|
| chords | Yes | The chords in order, e.g. "G D Em C" or "Am F C G". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the bar is lower; the description still adds real value by disclosing the return content (Roman numeral analysis, diatonic chord list, recommended solo scale) and by hedging with 'most likely key', signaling a heuristic rather than a definitive answer.
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 front-loaded sentence: the core action comes first, then the outputs are listed in a compact parallel clause. No filler and no repetition of the 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?
With no output schema, the description correctly compensates by naming what comes back, which is exactly what an agent needs to decide whether this tool answers its question. Minor gap: no note on ambiguity handling or on whether an error is raised for unrecognized chord symbols.
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 with 100% schema description coverage, including a concrete format example ('G D Em C'), so the schema carries the burden. The description adds nothing about chord syntax, accepted separators, or how accidentals/enharmonic spellings are handled.
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 — derive the likely key of a song from a chord progression — and then enumerates the derived outputs (Roman numerals, diatonic chords, solo scale), which cleanly separates it from siblings like get_scale or transpose_chords that operate on already-known keys.
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 is only implied: the agent can infer you call this when you have a chord list and want the key, but the description never states when to prefer it over get_scale or transpose_chords, nor any exclusions. No mention of what to do with ambiguous or modal progressions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Finds songs a guitarist can play with the chords they already know, from Fretwork's free library of 87 public-domain folk, gospel, blues, campfire and Christmas songs. Each song has chords, key, time signature, level and a free play-along page. Can also list songs that need just one or two new chords.
| Name | Required | Description | Default |
|---|---|---|---|
| level | No | Filter by level (default any). | |
| chords_known | Yes | Chords the player can already play, e.g. "G C D Em". | |
| max_new_chords | No | Also include songs needing up to this many extra chords (default 0). | |
| time_signature | No | Filter by time signature (default any). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish that this is a read-only, idempotent, non-destructive, closed-world lookup. The description adds useful context about the library scope, song metadata, and the ability to include songs needing extra chords, though it does not mention ordering or result limits.
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 definition is front-loaded and only three sentences long. The middle sentence listing song metadata and the play-along page is useful because there is no output schema, though it is slightly catalog-like rather than essential.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description helpfully states that each song includes chords, key, time signature, level, and a play-along page. It is complete enough to call correctly, but it does not describe result ordering, pagination, or exact return shape.
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 all four parameters are already documented in the schema. The description reinforces the meaning of chords_known and max_new_chords in natural language, but it adds little syntax or interpretation beyond what the schema already provides.
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: finds songs a guitarist can play using chords they already know. It also scopes the result to Fretwork's 87-song public-domain library and distinguishes itself from sibling tools by focusing on songs rather than chords, keys, scales, or transposition.
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 use case is clearly implied: a guitarist supplies known chords and gets playable songs, optionally allowing one or two new chords. However, it does not explicitly say when to use this instead of siblings like find_key, find_capo, or transpose_chords, nor does it state exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns playable guitar shapes for a chord name (open position and movable barre shapes), with frets, fingering where known, the notes in the chord and a text chord diagram. Handles major, minor, 7, maj7, m7, sus2, sus4, add9, 6, m6, 9, dim, m7b5, dim7, aug, power chords and slash chords such as G/B.
| Name | Required | Description | Default |
|---|---|---|---|
| chord | Yes | Chord name, for example "F", "Bm", "F#m7", "Cadd9", "Bbmaj7", "G/B", "E5". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, so safety and determinism are covered. The description adds real context beyond that: the return payload shape (frets, fingering 'where known', note spellings, text diagram) and the fact that fingering may be missing, which sets expectations for a partial response.
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?
One dense sentence, front-loaded with the verb and resource, with the chord-type list placed at the end as supporting detail. The enumeration is long but each entry reduces the chance of an unsupported-chord call, so it earns most of its space.
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 carries the burden of describing the return value, and it does so concretely (shapes, frets, fingering where known, notes, text diagram). For a single-parameter read-only lookup, an agent has everything needed to call it 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 coverage is 100% and the single parameter is well exemplified, so the baseline is 3. The description earns a point by enumerating the accepted chord vocabulary (maj7, m7b5, dim7, sus, add9, power chords, slash chords like G/B), which tells the agent what syntax will actually resolve beyond the handful of schema examples.
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 ('Returns playable guitar shapes for a chord name') and immediately scopes what comes back: open and barre shapes, frets, fingering, notes, diagram. This clearly distinguishes it from the inverse-direction sibling identify_chord, which takes shapes and returns a 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?
Usage is only implied by the input ('for a chord name'), and there is no explicit routing guidance toward identify_chord, get_scale, or transpose_chords. An agent can infer when to call it, but nothing states when not to or which sibling to prefer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Gives the notes of a scale in any key and where they fall on the guitar fretboard (standard tuning), string by string, with root notes marked. Scales: major, natural minor, harmonic minor, melodic minor, the seven modes (dorian, phrygian, lydian, mixolydian, locrian), minor pentatonic, major pentatonic, blues and major blues.
| Name | Required | Description | Default |
|---|---|---|---|
| root | Yes | Key note, e.g. "A", "F#", "Bb". | |
| scale | Yes | Scale type, e.g. "minor pentatonic", "major", "blues", "dorian". | |
| to_fret | No | Highest fret to show (default 12). | |
| from_fret | No | Lowest fret to show (default 0). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is covered and the description doesn't need to restate it. The description does add genuine context beyond annotations: standard tuning only, root notes visually marked, and output organized string by string. It stops short of anything further, so 3 is the right level with annotations doing the safety work.
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, front-loaded with the core action and output shape before the scale catalog. The long scale list is bulky but earns its place because it substitutes for a missing enum; without it the tool would be guess-prone.
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 carries the return-value burden and does so reasonably: it tells the agent to expect per-string note positions with roots marked. Combined with complete param docs and safety annotations, an agent has enough to call it correctly; only the exact return structure (data format, whether notes or fret numbers are returned) is left 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 coverage is 100%, so baseline is 3, but the description adds real value for the `scale` parameter, which has no enum in the schema: it enumerates the accepted scale names (major, natural/harmonic/melodic minor, the seven modes, the two pentatonics, blues and major blues). It says nothing extra about from_fret/to_fret, which the schema already documents with defaults and bounds.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: it returns the notes of a named scale plus their fretboard positions, string by string, with root notes marked. It also pins the tuning (standard), which cleanly separates it from chord-oriented siblings like get_chord_shapes and identify_chord.
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 domain is clear enough that an agent can infer this is the tool for scale/chart requests rather than chord or song lookup, but there is no explicit statement of when to prefer it over siblings such as get_chord_shapes, nor any preconditions or exclusions. Usage is implied by the subject matter rather than guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
A quick self-assessment that places a guitarist on Fretwork's 10-stage learning path (Stage 0 Getting Started to Stage 9 Artistry) from yes/no answers to up to nine questions about what they can already play, and says what to learn next. The questions build on each other, so answers are read in order up to the first "no". Called with no answers, it returns the nine questions.
| Name | Required | Description | Default |
|---|---|---|---|
| play_the_changes | No | Can you solo over a progression and target the chord tones as the chords change? | |
| tune_and_clean_notes | No | Can you tune the guitar and play a clean note on every string? | |
| change_chords_in_time | No | Can you change between basic open chords (like G, C, D, Em) in time and play a whole simple song? | |
| transcribe_and_tension | No | Can you transcribe a full solo and improvise with tension and release? | |
| bends_vibrato_full_solo | No | Can you play a solo with in-tune bends, vibrato and clear phrases? | |
| riff_blues_and_short_solo | No | Can you play a riff, a 12-bar blues and a short solo of your own? | |
| barre_chords_and_16th_groove | No | Can you play any major or minor barre chord and hold a 16th-note strumming groove? | |
| four_chord_song_with_pattern | No | Can you play a four-chord song start to finish with a strumming pattern? | |
| keys_and_pentatonic_anywhere | No | Can you name the chords in any key and solo with the pentatonic scale anywhere on the neck? |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, closed-world and non-destructive, so the safety profile is covered; the description adds the non-obvious short-circuit rule (answers read in order to the first "no") and the zero-argument discovery mode. It does not state the order the questions are evaluated in relative to the schema properties, nor what the return value looks like beyond "what to learn next".
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 sentences, front-loaded with the purpose, then the evaluation rule, then the no-argument mode — every sentence carries information. The parenthetical enumerating the stage range is slightly heavy but earns its place by defining the scale.
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 carries the return-value burden and does so partially: it says the tool returns a stage placement, a next-step recommendation, and, when called bare, the nine questions. It leaves the concrete response shape (stage number vs. name, whether next steps are a list) 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 coverage is 100%, so the schema already explains each boolean question, making 3 the baseline. The description adds genuine meaning the schema cannot express: that the nine answers are interdependent and evaluated sequentially rather than independently, and that all of them are optional.
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 verb and resource — a self-assessment that places a guitarist on a named 10-stage path — and states the exact scope (Stage 0 to Stage 9) plus the outcome (what to learn next). An agent can tell this apart from find_key, get_scale, or transpose_chords without opening any schema.
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 establishes clear context: this is a yes/no self-assessment, partial answers are fine because reading stops at the first "no", and calling with no answers returns the nine questions. It stops short of naming when to prefer a sibling such as make_practice_plan, which is the natural next step once a stage is known.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Names the chord a guitarist is holding from the fret on each string (standard tuning), lists its notes and returns a chord diagram. Use when someone asks "what chord is this?" and gives frets like x32010, 3-2-0-0-0-3 or "0 2 2 1 0 0" (low E string first; x = muted string).
| Name | Required | Description | Default |
|---|---|---|---|
| frets | Yes | Six frets from the low E string to the high e string. Use x for a muted string, 0 for open. Examples: "x32010", "3 2 0 0 0 3", "8-10-10-9-8-8". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already pin down the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower; the description still contributes by disclosing the accepted input dialects, the muted/open conventions, and the fact that it returns notes and a diagram rather than just a name. It does not mention failure behavior for unplayable fingerings, which keeps it from 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?
Two sentences, zero padding; the purpose and outputs come first, then the concrete invocation condition with examples. Every clause 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 single-parameter, schema-complete, annotation-rich tool with no output schema, the description covers what it returns (name, notes, diagram) and how to phrase the input. Nothing an agent needs in order to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline would be 3; however the description adds value by restating the low-E-first ordering alongside the schema and by showing the space-separated dialect ('0 2 2 1 0 0') in a natural-language sentence, reinforcing that separators are flexible. It stops short of stating the valid fret range or how many frets are required beyond the schema's own wording.
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 pair ('Names the chord a guitarist is holding'), and explicitly enumerates the three outputs: chord name, constituent notes, and a chord diagram. It is the inverse of the sibling get_chord_shapes (which returns shapes for a named chord), and the phrasing makes that direction unambiguous.
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?
Gives an explicit trigger: 'Use when someone asks "what chord is this?" and gives frets like x32010, 3-2-0-0-0-3 or "0 2 2 1 0 0"'. No exclusionary guidance is offered against alternatives such as get_chord_shapes or find_key, but the usage condition is concrete enough that an agent can route correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Builds a daily guitar practice routine and a 4-week focus plan sized to the player's level, the minutes they have each day and their goal (songs, strumming, fingerpicking, lead, barre chords, theory or general). Uses Fretwork's 10-stage curriculum, where stage 0 is for someone who has never played.
| Name | Required | Description | Default |
|---|---|---|---|
| goal | No | Main goal (default general). | |
| stage | No | Fretwork stage 0–9 (0 = never played, 1 = first chords, 2 = rhythm & songs, 3 = riffs & first solos, 4 = barre chords, 5 = scales & keys, 6 = lead guitar, 7–9 = advanced). | |
| days_per_week | No | Practice days per week (default 5). | |
| minutes_per_day | No | Practice minutes per day (default 20). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, non-destructive, closed-world. The description adds useful domain context: it draws on Fretwork's 10-stage curriculum and stage 0 is a first-timer. It doesn't describe output shape in detail, but the 'daily routine + 4-week plan' framing hints at it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with what is produced, then the sizing inputs, then the curriculum reference. 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?
With four optional params, no output schema, and rich annotations, the description gives enough to call correctly. The only gap is a fuller description of the returned plan structure, which matters slightly more because no output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the stage ladder, goal enum, and defaults are all documented in-schema. The description's mention of 'stage 0 is for someone who has never played' restates the schema, adding no new parameter semantics. Baseline 3.
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?
Specific verb+resource: builds a daily practice routine plus a 4-week focus plan, parameterized by level, minutes, and goal. Clearly a planning tool, distinguishable from lookup siblings like find_songs or get_chord_shapes without opening the schema.
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 establishes clear context (player level, daily minutes, goal) that implies when to call it, and no sibling overlaps with plan generation. It stops short of stating any exclusion or when-not condition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Moves a song's chords to a new key. Accepts a chord list, a chord chart with lyrics (chord lines are transposed, lyric lines are kept), or inline [C] chords. Give either from_key and to_key, or a number of semitones. Also suggests capo positions that let the guitarist keep easy open shapes in the new key.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | The chords or chord chart, e.g. "G D Em C" or a chart with chord lines above lyrics. | |
| to_key | No | Target key, e.g. "Bb" or "C minor". | |
| from_key | No | Current key, e.g. "G" or "A minor". Optional if semitones is given; if missing, the first chord is used. | |
| spelling | No | Accidentals for the result. auto follows the target key. | |
| semitones | No | Semitones to move (+ up, - down). Used when to_key is not given. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds real behavioral detail: chord lines are transposed while lyric lines are preserved, inline bracket chords are handled, and capo suggestions are produced as a side output. It doesn't say what the return payload looks like (single string vs. structured result), which keeps it from 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?
Three short sentences, zero waste, with the core action front-loaded and input modes and capo behavior following in priority order. Every sentence contributes new information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 5-parameter, single-required-param tool with no output schema, the description covers input formats, both transposition modes, and the capo side effect — enough to call it correctly. A brief note on the shape of the returned result would close the last 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 coverage is 100%, so baseline is 3; the description adds value by framing from_key/to_key and semitones as mutually exclusive input modes and by restating the three text formats in prose. It doesn't clarify spelling behavior or the first-chord fallback beyond what the schema already documents, so it is a modest gain over 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?
States a specific verb and resource — "Moves a song's chords to a new key" — and enumerates the three accepted input shapes (chord list, chord chart with lyrics, inline [C] chords), which makes it unmistakable against siblings like identify_chord or find_key. It does not explicitly differentiate itself from find_capo even though it also emits capo suggestions, 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?
"Give either from_key and to_key, or a number of semitones" is useful mode-selection guidance for invocation, but the description never says when to reach for this tool instead of find_capo (which also handles capo positions) or get_scale. Usage is implied by the purpose rather than contrasted with alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
find_capofind_keyfind_songsget_chord_shapesget_scaleguitar_level_checkidentify_chordmake_practice_plantranspose_chords
Add one secure layer between your agents and this server.