ScanSing: sheet music to MusicXML

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds real value beyond that: it discloses cost characteristics (cheaper than MusicXML) and side-effect absence (nothing is re-recognised), plus interpretation semantics for key vs keyName/mode.

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 compact sentences with no filler; the content list is front-loaded and the key/keyName caveat follows as a targeted clarification. Slightly awkward opening ('What is in a recognised score') is a minor structure cost but the text earns its length.

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

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

An output schema exists, so return values needn't be explained; the description nonetheless clarifies the one ambiguous field pairing (key vs keyName/mode). Combined with the cost/side-effect hints, an agent has enough to call this correctly, with only the `file` collection-mode usage left implicit.

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 both parameters (file, recognition_id) are fully documented in the schema. The description adds nothing about parameters – notably it never explains the collection-mode `file` selector – 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?

The description enumerates exactly what a recognised score returns (title, composer, key, time signature, tempo, duration, per-part name/range/clefs/lyrics), which makes the resource and its payload unmistakable. It never states the verb outright (it describes contents rather than saying 'returns a summary of'), so an agent infers 'describe' from the name, but the resource is clear enough to distinguish it from export/get_musicxml 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?

'Cheaper than reading the MusicXML' implies the trade-off versus get_musicxml, and 'nothing is recognised again' hints the recognition is already done. However, no sibling is named explicitly and there is no stated when-not condition (e.g. when you need the actual notation, use get_musicxml/export_score).

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds genuinely useful behavioral detail beyond that: one track per part, optional single-part export, transposition, and the non-obvious rule that repeats are played only once.

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 compact sentence covering output format, optionality and the repeats rule, with the key facts front-loaded. Slightly noun-phrase phrasing ('A link to...') but no wasted sentences.

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 six well-documented parameters and an output schema, the description needn't explain return values, and it covers the salient behaviors (track layout, transposition, repeat handling). Only the relationship to sibling export tools is left unstated.

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 (key, part, semitones, save_to, file, recognition_id) is already documented in the schema. The description only alludes to part and transposition, adding no syntax or format detail beyond what the schema provides; 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?

The description states a specific resource and output form: the score as a MIDI file, one track per part, with optional single-part and transposed variants. It is clear what the tool produces, though it never explicitly distinguishes itself from siblings like export_score or get_download_link.

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?

'to listen to or rehearse with' implies a use case (playback/practice rather than notation editing), but there is no explicit when-to-use or when-not-to-use guidance relative to siblings such as export_score or transpose_score, leaving the agent to infer selection.

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 cover the safety profile (readOnly, idempotent, non-destructive), yet the description still adds material facts: the returned link is short-lived, nothing is re-recognised, no pages are charged, and the layout is regenerated from MusicXML rather than overlaid on the scan. The only omission is how long 'short-lived' actually is.

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 most important fact — a short-lived link, PDF or PNG — is front-loaded, and each following clause carries information (engraving source, no re-recognition, no page charges). It is slightly rambling with awkward mid-sentence line breaks, but 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?

Eleven parameters, but only one required; the schema is fully documented and an output schema exists, so the description needn't restate fields or return shape. It supplies the essential context — cheap re-export from existing MusicXML, works on original or label_notes recognitions. Only the link lifetime and collection-mode ('file') usage are left implicit.

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?

With 100% schema description coverage the schema already explains every parameter, so baseline is 3. The prose adds real meaning only for a few: that labels of a label_notes recognition are engraved under the notes, and that part/transposition/labels can be applied 'on the way'. The other nine parameters (paper, scale, page, file, labels_key, semitones, format...) are 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?

The opening states the concrete output (a short-lived link to a freshly engraved score) and enumerates the two formats: PDF of every page or PNG pages. It also clarifies the key differentiator from a scan-based export — 'laid out anew from the MusicXML, not drawn over the scan'. It never names the closest sibling (export_midi / get_download_link), so an agent must infer that separation itself.

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: 'Works on any recognition: the original, one from label_notes...' plus 'no pages are charged' hints this is the cheap, repeatable way to produce a viewable artefact. There is no explicit statement of when to prefer this over export_midi, get_download_link, transpose_score or label_notes, even though the 'transposed or labelled on the way' phrasing overlaps visibly with those 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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds only that output is MusicXML for a subset of parts; it says nothing about the save_to write path (schema notes stdio-only) or that extraction requires a completed recognition.

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 sentences with zero filler, and the core resource (part MusicXML from a recognised score) is front-loaded. The opening noun fragment is slightly clipped but effective.

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

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

