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 mutation/safety profile (readOnly=false, destructive=false, idempotent=false). The description adds substantial context beyond that: errors refuse the save, warnings are persisted and marked, signed-in saves land in an account with a composer link, anonymous saves return a 30-day claim link, and rate limits are 5/day anonymously vs 15/day signed in.

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?

Well front-loaded: purpose, then precondition, then outcome branching, then limits. Every sentence carries information, though the clause 'as in the composer' and the restated save_to_my_account behavior are mild redundancy in an otherwise dense block.

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, yet the description still usefully characterizes the two return shapes (composer link vs claim link) that drive agent behavior. Preconditions, account branching, and rate limits together cover everything needed to call this 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 description coverage is 89%, so parameters are largely self-documenting; baseline is 3. The description elaborates the consequence of save_to_my_account rather than its syntax, and says nothing about illegal_threshold_ticks or tags, so it adds little at the parameter level 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 and resource ('Saves a melody as a new private song') and immediately differentiates from siblings like add_version and delete_song by noting this creates a NEW private song. The privacy default and account-vs-anonymous outcome are clear without opening the schema.

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

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

Explicitly names prerequisites ('run validate_melody or fit_melody_to_box first'), specifies exactly when to set save_to_my_account=true, and gives a concrete alternative path for apps that cannot sign in mid-conversation. Error-vs-warning handling (errors block, warnings save) is stated as a routing rule.

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 idempotentHint=true, but the description adds critical context beyond them: the deletion is permanent and irreversible, it also removes all box versions, and there is a mandatory two-step confirm protocol. It also disambiguates the claim_token path, which no annotation 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 sentences, zero filler. The irreversibility warning and the operational procedure are front-loaded in the order an agent needs them: what it deletes, then how to do it safely.

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 everything else an agent needs: both authorization modes, scope of deletion (all box versions), reversibility, and the confirmation gate. Nothing material is missing for a destructive tool with three params.

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 schema already describes 'confirmed' and 'claim_token', yet the description ties them to a concrete workflow (pass claim_token for account-less songs; re-call with confirmed: true after confirmation), adding meaning beyond the field-level text. song_id itself is left unexplained, but it is self-evident.

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 ('Permanently deletes ... songs') plus the exact scope: the signed-in person's song with all its box versions, or an account-less song via claim_token. This distinguishes it clearly from write siblings like create_song and add_version without needing their schemas.

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?

Explicitly covers both usage paths (signed-in vs. claim_token) and prescribes the confirmation workflow: tell the person which song will be deleted, get confirmation, then call again with confirmed: true. This is a complete when/how instruction rather than an implied one.

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=true and openWorldHint=false, so the safety profile is already covered; 'creating a download link' is consistent with a non-destructive read. The description adds useful non-annotation context — the sign-in requirement and that the operation spans both private and public tunes — though it doesn't say whether links expire or how they are consumed.

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 dense sentences, front-loaded with what the tool produces, followed by the format clarification and auth requirement. The parenthetical is long but each clause carries information an agent needs.

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 the description covers the key constraints: auth requirement, song scope, and format semantics. Minor gaps remain around link lifetime and PDF-only applicability of some options, but the definition is sufficient 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?

Schema coverage is 67% and the description compensates meaningfully: it disambiguates the otherwise undescribed 'format' enum by explaining pdf_long (one continuous strip) vs pdf_a4/pdf_letter (sliced to page) and enumerates mp3/midi/pdf. It adds little about box, grid, show_title, or strip_shape, which the schema already documents.

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 ('Creates a download link for one box version of a song') and enumerates the artifact types (MP3, MIDI, printable strip PDF), which is more than the title alone. It does not, however, explicitly distinguish itself from the sibling render_audio, which an agent might confuse for audio output.

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 usage context: it works on the person's own songs and on public tunes, and requires signing in. There is no explicit when-not guidance or named alternative (e.g., render_audio vs. export for download), so it stops short of the top band.

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=true and openWorldHint=false, so safety is covered. The description adds behavioral context beyond that: it lists every change made, reports the new melody and its validation, and describes what each strategy mutates. Consistent with a non-destructive read/compute operation.

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 compact sentences, front-loaded with the core action, then strategies, then the optional grid snap and return value. No filler, though the strategy sentence is dense.

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 spelled out, yet the description briefly notes it returns the new melody and validation. With 7 params, 3 required, and high schema coverage, an agent has what it needs, though the box-vs-target_box relationship and strategy tradeoffs could be clearer.

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 schema omits a description on the 'strategy' enum, so the description carries it: it defines transpose, nearest_note and transpose_then_nearest (default). It also explains quantize snapping. This adds real meaning beyond the 86% schema coverage baseline.

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

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

States a specific verb and resource: 'adjusts a melody so it can be played on a music box and lists every change.' This clearly distinguishes it from a plain validation tool, though it never names the sibling validate_melody or any other near-neighbor.

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?

Implies its use case (fitting a melody that isn't playable) and explains the three strategies plus which is default, but never states when to use this instead of validate_melody or render_audio. Guidance is implied rather than explicit.

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=true, openWorldHint=false), but the description adds real value beyond them: an authentication prerequisite, newest-first ordering, and delivery-conditional file links. It stops short of describing pagination or result-count limits for the list 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?

One sentence, front-loaded with the primary list behavior before the single-order variant, and it wastes no words while still enumerating the payload.

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, yet the description still summarizes them usefully. The auth requirement and ordering are covered; only list-mode limits/pagination are left unaddressed, which is a minor gap for a read-only lookup.

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 optional order_id is already documented as 'Omit to list recent orders.' The description's 'or one order' restates that contract without adding format or syntax 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?

