Kinetune

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

Goes well beyond the annotations by disclosing server-side processing (kept upright at up to 1536 px with a thumbnail, original file discarded), the non-public identity-reference role of the images, and the exact 402 plan_required / storage_full failure modes. That is exactly the kind of non-obvious behavior an agent needs before calling a write tool.

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

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

A single dense paragraph, front-loaded with what the tool does, then constraints, then failure modes. Most sentences carry distinct information, though the size/format limits overlap somewhat with the schema's maxItems and URL descriptions.

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?

There is no output schema, and the description compensates by explaining what happens to the uploaded files and their resulting form. Combined with documented quota errors and prerequisite checks, nothing material is missing for a correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains that hidden keeps photos off the artist's gallery and ties them to a music video's cast, and it clarifies what rights_confirmed is asserting. It also restates the per-upload limit of 20 and file constraints.

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 (upload photos of the artist) plus format and size constraints, so the operation is unmistakable. It does not explicitly distinguish itself from siblings like set_artist_picture or list_artist_photos, which is the only thing keeping 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 concrete conditions: the hidden flag is for photos intended for a single music video (ids passed in its cast), and rights_confirmed is mandatory. It also names get_account for checking plan and storage, effectively routing the agent to a prerequisite tool. No explicit statement of when to prefer this over set_artist_picture.

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

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

Goes well beyond the annotations by naming exact failure modes and their codes (402 plan_required, 402 storage_full, -2 handle collision), the validation thresholds (512 px short side, 15 MB, 256 px after crop, JPEG/PNG/WebP), and the fact that a brief mentioning @handle uses the piece verbatim. That is exactly the pre-call context the non-idempotent, open-world mutation annotation cannot carry.

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

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

