Kinetune

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

Annotations already declare non-readOnly, non-idempotent, non-destructive, so safety is covered. The description goes further and discloses the non-obvious trait that uploaded photos are identity references and are never shown publicly, which materially affects how an agent should use them. It stops short of covering overwrite/limit-exceeded behavior, hence not a 5.

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

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

Three sentences, zero filler, and front-loaded with the action and its limits before the rights and visibility caveats. Every clause carries a constraint or a behavioral fact.

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 3-parameter upload tool with no output schema, the description covers formats, count and size limits, the rights precondition, and the non-public nature of the photos. It omits only peripheral detail such as what happens when a limit is exceeded or how photos are later listed/removed.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: JPEG/PNG/WebP formats, minimum 512 px on the short side, and a 15 MB per-file ceiling. Those constraints are not encoded anywhere in the schema and directly shape how photo_urls should be populated.

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 (upload photos of the artist) plus the accepted formats and the cap of 6 per artist. The added note that these are identity references, not public-facing images, lets an agent distinguish this from set_artist_picture without opening 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?

It gives a real precondition ('Only with the rights to use them (rights_confirmed)') and a size/quantity envelope, which implies when this tool is applicable. However it never names alternatives such as set_artist_picture, list_artist_photos or delete_artist_photo, so routing between siblings is left 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 destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered and the bar is lower. The description still adds non-obvious behavior: the operation is refused with a 409 while the artist still has songs, which tells the agent to expect a failed call and why.

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 action comes first and the failure condition second. Every 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?

For a single-parameter destructive tool with annotations covering safety and no output schema to explain, the description supplies the crucial precondition and error behavior. A minor gap is that it says 'remove' while the tool is named 'archive', leaving the reversibility of the archival ambiguous.

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 there is a single parameter (artist_id), which the schema already documents with type and length bounds. The description implies the target is an artist but adds no syntax, format, or source-of-id detail, 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?

Names a specific verb and resource (remove an artist) plus a scope constraint (one with no songs), so the agent knows exactly what the call does. It does not, however, explicitly differentiate itself from the other artist mutations in the sibling set (rename_artist, create_artist, get_artist), 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 a clear precondition for use: the target artist must have no songs. That is effectively a when-to-use criterion an agent can act on, though no alternative tools are named and there is no explicit when-not-to-use guidance for artists that still have songs beyond the stated refusal.

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=true and readOnlyHint=false, so the safety profile is covered structurally. The description adds genuine value by disclosing the side effect that videos are retained, but says nothing about reversibility or effect on other linked resources (analyses, canvases).

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 short sentence with zero filler, and the most decision-relevant detail (videos stay) is included up front. It is terse rather than padded, though the parenthetical is slightly informal.

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 mutation tool whose annotations already flag destructiveness and idempotency, the description covers the key side effect. However, it never clarifies what 'archive' means relative to deletion or whether the action can be undone, which an agent handling a destructive tool would benefit from.

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% for the single song_id parameter, so the schema already carries the documentation burden. The description adds no format or lookup hints for the id, 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?

States a specific verb (remove/archive) and resource (song), and the parenthetical clarifies the scope of removal. It does not reference the sibling archive_artist or distinguish itself from delete_video, so the differentiation gap keeps it from 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?

There is no guidance on when to archive versus when to delete or otherwise act, and no alternatives or preconditions are named. The agent must infer usage entirely from 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 destructive=true, idempotent=true, and readOnly=false, so the safety profile is covered. The description adds a genuine behavioral consequence beyond that: '(credits released)', telling the agent the cost side-effect of cancelling. It does not cover error behavior for already-finished videos.

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 tight sentence that front-loads the action and appends the side effect in parentheses. No wasted words.

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 cancel operation, annotations cover the safety profile and the description adds the credit-release consequence. With no output schema, an agent still lacks guidance on what happens if the video is already complete or how success is reported, but the coverage is solid for this complexity level.

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% for the single video_id parameter, so the schema already carries the parameter meaning. The description adds nothing about the id format or constraints, 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 and resource ('Stop a ... video') and scopes it to 'queued or processing' work, which distinguishes it from other video tools. It does not name sibling alternatives like delete_video or retry_video, so an agent must infer the boundary itself.

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

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

The phrase 'queued or processing' implicitly tells when the tool applies (only in-flight jobs), which is useful state guidance. However, there is no explicit when-not guidance and no mention of related siblings such as delete_video or retry_video, so the routing decision is only implied.

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=false and idempotentHint=false, so the write/non-idempotent profile is covered structurally. The description adds genuine behavioral value on top: uniqueness is scoped per organization and the failure mode is a 409 conflict, which is exactly the kind of operational detail annotations cannot express.

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

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