States a specific verb ('Shows') and resource ('the signed-in person's orders') and even enumerates the returned fields (status, items, price, delivery links). No sibling tool covers orders, so it is unambiguously distinguishable.

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 'or one order' phrasing combined with 'Omit to list recent orders' implies the two modes, and 'Requires signing in' is a prerequisite. However, there is no explicit when-to-use guidance relative to neighbors like prepare_order or list_products, leaving context inferred.

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 adds useful context beyond that: prices are in US dollars and the response carries the details needed to place an order. It doesn't describe pagination or response shape, but the output schema exists, so a 3 is appropriate.

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 no filler; the content is front-loaded and the sequencing note closes cleanly. Efficient and readable.

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

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

For a one-parameter read tool with annotations and an output schema, the description supplies purpose, workflow placement, and currency context. Return values are covered by the output schema, so nothing critical 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% and the single enum parameter is fully documented in the schema itself. The description adds nothing about the product argument, so the baseline 3 applies.

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

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

States a specific verb ("Lists") and resource (variations/details for the two custom product types), so the agent knows exactly what comes back. Differentiation from siblings like list_products is only implied, not stated, so it falls 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?

Gives explicit sequencing guidance: "Call it before prepare_order." That tells the agent when to invoke it in the workflow. It does not, however, name exclusions or contrast it against list_products, keeping it below 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, 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?

Beyond the annotations (which only say it is a non-read-only, non-idempotent, open-world write), the description adds critical non-obvious behavior: 'Nothing is charged here,' the link expires in 7 days, the price is computed by the site, and the customer completes checkout in the cart. These directly inform how the agent should present the result.

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 purpose and no-charge fact are front-loaded in the first two sentences, followed by expiry, the confirmation precondition, and pricing. It is dense but every sentence carries information, with only the cart-mechanics clause ('adds photos... pays with PayPal') bordering on detail that could be trimmed.

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 formatting does not need explanation, and the description covers purpose, safety ('nothing is charged'), lifetime, and preconditions. The 9-parameter surface is largely handled by the schema, so nothing essential to correct invocation appears 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 78%, so the schema already documents most parameters (product, theme, note_count, variation_id, etc.). The description only references 'the song, the variation and the price' and adds no syntax or format detail beyond what the schema provides, so it stays at the high-coverage 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 precise verb+resource ('Prepares a custom melody or strip design order') and its key side effect (returns a cart link for review and PayPal payment). It clearly distinguishes this order-preparation tool from siblings like create_song, get_order_status, or render_audio.

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 precondition: 'Confirm the song, the variation and the price with the person before calling it.' This tells the agent when the call is appropriate, though it never names alternative tools or states when *not* to use it.

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?

Goes well beyond the readOnlyHint=true / openWorldHint=false annotations: duration cap (5 minutes), daily quota (20/60 audios, "the same melody again is free"), PRO-only gating for music_box, and the inheritance rule that saved songs use the author's chosen sound unless overridden. This is unusually rich operational context for a render tool.

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

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

Front-loaded with the core action and the input fork, then packs constraints and sound rules efficiently. Dense and mostly waste-free, though the quota/account clauses crowd the final sentence and could be slightly tighter.

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 description covers the key behavioral facts (input modes, sounds, quotas, duration). Only minor gaps remain, such as not clarifying what the returned audio handle looks like or its lifetime.

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 71%, so most parameters are self-documented, but the description adds real meaning the schema lacks: it explains the synth-vs-music_box tradeoff (free vs PRO), when song_id vs a melody object is required, and the sound override semantics. It leaves illegal_threshold_ticks and claim_token to the schema, which is acceptable.

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 ("Creates an MP3 of a melody... or of a saved song") and explicitly frames it as the listening/rendering path via "before or without saving it," which cleanly separates it from create_song. An agent can distinguish it from export_song and create_song 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?

Clearly states the two input modes ("Pass either song_id or a melody (box, bpm, notes)") and the intent (so you and the person can hear it). It gives conditions but does not name any sibling as an alternative or an explicit when-not-to-use case.

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?

Annotations already declare readOnlyHint=true and openWorldHint=false; the description reinforces this with the explicit "Saves nothing" side-effect statement and adds output behavior ("Every issue names the note and how to fix it"). It goes beyond the annotations by describing the diagnostic content of results, though it says nothing about failure semantics for malformed input.

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, front-loaded with the core purpose, then output format, then the workflow instruction. No filler and every sentence 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?

An output schema exists, so return values need not be explained, and the description still summarizes the error-shape (issues with note and fix). Purpose, checks, side effects, and call timing are all covered for a read-only validation 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 coverage is 100%, so baseline is 3, but the description maps behavior back to specific parameters: "off-grid notes" explains snap_beats, "same note repeated too fast" explains illegal_threshold_ticks, and "tempo and length" covers bpm. It adds conceptual meaning rather than merely restating field names.

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 ("Checks whether") and resource ("a melody... on a music box") and enumerates the actual check categories (out-of-box notes, repeats too fast, off-grid, tempo, length). An agent can immediately tell this validates rather than creates or renders, distinct from most 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?

Gives an explicit workflow trigger: "Call it before offering a melody to the person." That is clear when-to-use guidance. It does not, however, name the sibling alternative fit_melody_to_box or state when validation is unnecessary, so it stops short of full routing guidance.

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