Cesure

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds real behavioral value beyond them: it discloses atomic validation ('every measure must read and fill its time signature, or nothing is created') and that refusals name each fault with its location, which is exactly the kind of failure semantics an agent needs before calling. It does not cover auth or overwrite behavior, 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?

The format spec genuinely needs space, and the first sentence front-loads purpose plus an example. However it is an unstructured wall of prose with redundancy ('strings from 1 (the highest)' appears twice, the time-signature rule is stated twice, and uppercase emphasis substitutes for structure) that bulleting would have made far easier to parse.

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 domain as complex as a bespoke music-notation language, the description supplies grammar, edge rules, worked examples, and a link to the full format, and an output schema exists so return values need not be explained. Nothing material is missing for correct invocation.

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

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

Although the single parameter has 100% schema description coverage, that coverage is a tautology ('the score... in the notation described above'). The description carries the entire grammar of the .cesure value – beat syntax, durations, note/beat props, time-signature filling rules, and worked examples – which is indispensable for supplying a valid value.

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

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

The opening states a specific verb and resource ('Create a score you write as a .cesure') plus the resulting side effect ('open it as a draft'), so an agent immediately knows what gets produced. It stops short of distinguishing itself from close siblings like save_new_score or import_score, which are the tools an agent would most likely confuse it 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?

Usage is only implied: 'open it as a draft' hints that this creates without committing, which contrasts with save_new_score, but no sentence states when to prefer this tool over import_score or save_new_score. The agent must infer the routing from sibling names.

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 flag destructiveHint=true and idempotent=false, but the description adds substantial behaviour: atomic refusal of the whole call when a measure fails to parse or fill its time signature, the refusal naming each fault and its place, unchanged measures being preserved, and the column-wise propagation of repeats and tempo to other tracks. It even states what the response names.

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 operation contract is front-loaded, but the body is a very long single block that embeds a full notation grammar and many worked examples, duplicating what the linked format page and the schema cover. It is dense rather than wasteful, yet the notation reference could be trimmed in favour of the URL.

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

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

For a complex mutation tool with nested .cesure payloads, the description covers parsing rules, failure modes, cross-track effects, and input constraints, and an output schema exists so return-value details need not be restated. Nothing an agent needs before invoking it is missing.

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

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

Schema coverage is 100% so the baseline is 3, but the description goes beyond the schema by defining .cesure measure object semantics (id retention vs new measure, staves/voices, time-signature fill rules) and the exact meaning of from/to inclusivity and insertion. Only the track default is left 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 verb and resource with exact scope: 'Rewrite measures from..to (numbers, inclusive) of ONE track of the draft with .cesure measures'. It distinguishes itself from read_score by defining the notation it consumes and clarifies the insertion edge case (to = from - 1) and range removal (measures []).

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

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

The description gives clear operating context: it explains replacement vs insertion, deletion of omitted measures, cross-track column behaviour, and how pitch-vs-fret input constrains string choice. It does not name sibling alternatives (e.g., transpose, refinger) or when-not to use it, so it falls short of a 5.

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

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

Annotations declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, and openWorldHint=false; the description adds real behavioral context beyond them by promising the score is 'taken as it is, never rewritten' and that Cesure 'reads no page,' which independently corroborates the closed-world hint. It stops short of describing where the draft lands or what happens on repeated imports (relevant given non-idempotent).

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 accepted formats, followed by the exclusion rule. Two sentences, no filler; the stylized phrasing ('a score the person gives whole') is slightly harder to parse than plain language but does not waste 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?

For a single-parameter mutation tool with an output schema present, the description covers accepted input formats, the excerpt-not-rewritten contract, and the invalid-link case. The remaining gap — where the draft is created and whether re-importing duplicates it — is modest given annotations and the output schema carry some of that burden.

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 a single parameter at 100% schema description coverage, the schema already documents the 'score' field including that it must be verbatim. The description restates the accepted formats and adds the 'verbatim' emphasis, but contributes little syntax or format detail beyond the schema — the baseline 3 for schema-covered parameters is appropriate.

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

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