Two short sentences, front-loaded with the action and followed immediately by the constraint that governs success or failure. No filler and nothing 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?

For a one-parameter mutation with no output schema, the description covers purpose, uniqueness scope, and the error contract, while annotations cover idempotency and safety. It omits permission/auth requirements and what the response contains, but those are minor gaps for a tool this simple.

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

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

Schema coverage is 100% and the single parameter is fully documented as 'The artist name' with length bounds, so the schema does the heavy lifting. The description's 'by name' plus the per-organization uniqueness constraint adds a little meaning about the name's role as a unique key, but no format or validation nuance 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 ('Add') and resource ('artist') with the input modality ('by name'), which cleanly separates it from get_artist, list_artists, rename_artist, and archive_artist. It stops short of naming any sibling explicitly, so the differentiation is inferable rather than spelled out.

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?

There is no when-to-use or when-not-to-use guidance, no prerequisite mentioned, and no pointer to alternatives such as list_artists for checking existence first. The uniqueness rule hints that duplicates matter but does not tell the agent to pre-check.

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, destructiveHint=false, idempotentHint=true), and the description adds real behavioral value: it spends credits, returns video ids immediately rather than blocking, and requires polling get_video. It does not reconcile 'spends credits' with idempotentHint=true (retry/double-charge safety), which is the main remaining gap.

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?

Four short sentences, cost and quote dependency front-loaded, no filler. The final sentence about uploading in Spotify for Artists earns its place as downstream context, though the clipped grammar across sentences makes it read as notes rather than a polished definition.

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

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

With no output schema, the description compensates well by stating what comes back (video ids) and how to follow up (poll get_video), plus the credit cost and quote prerequisite. It omits failure/cancel behavior and retry semantics despite the idempotentHint, but is otherwise sufficient to invoke 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 100% across 12 parameters with 5 enums, so the schema already carries the parameter burden; baseline is 3. The description only restates the quote_id/request-identity constraint already spelled out in the schema, adding no new semantics for fields like direction, variations, or callback_url.

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 (make/create the Canvas) and, crucially, distinguishes itself from the sibling quote_canvas by noting it takes the quote's request 'plus its quote_id' and spends credits. The phrasing is grammatically awkward ('Make the Canvas a quote priced'), which slightly blurs the action, but the intent is recoverable.

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?

Encodes the workflow: reuse the quote request plus quote_id, then poll the named sibling get_video until status is completed, then upload the file in Spotify for Artists. It gives a clear precondition and a follow-on path, though it never explicitly says 'call quote_canvas first' or when not to use this tool.

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, destructiveHint=false, idempotentHint=true), so the bar is lower, yet the description adds genuinely useful context beyond them: that the call spends credits, that it returns video ids immediately (asynchronous), that each video yields one file per requested format, and that polling is required. Minor gap: it does not say what happens to already-spent credits on a failed render.

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?

Four compact sentences, cost and the quote linkage front-loaded, each sentence carrying distinct information (pricing, request contract, return shape, format layout). The garbled first clause costs a point but nothing is padded.

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

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

For a 9-parameter, nested-object mutation with no output schema and a sibling polling tool, the description covers the essentials an agent needs: credit spend, quote matching, immediate id return, polling target, and per-format file output. It could be stronger on failure/refund behavior and on how variations map to returned ids, but the core call path is 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 description coverage is 100%, so all nine parameters are already documented in the schema, including quote_id's 'request must be identical' note and the same-value constraints on metadata and callback_url. The description restates the identical-request requirement, adding only marginal semantics beyond the schema, 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?

States a specific verb+resource ('Make the lyric video') and frames it as the paid execution step of a previously obtained quote, which distinguishes it from quote_lyric_video without naming it directly. An agent can infer it is the render step, but the awkward phrasing ('Make the lyric video a quote priced') and the absence of an explicit sibling reference keep it from 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 clear sequencing: send the same request as the quote plus its quote_id, then poll get_video until completed or failed. It names the follow-up tool explicitly. However, it never states the prerequisite that quote_lyric_video must have been called first, nor when this tool is inapplicable, so it stops short of full when/when-not 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 already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is fully covered structurally; the description adds nothing on top. It does not say the deletion is permanent, whether the photo can be restored, or what happens to the artist's picture if this photo was the primary one. With annotations carrying the burden, this is a bare-minimum pass rather than added value.

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 words, zero padding and front-loaded, so nothing is bloated. However, the brevity is under-specification rather than discipline: the single sentence is too thin to orient an agent on a destructive tool. Adequate structure, insufficient substance.

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 mutation with no output schema and no annotations-level detail beyond hints, an agent still lacks permanence/reversibility information and any hint about preconditions. The description is technically callable but leaves meaningful gaps for an irreversible delete.

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% (both artist_id and photo_id are documented in the schema), so the schema does the heavy lifting. The description contributes no additional meaning such as format, source, or how photo_id is obtained. Baseline 3 for a well-covered two-parameter 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?