Front-loads the core definition and keeps nearly every sentence actionable (sources, constraints, handle derivation, error codes). It is a single dense block and spends a sentence on scene-setting ('The kit is what a music video is made from besides the artist's photos'), which is helpful framing but slightly 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 (1 nested) tool with no output schema, it covers sources, prerequisites, validation and error codes thoroughly enough to call it correctly. It never says what a successful call returns (e.g., the created handle or id), which is the one gap an agent would want filled.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds genuine meaning: handle is derived from the name with a -2 suffix on collision, crop is for cutting a prop out of a larger photo and must keep at least 256 px, and rights_confirmed is only needed for upload/file_url (not stock_id). It does not clarify description vs. the stock caption default beyond the schema.

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

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

States a specific verb and resource plus its scope: creating an outfit, place or prop kit piece from an image, link or stock photo, optionally cropped. It also draws the boundary between outfit (artist's) and place/prop (workspace's), which no sibling tool covers, so an agent can place it against add_artist_photos, search_stock and update_kit_piece immediately.

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

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

Gives concrete routing rules: an outfit needs artist_id, a place or prop is the workspace's, stock_id comes from search_stock (credited, no rights needed) while an upload/file_url needs rights_confirmed plus an active plan and storage room. It does not explicitly point at update_kit_piece for edits or list_kit for inspection, so alternatives are implied rather than enumerated.

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 destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds a useful behavioral fact — that future videos fall back to the transcription — but does not state that existing custom lyrics are discarded, whether the revert is reversible, or which permission is needed.

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 no filler, and the effect is front-loaded. It is efficiently sized, though the opening clause is metaphorically worded rather than action-oriented.

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 with no output schema and full annotation coverage, the description is close to adequate, but as a destructive operation it should state clearly that the custom lyrics are removed and that the change is effectively permanent.

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

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

With a single parameter and 100% schema description coverage, the schema already documents song_id. The description adds nothing about the parameter (no id format, source, 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?

The description conveys the effect (reverting to transcribed words) rather than naming the action: it never says it removes or clears the song's custom lyrics. Combined with the tool name and title the intent is inferable, but the description alone is vague and gives no differentiation from siblings like set_song_lyrics or create_lyric_video.

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 and no named alternative. The only context offered is a downstream consequence ('videos made from then on show the words as transcribed'), which is not usage guidance.

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

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

Annotations already declare non-readonly, non-idempotent, non-destructive, but the description adds substantial behavioral context beyond them: the 409 uniqueness failure, the one-artist-per-workspace constraint, the refusal until the workspace becomes a label, and the no-plan requirement. These are exactly the operational traits an agent needs before invoking a mutating create tool.

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

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

Three short sentences, each carrying distinct information: action, uniqueness/conflict rule, workspace constraint, and billing exception. It is front-loaded with the action and has 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 explains the important preconditions and failure modes, which is more than most create tools provide. It does not say what the tool returns (e.g., the created artist object or ID), which is a minor remaining gap for a create operation.

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 required parameter and the schema description coverage is 100%, so the schema already defines name fully. The description only repeats "by name" and adds no constraints, formats, or examples beyond the schema; the baseline 3 applies.

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

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

The description states a specific verb and resource ("Add an artist by name") and immediately clarifies scope: creation of an artist, not a rename or organization creation. An agent can distinguish it from rename_artist and create_organization without opening any schema.

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

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

It provides concrete preconditions and failure modes (unique per organization, 409 when taken; a second artist in a workspace is refused until it becomes a label via update_organization) and notes the tool works without a plan for onboarding. It stops short of explicitly naming when to prefer a sibling (for example, create_organization) or stating exclusions, but the usage context is clear.

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?

Adds substantial context beyond the annotations: it is a credit-spending write, returns video ids immediately rather than the finished asset, requires polling get_video, and documents specific failure modes (402 plan_required, 402 storage_full) with the get_account fields that reveal them. The idempotency expectation (identical request to the quote) is also conveyed, complementing idempotentHint.

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?

Dense and front-loaded — the cost and the quote pairing come first, then the async flow, then preconditions. The telegraphic phrasing ('Make the Canvas a quote priced') slightly costs readability but no sentence 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?

Given 13 params, no output schema, and an open-world mutation, the description covers cost, async result handling, and both documented error conditions, which is most of what an agent needs. The post-creation manual upload step is mentioned but the callback_url alternative path is left entirely to the schema.

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 basics are already documented; the description still adds the crucial cross-parameter constraint that the request must be identical to the quote (relevant to quote_id, metadata and callback_url). It doesn't explain variations/stock_id interplay, which the schema handles.

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

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

States a specific verb and resource ('Make the Canvas... spends credits') and immediately separates itself from the sibling quote_canvas by requiring the same request body plus a quote_id. An agent can tell this is the paid fulfilment step of a quote/create pair.

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?

Explicit sequencing: send the identical request as the quote, add its quote_id, then poll get_video until completed, and upload in Spotify for Artists. Preconditions (active plan, storage room) and how to check them via get_account are named, though an explicit 'use quote_canvas first' pointer and mention of cancel_video/wait_for_video as alternatives is absent.

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, it discloses that the call spends credits, returns video ids immediately, requires polling, and produces one file per requested format. It also documents the 402 plan_required and 402 storage_full failure conditions and where to check them.

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

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

The key operational fact, that this creates a previously quoted video and spends credits, is front-loaded. The remaining sentences are dense but all carry operational value about return behavior, polling, and preconditions.

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

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

For a complex creation tool with nested parameters and no output schema, the description covers the essential flow and caveats: quote pairing, credits, immediate ids, polling, file-per-format behavior, and account prerequisites. No critical usage gap remains.

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 explains the parameters thoroughly. The description reinforces that quote_id must match the original quote request, but adds little parameter-level meaning beyond what is already in the schema.

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

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

The description states a specific verb and resource: it creates the lyric video that was previously quote-priced. It also distinguishes itself from the sibling quote tool by requiring the same request plus the matching quote_id.

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 explains the workflow: use the same request as the quote plus quote_id, then poll get_video until completion or failure. It also names concrete preconditions and the diagnostic sibling get_account for plan and storage checks.

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 say it writes and is idempotent; the description adds what they cannot — credits are spent, execution is asynchronous, latency is roughly five minutes per minute of song, and the specific 402 conditions with their remediation calls. That is exactly the extra context the annotations leave out.

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?

Five sentences, front-loaded with the verb and the credit cost, then the call mechanics, then latency, then prerequisites. Slightly information-dense with the parenthetical error codes, but every clause carries operational value and nothing is redundant.

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

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

For a 16-parameter, nested, expensive, async mutation with no output schema, the description covers the return value (video ids at once), the polling path, timing expectations, and gating conditions. Nothing an agent needs to invoke it safely and correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description still adds cross-parameter meaning the schema does not: quote_id must match the original quote request exactly, and plan_id replaces a sent brief rather than supplementing it. It does not touch the many enum options (style, category, quality), which is acceptable given the schema documents 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?

Opening sentence names the exact action and its economic consequence: it makes the quote that was priced and spends credits. That separates it cleanly from quote_music_video, create_lyric_video and create_canvas without needing to open their schemas.

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

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

It states the precondition (an existing quote plus its quote_id, request must be identical), the alternative path (send plan_id from plan_music_video instead of a brief), and what to do afterwards (poll get_video until completed). Prerequisites for failure cases (402 plan_required, 402 storage_full) are named with the sibling that resolves them.

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

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

Goes well beyond the annotations: discloses the authorization requirement ('the key needs organizations:write'), that the owner is the signed-in person or key creator, that the org starts with no plan and no credits so nothing can be created until a plan is chosen, and that existing credentials keep acting on the old org. These are exactly the operational facts an agent would otherwise get wrong.

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

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

Front-loaded with the core action and dense with useful facts, but the opening two clauses overlap ('A new organization owned by you, with its own music, videos, Looks and credits' followed by 'Creates an empty organization'), and the mid-sentence interjections ('a workspace, in the app') interrupt the flow.

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

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

With only two required parameters, no output schema and full schema coverage, the description closes the remaining gaps: resulting state (empty, no plan, no credits), auth requirement, ownership, and how to continue working in the new org. An agent needs nothing else to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real downstream meaning for the enum: 'artist' implies a subsequent create_artist call and artist_id-free songs, 'label' implies a roster. The 'name' parameter is only echoed from the schema, not extended.

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

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

States a specific verb and resource ('Creates an empty organization (a workspace, in the app)') and immediately scopes what it is: its own music, videos, Looks and credits, owned by the caller. It also disambiguates from siblings by defining the two mutually exclusive shapes against create_artist ('type artist is for one artist... label for a roster').

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?

Explicit guidance on which type to pick and what to do next ('add that artist next with create_artist; its songs then need no artist_id'), plus a clear post-creation credential instruction. It stops short of naming the full alternative set (update_organization, list_organizations) or stating when not to create a new org at all.

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 supply the generic non-read-only/non-idempotent profile; the description adds the async analysis pipeline, expected latency (~1 minute), the lyrics-mismatch refusal behavior after analysis, and the fact that cover art is re-encoded at 1536/640/160 px rather than stored as uploaded. It also discloses the plan/storage gating that no annotation conveys.

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

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

Front-loads the action and required inputs, then layers constraints, async behavior, and errors in a logical order. It is dense with specifics rather than filler, though the single long paragraph could be broken up for faster scanning.

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 fully: it tells the agent what to poll (get_song, analysis.status), what a successful completion looks like ("ready"), what warnings to expect (lyrics mismatch), and which account fields gate the call. Nothing needed to invoke or verify the call is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds real value by giving accepted formats and size limits for the audio and cover URL parameters (MP3/WAV/M4A ≤250 MB; square JPEG/PNG 1000–6000 px ≤20 MB) and by explaining that artist_id may be omitted in an artist workspace. The lyrics caveat about repetition and partial coverage further clarifies semantics beyond the schema text.

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

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

"Add a song: master audio and square cover art" names the verb, resource, and the two required inputs, which cleanly separates it from siblings like create_artist, add_artist_photos, and create_lyric_video. An agent can identify what this creates 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 states preconditions (active plan, storage room), the follow-up sequence (poll get_song until analysis.status is "ready"), and an explicit alternative path for later edits (set_song_lyrics). It also names the failure modes (402 plan_required, 402 storage_full) with the sibling to 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 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 flag destructiveHint=true and idempotentHint=true, so the safety profile is covered structurally. The description adds real value beyond that by disclosing the downstream effect — existing plans referencing the piece can no longer be produced — which is exactly the kind of consequence an agent needs before invoking a delete.

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, zero filler, with the object definition front-loaded and the destructive consequence second. Every clause earns its place.

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

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

For a one-parameter destructive delete with full annotation coverage and no output schema, the description supplies the essential missing piece: what breaks after deletion and how to recover. Minor gaps remain (whether deletion is soft/hard, what happens to plans already in flight), but nothing blocks correct invocation.

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

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

Single parameter with 100% schema description coverage ("The kit piece id"), so the schema carries the semantics. The description adds nothing about the id's form or where to obtain it (presumably list_kit), which is the baseline expectation when coverage is complete.

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") plus the resource, and crucially defines what a kit piece actually is ("outfit, place or prop"), which the name alone does not convey. It doesn't explicitly distinguish itself from nearby delete tools like delete_look or delete_video, so sibling differentiation is only partial.

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 consequence clause ("A plan that used it can't be made any more: plan again") gives a workflow signal about when this is appropriate and what to do afterwards. However, no alternatives are named and no explicit when-not-to-use condition is given, leaving tool selection largely 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 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 say nothing about cost, latency, or rate limits, and the description supplies all three: free to design, limited number per hour, about a minute. It also discloses what is returned (a lookbook, pieces not yet drawn), the price.draw.credits cost with an instruction to tell the user, and the exact 402 plan_required / storage_full failure modes with the get_account fields to check.

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?

Dense and front-loaded: the core act, then sequencing, cost, return shape, and prerequisites with error codes. Every sentence carries information, though the opening clause and the "before the plan / before plan_music_video" repetition make the first sentence harder to parse than needed.

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

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

For a non-idempotent, open-world generative tool with no output schema, the description covers what is produced, what it costs, how long it takes, the required follow-up call after user consent, and both gating conditions with their error codes and diagnostic account fields.

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

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

Schema coverage is 100%, so the schema already documents every parameter, including the cast photos, trim, scenes mode and direction handles. The description adds only the general "same brief as plan_music_video" tie-in, which is minor context beyond the schema; baseline 3 applies.

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

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

States a specific action: the director designs the outfits, places and props, returning a lookbook of kit pieces plus designed pieces. It clearly separates this from the siblings (plan_music_video, render_music_video_lookbook). The first sentence is somewhat convoluted ("before the plan") but the resource and output are identifiable.

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

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

It gives explicit ordering: optional, run before plan_music_video, same brief as plan_music_video, and then render_music_video_lookbook after the user approves the price. It does not spell out when to skip the design step entirely beyond calling it optional, but the sequencing versus siblings is clear.

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 this as a safe, idempotent, closed read; the description goes well beyond them by documenting downstream error semantics (402 plan_required, 402 storage_full), that monthly credits reset while top-ups never expire, and that deleting videos or archiving songs frees space immediately. That is actionable behavioral context an agent could not infer 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?

Purpose is front-loaded in the first clause and nearly every clause carries operational information. However, the storage/billing portion is a single long run-on sentence with deeply nested parentheses, which slows parsing; bulleting would preserve the content with less cognitive load.

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?

There is no output schema, so the description carries the full burden of explaining the return payload, and it does: identity, auth scopes, credit balance breakdown, plan activity, storage limits, billing location, period end, and scheduled changes. An agent has everything needed to interpret the result and act on it.

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

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

Zero parameters, so there is nothing to disambiguate and the baseline is 4; the description instead spends its budget describing the returned fields (balance components, used_bytes vs limit_bytes, scheduled_change). No parameter meaning is needed or 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?

Opens with a specific statement of what is returned: signed-in identity, the organization/workspace, and its credit balance. That distinguishes it cleanly from the sibling list_organizations, which enumerates many orgs rather than reporting the current credentials' account.

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

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

Explicitly gives the trigger condition: 'Check it before creating anything', and explains the 402 plan_required and 402 storage_full outcomes the agent may hit when it skips this. It does not name a when-not or contrast with siblings such as get_options or list_organizations, 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?

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, non-destructive and closed-world, so safety is covered. The description adds nothing behavioral — no note on error behavior for a missing kit_id, no indication of what is returned, no scope constraints. It does not contradict the annotations.

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

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

Four words that read as a label rather than a description, with no front-loaded verb or purpose. This is under-specification rather than effective conciseness — the sentence is short because it omits necessary information.

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

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

No output schema exists, so the description should at least signal what a 'kit piece' lookup returns (a piece object with outfit/place/prop attributes). For a simple read tool with full annotation coverage and full param coverage, this is the main remaining gap, and it is unfilled.

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?

Single parameter with 100% schema description coverage, so the schema already documents 'The kit piece id'. The description adds no further semantics about the id format or where it comes from; baseline 3 applies when the schema does the work.

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 name carries the verb+resource (get a kit piece), and the fragment 'One outfit, place or prop' clarifies what a kit piece conceptually is. But the description itself does not state that it retrieves a single kit piece by id, nor distinguish it from list_kit or get_look. Purpose is only implied, not 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?

No indication of when to use this versus list_kit (browse all pieces) or get_look (which presumably composes pieces). The agent must infer that kit_id is obtained elsewhere and that this is the single-item lookup path.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, non-destructive, closed-world), so the bar is lower. The description adds genuine behavioral context beyond them: which fields carry the background plates versus thumbnails, that previews are 480 px wide copies, and that previews are null when no photo or video background exists.

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 a short purpose sentence, then a second sentence carrying the field semantics. The second sentence is dense and reads a bit fragmentary due to the dotted field paths, but every clause conveys useful information.

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

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

With no output schema, the description must carry the return-shape burden, and it only documents the backgrounds sub-object. The design field and other top-level fields of a Look are never described, so the agent is partially informed about what comes back.

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 documented parameter (look_id), so the schema does the heavy lifting. The description adds nothing about the id's format or source. 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+resource: retrieving a single Look with its design and preview images. The word 'One' implicitly contrasts with the sibling listing tools (list_looks, show_looks), though it never names them. Clear purpose without explicit sibling differentiation.

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 statement of when to use this versus list_looks, show_looks, or get_video, and no prerequisites or lookup context. The singular 'One Look' implies a single-record fetch, but the agent is left to infer that this is the by-id retrieval path.

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

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

Annotations already declare the safe, idempotent read profile, and the description adds real behavioral detail beyond them: the four status values and what 'rendering' means for retry timing, the 'kept' flag semantics, ownership, and price fields for draw/redesign. It stops short of describing error behavior for a missing or unauthorized lookbook.

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

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

The content is information-dense with little true padding, but it is delivered as one long run-on with awkward phrasing ('kept (true unless left out)') and buries the status semantics mid-sentence. Front-loading what the tool returns before the field catalog would improve it.

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 explaining return values and does so well for status, image_url, kept, ownership, and price. Given the read-only, idempotent annotations and single required parameter, this is close to complete; only not-found/error behavior is missing.

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

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

Schema coverage is 100% and the single lookbook_id parameter is fully documented in the schema. The description adds no syntax or format information about the id, so the baseline of 3 is appropriate.

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

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

The description conveys that the call yields a lookbook together with its pieces and their drawing state, so an agent can infer a retrieve operation on a lookbook resource. It never states the verb ('returns'/'fetches') explicitly and doesn't distinguish this lookbook from the sibling get_look, leaving a small ambiguity.

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

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

Usage is only implied: the 'rendering: check back in about a minute' note signals this is the polling tool to call while pieces draw. There is no explicit statement of when to prefer this over get_look, get_music_video_plan, or wait_for_video, and no exclusions 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond that — not what a plan contains, not what happens if the plan_id is unknown or still being generated, not whether plans expire.

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 are technically concise and front-loaded, but this is under-specification rather than conciseness. No sentence conveys actionable information about the operation.

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?

There is no output schema, so the description is the only place an agent could learn what a "plan" returns — structure, stages, or linkage to videos — and it says nothing. For a lookup tool in a large sibling set, this leaves the agent unable to predict the result.

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 documented pattern for plan_id, so the schema carries parameter semantics fully. The description contributes nothing about the identifier, which is acceptable at the baseline given full schema coverage.

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?

"A plan made earlier" is a noun fragment that restates the tool title rather than stating a verb+resource. It vaguely implies retrieving a previously created plan, but an agent gets no confirmation that this is a read/lookup of a stored plan object, nor any differentiation from siblings like get_music_video_lookbook, get_video, or plan_music_video.

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 guidance whatsoever on when to call this versus plan_music_video, design_music_video_shoot, get_music_video_lookbook, or get_video. The description contains no conditions, prerequisites, or alternatives.

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, closed-world and non-destructive, so safety is covered. The description adds genuinely new behavioral context: the catalog is admin-set and mutable, and an existing subscription retains the values it was bought with. That snapshot/mutability nuance is exactly the kind of detail annotations cannot carry.

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

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

Lead sentence front-loads the core resource list, and the usage instruction comes last, which is the right order. The nested parenthetical describing plans and credit_packs is dense and slightly hard to parse, but every clause carries information and nothing is padding.

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?

There is no output schema, so the description must explain the return shape, and it does: the selectable categories, the credit table, and the two sale objects (plans with price/credits/limits/features/highlight, credit_packs with credits/price). Combined with the mutability caveat, an agent has enough to call it and interpret the response.

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 to disambiguate and the baseline is 4. The description does add value by naming units ('price in cents') and the highlighted-recommendation flag, which help interpret the result even though no inputs exist.

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

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

The description enumerates exactly what the tool returns: video types, look categories, background sources, formats, credit prices, plans and credit packs. That enumeration makes it clearly distinct from sibling listers like list_looks or show_songs. It reads more as a noun inventory than a verb phrase, but an agent can tell what the tool is for 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?

"Use it to pick a category or source and to explain prices" gives explicit triggering conditions tied to real tasks (choosing an enum value, explaining cost). It does not name when not to use it or point to alternatives such as search_stock, but the 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 cover read-only/idempotent/non-destructive safety, but the description adds rich behavior: signed cover/preview/thumbnail URLs with dimensions and formats, 7-day signature stability for caching, and detailed meanings of analysis.lyrics.status values. This is valuable context beyond what annotations and schema provide.

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

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

The description is front-loaded with a clear summary, then gives efficient field explanations. It could be split for readability, but every sentence earns its place for an output-heavy tool with no output schema.

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

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

With no output schema, the description explains key return fields (image URLs and lyrics status) and caching behavior. It does not cover all possible song fields or explicitly distinguish get_song_analysis, but is largely complete for the core retrieval use case.

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

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

Schema description coverage is 100% and the single song_id parameter is documented in the schema itself. The description adds no info about song_id format or constraints, but baseline 3 applies when the schema already does the documentation.

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 resource and return content: 'One song and its analysis status.' However, it does not explicitly differentiate from sibling tools like get_song_analysis or list_songs, so an agent must infer which retrieval tool to use.

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, prerequisites, or alternatives are given. It describes return fields but never says when to call this instead of get_song_analysis, show_songs, or similar siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so the safety profile is covered. The description adds non-obvious semantics the annotations cannot: that lyrics.text is your own lyrics or an auto-transcription and lyrics.yours disambiguates them. It omits any statement about analysis-not-ready/error behavior, which matters given the reanalyze_song sibling.

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 short and front-loaded: the payload inventory comes first, then the workflow hint, then the lyrics-semantics note. Every sentence carries information, though the phrasing is terse enough that 'hook' and the lyrics.yours explanation read a little compressed.

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 has to convey the return shape, and it does so reasonably by naming the returned data families and clarifying the lyrics fields. Minor gaps remain — 'hook' and the section object are not explained, and no error/empty-analysis case is covered.

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, song_id, with 100% schema description coverage, so the schema already carries the meaning. The description adds nothing about the id's format or origin, which is the correct baseline of 3 when structured fields do the work.

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

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

The description gives a specific verb+resource and enumerates the payload concretely (word-timed lyrics, tempo, beats, sections, hook), which tells an agent what this returns far better than the title alone. It never names a sibling, though, so it does not explicitly separate itself from get_song or reanalyze_song.

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

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

It supplies a concrete downstream use case — 'Use the section times to choose a trim for a lyric video' — which tells the agent when this tool is the right pick in a workflow. There is no exclusion or prerequisite guidance (e.g., what to do if analysis is absent, or how it differs from get_song), so it stops short of a full when/when-not statement.

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

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

Annotations already cover read-only/idempotent, and the description layers substantial extra behavior: URL signing expiry of seven days, queue-reason semantics (plan_limit with position, render_capacity with estimated_wait_seconds), null handling for poster_seconds on older videos, and the meaning of AI_VIDEO_UNAVAILABLE. This is exactly the kind of context annotations cannot carry.

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

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

Front-loaded with the return payload and the status enumeration, then progressively details poster variants and error codes. It is long but nearly every sentence carries information an agent needs; only the poster-type breakdown is slightly verbose.

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 explaining returns and does so thoroughly, covering the success shape, the pending shape, and the failure shape. Minor gaps remain around how long status data persists and whether fields are absent versus null while processing.

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 required parameter with 100% schema description coverage, so the schema already documents it. The description adds no format, source, or lookup guidance for video_id, leaving it at the baseline for full coverage.

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 exactly what the tool returns for a single video: status, progress, credits, and, when completed, download links. It's clearly a per-video status/result fetch, distinguishable from list-oriented siblings, though it never names show_video, wait_for_video, or list_videos to confirm the distinction.

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

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

Usage is implied (poll this to learn whether a video is queued, processing, completed, failed, or cancelled) and the failure text hints at retrying later. But there is no explicit guidance on when to use this versus wait_for_video, show_video, or retry_video, and no stated conditions or exclusions.

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

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

Annotations already state readOnly=false, idempotent=true, and destructive=false, so the description is not required to carry the full safety burden. Still, it adds almost no behavioral context beyond bare inclusion semantics: it does not explain what state is changed, how true/false values affect the video, or what the caller should expect. It does not contradict the annotations.

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

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

The description is a single front-loaded sentence with no wasted words. However, it is under-specified for a three-parameter mutation tool, so its brevity reflects incompleteness rather than well-structured conciseness. It is efficient but not sufficiently 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 mutation tool with three required parameters and no output schema, the description should clarify the state change and expected behavior. Annotations cover idempotency and non-destructiveness, but the description itself does not explain how kept changes the lookbook or how this tool relates to sibling operations. It is too incomplete for reliable invocation without reading the schema and relying on inference.

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

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

Schema coverage is 67%, with lookbook_id and piece already described in the schema. The description adds some meaning for the undocumented kept flag by framing the operation as whether a piece goes into the video, but it does not explicitly map true/false to include/exclude or add detail about the other parameters. This is adequate but thin.

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 conveys that this tool controls inclusion of a piece in the video, which roughly matches the name and title. However, it does not use a clear action verb such as set or toggle, and it omits the lookbook context present in the tool name. The purpose is inferable but vague rather than specific and differentiated.

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

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

The description gives no guidance on when to use this tool versus alternatives such as redraw_music_video_lookbook_piece or update_music_video_lookbook. It also does not mention prerequisites, sequencing, or exclusions. The agent must infer its place from the name and siblings 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?

With readOnlyHint, idempotentHint, and destructiveHint=false already covering safety, the description adds non-trivial output semantics: the upright url can be up to 1536 px, width and height describe it, and thumbnail_url is a 320 px short-side grid copy. It does not cover ordering or pagination, but it meaningfully clarifies returned representations beyond annotations.

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

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

Two dense sentences: the first identifies the photo set and the second explains URL variants and sizing. The field semantics are front-loaded after the resource label; there is little waste, though the first sentence is a fragment rather than a direct statement of the tool’s action.

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?

No output schema exists, so the description bears responsibility for explaining returned values; it does a reasonably good job by defining url, its dimensions, and thumbnail_url. It leaves array shape, ordering, and empty-state behavior implicit, so it is not fully complete.

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

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

Schema coverage is 100% for the single artist_id parameter, so the schema already carries parameter meaning. The description never mentions artist_id, which is acceptable at the baseline but adds no semantic value.

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

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

The description identifies the resource as the artist’s photos and labels them identity references, but it never uses a retrieval verb such as list or return and does not distinguish this read operation from add_artist_photos, delete_artist_photo, or set_artist_picture. The name supplies the action, so the description alone is only partially clear.

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

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

It explains the role of photos relative to Looks/Canvas and cover art, but gives no explicit when-to-use instruction, precondition, or named alternative for listing versus adding/deleting/setting photos. The context is conceptual rather than actionable tool-selection 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 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 readOnly, idempotent, closed-world and non-destructive behavior, so the description is not responsible for safety disclosure. It adds useful context by explaining what each returned URL represents (cropped 1536px image vs 320px thumbnail vs source rectangle) and how the kit relates to briefs. Pagination or ordering behavior is not mentioned.

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

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

The description is informative but runs five dense sentences with nested parentheticals. The first sentence defines the domain concept rather than front-loading the listing action, and some phrasing (e.g. repeatedly explaining outfits vs places/props ownership) could be tightened. It earns most of its content but is verbose for a two-parameter list tool.

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?

There is no output schema, so the description carries the burden of explaining returned fields, and it does so well: name, @handle, url, thumbnail_url, source_url, width and height are all covered. The relationship to music video briefs is also explained. It lacks any statement about result ordering or pagination, which keeps it from a 5.

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

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

The schema already documents both parameters at 100% coverage, so baseline is 3. The description adds real meaning for artist_id by spelling out the exact scope difference (workspace pieces + this artist's outfits vs all artists' outfits), which is more precise than the schema's terse 'Only the workspace's pieces and this artist's outfits'. The kind parameter gets only implied domain explanation.

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 defines what is returned (outfits, places, props that make up the kit) and how those pieces relate to a music video brief. The verb 'list' comes from the title rather than the description, and no sibling tool (e.g. get_kit_piece, list_looks) is explicitly contrasted, 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?

It gives explicit conditional guidance: with artist_id you get the workspace's places and props plus that artist's outfits; without it you also get every artist's outfits. That covers the main decision an agent faces. It does not name when to use get_kit_piece instead or any other alternative, which keeps it from 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?

With annotations already declaring read-only, idempotent and non-destructive, the description adds genuinely new behavioral context: that featured_artist Looks are private and serve only that artist's songs, and how artist_id filters them out. Useful domain-specific disclosure beyond the safety profile.

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

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

Three sentences, front-loaded with the purpose before the usage guidance. Efficient overall, though the JSON-snippet and artist-filtering clause make it slightly dense.

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

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

For an 8-parameter list tool with no output schema and only 63% schema coverage, the description omits pagination (limit/offset), sorting, and search behavior that an agent would need to call it fully. It covers the artist-privacy nuance well but is incomplete on the rest.

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 63% with 8 parameters. The description meaningfully clarifies artist_id semantics and the id-reuse pattern, but says nothing about q, sort, limit, offset, or category. It adds real value for one parameter while leaving the rest to the schema.

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

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

States a specific verb+resource ('Browse Official, Community and your own Looks') and defines the domain object ('A Look is a complete, reusable lyric-video design'). It does not explicitly distinguish itself from siblings like get_look or show_looks, leaving the agent to infer the listing vs. detail distinction.

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 concrete usage context: reuse a Look via {"mode":"existing","id":…}, and when choosing for a song, pass artist_id to omit Looks showing another artist. This is actionable when-to-use guidance, though it offers no explicit when-not or direct sibling routing.

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

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

Annotations already declare a safe, idempotent read, so the description focuses on what annotations cannot express: the organizations:read scope requirement, API-key-owner semantics, and hard isolation between organizations (separate plan, music, videos, Looks, credits). Auth and scoping context is genuinely additive.

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

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

Front-loaded with the core statement before the type/current/switch explanations. The prose is dense — one sentence carries the whole org-isolation explanation via semicolons — but no sentence is 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 and no parameters, the description has to carry the return-value semantics, and it does: it defines type (artist vs. label), the current marker, and per-user role. Nothing needed to interpret the result is missing.

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

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

Zero parameters, so the baseline of 4 applies and nothing needs documenting. The description instead explains the meaning of the response-side fields it will return (role, type, current).

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

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

Opens with a precise verb-scoped statement: 'The organizations you belong to, your role in each and the one these credentials act for.' That distinguishes it from get_account, create_organization, and update_organization among the siblings without naming them.

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

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

Explains the two access contexts (signed-in person vs. API key, which resolves to the key's creator) and tells the agent how to act in a different organization. It stops short of naming an explicit alternative tool or stating when not to call it, so it sits just below a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: image links are signed for 7 days and remain stable within a day so they are safe to cache, and the analysis.status prerequisite gates video creation.

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?

Compact and mostly front-loaded: listing scope, then the analysis prerequisite, then paging, then image-link details. No filler sentences, though the opening fragment is less direct than an explicit 'Lists songs...' statement.

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 usefully documents the returned fields (cover, duration, analysis status) and the three image URL variants with their sizes, formats, and signing lifetime. An agent can call and interpret results without further help; only sibling disambiguation is missing.

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

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

Schema description coverage is 100%, so the schema already documents q, sort, limit, offset, status, and artist_id with enums and bounds. The description only loosely echoes search/paging usage and instead spends its words on response field details, adding little parameter meaning beyond the schema baseline.

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

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

The description opens with a noun phrase ('Songs with their cover, duration and analysis status') rather than a verb+resource, so the listing action is only implied. It also fails to distinguish itself from close siblings such as show_songs and get_song, leaving the agent to guess which retrieval tool applies.

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 paging mechanics ('pass q to search, and limit/offset to page') and a domain prerequisite (a song must be ready before videos), but never says when to choose this tool over show_songs, get_song, or list_videos. No exclusions or alternatives are stated.

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

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

Annotations already establish read-only/idempotent safety, and the description adds substantive behavior beyond that: newest-first ordering, pagination termination semantics, counts behavior across song_id/artist_id/q and by video type, output fields per video, and the meaning of queue states (plan_limit vs render_capacity) for waiting videos. This is unusually rich disclosure for a list tool.

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

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

It is front-loaded with ordering and pagination, and every sentence carries operational value (pagination, counts, outputs, get_video routing, queue states). It is somewhat dense and the clause 'counts says how many videos match song_id, artist_id and q: all, and by type' is grammatically compressed enough to require re-reading.

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?

There is no output schema, so the description must describe returned shape, which it does: counts, per-video outputs (aspect_ratio, poster_url, poster_seconds, web_url), and queue metadata for waiting videos. It also names the follow-up tool (get_video) for downloads, leaving no major gap for correct invocation.

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

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

With 67% schema coverage, the description compensates well by adding the default limit of 50, the fact that cursor must be reused with identical filters, and how counts relate to song_id, artist_id, and q. The q search scope and type enum values are left primarily to the schema, which is acceptable at this coverage level.

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 opens with a specific verb and resource ('Videos, newest first, with status and thumbnails'), establishing both scope and ordering immediately. It explicitly separates this tool from get_video by noting that get_video carries download links, so an agent can distinguish the two without opening schemas.

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

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

It gives a precise pagination protocol: limit defaults to 50, next_cursor is null on the last page, otherwise pass it as cursor with the same filters. It also routes the agent to get_video for download links. However, it never states when to prefer this listing over related tools such as show_video or when not to use it, so usage is well-contextualized but not fully exclusive.

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?

Adds substantial context beyond the annotations: it is free, rate-limited to a limited number per hour, takes about a minute, and produces no charge. The annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true) don't convey cost, latency, or throughput limits, so this is real added value. It stops short of describing failure modes or what happens to earlier plans after a revise.

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 sentences, front-loaded with what the tool is and its cost, then the return shape, then the workflow. No filler and no restatement of the title.

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 11-parameter nested-schema tool with no output schema, the description covers cost, latency, and the structure of the returned plan, plus the full downstream workflow. Minor gaps remain around retrieving a plan later (get_music_video_plan) and revise history handling, but an agent can call it correctly from what is here.

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 every parameter including cast, trim, direction handles, and revise. The description only reinforces the plan_id linkage to downstream tools and the one-shot-per-15-second structure, which is marginal 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 specific verb+resource: it produces the director's treatment and shot list for a music video, explicitly framed as the pre-charge planning stage. That framing alone separates it from create_music_video and quote_music_video without opening their schemas.

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

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

Gives an explicit sequence: generate the plan, show the user, iterate with `revise` until satisfied, then call quote_music_video and create_music_video with the plan_id. It also names the alternative stage (charging) and tells the agent not to skip ahead.

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, idempotent and non-destructive, so the safety profile is covered. The description adds genuine billing context not in annotations: credits are reserved at creation and only charged when the video is delivered. It stops short of detailing expiry or quote validity windows.

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 what the tool returns, then the critical usage rule, then the billing rationale. No filler; every sentence carries weight.

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 usefully names the return fields (quote_id, credits, breakdown). For a 12-parameter read tool it covers purpose, output and the billing lifecycle well, though it could note whether quote_id must be passed to creation.

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 12 parameters (including enums like style, source, quality) are already documented in the schema. The description adds no parameter-level detail beyond what the schema provides, 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 (quote) and resource (Spotify Canvas) and clarifies the output (exact credits before charging). The resource name distinguishes it from quote_lyric_video, though the description never explicitly names that sibling.

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 explicit when-to-use guidance and sequencing relative to create_canvas. The pricing lifecycle (reserved at creation, charged on delivery) reinforces why the quote must precede creation.

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 readOnly/idempotent annotations, the description adds substantive behavioral context: credits are reserved at creation and charged only on delivery, and the quote expires after 30 minutes. This lifecycle information is exactly what an agent needs to avoid surprising the user with charges.

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

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

The description is compact and front-loaded: it opens with the core purpose ('exact credits ... before anything is charged'), then lists returns, then the required ordering, then quote validity. Every sentence carries useful information.

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

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

Given the rich 100%-covered schema, the description fills the important gaps: return fields, quote validity window, and charge timing. No output schema exists, but the description explicitly names what the quote returns, so an agent has enough to call and interpret the tool.

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

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

Schema description coverage is 100%, so the schema already documents all 8 parameters, including the complex nested look object. The description does not add parameter-level meaning beyond what the schema provides, which is appropriate but sets the baseline at 3.

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

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

The description states a specific verb and resource: obtaining the exact credit quote for a lyric video before any charge. It also names the return fields (quote_id, credits, credits_per_video, breakdown), so an agent can immediately distinguish this from create_lyric_video, which actually creates the video.

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 clear usage guidance: 'Always quote first and tell the user the credits before creating.' This establishes the required ordering relative to creation, though it does not explicitly name create_lyric_video or describe any when-not conditions.

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

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

Annotations already mark this as read-only, idempotent, non-destructive, and closed-world. The description adds meaningful billing context beyond that: credits are reserved at creation and charged only on delivery, and the quote returns quote_id, credits, and a breakdown.

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

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

The description is front-loaded with the core purpose and return values, then adds the billing and prerequisite workflow in a compact set of sentences. Every sentence contributes either routing, output, or behavioral context.

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 15-parameter tool with full schema coverage and no output schema, the description covers purpose, key return fields, prerequisites, and the quote-before-create workflow. Minor gaps remain, such as quote validity or explicitly how quote_id is reused at creation, but the structured schema fills most parameter 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%, so the schema already carries the burden of documenting all 15 parameters, including trim length and cast photos. The description reinforces that price follows section length and the artist needs photos, but it does not add parameter meaning beyond what the schema already states.

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

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

The description states a specific verb and resource: it quotes the exact credits for an AI music video before charging. It also distinguishes the quote step from creation by saying to always quote first and tell the user the credits before creating.

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 clear workflow guidance: always quote first, tell the user the credits before creating, and ensure the artist has photos. It does not explicitly contrast with other quote tools such as quote_lyric_video or quote_canvas, so it stops short of full alternative 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?

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 non-readOnly, non-idempotent, non-destructive, open-world. The description adds genuinely useful context beyond them: this spends credits, the price source is price.redesign.credits, and critically that the user's own pieces are preserved so only director pieces are affected.

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 action and immediately followed by the cost and the scope guarantee. The trailing 'credits: price.redesign.credits' repeats the schema description but stays compact.

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 credit-spending mutation with no output schema and fully documented params, the description covers cost, scope of effect, and the input note. It doesn't say what the response looks like or any state preconditions, but nothing essential to invoking it correctly is missing.

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

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

Schema description coverage is 100%, so all three parameters are documented in the schema itself. The description only restates that a note drives the change and that credits maps to price.redesign.credits, adding little beyond the structured fields. 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 (redesigns) and resource (the director's pieces in a lookbook), plus the mechanism (a note, redrawn). The plural 'pieces' scope implicitly distinguishes it from the single-piece sibling redraw_music_video_lookbook_piece, though neither sibling is named.

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

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

Usage is implied by 'redesigns... with a note', but there's no explicit when/when-not guidance and no named alternatives such as redraw_music_video_lookbook_piece or keep_music_video_lookbook_piece. The agent must infer the batch-vs-single distinction.

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

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

The description adds genuinely useful information beyond the annotations by flagging that the call spends credits and pointing at the price field. It does not explain what happens to the existing piece (replaced or a new variant kept alongside), whether credits are refunded on failure, or why it is non-idempotent—all material for a paid mutation.

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 clauses, cost warning placed up front, no filler. The phrase "director's pieces" is slightly oblique and the trailing "credits: price.credits_per_picture" reads as a terse field pointer, but nothing is wasted.

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

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

No output schema exists, so the description should say what comes back—presumably a redrawn piece plus remaining credits—and whether the original is preserved. Given the paid, non-idempotent, sibling-rich context, the definition is minimally adequate but leaves the agent guessing about results.

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, including the note example and the piece number. The description restates the optional note and the credits price without adding format or constraint detail, so the schema is doing 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?

"Draws one of the director's pieces again" gives a concrete verb (redraw) and resource (a lookbook piece), so the action is legible. It does not distinguish itself from close siblings like keep_music_video_lookbook_piece or redesign_music_video_lookbook, which an agent would need to tell apart.

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 only usage hint is that the note is optional and describes a change to make. There is no statement of when to call this instead of redesign_music_video_lookbook (whole lookbook) or keep_music_video_lookbook_piece (accept a variant), and no prerequisites or preconditions given.

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

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

Annotations already declare readOnlyHint=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?

Goes well beyond the annotations by disclosing billing semantics (credits are held then charged per picture, failed draws are not charged), the 409 price-mismatch error path, and the async polling requirement. These are exactly the traits an agent can't derive from readOnlyHint=false / idempotentHint=false.

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 dense sentences, zero filler, with the core action and credit spend front-loaded and the polling instruction last. Every clause carries operational information.

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

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

With no output schema, the description correctly covers the async lifecycle by pointing to get_music_video_lookbook for results. It doesn't describe what a completed lookbook contains or how failures surface in the polling status, which are minor residual gaps.

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

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

Schema coverage is 100%, so baseline would be 3, but the description adds real meaning: credits must equal price.draw.credits and a different value yields 409 with the current price. That constraint is not expressible in the schema and directly affects how the agent should populate the 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 ('Draws'), resource ('pieces'), and a meaningful scope constraint ('not drawn yet'), which implicitly separates it from redraw_music_video_lookbook_piece. It never names the closest sibling (redraw_*/redesign_*) explicitly, so the agent must infer the boundary between drawing new vs. re-drawing existing pieces.

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 concrete post-call guidance: poll get_music_video_lookbook until status is ready, and warns that a mismatched price returns 409. It does not state prerequisites (e.g., whether design_music_video_shoot must run first) or when to choose redraw_music_video_lookbook_piece instead.

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 establish readOnly=false, idempotent=false and destructive=false; the description adds consequential behavior they cannot express — that retrying incurs a new charge, that the existing Look, background media and loops are reused so prior work isn't re-billed, and the edge case where a pre-Look failure forces a fresh design. That is real cost and reuse semantics beyond structured fields.

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

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

Three tight sentences, front-loaded with the action and the cost warning, then reuse behavior, then the failure edge case. Every sentence carries distinct information with no restatement of the title or schema.

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

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

With no output schema, the description should ideally hint at what comes back (a new video id vs. reusing the same one) and whether the prior video record is replaced or coexists. It otherwise fully covers eligibility, cost, and reuse, so only that return-value ambiguity remains.

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 (video_id) with 100% schema description coverage, so the schema already carries the meaning. The description adds nothing about the id's format, source, or behavior on invalid ids, so this is the standard 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?

States a specific verb and resource ('Run a finished, failed or cancelled video again') and scopes exactly which video states are eligible for retry. This implicitly separates it from create_lyric_video (new video) and cancel_video (terminal state), so an agent can route 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?

Clear usage context: this is for videos that already exist in a finished, failed, or cancelled state, and the parenthetical '(new charge)' warns of cost before invoking. No sibling alternative is named explicitly (e.g. when to prefer create_lyric_video), so it stops 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 cover readOnly/openWorld/idempotent, yet the description still adds real behavior: 24 results per page, the fact that clips too short for the loop are excluded, and the meaning/size of the returned URLs. It does not mention auth requirements, rate limits, or empty-result 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?

Front-loaded with purpose, then pagination, then usage and parameter clarification. Dense but each sentence carries information; it is a single run-on paragraph that could be broken into clearer units.

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 appropriately carries the return-value burden by describing thumbnail_url, preview_url, and preview_video_url. Combined with pagination and integration guidance, it is nearly complete, though error/empty-result handling is unaddressed.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: orientation is mapped to aspect ratios ('portrait for 9:16 and 1:1, landscape when 16:9 is among the formats') and seconds is tied to the clip-length filtering rule. q and kind are left to the schema.

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

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

The description opens with a specific verb and resource: 'Find stock photos or clips to use as a background.' The intended use (background media) is stated, which is clearer than most siblings. It doesn't explicitly contrast itself with upload_background, so it stops short of full sibling differentiation.

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

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

It explains how the result is consumed ('Pass an item's id as look.background.stock_id ... or as a Canvas's stock_id to use it instead of the director's pick') and the Canvas-vs-Look loop distinction via the seconds parameter. It gives clear context but never states when not to use this tool or names an alternative.

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

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

Annotations already declare it a non-destructive, idempotent mutation. The description usefully clarifies that the source photo is left unchanged and that the result is a 512px square image_url cut from the photo, which goes beyond the annotations and adds real value, but omits permissions or any return/update propagation detail.

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 dense sentences, front-loaded with the action and effect. Nearly every clause carries information, though the prose is fairly packed.

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 non-destructive, idempotent mutation with no output schema, the description covers the effect, the side-effect (source photo unchanged), and crop semantics adequately; only minor operational details (like idempotency behavior) are left to annotations.

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

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

Schema coverage is 100%, so the schema baseline is 3, but the description adds meaningful semantics for crop beyond the schema: x/y as the top-left corner in fractions, size relative to the photo's short side, and centering when omitted.

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 (choose the photo that becomes the artist's picture and its crop). It is clearly distinguishable from siblings like add_artist_photos and delete_artist_photo, though it does not name those alternatives explicitly.

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

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

The description implies the use case (replacing the artist's picture with a chosen photo) and hints at the workflow via 'the first photo becomes the picture automatically', but gives no explicit when-to-use/when-not guidance or named alternatives in the body.

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 (idempotent, non-destructive, openWorld) cover the safety profile, and the description adds real behavioral context beyond them: published Looks join the Community library under @username, publication earns 10 credits, and a Look showing an artist returns 409. Auth requirements and the response body are not described, keeping it below 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, front-loaded with the core action, and each sentence contributes distinct value (effect, side effect, error condition). 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?

For a simple two-param mutation with an idempotent annotation and no output schema, the description covers the outcome, the community-library consequence, and the 409 edge case. Only the auth/return behavior is left implicit, which is minor here.

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 50% and the visibility enum already enumerates public/private, so the description adds little syntactic meaning beyond restating those values. The look_id parameter is documented in the schema, and the description does not extend it.

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

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

States a specific verb+resource ('Make one of your Looks public or private') and clearly distinguishes itself from siblings like rename_look and delete_look. An agent can identify the operation 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?

The description makes clear this is the tool for toggling Look visibility, and context signals show no obvious alternative sibling. It gives the effect of each choice but does not explicitly name when-not to use it or a substitute 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?

Despite annotations already marking this destructive and idempotent, the description adds substantial behavioral context: matching lyrics that don't align return 409 and leave the song unchanged, results are synchronous (analysis.lyrics) or async (202), and videos made afterward use the lyrics while existing videos are untouched. This is exactly the kind of beyond-schema disclosure the annotations cannot supply.

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?

Dense but well front-loaded: the core action comes first, then format, then validation and timing semantics. Some sentences are long, but each carries distinct information rather than restating the title or 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?

There is no output schema, so the description must cover return behavior, and it does: synchronous analysis reporting (analysis.lyrics) versus asynchronous 202, plus the 409 failure mode. For a two-parameter destructive mutation, the coverage 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 coverage is 100%, so baseline is 3, but the description adds real meaning beyond the schema: lyrics may be plain text with Suno-style [Verse]/[Chorus] tags and (x2) repeat marks, or the contents of an SRT, WebVTT, or LRC file, and timing always comes from the audio. This clarifies the accepted input format in ways the schema's maxLength/minLength cannot.

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 leads with a specific verb + resource: 'Give a song its own lyrics, or replace them,' which unambiguously identifies the action. It does not name the sibling it contrasts with, such as clear_song_lyrics, so an agent must infer the distinction, but the purpose itself is stated with precision.

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

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

The description implies usage ('replace them', 'your text fixes misheard words') and specifies rejection conditions, but never states when to choose this tool over clear_song_lyrics or reanalyze_song. It is adequate but leaves 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 only declare the safe read profile (readOnly, idempotent, non-destructive), but the description adds the crucial interaction model: this renders an interactive gallery, waits for a pick, and returns it as a message naming the Look. That return/round-trip behavior is exactly the kind of trait the annotations cannot express, though latency/blocking expectations are unstated.

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

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

Three sentences, zero waste: core behavior first, then when-to-use and the song_id variant, then the return contract. Each sentence earns its place and the most important information is front-loaded.

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 nine fully documented parameters and no output schema, the description provides the one thing the schema can't: what calling this actually produces (an interactive gallery plus a message naming the pick). Nothing essential is missing, though the absence of any latency/interaction-cost note is a minor gap.

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

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

Schema description coverage is 100%, so all nine parameters are already documented in the schema. The description's only param note (song_id previews with an analyzed song) restates what the schema already says, adding no new syntax or format detail. Baseline 3 applies.

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

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

States a specific verb ('Shows') and resource ('Looks') plus the distinctive modality: a gallery the person can play and pick from, with each Look playing as the real render. That interactive framing implicitly separates it from list_looks, but the sibling is never named, so an agent must infer the distinction.

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 triggering condition ('whenever they want to see, browse or choose Looks') and explicitly scopes song_id to previewing with an analyzed song. However, 'browse' overlaps with list_looks and no when-not or alternative is offered, leaving the boundary 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?

The annotations already establish that this is a read-only, idempotent, non-destructive, closed-world operation. The description adds useful context about what each result contains, including covers, length, analysis status, and available lyric/Canvas/music-video offerings.

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

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

The description is two sentences and front-loads the returned content before the usage cue. It is appropriately sized with no redundant or wasted phrasing.

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 list tool with full parameter documentation and annotations, the description is mostly complete: it explains the result contents and the primary use case. It is only missing explicit sibling differentiation, especially against list_songs and get_song.

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 q, limit, offset, and artist_id are already documented in the schema. The description does not add meaning beyond the schema for filtering, paging, or limiting.

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: it shows the person's songs as a list, and it names the returned contents such as covers, length, analysis status, and available video types. It is clear, but it does not explicitly distinguish itself from siblings like list_songs or get_song.

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

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

It gives an explicit usage cue: use it when the user wants to see or pick a song. However, it does not say when not to use it or name alternatives such as list_songs or get_song for narrower lookup needs.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the remaining burden is low, and the description adds genuinely new behavior: the card renders on its own with progress, then plays, plus a download per format. It also removes an expected precondition by stating wait_for_video is unnecessary. Minor gap: nothing about what happens with an invalid or still-queued id.

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

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

One front-loaded sentence led by the verb, with the post-create nuance and the fallback trigger appended rather than buried. No redundant restatement of the title or 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?

No output schema exists, and the description compensates by explaining what the caller gets back (a player card with render progress and per-format downloads). For a one-parameter read-only display tool that is close to sufficient; only error/edge behavior is left unstated.

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

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

Schema coverage is 100% and the single parameter's constraint (1-8 items) is fully documented there, so the baseline applies. The description adds that the ids come from the create_* tools' return values, which is useful provenance but not additional format or semantics beyond the schema.

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

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

States a specific verb and resource ("Shows videos as players") and describes what that actually means: a live render with progress, then playback with per-format downloads. It implicitly separates itself from get_video/list_videos by describing a player surface rather than data retrieval, though it never names those siblings explicitly.

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

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

Gives explicit trigger conditions: immediately after create_lyric_video, create_canvas, or create_music_video using the returned ids, or whenever the person asks to see a video. It also names the alternative it supersedes ("no need to wait_for_video then"), which is exactly the routing decision an agent needs.

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

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

Goes well beyond the annotations: public visibility to Kinetune's users under the person's real name, privacy exclusions (no private links or contact details), a consent requirement, the self-vote/follow side effect, an email notification when the idea ships, and a rate limit of 5 per day. For a non-idempotent, non-read-only write these are exactly the traits an agent needs.

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 what the tool does, then trigger, then safety constraints, then limits — a sensible order with little waste. It runs long and packs several constraints into single sentences, but each sentence carries distinct operational value.

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 three simple parameters, full schema coverage and no output schema, the description covers everything an agent needs: when to call it, what gets published and under whose name, what consent is required, side effects, and the rate cap.

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

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

Schema coverage is 100%, so the baseline is 3. The description reinforces title ('one line, in the person's words') and body ('how they would use it'), but this largely restates the schema's own descriptions, and the `area` enum is never mentioned in the description.

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 ('Suggest a feature or change', 'Posts an idea to the Community board') plus the outcome (others vote and comment). No sibling tool does anything similar, so there is no ambiguity to resolve.

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

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

Gives an explicit trigger with a quoted user utterance pattern ('Use it when the person asks for something the product can't do yet: "I wish it could…"') and a consent precondition ('ask before posting'). No alternative tool is named, but none exists in the sibling set, so the guidance is close to complete.

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 (not read-only, not destructive, idempotent, closed-world), and the description adds genuinely new facts: it is free, it skips a director call, and it returns the next draft with treatment and shots preserved. That cost and mutation semantics are exactly the context annotations can't express; only the fate of the prior draft is left implicit.

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 (~35 words) with the outcome and cost stated up front and the input rule last. Slightly telegraphic openings ("Another stock photo for one of a plan's places") cost a beat of clarity, but nothing is wasted.

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

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

For a 3-parameter mutation with no output schema and full annotation coverage, this is close to sufficient: effect on the plan, return behavior, and cost are all stated. A sentence on whether the previous draft is discarded would close the last gap.

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

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

Schema coverage is 100%, so baseline would be 3, but the description adds real constraints on stock_id beyond the pattern: it must come from search_stock, depict the same kind of place, and contain no people. Those are semantic selection rules the schema cannot encode.

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?

"Another stock photo for one of a plan's places" plus "Returns the next draft: the same treatment and shots, set in this photo" states the resource being replaced and the effect (a re-rendered draft), which clearly distinguishes it from siblings like redesign_music_video_lookbook or design_music_video_shoot. The phrasing is slightly elliptical — the verb "swap/replace" is only implicit in "another photo" — but the title reinforces it.

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 selection criteria ("same kind of place, with no people, from search_stock") and a cost/effort condition ("no director call, free"), which tells the agent when this is preferable to a full regeneration. What's missing is an explicit when-not-to-use case or a named alternative that does trigger a director call.

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