The description names a specific verb ('Open as a draft') and resource (a score) and enumerates the three accepted input forms: .cesure file text, AlphaTex, or an 'Open in Cesure' link. This makes the tool's function clear without opening the schema, though it does not explicitly contrast itself with close siblings like create_score, save_new_score, or open_in_cesure.

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 supplies one useful negative condition — links to non-score pages (video, recording) import nothing — which implicitly tells the agent what input is valid. However, it never names an alternative tool or states when to prefer create_score or open_in_cesure over this one, leaving routing 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 readOnly/idempotent/non-destructive, so the bar is low, and the description clears it by adding real behavior: 200-result batches, offset-based skipping, that 'more' carries the next offset, most-recent-first ordering, and the account-linking prerequisite. It adds value beyond the annotations, though it omits any rate-limit or failure behavior.

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

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

The resource is front-loaded, but the whole definition is one run-on sentence with nested parentheticals, and the 'more gives the next offset' rule is stated once in the description and again in the schema. Accurate but harder to scan than it needs to be.

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

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

For a single-parameter read tool with an output schema, the description still covers ordering, page size, pagination continuation, returned fields, and the account-link prerequisite, leaving little ambiguity. It does not explain the tag-count portion's shape, but the output schema covers returns.

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 offset parameter is fully documented there, including default 0 and the next-offset pointer. The description essentially restates the schema semantics with no extra syntax or format detail, so 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?