"Remove one photo" only restates the name/title in weaker terms; it drops the essential qualifier that this is an ARTIST photo, not a look, canvas, or lyric video asset. With siblings like set_artist_picture, add_artist_photos, and list_artist_photos, the vague "one photo" does not let an agent distinguish which photo collection is affected. This is close to tautology rather than a specific verb+resource statement.

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

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

No when-to-use guidance, no mention of alternatives (e.g., the archive_* tools or set_artist_picture for replacement), and no note that this irreversibly removes an asset. The agent gets no signal about when deletion is the right call versus another sibling.

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=true and readOnlyHint=false, so the safety profile is covered. The parenthetical 'videos made with it stay' adds real context the annotations cannot convey: the delete is non-cascading and dependent assets survive. It stops short of saying whether the operation is reversible.

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 action and resource, with the side-effect note in parentheses where it costs least. 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?

For a single-parameter destructive tool with full annotation coverage, the description answers the two things an agent most needs: what object disappears and what survives. It omits reversibility/permission details, which is a minor gap for its size.

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

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

Only one parameter, look_id, and its schema description coverage is 100%, so the schema already carries the meaning. The description adds no format, source, or validation details beyond it, matching the baseline 3.

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

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

States a specific verb ('Remove') with a specific resource ('Looks') and scopes it to the caller's own looks. It is easily distinguished from delete_video and the archive_* siblings, though it never names an alternative.

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?

There is no when-to-use framing, no prerequisites, and no mention of alternatives such as archive_artist/archive_song or set_look_visibility. The agent must infer that this is the destructive removal path from the name alone.

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=true, covering the safety profile. The description adds real context by noting that associated files are also deleted (collateral scope), but omits permanence, ownership/permission requirements, and recoverability.

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 short sentence that front-loads the verb and resource with zero filler. Every word earns its place.

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

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

For a simple destructive tool with no output schema and annotations that already signal destructiveness and idempotency, the description covers the essential action and its file-deletion side effect. A note about irreversibility or required permissions 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?

There is one parameter with 100% schema description coverage, so the schema documents video_id fully. The description adds no format, source, or lookup guidance beyond the schema, matching the baseline for a fully-covered single parameter.

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 (delete) and resource (video) plus a scoping detail ("finished video"), which implicitly separates it from cancel_video and archive-style siblings. It is clear but does not explicitly name any alternative, so the differentiation is inferred rather than stated.

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 word "finished" implies this only applies to completed videos, which hints at when to use it rather than cancel_video. However, no explicit when/when-not guidance or alternative tool is named, leaving the 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 the safe-read profile (readOnly, idempotent, non-destructive), so the bar is lower, yet the description adds real content: it enumerates what comes back (org, auth method, scopes, credit balance broken into available/monthly/top-ups). With no output schema, this return-shape disclosure is genuinely useful; it just omits edge behavior such as exhausted-credit or auth-failure states.

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 identity/org/balance summary before the workflow hint. No filler, though the middle sentence partially restates the first.

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

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

With no output schema, the description carries the return-value burden and does so by naming the organization, auth method, scopes and credit breakdown. It is nearly complete for a zero-parameter read tool; only failure/edge semantics are left implicit.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. No parameter guidance is missing.

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

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

The description states a specific resource ('the organization the credentials act for', 'their scopes', 'the credit balance') with concrete subfields, so the agent knows exactly what this returns. It is clearly distinct from every sibling, which operate on artists, songs, videos and looks rather than account/identity.

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-to-use cue: 'Check it before creating videos.', which tells the agent where this fits in a workflow. It stops short of naming exclusions or alternatives, but there is no sibling that overlaps, so no route-away guidance 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds no context whatsoever about behavior, error handling, or what is returned, so it contributes nothing beyond the structured data.

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 words are technically concise with zero waste, but this is under-specification rather than effective brevity. There is no structure or front-loaded information to evaluate.

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 simple single-parameter read tool with full annotation coverage, a minimal description could be adequate, but "One artist" leaves the agent relying entirely on the name and schema. It is not misleading, but it is far from 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 description coverage is 100% and the sole parameter artist_id is documented in the schema with length constraints. Per the baseline rule for high coverage, a 3 is appropriate; the description adds no format or meaning 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?

