Musicboxmelodies

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

Annotations declare destructiveHint=true and idempotentHint=true, and the description usefully explains the destructive mechanism ('Replaces that box's version if it exists') and the auth modes (signed-in vs claim_token), which is context beyond the booleans. It does not describe failure modes or what happens when the melody has errors.

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 core action, then the replacement rule, then the auth scope and precondition. No wasted words; every sentence carries distinct 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 an output schema present, return values need no explanation, and the description covers action, replacement, auth, and the melody-validity precondition. Only minor gaps remain (error behavior, relationship to validate_melody).

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 already 83%, so the baseline is 3, but the description adds real meaning by spelling out the box dimension ('15, 20, 30 notes or freestyle') and the one-version-per-box constraint. It reinforces rather than merely restates 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: 'Saves a melody as the version of an existing song for one box.' It also scopes the cardinality rule (one version per box) and the replacement behavior, which distinguishes it from siblings like create_song and fit_melody_to_box.

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 context for when it applies: the signed-in person's songs, or an account-less song via claim_token, plus the prerequisite that the melody must have no errors. It does not name explicit alternatives (e.g. validate_melody as the fix path), so it stops short of full when/when-not 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?

Annotations only declare the create/non-destructive/non-idempotent profile; the description goes well beyond by disclosing that warnings are saved and marked, the distinction between account and anonymous saves, the 30-day claim-link validity, and concrete rate limits (5/day anonymous, 15/day signed in). This is exactly the behavioral context annotations cannot carry.

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 block is dense and slightly long, but it is front-loaded with the core action and prerequisite, and every sentence (warnings, account flow, claim link, limits) carries information an agent needs. No filler 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 an output schema present, return values need not be explained, and the description still covers prerequisites, account versus anonymous outcomes, claim-link handling, and rate limits. Nothing an agent needs to invoke this 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 89%, so the schema already documents most parameters and baseline is 3. The description adds real semantic meaning for save_to_my_account by explaining the sign-in consequence rather than just restating the boolean, which lifts it above baseline.

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

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

The description states a specific verb and resource ('Saves a melody as a new private song') and immediately frames it against siblings by naming the prerequisite tools validate_melody and fit_melody_to_box. The 'private' scope qualifier further distinguishes it from visibility-related siblings like set_song_visibility.

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 preconditions ('must have no errors ... run validate_melody or fit_melody_to_box first') and clearly delineates when to use save_to_my_account versus saving anonymously, including guidance for apps that cannot sign in mid-conversation. The account/no-account branch is fully specified.

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 (readOnlyHint, openWorldHint), and the description adds useful behavioral context the annotations don't carry: the auth requirement and the semantic distinction between 'pdf_long' (one continuous strip) and 'pdf_a4'/'pdf_letter' (sliced to page). It does not discuss the download link's lifetime or any rate limits, keeping it short of 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?

Front-loaded with the core action, then format semantics, then scope/auth. Every clause carries information with no filler, though the parenthetical format explanation slightly interrupts the flow.

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?

Since an output schema exists, return values need not be explained; the description covers purpose, auth, scope and format semantics. Missing only minor operational detail (link lifetime, whether repeated calls regenerate links).

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 67%, and the only enum without a schema description (format) is explained in the description via the pdf_long vs pdf_a4/pdf_letter distinction. It adds real meaning over the schema for the highest-choice parameter, though it leaves box, grid, show_title and strip_shape to their schema descriptions.

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 ('Creates a download link for one box version of a song') and enumerates the concrete outputs (MIDI file, printable strip PDF). An agent can immediately tell this is the export/generation path, distinct from siblings like import_midi or get_song.

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?

'Works on the person's songs and on public tunes' clarifies the scope of what can be exported, and 'Requires signing in' sets an access precondition. It stops short of naming when to prefer an alternative, but for an export tool with no true sibling alternative this is adequate context.

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 this is a read-only, closed-world operation, and the description is consistent with that. It adds real behavioral context beyond the annotations: it reports every change made and returns the new melody plus its validation. Does not discuss determinism or reproducibility of the fit.

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 tight sentences: purpose first, then the strategy semantics, then the optional quantization. Front-loaded and free of filler, though the strategy parenthetical is slightly dense 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 7-parameter tool with an output schema, the description covers the decision-relevant parts (strategy choice, quantization, target box behavior) so an agent can call it correctly. It does not need to restate return values 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?

Schema coverage is high (86%), so the baseline is 3, but the description earns extra credit by defining the strategy enum's three values and the default, which the schema leaves undocumented, and by explaining the optional grid snapping.

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 ('Adjusts a melody so it can be played on a music box') plus the side effect ('lists every change'). This is clearly distinct from validate_melody and list_music_boxes, though it never names a sibling to sharpen the contrast.

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 operating context: use the strategy enum to choose transpose/nearest_note/transpose_then_nearest, and note the default. No explicit when-not-to-use or routing to alternatives such as validate_melody for a check-only path.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: the output is in the melody format accepted by validate_melody, and access spans public/private/anonymous scopes with the claim_token path for unauthenticated saves. It does not discuss pagination or size limits, but that is minor here.

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 core purpose before the access cases and id-finding hint. Dense but essentially waste-free; the parenthetical about validate_melody earns its place by linking format compatibility.

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 narrated. The description supplies everything else an agent needs—id sources, the anonymous-song token path, box-version scope, and output format compatibility—leaving no practical gap for a read-only getter.

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 schema already documents song_id, box (including its preferred-version default), and claim_token. The description reinforces the claim_token scenario but adds no syntax or format detail beyond what the schema provides, so the baseline 3 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 states a specific verb and resource ('Gets a music box tune') and pins down the returned content ('its notes in the melody format ... for one box version'). It also explicitly ties the output format to the sibling validate_melody, letting an agent distinguish this from export_song or fit_melody_to_box.

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 tells the agent how to obtain the required id ('Use search_songs or list_my_songs to find song ids') and enumerates the access cases—public tunes, the signed-in user's songs, and anonymous songs via claim_token. It lacks explicit when-not guidance or a named alternative for retrieving melody data, keeping it just below 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 already declare readOnlyHint=true and openWorldHint=false, but the description adds real behavior the annotations don't convey: drums are ignored, nothing is persisted ('Saves nothing'), the input is size-capped, and the result is validated against a target box. The 512 KB note roughly mirrors the schema maxLength but frames it in human-readable binary terms, which is useful.

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

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

Two tightly written sentences that front-load the core action, then add the highest-value caveats (drums ignored, no persistence). No filler and no repetition of the schema.

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

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

With an output schema present, the description needn't explain return values, and it covers input encoding, size limits, validation scope, and the non-persistent nature of the call. The main remaining gap is what happens on validation failure and how the result should be passed downstream.

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 both parameters are documented in the schema, so the baseline is 3. The description reinforces 'base64' input and the box-validation role of the second parameter but adds no syntax, format, or default details 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?

The description gives a specific verb and resource: converts a base64 MIDI file into 'the melody format' and validates it against a box. It also places the tool in the workflow (so you can fit, edit and save it), which links it to siblings like fit_melody_to_box. It stops short of explicitly contrasting itself with validate_melody, which also validates melodies.

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 rather than stated: 'so you can fit, edit and save it' signals this is the first step in an import-fit-save pipeline. There is no explicit when-to-use/when-not-to-use guidance, no mention of when to prefer validate_melody on an already-imported melody, and no stated prerequisites or error conditions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds that results include 'exact playable notes and rules,' which is useful content context, but it does not expand on behavioral traits 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?

Two tight sentences, purpose first and the call-ordering instruction second. Nothing is padded or 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 zero params, an existing output schema, and read-only annotations, the description covers everything an agent needs to select and invoke the tool. Only the explicit sibling routing is 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?

The tool takes zero parameters, so the baseline is 4; there is no parameter semantics to misrepresent and the description correctly implies a no-argument enumeration call.

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 (Lists) and resource (music box types) with the scope qualifier 'a melody can be written for, with their exact playable notes and rules.' An agent can distinguish it from validation/composition siblings at a glance.

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?

'Call this before composing or validating a melody' gives a clear usage context and sequencing rule. It stops short of naming the specific alternative tools (e.g., validate_melody, fit_melody_to_box) it should precede, but the triggering condition is unambiguous.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description still adds useful behavior: it returns private items the caller owns, it is ordered newest first, and it requires an authenticated session. Return format and pagination behavior 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?

Two short sentences with zero filler. The core scope (own songs, newest first, includes private) is front-loaded ahead of the auth requirement.

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 and annotations covering the safety profile, the description needn't explain return values. Auth and result scope are covered; only pagination semantics are missing for a tool whose whole job is a paged list.

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 only 50% — page_size documents its default but page has no description at all — and the description adds nothing about how paging works, whether page defaults exist, or how results are bounded. It does not compensate for the schema gap.

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

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

States a specific verb and resource with meaningful scope modifiers: the signed-in person's songs, newest first, including private ones. That distinguishes it clearly from search_songs and list_music_boxes, 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?

"Requires signing in" gives one real prerequisite, but the description never says when to prefer this over search_songs or get_song, nor what it excludes. Usage is implied by the 'my songs' framing 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 readOnlyHint=true and openWorldHint=false, so safety and world scope are covered. The description adds that prices are in US dollars and that checkout happens externally on the website, which is genuinely useful framing beyond the annotations, but it says nothing about freshness of pricing or result size.

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 opens with the core action and resource before adding catalog detail and the ordering disclaimer. It is slightly list-heavy but every clause carries information an agent can use.

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 not be described, and the annotations cover the read-only/closed-world profile. The description supplies the catalog subject matter and the external-payment boundary, leaving little an agent would need before calling it.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. No invented or misleading argument semantics are introduced.

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 ('Lists') and resource ('what Musicboxmelodies sells'), then enumerates the catalog: custom music box melodies, printable strip designs, PRO composer accounts, with prices and delivery times. This is clear, though it does not explicitly contrast itself with the closest sibling list_music_boxes, so an agent must infer the distinction between a product catalog and a box inventory.

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 enumerations of prices and delivery times suggest browsing the catalog for purchase decisions. The line 'Orders are placed and paid by the person on the website' partially bounds the tool's scope (it cannot transact), but no sibling or alternative is named and no explicit when-to-use condition is given.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the 'at most 20 per page' result cap, but that largely restates the schema's page_size maximum of 20, and it says nothing about rate limits, auth needs, or total-result behavior. Modest added value over structured fields.

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, no filler, and the scope ('public catalog') is front-loaded ahead of the field list and the pagination cap. 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?

With an output schema present, return-value explanation is unnecessary, and the description still covers scope, searchable fields, optional filter, and pagination bound. Nothing an agent needs to invoke this read-only search 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 description coverage is 100%, so all four parameters are already documented (query, box, page, page_size). The description echoes the same semantics (search fields, box-type filter, page size) without adding syntax, defaults, or edge-case meaning beyond the schema. 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?

Specific verb+resource: 'Searches the public catalog of music box tunes' with an explicit scope qualifier ('public catalog', 'made by the Musicboxmelodies community'). This distinguishes it from sibling list_my_songs (personal) and get_song (single lookup) without needing to open either 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?

States the searchable fields ('song name, artist or arranger') and the optional narrow-by-box-type filter, plus the 'omit to list tunes' behavior, which gives clear usage context. It stops short of naming when to prefer a sibling (e.g., list_my_songs for personal tunes), so it lacks explicit alternatives/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 a non-read-only, idempotent, non-destructive, open-world operation, so the safety profile is known. The description adds genuinely new behavioral context: the scope is limited to the signed-in person's songs, and making a song public requires a confirmation round-trip. It stops short of describing what changes for the listener or whether toggling back is symmetric.

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, no padding. The visibility outcome is stated first and the constraint/confirmation flow second, which is the correct front-loading for an agent that must decide before acting.

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 not be explained, and the description covers scope, the confirmation requirement, and the two visibility states. It is nearly complete for a simple mutation, missing only auth/ownership failure behavior and song_id format at maxLength 40.

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 only 33%, so the description carries extra burden; it does explain the meaning of 'public' and reinforces the confirmed: true gate, matching the schema description for that param. However, song_id is left entirely unspecified and the description does not clarify the confirmed/visibility interaction for a private call.

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 ('Makes one of the signed-in person's songs public ... or private') and even defines what public means ('anyone can find and play it on musicboxmelodies.com'). It is clearly distinguishable from siblings like create_song, add_version, or export_song.

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 an explicit when-not ('Only make a song public when the person asked for it') and a concrete procedure (ask to confirm, then call again with confirmed: true). The private/public enum plus this instruction covers the decision an agent must make before calling.

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 declare readOnlyHint=true and openWorldHint=false, so the description does not need to establish that this is a safe, local read operation. It adds useful behavior beyond that: 'Saves nothing' reinforces no side effects, and 'Every issue names the note and how to fix it' describes the actionable output. It does not cover auth or rate limits, but for this tool the added context is meaningful.

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 four short sentences, front-loaded with the core purpose and then progressively adding output behavior, side-effect clarity, and usage timing. Every sentence carries a distinct piece of information, and nothing is redundant or buried.

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

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

Given the presence of an output schema, annotations, and complete parameter documentation, the description is complete enough: it states the checks performed, the actionable nature of each issue, the absence of side effects, and the workflow timing. An agent has everything needed to select and invoke it correctly without requiring return-value details in the description.

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 input schema already documents all five parameters thoroughly. The description mentions validation categories that map conceptually to box, bpm, notes, snap_beats, and illegal_threshold_ticks, but it adds no syntax or format meaning beyond what the schema provides. A baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description clearly states a specific verb (checks) and resource (a melody on a music box), and goes on to enumerate the exact validation categories (notes outside the box, repeated notes, off-grid notes, tempo, length). However, it does not explicitly name or contrast with sibling tools like fit_melody_to_box, so it stops short of the highest sibling-differentiation bar.

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 when-to-use signal: 'Call it before offering a melody to the person.' This tells the agent the appropriate moment in the workflow. It does not, however, state when not to use it or point to an alternative like fit_melody_to_box for repairing invalid melodies, so it falls short of explicit alternatives or exclusions.

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