With an output schema, full parameter descriptions and complete annotations, most burden is lifted; the description only needs to convey scope and the part-name lookup path, which it does. The remaining gap is the relationship to get_musicxml/export_score, which an agent may need to disambiguate sibling choice.

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%, including the accepted part id/name/number formats and multi-part comma syntax, so the schema carries the burden. The description contributes the extra fact that valid part names come from describe_score, which slightly helps the `part` parameter but is not format detail beyond the schema.

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

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

States a specific verb+resource: returns the MusicXML of one or a few parts of a recognised score, with a concrete example (alto line of a choir piece). It does not explicitly distinguish itself from get_musicxml or export_score, so the agent must infer that this is the partial-extraction counterpart.

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 one concrete workflow hint — 'Part names are in describe_score' — which tells the agent how to obtain a valid `part` value. However, it never states when to choose this over get_musicxml/export_score or what happens if the score isn't recognised yet.

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 readOnly/idempotent/non-destructive, and the description adds cost-relevant reassurance ('Nothing is recognised again, no pages are charged') plus result semantics (nearest first, key, empty means no shift fits). That is genuine context beyond the annotations, though it omits any note on limits or performance.

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

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

The core operation is front-loaded, but the opening is a long run-on sentence and the parentheticals ('a singer's voice, an instrument's compass, a kalimba's tines') are decorative rather than informative, diluting clarity.

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

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

Given an output schema and full annotations, the description only needs to supply intent, cost behavior and follow-up routing, all of which are present. The only gap is the absence of explicit when-not guidance.

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 low/high/part/file are already documented. The description adds only the part-scope default ('the whole score') and the semitones handoff, which is marginal extra meaning over the schema.

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

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

The description names the specific operation: determining whether a part's notes lie within a low…high range and enumerating the transpositions that fit. It also ties the result to transpose_score, which separates it from that sibling, though the phrasing is roundabout.

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 states the default scope ('default: the whole score') and gives a clear next step ('Pass a shift's semitones to transpose_score'), but never says when to use this versus transpose_score or describe_score, nor any 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?

Annotations already cover safety (readOnly, idempotent, non-destructive), but the description adds genuinely useful traits beyond them: the link expires with the recognition (~1 hour) and requires no auth key. It also explains that MP3 is the MIDI rendered and inherits its tempo, which affects how the transposition params behave per format.

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 fact (keyless, short-lived link) in the first sentence, and each subsequent sentence covers a distinct concern. Slightly fragmented by the trailing MP3 remark, but there is little waste.

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

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

With an output schema present, return-value detail is unnecessary, and the description covers lifetime, auth, intended consumers and the format caveat. Minor gaps remain around collection-mode `file` behavior and error cases, but nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so all eight parameters are already documented, and the description largely restates the schema's `labels` explanation rather than adding semantics. The one net-new point, that MP3 has no tempo of its own, is marginal against a fully documented schema.

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

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

States a specific verb+resource: returns a short-lived, keyless link to the MusicXML, MIDI or MP3 of a recognition. It implicitly separates itself from file-returning siblings like export_score and export_midi by framing the result as a shareable link, but never names them.

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 'give it to the user to open in a browser, MuseScore, Sibelius or a DAW' clause gives real usage context. However, nothing says when to prefer this over get_musicxml, export_score or export_midi, and no prerequisites or exclusions 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?

Annotations already cover read-only, idempotent, non-destructive safety. The description adds meaningful behavior beyond them: paged delivery ('a slice at a time'), an alternative local-file mode, and the non-obvious billing rule that labeling notes incurs no page charges — something no annotation or schema conveys.

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 the resource front-loaded and the modal alternative and billing caveat in the same breath. 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?

An output schema exists, so return-shape explanation is unnecessary. The description covers slicing, the file-save variant, and cost behavior; it could note how to continue paging across slices, but the offset parameter in the schema carries that.

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

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

Schema description coverage is 100%, so the baseline is 3; labels_key, save_to, max_chars, and offset are all documented there. The description only vaguely reinforces slicing and labels, adding little beyond what the schema already states.

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

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

States a specific verb and resource: retrieves MusicXML for an earlier recognition, delivered as a slice or written to a local file. It does not name a sibling it is explicitly distinct from (get_recognition, export_score), but the resource is concrete enough to disambiguate.

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?

'of an earlier recognition' implies a recognition must exist first, and the labels clause points to label_notes for that feature's semantics. Beyond that it gives no guidance on when to prefer this over get_recognition, inspect_score, or export_score.

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

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

The annotations already establish that this is a read-only, idempotent, non-destructive operation. The description adds that it retrieves status and summary for an existing recognition, but does not describe async behavior, statuses, or result characteristics beyond 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?

The description is a single efficient sentence with no wasted words. It front-loads the operation and resource clearly.

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 rich annotations, a fully described single parameter, and an output schema, the description is largely complete. A bit more explicit guidance about when to use it after recognize_sheet_music would make it fully self-contained.

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 recognition_id parameter is documented as the ID returned by recognize_sheet_music, including an example prefix. The description adds little beyond the schema, which is appropriate at 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?

The description states a specific resource and operation: retrieve the status and summary of an earlier recognition. It is clear enough to distinguish from the sibling recognize_sheet_music, though it does not explicitly name that alternative in the description itself.

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 implied by 'earlier recognition,' and the schema parameter description ties the ID to recognize_sheet_music. However, the description does not explicitly say when to use this tool, when not to, or what alternatives exist.

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

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

The annotations already mark this as non-read-only, non-idempotent, closed-world, and non-destructive. The description adds important operational details beyond that: the URL works once, expires in 15 minutes, the upload waits for recognition, and prints a summary containing `id`.

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 dense but appropriately sized for a multi-step remote upload workflow. It is front-loaded with the core purpose and then covers execution, timing, follow-up, and exclusions without waste.

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

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

Given an output schema and 100% schema coverage, the description need not explain return values. For a remote upload workflow with expiration and follow-up requirements, the definition supplies everything an agent needs to select and invoke it correctly.

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

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

Schema coverage is 100%, so the schema already documents all five parameters. The description only references a FILE placeholder in the command and does not add meaning for `mode`, `pages`, `labels`, or `labels_key`, 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 states a specific resource (a one-off upload URL) and its purpose (uploading a local file so it is recognized on a remote server). It also distinguishes this from the sibling path for chat attachments: 'Not for a file attached to the chat: pass that to recognize_sheet_music as `attachment`.'

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 explicit when-to-use guidance: the file is on the user's machine and the server is remote. It also explains the exact workflow (run the returned `command` with the file path in place of FILE), what happens next, and which follow-up tools to use with the resulting `id`.

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 readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds genuinely non-obvious behavior beyond that: shared keys (plan owner/shared) have no quota and return nulls, which prevents an agent from misreading null as an error.

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

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

Two short sentences, front-loaded with what the tool reports and followed by the one edge case that matters. Nothing is redundant or padded.

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?

An output schema exists, so return-field documentation is not the description's burden, and the null-value caveat is the key operational nuance. It stops short of noting anything about when the counter resets or what 'this month' means calendrically, a minor remaining 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The description correctly avoids restating an empty schema.

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

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

The description states precisely what is returned: pages used this month, pages remaining, and the plan for the calling key. That is a specific resource with a clear scope, and no sibling tool (all score/MIDI/upload tools) overlaps with it, so an agent can select it unambiguously.

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 — an agent infers it should call this when it needs quota or plan information for the current key. There is no explicit 'use this when' statement, though no alternative tool exists that would require routing guidance 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?

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered; the description goes further by disclosing the economically important traits that annotations cannot express — no recognition is performed and no pages are charged. That is exactly the value-add expected. It does not mention rate limits or what an unsupported file type returns, preventing 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, front-loaded sentences: capability first, usage second, provenance last. The API/docs sentence is mild boilerplate but does not obscure anything.

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

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

With an output schema present, return values need no explanation, and the description covers the two things an agent otherwise could not infer — that it is free of page charges and that it should be used to size work before recognition. Adequate for a read-only inspection 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 description coverage is 100%, with each of url, path, attachment and file_base64 already documented in the schema, so the baseline is 3. The description gives no additional guidance on choosing among the four input methods, which would have been the natural value-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?

States specifically that it returns a file's kind and page count, and the clause 'without recognising it or charging pages' distinguishes it from recognize_sheet_music and the other export/recognition siblings. The phrasing is noun-first rather than verb-led, which slightly softens the action, but the effect is unmistakable.

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 two concrete uses — choosing a `pages` value for a long PDF and checking quota first — and points to get_usage as the quota sibling. It lacks an explicit 'do not use this to actually transcribe; use recognize_sheet_music instead' exclusion, so it falls short of full alternative routing.

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

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

Beyond the annotations (readOnlyHint=false, non-idempotent, non-destructive), the description adds real behavioral context: a NEW recognition is produced, the source `labelledFrom` is left unchanged, nothing is re-recognised, and no pages are charged. The billing note is unusually valuable. It stops short of describing failure modes or what happens for an unlabelable note.

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?

It is front-loaded with the core behavior, but the 'as method books print it for beginners' simile and the elongated sentence structure add words that don't help an agent decide or invoke. The parenthetical tool list is useful; the rest is denser than needed.

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

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

With an output schema present, the description correctly focuses on what the return means — the new `id` is the labelled result and `labelledFrom` is the original — and covers the key/scheme interplay and the save_to write path. Complete enough to invoke confidently.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by explaining the coupling between `scheme` and `key` — movable-do, degrees and kalimba count from the key's tonic while letters and solfege-fixed name absolute pitch. That relationship is not stated in the schema.

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

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

The description states a specific verb and output: a new recognition whose MusicXML carries each printed note's name as a lyric line, with chord naming order and lyric preservation spelled out. It differentiates itself from siblings by naming the downstream tools it feeds (export_score, extract_part, transpose_score), though the opening sentence is indirect prose rather than a plain 'creates a labelled copy of a score' statement.

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 implied through the follow-up tooling ('use it with export_score for a printable PDF...') and the clarification that the original `labelledFrom` is untouched, but there is no explicit when-to-use or when-not guidance and no alternative labelling tool is 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 cover the safety profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false), and the description adds genuinely useful context beyond them: the call goes to an external ScanSing API, local paths only work in stdio mode, and a PDF is too large for base64. It does not mention latency, cost/quota (get_usage exists), or whether the result is immediate or retrieved later.

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

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

Front-loaded with the action and its output, then the input constraint, then the alternative, then the API note. Each sentence adds a distinct decision-relevant fact; the parentheticals carry real content rather than 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 an output schema present, the description need not explain return values, and it covers the tricky parts of an 11-parameter, zero-required tool (source selection, local-file limits). The one missing piece is the relationship to get_recognition/get_musicxml, which the agent would need to know to use the result after recognition.

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

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

Schema description coverage is 100%, so the baseline is 3; the description earns an extra point by stating the mutual-exclusivity rule for url/attachment/file_base64/path, which the schema does not enforce. Other parameters (mode, labels, save_to, filename) are left entirely to the schema, so it does not fully compensate for selection subtleties.

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?

Names a specific verb and resource ('Recognize a PDF or image of sheet music') and states the concrete return ('MusicXML with a summary (pages, parts, measures, warnings)'). It also routes away from get_upload_link for local files, so an agent can distinguish it from at least one sibling without opening a 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?

Gives an explicit input constraint ('Give exactly one of url, attachment, file_base64 or path') and an explicit alternative with its trigger condition ('A file on the user's own machine ... use get_upload_link instead'). It never addresses the async sibling flow (get_recognition, get_musicxml, export_score), which is the main remaining selection 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?

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description still adds real behavioral value beyond them: notes are respelled to fit the new key signature and chord symbols are transposed along with the notes.

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?

Roughly three compact clauses with the core action front-loaded and no filler. The nested parentheticals make it slightly dense to parse, but every sentence carries 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?

With a full-coverage schema and an output schema present, the description need not explain return values, and it covers the two driving parameters well. It is silent on the collection-mode/file flow and on where the transposed result lands, which are minor omissions for a transform tool with structured support.

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 description adds meaning the schema lacks – that -2 means a tone down, that key uses the nearest direction, and that supplying both key and semitones is what selects the octave. It does not clarify the similarly-named file/save_to/part parameters, which the schema handles.

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 (transposing the MusicXML/score to another key) plus concrete effects – respelling notes and moving chord symbols. It is unambiguous what the tool does, but it never contrasts itself with siblings such as fit_range or extract_part that also manipulate the score.

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

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

It explains how to choose between the two transposition modes ('by semitones' or 'to a key', and giving both to pick the octave), which is useful selection guidance at the parameter level. It offers no guidance on when to reach for this tool versus other score-manipulation siblings, so usage is only implied.

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