"One artist" is a noun phrase that essentially restates the tool name get_artist without a verb or stated scope. It weakly implies single-artist retrieval versus list_artists, but an agent gets no explicit statement of what the tool does or how it differs from siblings like get_song or list_artists.

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?

There is no guidance on when to use this tool versus list_artists, get_song, or other read siblings. The implied usage (fetch a known artist by id) is left entirely 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 and non-destructive, so the safety profile is covered. The one piece of added context is content scope: the response carries the design and preview images, which is useful for an agent deciding whether it needs a follow-up call. Nothing about auth, rate limits, or missing-look 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?

A single short clause with zero padding, and the most useful information (what comes back) is placed immediately. It is under-specified rather than bloated, and the missing verb makes it slightly cryptic.

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 no output schema, the description does the minimum necessary by telling the agent what the payload contains. An agent would still not know how a nonexistent look_id is signalled, but annotations and the single-parameter schema leave little else to guess.

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 one parameter with 100% schema description coverage, so the schema documents look_id fully. The description adds no format, source, or lookup guidance beyond it, which is the expected baseline 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 fragment names a specific resource ('One Look') and discloses the payload ('its design and preview images'), which is enough to separate it from list_looks and the rename/delete/visibility siblings. It lacks an explicit verb, so it reads as a caption rather than a task statement.

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

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

Nothing states when to call this rather than list_looks or get_artist, nor any precondition on look_id. The singular-vs-plural contrast with list_looks is inferable at best.

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 the tool as read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds that it includes a credit table and lists everything a request can choose from, which is useful context about the return content. It doesn't describe return format, pagination, or other behavioral details, but with annotations present, this is adequate.

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

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

Two sentences, front-loaded with the list of contents and followed by the use case. Every phrase earns its place, with no redundant or vague statements.

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 no-parameter catalog tool with no output schema, the description sufficiently summarizes the return content and when to use it. It could go further by describing the structure of the response (e.g., grouped by type), but given the simplicity and annotation coverage, it is nearly 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?

The tool takes zero parameters, so the baseline score is 4. The description doesn't need to explain parameter semantics, and the empty schema is fully self-explanatory.

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 enumerates what the tool returns: video types, Look categories, background sources, formats, and credit prices. It is a catalog of selectable options, which is distinct from sibling tools like get_look or list_videos. It doesn't explicitly name a sibling it is not, but the aggregate nature is evident.

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 second sentence gives clear context: 'Use it to pick a category or source and to explain prices.' This tells the agent when to call it. However, it lacks explicit exclusions or alternatives (e.g., 'not for fetching details, use get_look instead'), 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 already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description's only added value is revealing that the response includes an 'analysis status' field, which no output schema documents; beyond that it discloses nothing about behavior, errors, or permissions.

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?

At six words it is certainly front-loaded and free of filler, but this reads as under-specification rather than disciplined concision — nothing is wasted because almost nothing was said. It fits on one line but omits information the 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?

For a single-parameter read tool whose annotations cover the safety profile, the essentials are minimally present, and the 'analysis status' note partially compensates for the absent output schema. Still missing is any differentiation from get_song_analysis and any return-shape detail.

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

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

Schema description coverage is 100% with a single required song_id, so the schema already carries the parameter semantics. The description adds no format, ID source, or constraint details beyond it, making the baseline 3 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 phrase 'One song and its analysis status' conveys the resource (a single song) and hints at returned data, but supplies no verb and never distinguishes itself from close siblings like get_song_analysis, list_songs, or get_video. An agent can guess it retrieves one song, but the boundary with get_song_analysis is not drawn.

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?

There is no when-to-use statement, no prerequisites, and no mention of alternatives, even though get_song_analysis (same resource, analysis focus) sits right next to it in the sibling list. The agent must infer the selection rule from the names alone.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds payload content beyond the annotations, but does not disclose what happens if analysis is missing (the reanalyze_song sibling implies this state exists) or any latency/retry 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?

Two tight sentences with no waste: the payload enumeration comes first and the usage hint second. Nothing is padded, though the fragments are terse enough that a little more structure could help.

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

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

With no output schema, the description carries the return-value burden and does list the analysis components, which is the key missing information. It stops short of describing the shape of those components or the empty/failed state, so a small gap remains for a data-rich read 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?

One parameter with 100% schema description coverage, so the schema documents song_id fully and the description adds no format or sourcing detail. Baseline 3 applies when structured fields do 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 enumerates the exact payload (word-timed lyrics, tempo, beats, sections, hook), which makes it distinguishable from get_song (metadata) and get_video. The verb is only implied by the name rather than stated, but the resource contents are unambiguous.

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

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