Names a specific verb+resource (list the person's scores in their linked Cesure account) and enumerates the returned fields. It is distinguishable from read_my_score and search_catalog by the plural listing and account-scoping, though no sibling is named 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?

States the prerequisite 'Needs the account linked,' which is useful context, but never says when to prefer this over search_catalog or read_my_score, nor when not to use it. Usage is only implied from the name and the plural listing.

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

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

With readOnlyHint, idempotentHint, and destructiveHint already declaring the safety profile, the description still adds real behavioral context: in host-drawing apps the player plays the draft inline in the conversation, while elsewhere the response returns a short link that opens the draft in Cesure with no account required, plus a score summary. That is meaningful environment-dependent behavior beyond the annotations.

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

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

The first sentence is front-loaded and clear, but the second is circuitous ('Where the host draws apps', 'everywhere') and forces the reader to parse two vague spatial clauses to extract the actual behavior. It is not bloated, but the phrasing costs more effort than it should.

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

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

The tool is a single-parameter, read-only, idempotent operation with an output schema, so return values need not be spelled out. The description covers the two outcomes (inline playback vs. shareable link plus summary), which is sufficient context for an agent to call it correctly; only explicit routing guidance is absent.

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 'draft' parameter is documented in the schema as 'the id a previous tool gave (draft).' The description adds no format, sourcing, or validity details beyond that, 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 opening sentence gives a concrete verb and resource: 'Show the draft in the Cesure player, to read and hear it.' That is enough to distinguish it from read-oriented siblings like read_score and read_my_score, which retrieve score data rather than render/play a draft. It stops short of explicitly comparing itself to those siblings, so it lands at 4 rather than 5.

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

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

The description implies when the tool behaves differently (host apps that draw vs. elsewhere) but never states when an agent should call this instead of alternatives such as read_score or list_my_scores. There is no explicit precondition, sequencing (e.g. 'after create_score'), or exclusion. Conditional outcome is not the same as usage guidance.

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

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

Annotations flag destructiveHint=true and readOnlyHint=false but say nothing about scope or limits; the description fills that gap by disclosing the all-or-nothing batch semantics, the 500-change ceiling, the create-if-absent behavior of 'add' with case-insensitive name comparison, the conditional nature of delete_unused_tags, and the guarantee that no score is renamed, deleted, altered, or re-dated. It also describes the exact rollback path, which annotations alone could not convey.

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

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

The critical facts (action, atomicity, 500 cap) are front-loaded, and every clause carries information. The middle sentence is a dense run-on enumerating four operations, which makes it harder to scan, but there is no filler and nothing 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?

With an output schema, full schema coverage, and annotations present, the description supplies everything else an agent needs: atomicity, change budget, per-operation side effects, reversal semantics, and the account-linkage prerequisite. Combined with the structured fields, nothing material 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 goes well beyond the terse schema strings: 'add' creates a tag when the account has none of that name (names compare without case), 'remove' takes it off, and 'delete_unused_tags' deletes only tags no score carries. It also explains that tag creation by 'add' counts toward the 500-change limit, a semantic no field description captures.

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 (batch tag organizing on the linked account's scores) and enumerates the exact sub-actions: create_tags, add, remove, delete_unused_tags. The clause 'It never renames, deletes or changes a score' implicitly separates it from score-mutating siblings such as update_my_score, edit_measures, and transpose, so an agent can route correctly 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 gives a clear operating context: one atomic batch, capped at 500 changes counting tags that 'add' creates, and a hard prerequisite ('Needs the account linked'). It also notes that the inverse operations undo an organizing. However, it never states when to prefer this tool over alternatives (e.g. update_my_score) or when-not to use it, so no explicit alternatives are offered.

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 declare readOnlyHint=false and idempotentHint=false, and the description is consistent with that by disclosing that the score is opened 'as a draft' rather than mutated in place, plus the account-link prerequisite. It stops short of describing failure modes or what happens to an existing draft.

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-loads the action and result, then appends the id source, the alternative tool, and the prerequisite. Everything earns its place, though the chained clauses make it slightly run-on.

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 need not be spelled out, yet the description still names the draft and summary and points to read_score for measures. The account-link requirement is covered; only edge cases (unlinked account, invalid id) are 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 description coverage is 100% and the single id parameter is fully documented there; the description only repeats the same provenance ('by the id list_my_scores gives'). Baseline 3 is appropriate when the schema carries 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 and resource ('Open one score of the linked account as a draft') and names its closest sibling distinction ('read_score reads its measures'), so an agent can tell it apart from read_score and list_my_scores 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 clear provenance for the required argument ('the id list_my_scores gives') and states the prerequisite 'Needs the account linked'. It also implicitly routes measure-level reads to read_score, but there is no explicit when-not or exclusion statement.

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, so the safety profile is covered. The description adds genuinely new behavioral context: a 200-measure-per-call ceiling, a continuation hint embedded in the response, and the presence of repeat signs and tempo changes in the payload. It stops short of describing error or empty-track behavior.

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

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

It is a single front-loaded sentence with no filler, and the core action leads. However, the run-on structure with 'from..to', stacked parentheticals, and garbled phrasing ('the answer's more says where to go on') makes it harder to parse than the content warrants.

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 need not be spelled out, and the description nonetheless covers defaults, the call-size limit, continuation, and the shape of the returned measures. It is complete for a read tool, with only sibling routing left 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 description coverage is 100%, so from/to/track/draft are already documented in structured data, and the description mostly restates them ('from..to of a track', 'by id a previous tool gave'). It adds only the 200-cap default nuance, 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 names a concrete verb and resource ('Read measures from..to of a track of the draft') and even enumerates what comes back (id, time signature, voices, repeat signs, tempo changes). It is specific, but it never distinguishes this tool from the similar sibling read_my_score, so an agent cannot differentiate the two from the text alone.

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 operational bounds ('all by default, 200 at most a call: past them, the answer says where to go on'), which is useful pagination guidance, but there is no explicit when-to-use or when-not-to-use against read_my_score, open_in_cesure, or list_my_scores. The agent must infer the selection criteria.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the safety profile is covered. The description usefully adds that pitches are preserved and that the operation re-derives string/fret placement, but it never says existing fingering is overwritten in place, whether the change is undoable, or how it interacts with the draft/save flow.

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, front-loaded with the operation's effect and then the mode/capo options. Nothing is padded, though the mode list compresses three definitions into parentheticals that could be hard to parse quickly.

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

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

An output schema exists, so return values need not be explained, and annotations carry the safety profile. Still, for a destructive in-place mutation on a draft, the description omits prerequisites (how to obtain 'draft'), scope behavior (track defaults to every track) and reversibility, leaving real gaps.

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

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

Schema description coverage is 100%, so all four parameters are already documented with defaults and enum values. The description largely restates mode and searchCapo wording that is identical to the schema, adding only the 'string and fret' framing; 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 gives a concrete verb+resource: re-placing the notes of a draft onto the neck as string/fret while preserving pitches. That is far more specific than the vague title 'Place the notes again'. It stops short of naming the closest sibling (transpose) explicitly, so the agent must infer the contrast from 'keeping their pitches'.

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?

'Keeping their pitches' implicitly distinguishes this from transpose, which changes pitches, and the mode explanations hint at selection criteria. However there is no explicit when-to-use/when-not statement, no mention of prerequisites (a valid draft id from a previous tool), and no named alternative.

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

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

Annotations cover the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), and the description adds real value beyond them: it never overwrites an existing score, free accounts are capped at 3 scores, and the account must be linked. That is substantive non-obvious behavior, though failure modes (what happens at the 3-score cap) are left unstated.

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 where each clause carries information (NEW, non-overwrite, free-tier cap, title default, account requirement). The stacked parentheticals make it slightly dense but nothing is wasted.

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

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

With an output schema present it needn't describe return values, and annotations carry the idempotency/destructiveness profile. The prerequisite and creation semantics are covered, leaving only the cap-overflow behavior and sibling disambiguation as gaps.

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

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

Schema description coverage is 100%, so both parameters are already documented. The description adds that the title defaults to the score's own title, which slightly reinforces the schema default, but no extra syntax or provenance detail is added beyond it.

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

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

States a specific verb and resource ('Save the draft as a NEW score in the linked account's library') and clarifies the non-overwriting semantics. It never names the sibling create_score, so the agent must guess which creation path applies, 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?

It gives one clear prerequisite ('Needs the account linked') and implies the draft-from-a-previous-tool workflow, but offers no explicit when-to-use versus create_score, import_score, or update_my_score. Usage is inferable rather than 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 the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description nonetheless adds real behavioral context: the multi-word AND matching rule and the fact that joining words such as 'by' are ignored, which tells the agent how results are actually derived.

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, front-loaded with the verb and resource, with the matching rule and return fields trailing. It is efficient and waste-free, though the run-on clause structure makes it slightly harder to scan than a split sentence would be.

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

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

For a two-optional-parameter, closed-world read tool with an output schema, the description supplies what the schema cannot: matching semantics and a preview of returned fields. Nothing critical is missing, though an explicit note on result ordering/pagination would make it fully complete.

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

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

Schema coverage is 100%, so the query and language parameters are already fully documented in the schema, including the default language and the empty-query behavior. The description restates the query semantics but adds no syntax, format, or language-selection 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 names a specific verb and resource ('Search Cesure's catalog of free pieces') and goes further by specifying the match semantics (words of title and/or composer, stop-words like 'by' ignored). None of the sibling tools overlap with this read/search role, so an agent can distinguish it 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?

Usage is implied by the description ('search ... catalog'), and the schema notes that an empty query lists the catalog, but there is no explicit statement of when to reach for this tool versus alternatives, nor any exclusion criteria. Adequate but leaves the routing inference to the agent.

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 declare a destructive, non-read-only, non-idempotent mutation, and the description is consistent and far richer: it details displacement rules, the 4-semitone cap on retuning, harmonic handling, default choices, and explicit refusal behavior ('refused, saying why and naming the one that can'). This is deep behavioral disclosure that goes well beyond the annotation set.

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

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

The core action is front-loaded, but the remainder is a dense, run-on passage with convoluted constructions ('A note no string of its track carries at its shifted pitch goes where notesOffTheNeck says'). The content largely earns its place but the phrasing taxes comprehension and could be structured far more legibly.

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 4-parameter mutation tool with an output schema, the description covers defaults, refusal cases, and edge behavior comprehensively; the output field names it lists are redundant given the output schema. It leaves slightly unclear whether the source draft is mutated in place or a new draft produced, but is otherwise complete.

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

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

Schema covers 100% of parameters, so the baseline is 3, but the description adds substantive meaning: it explains what retune_lowest_string (tune down at most 4 semitones, then octaves) and change_octave actually do, and likewise keep_harmonic vs play_fretted, which the enum labels alone do not convey. The added semantics exceed the schema text.

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?

Opens with a specific verb+resource: 'Shift the notes of the draft by some semitones,' which an agent can clearly distinguish from siblings like edit_measures, create_score, or refinger. It is unambiguous what the tool does, though it does not explicitly contrast itself against the neighboring edit tools.

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

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

Usage is implied by the operation (use when you want to shift pitch by semitones) and the defaults for off-the-neck handling are spelled out, but there is no explicit when-to-use vs alternatives guidance or statement of prerequisites such as which draft ids are valid. The guidance is inferable rather than 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 declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: the undo is a swap rather than a stack pop (calling again redoes), it is strictly one step, and it may silently be unavailable ('only when Cesure had room to keep that score').

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 action is front-loaded in the first clause and every element (scope, redo behavior, one-step limit, availability caveat) earns its place. It is a dense single sentence with an interrupting parenthetical, which is slightly harder to scan than it needs to be.

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 need no explanation, and the one parameter is fully documented. The description supplies the irreversibility/redo model and the preconditions, which is close to complete for a single-step undo 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?

With a single parameter at 100% schema description coverage, the schema already defines 'draft' as the id from a previous tool. The description refers to 'the draft' but adds no format, source, or validation detail beyond what the schema states, 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 gives a precise verb and resource — restoring the draft's previous score state — and explicitly scopes what a 'last change' can be (edit_measures, transpose, refinger, or an undo), which separates it from those sibling tools 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?

It states the operative conditions clearly: it applies after one of the four listed mutations and undoes exactly one step. There is no competing 'undo'-style sibling to redirect the agent to, so no explicit when-not clause is needed, but there is also no general guidance on what to do if more history is needed.

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 destructiveHint=true, idempotentHint=false, readOnlyHint=false, so the safety profile is covered. The description adds real value beyond that: the save is refused and nothing is overwritten if the score was saved in Cesure since, the library retains the earlier version, and the account must be linked.

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 a compact, front-loaded paragraph with no filler, and each sentence carries a distinct fact (overwrite, conflict refusal, version retention, prerequisite). Phrasing such as 'the score of the linked account's library it was opened from' is awkward but not wasteful.

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 destructive single-parameter mutation with an output schema, the description covers the essentials: what is overwritten, when the write is refused, what happens to the prior version, and the auth precondition. Return values need not be explained since an 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?

There is a single parameter with 100% schema description coverage, so the schema already carries the syntax. The description only adds the linkage that the draft originates from read_my_score ('it was opened from'), which is minor beyond what the schema states.

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

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

The description gives a concrete verb and resource ('Write the draft back over the score of the linked account's library it was opened from') and ties the operation to read_my_score, so an agent can tell this is an overwrite-in-place of an existing score. It stops short of explicitly contrasting with the save_new_score sibling, so sibling differentiation is only implicit.

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

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

Usage is implied ('as saving in the app does') and a key precondition is stated ('Needs the account linked'), plus a conflict-refusal condition. However it never says when to choose this over save_new_score or create_score, leaving the selection logic to inference.

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