'Use the section times to choose a trim for a lyric video' gives a downstream use case and implicitly routes to create_lyric_video/quote_lyric_video, but it never states when this should be called versus get_song or reanalyze_song, nor any prerequisite such as the analysis already existing.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the closed set of status values (queued, processing, completed, failed, cancelled) and the fact that download URLs are signed for 7 days, which tells the agent links expire and must be refreshed.

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 with no filler. It is slightly back-to-front — leading with the return payload rather than the action — but the content is dense and every clause (status enum, three URL types, 7-day signing) 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 no output schema, the description must describe return values, and it does so reasonably: status semantics, the outputs object, and the three URL variants. It still leaves some gaps — what 'credits' and 'progress' contain, and behavior for an unknown video_id — but it is close to complete for a one-parameter read.

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% for the single video_id parameter, so the schema already carries the parameter documentation and the description adds nothing about id format or sourcing. Baseline 3 applies 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 names the resource (a video) and enumerates exactly what is returned — status, progress, credits, and completed download links — so an agent can tell it apart from list_videos or create_lyric_video. However, it never states a verb like 'retrieve' and does not differentiate itself from wait_for_video, which is presumably the polling alternative.

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?

There is no when-to-use guidance at all: no statement that this is the call to poll after submitting a render, and no mention of wait_for_video as the alternative for blocking until completion. The agent must infer the usage pattern entirely from the return-value list.

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, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral fact beyond that — the cap of up to 6 photos and their role as identity references versus cover art — but says nothing about return format or ordering.

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 the resource front-loaded, so it is not bloated. However, the second sentence is largely conceptual framing about how photos relate to Looks, Canvases and cover art, which does not help an agent invoke the tool correctly and does not earn its place as strongly as operational guidance would.

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?

This is a simple read-only, single-parameter list tool with no output schema, so the description need not explain return values. Still, it omits the one thing an agent would want for a list endpoint — what a photo entry looks like (id, URL, dimensions) — beyond the 'up to 6' count.

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 (artist_id) with 100% schema description coverage, so the schema already carries the parameter semantics and the baseline is 3. The description adds no format, id-shape, or sourcing detail beyond what the schema provides.

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

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

The description identifies the resource (an artist's photos, described as identity references) but uses a bare noun phrase with no verb, so it never actually states that it lists/retrieves them. It does implicitly separate these photos from cover art, which helps a little against siblings like set_artist_picture, but does not name any sibling or clarify the operation.

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?

There is no when-to-use guidance at all: nothing tells the agent when to call list_artist_photos versus add_artist_photos, delete_artist_photo, or get_artist. The framing sentence implies the photos matter for Looks/Canvases, but no actionable selection criteria are 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, and the description adds genuinely non-structured behavior: results are sorted by name and paginated at 50 per page by default. It stops short of describing what an empty search returns or how the picture field is delivered.

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 resource and payload, and the paging behavior arrives in the same compact sentence. The middle clause 'Songs belong to an artist; create the artist first' reads as a misplaced note about the create/attach workflow rather than this listing tool, costing a little focus.

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

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

With no output schema, the description correctly carries the return-value burden by naming the counts and picture per artist, and it covers sorting and default paging. Only the shape of the response envelope and total-count/pagination metadata are left unstated.

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

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

Schema coverage is 100%, so q/limit/offset are already documented in the schema, and the description largely restates them ('pass q to search by name, and limit/offset to page'). It confirms the search-vs-paging split but adds no format, matching, or boundary detail beyond the schema.

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

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

The description names the resource (artists) and what a returned record contains (name, song count, photo count, picture), which distinguishes it from single-item siblings like get_artist and from list_songs/list_videos. It opens with a noun phrase rather than an explicit verb, but the intent to enumerate a collection is unmistakable.

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

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

It offers 'create the artist first', which is a related-workflow hint rather than guidance on choosing this tool over get_artist or list_artist_photos. There is no statement of when the collection view is preferred over a single-artist fetch, so usage is only implied.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is covered without the description. The description adds useful domain context (what a Look is, how to reuse its id) but says nothing about pagination via limit/offset or what the listing returns.

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 that front-load the purpose before the reuse hint. Efficient with no filler, though the {"mode":"existing"} snippet is arguably tangential to a listing tool rather than to selection.

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 read-only, zero-required-param listing tool with no output schema, the description covers purpose and scope adequately. It is thin on return shape and pagination behavior across its six optional parameters, which an agent would need to page results correctly.

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

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

Schema coverage is only 50%. The description effectively explains the 'scope' dimension by naming Official/Community/your own Looks, but it leaves q, sort, limit, offset and category entirely to the schema, with category's dependency on get_options undocumented here. It adds some value but does not compensate for the coverage 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 ('Browse') and resource ('Looks'), plus the scope it covers (Official, Community, your own). It even defines what a Look is ('a complete, reusable lyric-video design'), so an agent can distinguish this listing tool from get_look or delete_look 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?

Browsing is implied as the use case, and the reuse instruction ('Pass its id as {"mode":"existing","id":…}') hints at downstream use. However, it never states when to prefer this over get_look for a single Look or how it interacts with the search-style params like q. Usage is implied, not 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds the useful default-page-size behavior (50 per page) and the analysis prerequisite, but does not disclose ordering defaults beyond what the schema's sort does, nor rate limits or total-count 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?

Two tight sentences front-load what a song record contains and the analysis readiness rule, then cover paging. No filler, though the paging mention largely duplicates 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?

Covers the key domain rule (analysis must be ready before videos) and paging defaults. With no output schema, the description does not enumerate the returned list envelope or total count, and six optional filters are left entirely to the schema, so it is adequate but not rich.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema (q, sort, limit, offset, status, artist_id). The description only repeats limit/offset and q at a high level, adding no syntax or format detail beyond the schema. 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?

States a clear verb+resource: lists songs with cover, duration, and analysis status. Distinguishes from get_song by being a collection lister, though it does not explicitly name siblings like list_artists or get_song to sharpen the boundary.

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

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

Provides operational guidance (use q to search, limit/offset to page) and a workflow cue that analysis must be 'ready' before videos. But it does not say when to prefer this over get_song or when to filter by status vs. artist_id.

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

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

Annotations already establish readOnly/idempotent/non-destructive, so the safety profile is covered. The description goes beyond them with real billing behavior: credits are reserved at creation and charged only on delivery, and the quote is exact. It omits auth requirements and quote expiry, which keeps 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?

Three tight sentences with no filler. The core behavior (exact credits, nothing charged yet) is front-loaded, followed by the return shape and then the workflow directive.

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

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

With no output schema, the description carries the burden of return values and does so by naming quote_id, credits and a breakdown. For a read-only pricing tool the remaining gaps (quote validity window, currency units) are minor, though they would matter for an agent handling expiry or re-quoting.

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 all 11 parameters, including the enums, defaults and the 'quote and create with the same value' note for metadata/callback_url. The description adds no additional parameter meaning, so the baseline of 3 applies.

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

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

The description states a precise verb and resource ('quote' a Spotify Canvas) and frames the scope exactly: 'the exact credits ... before anything is charged.' It also names what comes back (quote_id, credits, breakdown), so the agent can distinguish it from create_canvas without opening 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?

'Always quote first and tell the user the credits before creating' gives an explicit ordering rule that ties this tool to the create step. It stops short of naming create_canvas directly or describing when a quote is unnecessary, but the intended usage context 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 readOnly and idempotent, so the bar is lower, and the description still adds real behavior: credits are reserved at creation, charged only on delivery, and the quote expires in 30 minutes. It also lists the return fields, which matters because there is no output schema. It stops short of covering idempotency semantics or what happens on quote reuse.

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?

Four tight sentences, front-loaded with purpose and return contents, then the quote-before-create rule and validity window. No filler, though the return-field list is the only mildly expendable clause.

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 an 8-parameter tool with nested objects and no output schema, the description usefully compensates by naming the return values and explaining the reserve/charge lifecycle. The only remaining gap is how quote_id ties back into the create call, which the schema fields partially cover.

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

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

Schema description coverage is 100% with detailed nested definitions (look modes, trim, aspect_ratios, metadata note "Quote and create with the same value"), so the schema carries parameter meaning. The description adds no parameter-level detail, making the baseline 3 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?

Specific verb (quote) plus resource (lyric video) and it explicitly frames itself as the pre-charge step before creation, which separates it from create_lyric_video. It does not name the near-sibling quote_canvas, so sibling differentiation relies on the resource name rather than an explicit callout.

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?

"Always quote first and tell the user the credits before creating" gives an explicit ordering condition for when to call this instead of creating directly. There is no when-not guidance or comparison to quote_canvas, but the workflow context is clear and actionable.

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 disclose the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the bar is lower. The description adds the useful precondition that this is a retry for a failed analysis, but says nothing about whether the re-run is asynchronous, how long it takes, or how to observe the result — relevant for a mutation that triggers a job.

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?

Four words is efficient and front-loaded with the core action, so there is no wasted text. But the brevity tips into under-specification rather than tight conciseness — the sentence is arguably shorter than the task 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?

For a one-parameter tool whose annotations cover safety, the description is barely adequate. It omits the surrounding workflow context that its siblings imply (checking analysis via get_song_analysis, waiting for a job like wait_for_video), so an agent cannot tell how a retry fits into the overall flow.

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% for the single song_id parameter, so the schema already documents it fully. The description adds no meaning beyond the schema (e.g. whether the id must reference a song in a failed state). 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 names the action (retry an analysis) but never states the resource (song) or what 'analysis' means here; that information lives only in the tool name and title. It also does not distinguish this re-run tool from the sibling get_song_analysis, which likely retrieves the same analysis. Purpose is implied rather than stated.

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?

"Retry a failed analysis" implies the trigger condition (a prior failure), which is real usage guidance. However, it names no alternatives and gives no exclusions — e.g. how to check status, what to call after the retry, or whether it is valid on a song that never failed.

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=false, idempotentHint=true, and destructiveHint=false, covering the safety and repeat-call profile. The description adds nothing beyond that: it does not say whether renaming affects downstream references (URLs, credits, other objects), what happens for an unknown artist_id, or whether names must be unique.

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 four-word sentence with no waste and the intent is front-loaded. Brevity here reflects under-specification rather than disciplined conciseness, so it lands at the minimum viable level.

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 mutation tool with no output schema, the description should at least cover failure modes or side effects of renaming. With fully documented parameters and annotations, the core is covered, but the behavioral gaps leave the agent under-informed about consequences of the call.

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

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

Schema description coverage is 100% with two parameters (artist_id, name) each documented in the schema. The description adds no extra meaning such as naming constraints, conflict handling, or formatting rules, 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?

"Change an artist's name" names a verb and a resource, so the basic purpose is inferable. However, it is essentially a paraphrase of the title "Rename an artist" and adds no distinguishing detail against close siblings like rename_song and rename_look. It is minimally clear but not differentiating.

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?

There is no when-to-use guidance, no prerequisite information, and no mention of alternatives such as rename_song or rename_look. An agent must infer everything about selection context from the name alone.

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=false, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds nothing on top of that: no note about permission requirements, whether the rename is reflected immediately, or how the new name is validated.

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

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

It is front-loaded and free of waste, but it is essentially a restatement of the title rather than a description that earns its four words. Brevity here reflects under-specification rather than disciplined conciseness.

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 simple two-parameter rename with full schema coverage and annotations covering idempotency and safety, the description is minimally sufficient. It leaves out what a Look is and any caveats about renaming, which an agent might want before invoking.

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 ('name' as the new name, 'look_id' as the Look id) are documented in the schema. The description adds no format or constraint context beyond what the schema provides, 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 (Rename) and resource (Look), and the resource noun clearly separates it from siblings like rename_artist and rename_song. It does not explain what a 'Look' is, but the operation itself is unambiguous.

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

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

No when-to-use guidance, no prerequisites, and no mention of nearby siblings such as set_look_visibility or get_look. The agent must infer that this is the mutation path for changing a Look's name.

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 the behavioral profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower, but the description contributes nothing on top: it says nothing about whether the previous title is recoverable, whether the rename propagates to other entities, or any authorization requirement. It does not contradict the annotations, but it is a pure name restatement.

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 four-word sentence is maximally front-loaded and wastes no tokens, but at this length it shades into under-specification rather than crisp conciseness given there is a mutation involved. It earns its place only barely.

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 simple (two required scalar params, no nested objects, no output schema) and the annotations fully cover the safety profile, so an agent can invoke it without the description. However, the description supplies no information about the mutation's effect or scope, leaving the definition minimally viable rather than 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% — song_id and title are both fully documented in the schema, including length constraints. The description adds no additional semantics, so the baseline 3 applies; there is no gap for it to compensate for.

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?

"Change a song's title" restates the tool name rename_song and its title "Rename a song" almost verbatim. It adds no distinguishing detail beyond what the identifier already conveys, and does nothing to separate it from sibling renamers like rename_artist or rename_look.

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?

There is no indication of when to use this tool versus the sibling rename_artist/rename_look tools, nor any prerequisite or precondition (e.g., ownership, archived state). An agent must infer all usage context from the name alone.

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 generic profile (not read-only, not idempotent, not destructive); the description adds the materially important behavior that this incurs a 'new charge' and reuses the existing Look, background media, and loops so prior work is not re-billed. That cost and reuse disclosure is exactly the kind of context annotations cannot carry, though it says nothing about permissions or processing time.

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 zero filler; the core action and eligible states come first, and the cost/reuse caveat follows logically. Nothing is repeated from the schema or annotations.

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, no-output-schema operation, the description covers the action, the eligible input states, and the billing/reuse consequences - everything an agent needs to decide and call correctly. No return-value explanation is required.

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 one parameter at 100% schema description coverage, the schema already documents video_id fully. The description adds no format, length, or ID-source detail beyond it, so the baseline of 3 applies.

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

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

The description states a specific verb ('Run ... again') and resource ('a finished, failed or cancelled video'), making it immediately distinguishable from siblings like create_video, cancel_video, and get_video. An agent can tell that this re-executes an existing video rather than producing a new one.

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 clearly states the applicable conditions - videos that are finished, failed, or cancelled - which tells the agent when this tool is usable rather than one of the create_* siblings. It stops short of explicitly naming an alternative tool or stating when not to use it (e.g., for in-progress videos).

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 idempotentHint=true, destructiveHint=false and readOnlyHint=false, so the safety profile is partially covered. The description adds meaningful context beyond them: the photo itself is not modified (only a square cut is used), and the automatic centered default when no crop is given. It does not mention permissions/auth or repeat-call behavior, but it corroborates the non-destructive, idempotent profile rather than contradicting it.

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

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

Three tight sentences with the action front-loaded, followed by the default behavior and the crop semantics. Every sentence carries information (scope, default, parameter meaning), with no filler, though the crop clause is dense enough that it reads as a single packed unit rather than clearly separated points.

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 3-parameter mutation with nested object, 100% schema coverage, no output schema and mostly covered annotations, the description supplies the missing pieces: crop coordinate semantics and default centering behavior. It lacks only return-value/permission detail, which is minor here since no output schema exists and the annotations cover the safety profile.

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 further than the schema: it explains that x/y are the top-left corner in fractions of the photo and size is the side relative to the photo's short side — semantics the nested x/y/size properties do not document individually. That meaningfully reduces ambiguity for a non-obvious numeric crop.

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 with scope: choosing which photo is the artist's picture and how it is cropped to a square, plus the invariant that the underlying photo is unchanged. This is clearly distinct from siblings like list_artist_photos (which it names via the schema) and delete_artist_photo. An agent can tell what this tool does without opening the schema.

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

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

It gives useful default context — the first photo becomes the picture automatically, centered — and states that omitting crop centers the square. It implies the prerequisite that the photo must be one of the artist's photos and points at list_artist_photos in the schema. However, it names no alternative tool or explicit when-not condition (e.g., adding photos first via add_artist_photos), 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.

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

Beyond the annotations (which only mark it idempotent, non-readonly, non-destructive), it discloses the concrete consequences of publishing: credit reward, listing in the Community library under the caller's @username, and the failure condition for Looks showing an artist. This is meaningful side-effect and outcome detail an agent cannot get from the schema.

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

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

Three tight sentences, front-loaded with the core action and consequence, with zero filler. The parenthetical credit and 409 notes are compact and informative.

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 2-parameter, no-output-schema mutation tool, the description covers purpose, consequence, and the key error case. It could mention the return/state on success, but the essentials for correct invocation are present.

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 50%, but the description compensates by explaining what the two visibility states actually mean behaviorally (public joins the Community library for a credit cost; artist Looks stay private). It adds real meaning to the enum values rather than restating them.

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 (make public/private) and a specific resource (a Look), and the title reinforces it. It is easily distinguished from siblings like rename_look or delete_look.

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: do this to publish (earning 10 credits) or unpublish, and notes the effective when-not case where an artist-containing Look cannot be made public (409). It doesn't name an alternative tool, but the when/when-not conditions are 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 already cover safety (readOnly, idempotent, non-destructive, not open-world), and the description adds the useful wait-ceiling and polling instruction. However, it never says what happens when max_seconds elapses without completion — whether it errors, or returns the still-processing video. For a blocking/wait tool that timeout outcome is the single most important behavioral fact, and it is absent.

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, both load-bearing: the first defines the operation and its return, the second defines the polling loop. The primary constraint (max_seconds/default) is front-loaded with no filler.

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

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

With no output schema, the description carries the return-value burden but only says 'returns it like get_video,' which requires the agent to consult that sibling. Combined with the missing timeout-outcome behavior, the definition is adequate but leaves a real gap for a wait/poll tool with a 55-second ceiling.

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%: video_id and the 5–55 range with default 50 are fully documented in the schema. The description merely restates max_seconds and its default, adding no syntax or semantic nuance beyond it; 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 and resource ('waits ... for a video to finish') plus the wait semantics (max_seconds, default 50). The clause 'returns it like get_video' explicitly distinguishes it from the sibling get_video, so an agent can choose between them without opening 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?

'Call again while status is queued or processing' tells the agent this is a polling loop rather than a one-shot read, which is the key usage decision. It never states the inverse (use get_video for a single non-blocking snapshot), so the contrast is implied rather than spelled out.

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