Kinetune

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

Goes well beyond the annotations, which only say non-read-only, non-destructive, open-world, non-idempotent. It discloses real operational behavior: handle auto-derivation from the name with a '-2' suffix when taken, workspace-wide handle uniqueness, shared defaulting to false, handle-level implications for music video briefs, and image validation bounds (JPEG/PNG/WebP, 512 px short side, 15 MB, rights_confirmed). It also surfaces two failure modes with their codes and remediation – 402 plan_required and 402 storage_full, both checkable via get_account.

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 dense and mostly earns its place given 11 parameters and nested crop semantics, but the structure is poor: it opens mid-sentence with an object fragment instead of the action, and reads as one undifferentiated block. The shared/owner_name rule is stated twice in near-identical wording ('shared true offers it to every other artist's songs too (default false)' appears in both the second and fifth sentences), which is pure waste.

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-object create with no output schema, the description covers the pieces an agent would otherwise get wrong: which id goes where, the source fork, the crop rationale, and both precondition failures with error codes and where to check them. The notable gap is the return value – with no output schema, the agent is not told what a successful call yields (presumably the piece and its generated handle), which matters here because the handle is auto-derived.

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 baseline is 3, and the description does add genuine meaning on top: the default resolution rule for owner_artist_id, the artist_id-is-outfits-only rule, where stock_id comes from, and the crop fraction semantics for cut-outs. However, it says nothing about the description parameter, the shared-vs-owner_name interaction is only partly explained, and several parameters (name length, handle pattern, crop minimums) are left entirely 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 names the resource precisely (an outfit, place or prop in an artist's kit) and explains the kit/artist/song relationship, which an agent cannot get from the schema alone. It is weakened only by the opening fragment 'An outfit, place or prop from an image, a link or a stock photo, cropped' – no verb is stated, so the agent must infer 'add' from the name/title rather than the prose. It does implicitly separate itself from search_stock (source of stock_id) and get_account (plan/storage preconditions).

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?

Strong conditional guidance: outfit → artist_id, place/prop → owner_artist_id with a stated fallback chain (workspace's only artist, else first, shared), and an explicit source decision between an upload/file_url and a stock_id from search_stock (credited, no rights needed). It also states the crop use case ('for a prop cut out of a bigger photo'), which tells the agent when that parameter matters. It never contrasts with the obvious siblings update_kit_piece, delete_kit_piece or get_kit_piece, and gives no when-not guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered; the description adds the useful behavior that the server returns 409 Refused when songs still exist. It does not say whether archived artists/associated photos and kit pieces are retained or restorable.

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-loads the action, but the sentence is grammatically tangled ("has no songs Refused (409) while the artist still has songs"), forcing the reader to reconstruct the precondition and the error condition from fragments.

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 tool with annotations covering idempotency and destructiveness, the description supplies the missing pieces: the song-count precondition and the 409 outcome. Only the post-archive state of the artist and related assets is left unexplained.

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 carries the burden and baseline 3 applies. The description adds nothing about artist_id format or where to obtain it (e.g., from list_artists).

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 ("Remove an artist") and scopes it to artists that have no songs, which separates it from create_artist/rename_artist/get_artist. It doesn't distinguish itself from any delete-style sibling, and "Remove" reads slightly at odds with the archive_artist name, but the operation is recognizable.

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 precondition for calling it — the artist must have no songs — which is the key usage gate for an agent. No alternatives are named and reversibility/restore paths are not mentioned, 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 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 genuinely useful behavioral context that annotations cannot express: future videos will render with the auto-transcribed words. It stops short of stating whether the removed lyrics are recoverable or what precondition (an existing custom lyric set) is required.

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?

Only two short sentences, so there is no padding, but the second sentence is grammatically broken and reads as a run-on, which hurts front-loading and scanning. Brevity is not the issue; legibility is.

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 tool with no output schema and annotations covering the destructive profile, the description is close to sufficient. However, for a destructive revert it omits whether the change is reversible and what state the song must be in, which are the two things an agent most needs before invoking 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?

There is a single required parameter (song_id) at 100% schema coverage, so the schema fully documents it. The description never references song_id or clarify that it targets one song's lyric set, so it adds nothing beyond the schema, capping this at the 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 title 'Remove a song's lyrics' supplies a specific verb and resource, and the description explains the resulting state ('go back to the transcribed words'). The garbled phrasing ('Videos made from then on show the words as transcribed') weakens it, but an agent can still tell this clears custom lyrics rather than editing 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?

There is no explicit when-to-use guidance and no mention of the obvious counterpart sibling, set_song_lyrics, which is the tool to call for the opposite operation. The agent must infer that this is the revert/undo path from the title alone.

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

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

Annotations only declare the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false); the description adds three concrete behavioral facts beyond them: name uniqueness per organization returning 409, a second artist in a workspace being refused with 409, and operation without a plan. That is exactly the kind of failure-mode disclosure an agent needs before calling a 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, with the identity of the tool front-loaded. Minor flaw: the first two sentences run together without punctuation ('by name Names are unique'), which slightly hurts scanability.

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

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

For a one-parameter mutation with no output schema, the description covers the identity, the error conditions, and the plan-independence. It does not indicate what comes back on success (the created artist/id), which an agent may need for follow-up calls like set_artist_picture — the only real 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% and the single parameter carries min/max length, so the baseline is 3. The description earns above baseline by attaching the real semantic constraint to the name — uniqueness per organization — which the schema does not express.

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 ('Add an artist by name') and immediately characterizes the domain constraints (unique per organization, one artist per workspace). An agent can distinguish this from create_organization or add_artist_photos 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?

Gives clear context for when this is the right call: it works without a plan so onboarding can add the artist first, and it names update_organization as the path once a workspace must become a label. It stops short of explicitly naming a sibling alternative for the create case (e.g. list_artists to pre-check for a duplicate).

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 credit spend, async job behavior with the exact polling target, the external upload step in Spotify for Artists, and the two concrete failure modes (402 plan_required, 402 storage_full) with the fields to check first. It does not reconcile idempotentHint=true with a credit-spending create, so the duplicate-call cost behavior remains unclear.

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 with useful facts and short, but written as disconnected fragments with a garbled lead sentence, so the most important idea (this operation spends credits) is obscured rather than front-loaded. No padding, but poor readability.

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, 100%-documented create tool with no output schema, it covers the essentials an agent needs: prerequisites, billing, the async return-and-poll pattern, and post-creation upload. Gaps remain around idempotency/duplicate submission and how variations affect cost.

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, and the description mainly reinforces quote_id ('same request as the quote'). The one genuine addition is the cross-parameter identity constraint between quote and create, but it doesn't mention any of the 15 parameters by name beyond quote_id.

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 (create the Canvas, priced via a quote, spending credits) and describes the async outcome (video ids returned, poll get_video). The opening fragment 'Make the Canvas a quote priced' is grammatically broken, and it never explicitly distinguishes itself from create_music_video or create_lyric_video, so it stops 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?

Makes the quote-first flow explicit ('Send the same request as the quote plus its quote_id') and names the follow-up tools to use: get_video for polling and get_account for plan/storage prechecks. It does not name quote_canvas directly or say when to choose a Canvas over a music video, so the alternative routing is implied rather than stated.

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

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

Beyond the annotations, it discloses that credits are spent, that video ids are returned immediately, that polling get_video is required, and that each format produces its own file. It also documents active-plan and storage requirements with specific error codes 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 description is dense but every sentence carries useful information, and it is front-loaded with purpose, billing, and the quote requirement. The opening clause is grammatically awkward and slightly slows comprehension, but there is no obvious 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 complex 9-parameter creation tool with no output schema, it covers the essential behavior: cost, quote matching, immediate return of video ids, async polling, per-format files, plan requirements, and storage failures. Combined with the detailed input schema and annotations, an agent has enough context to call it correctly.

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

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

Schema description coverage is 100%, so the nested schema already documents the parameters thoroughly. The description adds the important cross-parameter constraint that the request must match the quote exactly and include its quote_id, but it does not add much semantics for the other parameters beyond what the schema already provides.

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

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

The description states that this creates the lyric video from a quote and spends credits, which is a specific verb and resource. It implicitly distinguishes itself from quote_lyric_video by requiring the same request plus quote_id, though the phrasing "Make the lyric video a quote priced" is awkward.

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 indicates the workflow: use the same request as the quote plus its quote_id, then poll get_video until completion. It also states plan and storage prerequisites and the corresponding 402 errors, but it does not explicitly name quote_lyric_video as the required prior step or explain when not to use this tool.

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

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

The annotations already disclose non-readonly, open-world, idempotent, and non-destructive behavior. The description adds useful operational context beyond annotations: credits are spent, video ids return immediately, completion is asynchronous, and rendering takes roughly five minutes per minute of song.

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 mostly front-loads the key workflow, return behavior, timing, and preconditions. The opening phrase 'Make the music video a quote priced' is awkwardly worded, but the rest is efficient.

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 25-parameter asynchronous generation tool, the description covers the essential lifecycle: quote matching, credit spend, immediate video-id return, polling, timing expectations, and plan/storage prerequisites. The detailed schema carries the per-parameter semantics.

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 96%, so the input schema already documents nearly all 25 parameters in detail. The description clarifies the central quote_id rule that the request must match the quote, but otherwise does not add much parameter-level 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?

The description states a specific verb and resource: make a quote-priced music video. It distinguishes the operation from quote_music_video by requiring the matching quote_id, and from get_video by explaining the immediate video-id return followed by polling.

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 procedural guidance: send the same request as the quote plus its quote_id, then poll get_video until status is completed. It also names preconditions and failure cases, including active plan requirements, storage requirements, and which get_account fields 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?

Beyond the annotations (which only say this is a non-read-only, non-destructive, non-idempotent write), the description discloses real behavioral facts: the new org starts with no plan and no credits and is unusable until the owner subscribes, and API-key calls require the organizations:write scope and act as the member who created the key. Those are non-obvious auth and post-condition details the agent could not infer.

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?

Almost every sentence carries useful content, but the structure is poor: the opening is a duplicated/garbled fragment, the type guidance is packed mid-paragraph, and the credential paragraph is long and appended rather than front-loaded. It is dense rather than concise.

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

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

For a two-parameter creation tool with no output schema, the description covers the prerequisites (plan and credits), the auth requirement (organizations:write), the meaning of each type, and how to continue working in the new org. Nothing an agent needs in order to call 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 coverage is 100%, so the schema already documents name and the type enum, meaning the baseline is 3. The description adds workflow semantics on top: choosing 'artist' implies a follow-up create_artist call and removes the need for artist_id on later songs, while 'label' means a roster — information not present in the enum 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?

The description states a concrete verb and resource: it creates an empty organization (workspace) owned by the signed-in person, and it spells out the three type values with their practical meaning. It is distinguishable from siblings such as create_artist, though the first sentence is a garbled fragment ('A new organization owned by you... Creates an empty organization') that briefly muddies the read.

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 explicitly routes the agent between type choices ('type artist is for one artist (add that artist next with create_artist; its songs then need no artist_id), label for a roster') and states the prerequisite that the owner must pick a plan before anything can be created. It also tells the caller what to do afterward with existing credentials (sign in again and pick it, or create an API key in it), which is exactly the when/after guidance 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?

Going well beyond the annotations (which only say it is a non-read-only, non-idempotent, open-world write), the description discloses the async lifecycle (analysis runs after upload, ~1 minute, must be polled), the irreversible cover-art transformation (re-encoded to 1536/640/160 px, "not as uploaded"), and the post-hoc lyrics validation that can reject the upload as a mismatch. It also names the account-level gating conditions and their HTTP status codes, which is exactly the operational context an agent needs before calling a mutating, quota-consuming 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 a single dense paragraph with the core action front-loaded and the dependency/polling guidance after it; every sentence carries operative information (limits, async flow, error codes, alternatives). The run-on punctuation around the cover-art sizes slightly hurts scanability, but there is 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 7-parameter mutating tool with no output schema, dependent on async analysis and account quota, the description covers the full call-to-result arc: what to send, what happens to the files, how to know when it is done, which sibling to call next, and which prerequisite tools to check. Nothing an agent needs to invoke or follow up 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 adds constraints the schema does not carry for audio_url: accepted formats (MP3, WAV, M4A) and the 250 MB ceiling, plus the cover-art pixel and 20 MB bounds. It also explains the payoff of supplying lyrics (word-accurate videos) and points at set_song_lyrics as the deferred path, adding intent beyond the field definition.

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 first clause names a specific verb and resource ("Add a song") and immediately names the two primary inputs, master audio and square cover art. It is clearly separable from siblings like rename_song, set_song_lyrics, or create_lyric_video, which operate on an existing song rather than creating one.

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

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

It gives concrete follow-up routing: poll get_song until analysis.status is "ready", and pass lyrics now or use set_song_lyrics later. Preconditions and their exact failure signals are spelled out (402 plan_required / plan check via get_account, 402 storage_full / storage via get_account). It stops short of an explicit "do not use this for X, use Y instead" exclusion, which keeps it just below a 5.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description nonetheless adds real context beyond them: deleting a piece invalidates any plan that referenced it, and the user must re-plan. That cascade effect is the kind of downstream impact annotations cannot express.

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

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

Very short, but two unrelated thoughts are jammed into one unpunctuated string, and the second clause is garbled ('A plan that used it can't be made any more'). The consequence information is worth keeping; the phrasing costs comprehension.

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 delete with no output schema, the definition covers the resource, the destructive nature (via annotations) and the downstream plan impact. It never states whether the deletion is recoverable, which is the one gap an agent might still need.

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, and the schema documents it fully ('The kit piece id', with min/max length), giving the 100%-coverage baseline of 3. The description adds nothing about id format or where to obtain a valid kit_id.

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 verb 'Remove' plus the concrete kit-piece kinds ('outfit, place or prop') make clear exactly which resource this deletes, distinguishing it from delete_look, delete_video and delete_artist_photo. It stops short of naming a sibling explicitly, and the missing punctuation turns the sentence into a run-on.

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 statement of when to choose this over update_kit_piece or archive_* alternatives, and no prerequisites. The closing note about plans is a consequence, not routing guidance for the call itself.

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, so the safety profile is covered. The description adds real value beyond them: the Look must belong to the workspace, and a public Look's reward is returned as a side effect. It still doesn't say whether deletion is permanent or how failures are surfaced.

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 compact sentence, front-loaded with the action and resource. The parenthetical consequence is efficiently attached rather than buried in a second paragraph.

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

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

For a destructive, single-parameter tool with no output schema, the definition covers ownership scope and the reward side effect, which is a reasonable minimum. It remains silent on irreversibility and post-deletion behavior, which an agent invoking a destructive call would want to know.

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% with a single documented look_id and an explicit id pattern, so the schema carries the parameter semantics. "The workspace's own Look" implies the id must resolve to owned content, a mild addition beyond the schema, but no format or error semantics are added.

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?

"Removes the workspace's own Look" gives a specific verb plus resource and adds an ownership qualifier, so the agent knows this deletes a Look rather than a Lookbook or plan. It does not explicitly say "music video Look" or distinguish itself from the sibling delete_look, so differentiation rests partly on the name and title.

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 never states when to call this versus delete_look, delete_music_video_lookbook, or delete_music_video_plan, nor does it mention prerequisites before deletion. The "workspace's own" phrasing hints at a restriction but gives no actionable when-to-use 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 destructive/idempotent/non-readonly, but the description goes further: it discloses the cascade (pictures are deleted too), the non-refund of already-drawn pictures, and the two concrete 409 conditions. That is exactly the extra context annotations cannot express.

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

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

Dense and front-loaded, but the phrasing is garbled and missing punctuation ("with its pictures Only a lookbook no shot list or video was made from"), which forces re-parsing. The parenthetical error codes are efficient, but the second sentence duplicates the first sentence's precondition.

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

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

For a destructive, single-parameter delete with no output schema, the description covers preconditions, cascade behavior, and refund semantics, which is nearly everything needed. It could briefly state what a successful call returns or whether the id remains queryable, but nothing essential to a correct 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?

There is a single required parameter with 100% schema description coverage including a format pattern, so the schema carries all the meaning. The description adds nothing about lookbook_id beyond what the schema states; 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 concrete verb (deletes), resource (lookbook), and scope (only a lookbook nothing was made from), and explicitly notes what it also removes (its pictures). This separates it from sibling delete_music_video_look / delete_music_video_plan / delete_look without the agent having to open another 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 two 409 preconditions (a shot list or video exists; pictures are currently being drawn) effectively tell the agent when not to call it, and implicitly route a blocked case elsewhere. It does not name the alternative tool to use when a 409 would occur, so it falls short of a full routing instruction.

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, but the description adds genuinely new information: the delete cascades to every draft the plan was rewritten from and into, plus their drawn frames, and the operation fails with a 409 when a video exists. The garbled phrasing weakens it, and it does not state whether the deletion is recoverable.

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 text is malformed and self-repeating: "with every draft of it Deletes the shot list with the drafts it was rewritten from and into" restates the same cascade twice in broken syntax. The important cascade and 409 facts are present but buried in unparseable structure rather than 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?

For a single-parameter destructive delete with annotations and no output schema, the definition covers the two things the agent most needs: what is destroyed alongside the plan, and the failure condition. Missing only recoverability and confirmation expectations, and the garbled wording makes the cascade scope harder to trust than it should be.

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% with a single required plan_id already documented with its pattern, so the schema carries the parameter burden. The description adds no syntax, format, or ID-source detail beyond what the schema supplies, which is the baseline case.

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

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

The description names a specific verb and resource ("Deletes a shot list") and ties it to the plan_id resource, which distinguishes it from delete_video, delete_music_video_look, and delete_music_video_lookbook in the sibling list. It does not explicitly name those siblings, and the run-on grammar blurs the statement of scope, 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?

A precondition is implied: the shot list must not have had a video made from it, and a 409 is returned if it did. That is a constraint rather than routing guidance; the description never says what to do instead (delete_video, cancel_video, or leaving the plan in place), so the agent must infer the alternative 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 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?

Beyond the annotations (which only say non-read-only, open-world, non-idempotent), the description adds rate limiting ('a limited number an hour'), latency ('about a minute'), an explicit cost source (price.draw.credits), and required account state with error codes. It also discloses what the output contains and that the designs are 'not drawn yet', setting the expectation that rendering is a separate paid step.

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

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

The purpose and the sequencing are front-loaded, which is right. But the text is a dense run-on with a repeated clause, and cost, prerequisites and return shape are crammed into one block rather than separated, making it slower to parse than it needs to be.

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

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

For a 15-parameter creation tool with no output schema, the description covers the return value (a lookbook of brief kit pieces plus designs, not yet drawn), the cost, the gating conditions and the follow-up call. What remains thin is how the lookbook relates to update/redesign/delete lookbook siblings, which an agent must infer from names.

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 93%, so the burden is largely on the schema, and the baseline of 3 applies. The description adds framing about kit pieces being used as-is versus director-designed pieces, which informs direction and cast semantics without adding anything not already documented per-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?

The description states a concrete verb and resource: the director designs outfits, places and props as pictures, producing a lookbook. It distinguishes itself from the shot list (plan_music_video) and from rendering (render_music_video_lookbook), so siblings are separable. The phrasing is muddled by a duplicated fragment ('before the shot list Optional, before the shot list (plan_music_video)'), which slightly dulls an otherwise precise 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?

Explicit ordering: run this before plan_music_video, then tell the user price.draw.credits, then call render_music_video_lookbook after their go. Prerequisites are spelled out with the exact failure signals (402 plan_required, check get_account plan.active; 402 storage_full, check get_account storage).

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 contributes the concrete scope of destruction — uploads and sheet — which is real added value. It stops short of stating whether the character request record itself is removed, whether the action is reversible, or whether anything else (e.g. face checks, looks) is 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?

Five words is not concision here, it is under-specification: the single sentence omits the object of the action and any consequence detail. There is nothing extraneous, but the description is too thin to earn its place as the primary semantic signal.

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

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

This is a destructive, irreversible-sounding operation on a workflow entity, and the description never says what remains after the call, whether the parent request survives, or what the caller should expect. Annotations cover the read/write and destructiveness flags, but the description should carry the domain consequences for a delete-style 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?

The single parameter request_id is fully documented in the schema (100% coverage) including the charreq_ prefix convention. The description adds no further meaning about the identifier or how to obtain one (e.g. via list_character_requests). With the schema doing the work, 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?

"Deletes its uploads and sheet" names a verb and two affected artifacts, but the pronoun "its" has no antecedent in the description itself — the agent must read the tool name or title to know it operates on a character request. The purpose is inferable but not stated explicitly, so it lands at vague rather than 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?

There is no guidance on when to discard versus keep (the sibling keep_character), when a request is eligible for discarding, or what state the request must be in. The agent is given no conditions or alternatives, only a bare statement of effect.

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 it is a non-read-only, non-idempotent, non-destructive write; the description adds genuinely new behavior: billing occurs only after the sheet passes a check (one person, clear face, no text), and a failed check is redrawn once free. That charging and retry semantics are exactly what an agent needs before spending user credits. It omits timing/asynchrony and how the result is retrieved, which keeps it off a 5.

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

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

It is short in word count but poorly structured: one run-on block with stacked parentheticals and an ungrammatical opening clause that obscures the main action. The valuable facts (billing rule, check criteria, outfit constraints) are buried mid-sentence rather than front-loaded, so density is achieved at the cost of comprehension.

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 paid, non-idempotent generation tool with no output schema, the description covers the essentials an agent needs: cost source, user consent, what gets drawn, how redraws differ, and the billing/validation outcome. The remaining gap is lifecycle detail (how long it takes, whether get_face_check must be polled afterward) rather than anything blocking a correct 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 coverage is 100%, so 3 is the floor, and the description earns more: credits is tied to price.credits from get_character_request (a value source, not just a type), outfit is pinned to "the base outfit line as the user left it" with explicit rendering constraints (one top, fitted trousers or skirt, solid colours, barefoot, no jewellery), and note is scoped to redraws with an example.

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 does convey that this generates a character sheet from a character request and can redraw it with a note, but the opening sentence is garbled ("Draws the sheet for the credits shown (again with a note to redraw) From photos, or an added sheet drawn again as a plain base sheet") and has to be re-read to parse. It never names siblings like start_character, keep_character, or get_face_check to delimit scope, so the agent must infer where this sits in the flow.

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?

"credits must be price.credits from get_character_request: tell the user first" gives a concrete prerequisite (call the sibling get_character_request) plus a consent step before charging. The note parameter is framed as the redraw path ("what to change when drawing again"). It stops short of explicit when-not guidance or stating what to do after a failed check, so it is strong but not 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?

Well beyond the annotations, it discloses billing behavior on retry ('replaces its frame for the same price'), the 409 price-mismatch protocol, roughly one minute of latency, no charge on failure, 400 for ineligible shots, plus 402 plan_required and storage_full prerequisites. This is exactly the operational 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 action and cost, then consent, pricing, retry semantics, and error codes in a tight sequence. It is dense and parenthesis-heavy but nearly every clause earns its place; the run-on flow slightly hurts readability.

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 paid mutation with no output schema, the description covers pricing, consent, retry semantics, latency, all relevant error codes, prerequisites, and follow-up tools. An agent has everything needed to call it safely and 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 meaning: credits must equal the price the user agreed to and a mismatched value returns 409 with the current price, and shot maps to a planned shot's opening frame. That goes beyond the schema's restatement of the same fields.

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 ('Draws the picture a planned shot opens on') and immediately flags the cost dimension. It is clearly distinguishable from siblings like draw_character_sheet or revise_music_video_shot by naming the planned-shot opening frame as its target.

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 when-to-use guidance ('Good for the shots that matter most (the opening, the hook); the others are made from their references as usual'), a consent prerequisite (tell the user the price, draw only after their go), and the downstream sequence (quote_music_video and create_music_video with the plan_id).

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

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

Annotations cover the safe, idempotent, non-destructive mutation profile, so the bar is lower. The description genuinely adds behavior beyond them: following triggers an email when the idea ships, delivered under the 'Product news' topic, and the recipient can unsubscribe in-app. It does not say what happens when the person is already following, but the added context is substantive.

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, but the single sentence is malformed — a run-on with a missing separator and the notification condition front-loaded instead of the action. Word count is appropriate; clarity and front-loading are not.

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 one-parameter tool with no output schema and informative annotations, the description is roughly adequate. It omits the repeat-call behavior (though idempotentHint=true covers it) and any pointer to unfollow_idea, so an agent still has to infer the action's meaning from the tool name.

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

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

There is a single parameter with 100% schema description coverage and a documented pattern, so the schema already carries the semantics. The description adds nothing about idea_id or how to obtain one, which matches the baseline 3 when schema coverage is high.

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 explains the consequence of following (email notification when the idea ships) but never states the action itself in verb+resource form, and its wording is garbled ('The person hears by email when it ships Sent under the Product news email topic'). An agent can infer it registers a follow/subscription, but the purpose is only 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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as unfollow_idea (the inverse) or vote_for_idea (a different form of engagement) among the many siblings. The opt-out clause describes a setting in the app, not how or when to invoke this tool.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond them: it explains the 402 plan_required and storage_full responses, that deleting videos or archiving songs frees space immediately, how monthly credits reset versus never-expiring top-ups, and the four free_song states with their prerequisites. It also discloses that image_fallback is derived, never saved, and follows the newest song — exactly the kind of non-obvious behavior an agent cannot infer from 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?

The purpose is front-loaded in the first clause, but what follows is a single ~350-word run-on with deeply nested parentheses covering credits, storage, billing, free_song, and image_fallback in one block. Nearly all content is useful, yet the flat structure makes it hard to scan and the parenthetical layers force 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?

With no output schema and a zero-parameter surface, the description carries the full burden of describing the return shape, and it does so field by field: plan state, storage bytes, billing, renewal date, scheduled_change, free_song states, image_url versus image_fallback. An agent can act on the response correctly without further documentation.

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 no parameters, so the baseline is 4 and there is no parameter meaning to add. The description instead spends its budget on what the no-argument call returns, which is the appropriate substitute.

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

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

The opening sentence names the exact resources returned: the signed-in identity, the organization (workspace), and its credit balance. It also disambiguates the organization concept ('type artist holds one artist, label a roster, creator projects'), which separates it from siblings like list_organizations or get_artist that enumerate rather than resolve the caller's own 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?

It gives explicit when-to-use guidance ('Check it before creating anything') and routes the agent to create_song for the free-song case, plus an instruction to tell the person to pick a plan on 402 plan_required. It stops short of naming which sibling covers listing multiple organizations or when this tool is unnecessary.

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 destructiveHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior: image_fallback is derived from the newest song's cover, is never persisted as the artist picture, and dynamically follows new or archived songs. That is real added context beyond the 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?

The description is a single run-on sentence with garbled syntax ('picture image_url is the picture uploaded for it', 'while it has none'), making it hard to parse. The most important information — what the tool returns — is buried mid-sentence behind awkward clauses.

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 explain return values, and it covers image_url and image_fallback in detail but says almost nothing about the rest of the artist object beyond 'song count'. It is adequate for the image semantics but incomplete as a specification of 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?

Schema description coverage is 100% for the single required artist_id parameter, so the schema already carries the parameter meaning. The description adds nothing about artist_id (format, source, or how to obtain it), so baseline 3 applies.

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

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

The description opens with 'One artist, with their song count and picture', which implies a single-record retrieval but never uses a clear verb like 'fetch' or 'retrieve'. It is distinguishable from list_artists only by inference from the word 'One', and nothing separates it from siblings such as get_song or get_idea beyond the resource name.

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 explicit when-to-use guidance and no mention of alternatives such as list_artists for browsing or get_song for song details. The only guidance is implicit in describing the returned fields.

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 safe, idempotent read. The description adds meaningful behavioral detail beyond them: the status lifecycle, the approximate drawing time, the distinction between price.credits and charged, and what extras represent. It remains somewhat cryptic, but it provides substantial context not present in 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?

The description is compact and avoids filler, but it is written as dense fragments and awkward run-ons. The status list and field explanations are informative yet not front-loaded with a clear purpose statement. It is concise but harder to parse than it needs to be.

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

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

There is no output schema, so the description carries the burden of explaining returned values, and it does so for statuses, sheet.url, price.credits, charged, and extras. It is fairly complete for a status-reading tool. It could still be clearer about where request_id comes from and how this tool fits alongside list_character_requests.

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 required parameter request_id is documented in the schema. The description does not mention request_id or add any meaning beyond the schema. With one fully documented parameter, 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 name and title imply retrieving a character request, and the description explains what its status and output fields mean. However, it opens with return-value fragments rather than an explicit verb+resource statement, so the core action is inferred instead of stated. It does distinguish one sibling, draw_character_sheet, by noting it redraws the character as a base sheet.

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 this is used to check progress, since it documents analyzing, drawing, drawn, and failed states and notes drawing takes about a minute. It also points to draw_character_sheet for redrawing as a base sheet. It does not explicitly say when to use this versus list_character_requests, wait_for_video, or other 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description adds substantial domain behavior: a check is 'done once and covering every model that shares it', a 'waiting' state means a check started in the last 30 minutes, and 'not_needed' also covers AI-made characters. That 30-minute staleness window and the cross-model sharing semantics are things the agent could not derive from the schema or 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?

It is information-dense with little outright filler, but the structure is poor: the opening clause is convoluted and grammatically broken, and the status enumeration is packed into one long colon-chained sentence. A reader must re-parse the first line to figure out what is being returned, so it is not well front-loaded despite being short.

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 fully-documented parameters, no output schema, and annotations covering safety, the description supplies the missing piece: the enumerated status values and what each means, including the failure remediation. What remains unstated is the exact response shape beyond the status value, which is minor for a simple lookup.

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

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

Schema description coverage is 100% and both parameters are documented with an enum for model, so the schema does the heavy lifting. The description adds only modest meaning, linking the model parameter to the get_options music_video.models[].face_check flag and clarifying that character_id represents a real person (performer or people in the video). That is useful but thin relative to 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 conveys the domain meaning well ('whether a model can show this real person yet', face check status), but the leading clause is grammatically broken ('their face check for it') and never uses a clean verb like 'returns the face check status'. It does not explicitly distinguish itself from the sibling read/write pair start_face_check and withdraw_face_check, so the agent must infer that this is the read variant.

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 concrete timing guidance: 'Asked before quoting such a model for each real person in it (the performer and the people)', which tells the agent exactly when in the workflow to call it and that it must be called per real person. The failure state even points toward remediation ('start another'), though it does not name start_face_check explicitly as the alternative tool.

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

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

Annotations already establish readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description does add genuinely non-obvious behavior: merged ideas redirect to the surviving idea, comments are bundled in, and people are rendered by name and picture only. It does not say whether comment sets are truncated or paginated, which matters for a read returning comments.

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 short and front-loads the core payload statement, which is good. The second clause ('Kinetune's word on it status_note is the team's word on its status') is garbled and effectively wastes a sentence on a point the first clause already made, reducing clarity rather than adding 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 does meaningful work by sketching the return shape: the idea, its comments, a status note, names and pictures for people, and merge redirection. For a single-parameter read tool this is close to sufficient, with only pagination/truncation of comments 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 idea_id parameter is documented with its pattern, so the schema carries the load and baseline 3 applies. The description adds one useful semantic nuance: passing an id that was merged into another idea returns the merge target rather than an error, but it gives no format 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 a specific resource and scope: 'One idea with its comments and Kinetune's word on it,' which contrasts with the bulk siblings like list_ideas by making clear this returns a single record. It never names list_ideas as the alternative, and the 'status_note' clause is grammatically tangled enough that the agent must infer what field is being described.

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 explicit when-to-use guidance: no statement that this is the tool for fetching a single idea by id versus list_ideas for enumeration, and no prerequisites such as needing a valid idea id from a prior listing. Usage is only implied by the phrase 'One idea'.

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 declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds genuine value beyond that by disclosing the return shape: backgrounds.portrait/landscape hold full background plates while backgrounds.previews holds 480 px thumbnail copies, and explicitly notes previews is null when a Look has no photo/video background.

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, but the prose is garbled: 'its design and preview images backgrounds.portrait and backgrounds.landscape' runs two ideas together with no punctuation, forcing the reader to re-parse which fields belong to which clause. The valuable null-behavior detail is buried in a trailing parenthesis rather than 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 no output schema, the description usefully explains the nested background fields, which is the most complex part of the response. However, it never mentions the top-level design/preview fields it advertises, nor error behavior for an invalid or unknown look_id, leaving the picture only partly 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 a single parameter (look_id) with 100% schema description coverage, so the schema already carries the semantics; the description adds nothing about format, source, or how to obtain a look_id. 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 description says it returns 'One Look with its design and preview images', which identifies the resource and implies a single-item retrieval, but never states the verb ('retrieve/fetch a Look by id') and does nothing to distinguish it from siblings like list_looks, show_looks, or get_music_video_lookbook. An agent must infer that this is the by-id fetch.

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 explicit when-to-use guidance and no alternatives are named, despite the presence of several closely related siblings (list_looks, show_looks, get_music_video_lookbook, get_video). The reader is left to infer that a known look_id is the precondition.

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/idempotent/non-destructive, so credit goes to the added behavior: both video and story are null while the video is private, and 'Never its maker's written brief' discloses an important privacy exclusion. These are meaningful traits beyond the annotations.

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

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

Despite being a single dense run-on sentence, every clause carries relevant information about the returned fields. Readability suffers from the lack of structure, but no fluff is present.

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 enumerates the returned video and story fields, compensating well for the missing output schema. However, it leaves the relationship to closely named siblings 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 coverage is 100% and the single look_id parameter is fully documented with its pattern. The description adds no meaning beyond the schema about the parameter, so baseline 3 applies.

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

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

The description states it retrieves 'One music video Look' along with the video it was saved from and the story's shots, distinguishing it from list_music_video_looks by scope. The phrasing is grammatically awkward ('One music video Look With the video...'), which slightly blunts an otherwise specific purpose.

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 explicit when-to-use guidance or named alternatives (e.g., get_look vs get_music_video_lookbook). Usage is only implied by the return-shape description and the note that both video and story are null while the video isn't public.

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 read operation, but the description adds meaningful context: the four status values, that 'rendering' means wait about a minute, that image_url appears only once drawn, and what 'kept' and ownership mean. It does not cover error cases such as an unknown lookbook_id, but the added behavioral value is substantial.

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 definition is compact with no filler, but it is a single run-on sentence with awkward phrasing ('as they are drawn status is proposed', 'price: per picture, to draw the rest') that forces re-reading. The return-shape details are front-loaded, but the purpose statement itself is not clearly leading.

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 returns. It covers the piece-level fields and status transitions reasonably well, but the overall response shape and the pricing semantics remain vague, and error behavior 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% and the single lookbook_id parameter is fully documented with a pattern, so the baseline of 3 applies. The description adds no further meaning about the identifier or format beyond what the schema already provides.

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

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

The description identifies the resource as a lookbook and describes its contents and status lifecycle, which is specific enough to distinguish it from generic look tools. However, it doesn't explicitly contrast with siblings like get_look or list_looks, so an agent must infer that this is the music-video lookbook variant.

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

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

Usage is implied rather than stated: retrieving a lookbook and polling when status is 'rendering' ('check back in about a minute') gives a clear operational hint. There is no explicit guidance on when to use this versus get_look, list_looks, or update_music_video_lookbook, leaving alternatives 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 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?

Beyond the read-only annotations, the description discloses important behavior: the catalog is admin-controlled and can change, subscriptions retain purchased terms, and some media URLs are signed for about a week. It also explains fallback and demo behavior, though the sheer density makes these traits harder to absorb.

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 dense, run-on block with heavy parenthetical nesting and semicolon chains. It contains useful details, but the structure obscures the main purpose instead of front-loading 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?

Given there is no output schema and the return object is rich, the description does a thorough job enumerating the catalog sections, pricing data, plan details, model guidance, recommendations, demo metadata, and fallback behavior. An agent has enough context to understand what it will receive.

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 has zero input parameters, so there is nothing for the description to clarify beyond confirming it is a parameterless catalog fetch. Baseline for zero parameters is 4.

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 establishes that this tool returns the catalog of selectable options, including video types, looks, backgrounds, formats, plans, credit packs, and pricing. It does not explicitly differentiate itself from sibling list/get tools, but the breadth of catalog content makes its purpose distinguishable.

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

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

It explicitly says to use the tool 'to pick a category or source and to explain prices,' which gives clear usage context. It does not mention when not to use it or name alternatives such as quote or account tools.

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 the description goes meaningfully beyond them: signed image URLs valid 7 days and stable within a day so they are cacheable, plus the exact semantics of each analysis.lyrics.status value including the side effects of 'checked'. It does not describe error behavior for a bad or missing song_id, which keeps it below a 5.

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

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

Information density is high and nothing is obviously padded, but it is a single run-on block whose opening sentence is garbled by a missing period, and the most important fact (what the tool returns) is buried behind image-resolution trivia. Front-loading and sentence boundaries would substantially 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 does real work explaining return fields (cover_art.url with dimensions, preview_url, thumbnail_url, analysis.lyrics.status) and the status enum meanings, which an agent could not otherwise know. The remaining gap is that it never clarifies the boundary against get_song_analysis, so an agent cannot tell which tool yields which analysis 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?

Only one parameter exists and the schema already documents it at 100% coverage ('The song id'), so the schema carries the burden. The description adds no format, sourcing, or example detail for song_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?

The description opens with the fragment 'One song and its analysis status', which conveys the resource but not a verb, and the missing punctuation makes the purpose statement read as if it runs into the field documentation. It never distinguishes this from siblings such as get_song_analysis or list_songs, even though it discusses analysis data that plausibly overlaps with get_song_analysis.

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 statement of when to call get_song rather than get_song_analysis, list_songs, or show_songs, and no prerequisites or exclusions are given. The agent must infer usage entirely from the name and the field documentation.

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 read-only/idempotent/no-destruction, so the bar is lower, and the description still adds genuine behavioral context: lyrics.text may be the user's own lyrics or a transcription with lyrics.yours saying which, and a song analyzed before voices were heard has no map.voices until its first music video plan listens to it. That disclosure of conditionally-missing fields is valuable; it stops short of stating what happens for an unanalyzed or missing song.

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?

Every clause carries real information and the length is defensible for a complex analysis object with no output schema, but the text is one dense run-on block that opens mid-thought with a confusing phrase instead of front-loading what the tool returns. The content earns its place; the structure does not.

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, and it does: lyrics, tempo/beats/sections, part kinds (clip, pair) with parent relationships, default_part, and voice/instrumental maps. It omits error or not-yet-analyzed behavior and the untimed fields (tempo, beats) are only named, but overall it is sufficient to use the tool 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 schema already documents both parameters, including min_seconds' default of 8 and the 15-second music-video case. The description largely restates that same meaning in prose and adds nothing new for song_id, so baseline 3 is appropriate.

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

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

The description enumerates the concrete contents of the resource (word-timed lyrics, tempo, beats, sections, hooks, video-cuttable parts), which makes clear it returns an analysis object rather than the song itself. However, the opening clause is garbled ("the parts a video can be cut to parts lists where a video can start and end...") and it never names or contrasts with the obvious siblings get_song and reanalyze_song, so an agent must infer the boundary.

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

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

There is real downstream guidance: pass a part's start/end as a video's trim (start_seconds, end_seconds) and choose a part at least as long as the video type's minimum (8s lyric video, 15s music video), which also explains min_seconds. But there is no explicit when-to-use-this-vs-alternatives statement and no mention of preconditions such as needing the song analyzed first, so usage is implied rather than stated.

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

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

With annotations covering read-only/idempotent, the description goes well beyond them: signed download/web/poster URLs valid 7 days, queue reason semantics for plan_limit vs render_capacity, poster frame semantics per video type, poster_seconds offset behavior and its null back-compat case, and the meaning of AI_VIDEO_UNAVAILABLE with a retry recommendation. That is exactly the behavioral context an agent cannot get from 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?

Dense but not padded – nearly every clause carries real semantics about returned fields. However it is one run-on blob with a broken opening sentence, and the most important information (what the tool does) is not front-loaded, so structure works against 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?

There is no output schema, so the description must carry return-value meaning, and it does thoroughly for statuses, URLs, posters, and errors. It still omits the general shape of the response (identity/other fields) and error behavior for an unknown id, so it is strong but not exhaustive.

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 video_id parameter is documented in the schema, but the description adds nothing about format, where the id comes from, or invalid-id behavior. Baseline 3 for a fully-covered single-param schema 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 enumerates what comes back (status, progress, credits, download links) which implies retrieval of a video record, but it never states the action plainly and never distinguishes itself from siblings like show_video, wait_for_video, or list_videos. The opening sentence is also garbled ('...the download links status is queued...'), so the purpose must be inferred from the title and name rather than read.

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 describes the queue/polling state but gives no explicit instruction on when to call get_video versus wait_for_video or show_video, and no exclusion or prerequisite. The only actionable hint is buried ('While it waits') and is about interpreting a queue reason, not about choosing the 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?

Beyond the annotations, the description discloses meaningful behavior: owner_artist_id falls back to the workspace's only artist (else its first) and cast is shared only when shared=true, ai_made=false routes through a face check, and 'The uploads are deleted' is a real side-effect warning. The replacement of an existing character ('replace true takes the place of theirs') and the upload deletion sit in mild tension with destructiveHint=false, but the primary operation is additive and no user artist or video is destroyed, so this is not a direct contradiction.

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 with no filler sentences, and the core action is front-loaded, but the branching is packed into a single run-on with nested parentheses and semicolons that is difficult to scan. The information earns its place; the layout does not.

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 mutation with no output schema, the description covers mode selection, defaults, sharing scope, the face-check gate, and the upload-deletion side effect. It does not say what state request_id must be in (a pending charreq) or what the agent gets back, but return values are less critical here and the operational picture is essentially 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 already 100%, so the baseline is 3, but the description adds semantics the schema does not: artist_id vs name/handle are mutually exclusive modes, owner_artist_id only applies to cast, shared and ai_made default behavior, and the fact that ai_made must be solicited from the user rather than inferred. That is genuine meaning added on top of the field-level descriptions.

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

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

The verb and resource are stated concretely ('Keeps the sheet in the kit') and the description distinguishes two creation modes, one tied to artist_id and one tied to name/handle as cast. It does not name any sibling (e.g. discard_character_request, start_character, draw_character_sheet) to tell an agent when this tool is the wrong choice, and the telegraphic phrasing makes the purpose harder to extract than it should be.

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 real branch-level guidance: use artist_id to keep as that artist, or name/handle to add cast in owner_artist_id's kit, plus an explicit instruction to ask the user about ai_made and never guess. It gives no routing against alternatives such as discard_character_request or start_character, so the when-not-to-use side is left to inference.

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

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

Annotations already 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?

Beyond the readOnlyHint/idempotentHint annotations, the description discloses non-obvious behavior: image_fallback is a derived, volatile value that tracks the newest surviving song, changes when a song is added or archived, and is never persisted as the artist's picture. It also documents null-producing cases for both image_url and image_fallback, which is exactly the kind of state semantics an agent cannot infer from 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?

The description is front-loaded with the resource and its return shape before moving to paging and then the image fallback rules, so an agent can stop reading early and still act. The final sentence is long and parenthetical-heavy ('song_id, preview_url 640 px and thumbnail_url 160 px WebP'), and 'to show in its place, or null without a song' is compressed to the point of ambiguity.

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 it covers the artist fields, the picture fields, sort order, and page size. The notable omission is that it never mentions the artist identifier, which an agent needs to chain into get_artist, rename_artist, or set_artist_image after listing.

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, and offset are already fully documented with bounds and defaults. The description only restates the intent ('search by name', 'page') and repeats the 50-per-page default, adding no syntax, matching behavior, or ordering interaction beyond the schema — baseline 3 is correct.

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

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

The opening sentence names the resource (artists) and enumerates the payload (name, song counts, picture), which is enough for an agent to recognize this as the collection-level listing tool next to get_artist and list_songs. It never explicitly contrasts itself with get_artist, so the sibling differentiation is implied by the plural framing 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?

It gives concrete invocation guidance: 'pass q to search by name, and limit/offset to page', plus the operative precondition 'Songs belong to an artist; create the artist first', which tells the agent this tool cannot be used to bootstrap an artist. What it lacks is explicit when-not guidance (e.g., use get_artist when you already have an id), so the routing is clear but not exhaustive.

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 read-only, idempotent, non-destructive profile, so the description's job is domain behavior — and it delivers the important lifecycle facts: a paid sheet waits 30 days then is deleted, and in-progress sheets expose status 'drawing'. It stops short of describing the full set of possible statuses or the shape of each entry.

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 carry useful density, but the first is grammatically broken ('but not kept yet Newest first'), fusing the scope clause and the ordering clause. The lifecycle explanation lands well, yet the reader has to re-parse the opening to extract the filter conditions.

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 parameters and no output schema, the description must convey what comes back: it does so by naming the two inclusion states, the 'drawing' status field, and sort order. The deletion-after-30-days rule is exactly the kind of consequence an agent needs before recommending keep_character. Only the exact response fields remain unspecified.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. No parameter text 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?

The description identifies the resource (character sheets) and the specific subset returned: those being drawn or drawn-and-paid-for-but-not-kept, with newest-first ordering. It implicitly contrasts with sibling list_characters (kept sheets) without naming it explicitly, so the differentiation is inferable 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?

It names keep_character as the action that resolves a waiting sheet and explains the 30-day expiry, which implies when to call this tool (to find sheets needing a keep/discard decision). It never states when NOT to use it or points to list_characters / get_character_request as 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 cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the description is free to add domain behavior — and it does: each character is a single kit sheet with five specific views in a base outfit, created via start_character, scoped to one artist's kit, and optionally shared to every other artist's videos via update_kit_piece. That is real context an agent cannot get from 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 text is a run-on block with a missing sentence break ('your cast Each character') and no front-loading of what the tool returns; it reads as internal design notes rather than a scannable definition. It is information-dense, but the density is buried in parenthetical asides about sheets, outfits, and missing views.

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 discloses the returned fields (owner_artist_id, owner_name, shared, outfit, missing) and what 'missing' means, which is exactly the gap a 3-param list tool with no output schema would otherwise have. Only the return ordering/grouping semantics ('theirs first, then shared') live in the schema rather than the description.

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

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

Schema coverage is 100%, so a 3 is the floor, but the description genuinely adds relational meaning: setting artist_id yields that artist's single character, whereas the unfiltered case returns cast members addressed by handle, and it explains owner_artist_id/owner_name ownership semantics and the shared flag. The wording is terse enough that the mapping to for_artist_id is only implicit.

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

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

The opening fragment 'The people videos can show: your artists' characters and your cast' identifies the resource domain (characters/cast) but never states the verb or that it returns a list — the agent has to infer 'list' from the name. It also does not distinguish this from siblings such as list_kit, get_kit_piece, or list_artists, which plausibly return overlapping data.

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 explicit when-to-use or when-not guidance and no routing to alternatives (list_kit, get_kit_piece, list_artists). The closest thing is an implicit context ('the people videos can show'), plus a parenthetical pointing at start_character and update_kit_piece, but those are creation/sharing tools, not alternatives for retrieving characters.

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 read-only, idempotent, closed-world and non-destructive, so the safety profile is covered. The description adds genuinely new behavior: next_cursor is null on the last page and must be passed back as cursor with the same filters, plus what each returned idea carries (votes, voted, following, author by name only) and that counts aggregates area and q by status. It stops short of describing ordering stability or error 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?

Nearly every clause carries information, but the pagination contract is buried mid-sentence inside the opening line and the prose reads as one long run-on. Splitting the page/cursor rule into its own sentence would front-load the most operative detail without adding length.

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 seven-parameter, zero-required listing tool with no output schema, the definition covers ordering, filtering, pagination, and the shape of the returned rows and counts. The main remaining hole is the area filter, which is undocumented in both the schema and the description.

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

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

At 57% schema coverage, the description compensates well: it supplies the default limit of 30 that the schema omits, defines the cursor round-trip contract, and interprets the status enum values (open expands to under_review, planned, in_progress). It adds little for area, whose enum has no description in either place, and leaves sort entirely 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 names the resource (Community board ideas), the ordering (most voted first), the scope (Everyone's ideas for Kinetune) and the paging model, which is enough to separate it from get_idea and suggest_idea. The opening clause is awkwardly spliced ('with your vote and follow Everyone's ideas...'), which costs it a point on 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?

It gives a concrete workflow rule: before suggesting an idea, search with q and vote for an existing one instead of duplicating. It also explains the filtering intent of status and yours. It never explicitly contrasts itself with get_idea or suggest_idea by name, so routing is implied rather than spelled out.

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

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

Annotations already declare this a read-only, idempotent, closed-world operation, so the bar is lower, but the description adds real payload context: the default returns every piece with no paging, url is a crop up to 1536 px, thumbnail_url is a 320 px copy, source_url is the uncropped original, and total is the match count. It also explains the shared-visibility model (shared true exposes a piece to every other artist's songs). What it omits is any indication of result ordering when no artist filter is supplied or of payload size risk when paging is skipped.

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?

Most sentences carry useful domain information, but the opening is a fragment that runs straight into the next sentence without punctuation ('...can mention The kit is what...'), and the first half is domain exposition rather than an action statement. A reader must reach the second half before learning the filtering and paging behaviour, so it is not well 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 no output schema and six optional parameters, the description carries the return-value burden and does it well, naming name, @handle, shared, owner_name, url, thumbnail_url, source_url, width/height and total. It is missing only fields the agent might also receive (identifiers, kind) and the default sort order when listing everything.

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 all six parameters, establishing a baseline of 3. The description does add genuine meaning on top — q searches name, @handle or description; artist_id results are ordered 'their own pieces first, then those other artists shared'; limit defaults to everything — but these are refinements of already-documented fields rather than filling a documentation gap.

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

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

The description defines the resource precisely — outfits, places and props making up an artist's kit — and the closing line 'Every piece by default' plus the filter behaviour makes clear this returns a collection rather than a single piece. It never states an explicit verb like 'list' (that lives only in the title) and never names the neighbouring get_kit_piece/list_looks, but the resource boundary 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?

It gives explicit routing between the two artist parameters: artist_id for 'what a brief for their song can mention' (own plus shared), owner_artist_id for 'only their own (their kit page)', and neither for everything. That is strong when-to-use guidance for the filter combinations, though it never points to sibling tools such as get_kit_piece for a single piece or add_kit_piece for mutations.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), and the description adds real behavioral context beyond them: Looks featuring an artist are private and only serve that artist's songs, and artist_id filters those out. It also explains the downstream consumption pattern of the returned id ({mode:'existing', id:…}), which is useful non-obvious behavior. Pagination/return shape 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?

Purpose is front-loaded, which is good, but the text is a run-on: the first sentence is missing a period before 'A Look', and the final clause ('choosing for a song, pass its artist_id...') is grammatically tangled enough to require a reread. Content earns its place, but the structure works against fast parsing.

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 still tells the agent what it gets back (Looks with ids) and how to reuse one, and it covers the non-obvious privacy rule that governs which Looks are even eligible. For an 8-param read-only browse tool with full annotation coverage, nothing essential 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 63%, and the description reinforces the two most consequential semantics: the scope taxonomy (official/community/mine) and artist_id exclusion behavior. The other parameters (q, sort, limit, offset, category, lyric_style) get nothing beyond the schema, and several are undocumented in both places, so the description only partially compensates.

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 ('Browse Official, Community and your own Looks') and defines what a Look is ('a complete, reusable lyric-video design'), which an agent cannot infer from the name alone. It does not explicitly distinguish itself from the close siblings get_look and show_looks, so the differentiation is 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?

Gives one concrete conditional: when choosing a Look for a song, pass that song's artist_id to exclude Looks showing another artist. However, it never says when to use list_looks versus get_look or show_looks, nor when to prefer scope=official/community/mine, leaving the primary routing decision to inference.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds genuinely useful behavior the annotations cannot convey: the 30-day recency window, the newest-first ordering, and the exclusion logic that only unused drafts are returned, which tells the agent why some drafts will be absent.

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

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

The content is front-loaded, but the first sentence is a run-on fragment and the second sentence restates the same two conditions at greater length ('shot lists not made yet' versus 'no video was made from'), so meaningful redundancy exists. Trimming to one precise sentence plus the routing hint would lose nothing.

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 single-parameter list tool with no output schema, the description covers what is returned (draft shot lists and lookbooks), the eligibility rules, the time window and the ordering. The remaining gap is the shape of each returned item, which is minor given the routing to get_music_video_plan and get_music_video_lookbook for details.

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 exists and schema coverage is 100%, so the schema already documents song_id ('The song'). The description reinforces that results are scoped to a single song ('A song's music videos'), but adds no format or validity details beyond that; baseline 3 is appropriate 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 description names a specific resource and an unusually precise filter: the latest draft of each shot list with no video made from it, plus lookbooks with no shot list written from them, limited to the last 30 days and sorted newest first. That is enough for an agent to distinguish it from list_music_video_looks or get_music_video_plan, though the opening fragment ('shot lists not made yet and lookbooks not used yet') is awkward and slightly muddies the 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?

It gives a clear downstream action ('Pick one up with get_music_video_plan or get_music_video_lookbook'), which implies this is a triage/selection tool for actionable drafts. However, it never says when NOT to use it versus near siblings such as list_music_video_looks, nor does it state prerequisites for the song_id.

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

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

Annotations already cover the safe-read profile (readOnly, idempotent, non-destructive), and the description goes well beyond them: 7-day signed URLs, a 404 when frames aren't offered, persistence of a frame across drafts while the shot is unchanged, exclusion from the video quote, and the meaning of the unavailable reasons. What's missing is any note on ordering or how frames relate to drawing one.

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 the two things returned (frames and price) and the size is roughly proportionate to the domain. However it is a single run-on block dense with nested parentheticals, so return fields, edge cases and pricing are harder to scan than they need to be.

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

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

For a one-parameter read tool with no output schema, the description covers return fields, signing lifetime, failure mode (404), persistence semantics and the pricing caveat, which is close to everything an agent needs. The remaining gap is how this list interacts with the frame-drawing sibling and the plan resource.

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 and the schema documents it at 100% coverage with a pattern and example, so the schema carries the load. The description supplies no additional information about plan_id beyond referring to "a plan's shots," which is the expected 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?

The description names the resource precisely — the opening frames drawn for a plan's shots, plus the credit price of drawing one more — and defines what an opening frame is (the picture of the moment a shot opens on). The listing verb is only implicit via the title, but the object of the tool is unambiguous enough to separate it from draw_music_video_frame.

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?

"For users who want control over key shots" gives a loose motivation for calling it, and the note that frames are never part of the video's quote hints at why one would inspect before drawing. But there is no explicit when-to-use/when-not wording and no named alternative (e.g. draw_music_video_frame or get_music_video_plan) for the agent to route between.

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, non-destructive and closed-world, so safety is covered. The description adds useful domain context (a Look carries category, style, takes, lipsync, treatment, places/props), but the closing clause 'pass its id as look_id with those choices' references a parameter this tool does not have, which muddies rather than clarifies behavior for a list operation.

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

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

Two sentences with no filler, but the first is a dense fragment stuffing scope options together and the second mixes return-shape description with an off-topic look_id instruction. The core listing purpose and padding/pagination hints are not 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?

For a 5-parameter paged list tool with no output schema, knowing what a Look contains is genuinely helpful. However, the description omits sorting/pagination semantics and the meaning of limit/offset, and its look_id remark points at a different tool, so an agent still lacks everything needed to page and order results correctly.

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

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

Schema coverage is only 20% (just q is documented), so the description must carry more weight and it only partially does. It does explain the scope enum meanings and its default of 'all', which the bare enum does not, but sort, limit, and offset receive no explanation at all, leaving three of five parameters semantically bare.

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 (music video Looks) and the scoping concept, but it never states the operation as a verb — the reader must infer "list" from the name/title, and the opening clause is a noun fragment. It also does not distinguish this from near-identical siblings such as list_looks, show_looks, or get_music_video_look, so an agent cannot confidently tell them apart from the text alone.

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

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

Usage is only implied: the enumeration of scope values ('all (default), community (public ones) or mine') gives the agent a hint about which visibility slice it wants. There is no explicit statement of when to choose this tool over list_looks or show_looks, and no note about paging through large result sets.

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 hints, it discloses authorization behavior (API-key calls are scoped to the creating member and need organizations:read), that 'current' identifies the acting organization, and that image_fallback is read-only, never persisted, and shifts as the newest song changes. It also warns that each organization has its own plan, music, videos, Looks and credits, which is the key behavioral constraint an agent must know before acting.

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 the core meaning, but the body is one long run-on paragraph with heavily nested clauses (the type enumeration and the image_fallback chain especially). The content largely earns its place given no output schema exists, yet it would read far better as separated statements about scope, auth, and returned fields.

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 carries the full burden of explaining the response and does so thoroughly: the entity type taxonomy, the current-organization marker, image fields and their fallback lifecycle, and per-organization isolation. An agent could act on the result correctly without further documentation.

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

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

The tool takes zero parameters, so the baseline is 4 and there is no input semantics to explain. The description instead spends its words on result-field meaning (type values, current, image_url, image_fallback), which is useful but belongs to output documentation rather than parameter semantics.

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

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

The opening clause states precisely what is returned: every organization the signed-in person belongs to, their role in each, and which one the credentials act for. Scope is narrowed explicitly (with an API key, only the member who created it), so an agent can distinguish this read listing from create_organization/update_organization without opening a schema.

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

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

It gives the practical context for calling it – determining which organization the current credentials act for – and closes with the alternative path when work must happen elsewhere: sign in again and pick the organization on the consent screen, or use an API key created in it. It also states the required scope (organizations:read) for key-based calls. What's missing is an explicit routing statement against siblings (e.g. versus get_account), but the framing 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 declare this a safe, idempotent read, so the description rightly spends its budget elsewhere: default page size of 50, signed image URLs valid 7 days and stable within a day (so they can be cached), and the three cover resolutions with their formats. The prerequisite that analysis.status must be 'ready' before video creation adds real downstream context. Missing only return-shape and pagination-total behavior.

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

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

The content density is good and the most useful facts (what a song carries, the analysis prerequisite, paging, image lifetimes) come early. But the opening is a malformed fragment — 'Songs with their cover, duration and analysis status A song must be analyzed...' — with a missing sentence break, which hurts front-loading and readability.

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 describes the returned item fields and the image URL semantics, and it covers all six parameters via the schema. The remaining gap is pagination behavior for limit/offset — no mention of how to detect more results — which matters for a paged list tool.

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

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

Schema coverage is 100% and every parameter carries a clear description including defaults, enums, and ranges, so the schema already does the heavy lifting. The description restates the 50-per-page default and the q/limit/offset roles without adding format or edge-case detail beyond the schema, which is the expected baseline-3 outcome.

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 (songs) and enumerates what each item carries — cover, duration, analysis status — which is more informative than the bare title 'List songs'. However, it never contrasts itself with the close siblings show_songs and get_song, so an agent must infer when this list variant is the right pick.

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 mention of 'pass q to search, and limit/offset to page' signals a browsable, pageable catalogue, and the note that a song must be 'ready' before videos hints at a pre-production workflow. No alternative tool is named and no when-not-to-use condition is given, so the agent gets context but no routing help.

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 read-only, idempotent, closed-world and non-destructive, so safety is covered. The description adds genuine value beyond that: next_cursor is null on the last page, the counts object is broken down by type, outputs carry aspect_ratio/poster_url/poster_seconds/web_url, and queued videos expose a queue reason (plan_limit or render_capacity) with position or ETA. It does not enumerate status values or say how empty results look.

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 dense and front-loads paging, which is good, but the prose is fragmentary and run-on — the first sentence lacks punctuation between "thumbnails" and "A page at a time", and several clauses drop their verbs. Density is achieved at the cost of parseability.

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 has to describe return shape and it largely does: status, thumbnails, counts, per-video outputs, and the queue sub-object for pending videos. Only the set of possible status values and the empty-result behavior are unaddressed.

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

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

With 71% schema coverage, the description fills real gaps: it supplies the limit default of 50 and its paging role, and explains that counts aggregate across song_id, artist_id, quote_id and q. However, it names the type values as "lyric_video, canvas, music_video" while the schema enum uses hyphens ("lyric-video", "music-video"), an inconsistency that could cause malformed calls.

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?

"Videos, newest first, with status and thumbnails, a page at a time" identifies the resource, the sort order and the pagination model. It also distinguishes itself from get_video for download links. The opening is a verbless fragment, so the reader must infer "list" from the tool name rather than the text.

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 routes one concrete need to a sibling ("get_video has the download links") and explains exactly how to continue paging with the same filters. It does not state when to prefer this over wait_for_video, show_video or the list_music_video_* siblings, so the higher-level selection guidance is incomplete.

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 tell the agent it is non-read-only, open-world and non-idempotent; the description adds materially more: it is free with an hourly cap, takes about a minute, and yields a plan object rather than a rendered video. It does not spell out what happens on failure or whether plans expire, but the cost, latency and side-effect profile are all disclosed beyond the annotations.

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

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

The workflow-critical sentence about revise/quote/create is front-loaded after the artifact definition, and nothing is padding. It is dense with stacked parentheticals and long clauses, which slows parsing slightly, but every sentence 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 17-parameter, nested, open-world planning tool with no output schema, the description covers what matters: what is produced, that it is free and slow, and how it connects to quote and create. Residual gaps around error handling and plan lifetime are minor given the rich schema and the named follow-up tools.

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 94%, so nearly every one of the 17 parameters is already documented in the schema, and the enum values, patterns and defaults carry most of the meaning. The description contributes the revise payload's role in the loop and the plan_id hand-off, but adds little about cast, trim, scenes or direction beyond what the schema already says; baseline 3 is appropriate.

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

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

The description names a specific artifact ('the director's shot list for a music video, the idea and every shot') and explicitly positions it as the step before anything is charged, which separates it cleanly from quote_music_video, create_music_video and design_music_video_shoot. It even describes the shape of what comes back (concept, kept character, shots up to ~14 seconds with lyrics and joins), so an agent knows exactly which artifact this tool produces.

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 a concrete workflow: show the plan to the user, rewrite it with revise until they like it, then call quote_music_video and create_music_video with its plan_id. When-not guidance is implicit but strong (it is the pre-charge step), and the alternative path (revise) is named with its trigger condition.

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 destructiveHint=false; the description adds value beyond them by explaining the billing lifecycle (credits reserved at creation, charged only on delivery) and by naming the returned fields in the absence of an output schema. It does not mention quote expiry or how long a quote_id remains valid before 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?

Two sentences, no filler, with the pricing guarantee and return fields front-loaded before the workflow instruction. The longer second sentence carries the create/charge semantics and earns its length.

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 14-parameter tool whose schema is fully documented and which has no output schema, the description supplies exactly what is missing: the returned fields and the cost/reservation model. Nothing an agent needs to call it correctly is absent.

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

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

Schema description coverage is 100%, so all 14 parameters including enums, defaults and ranges are already documented in the schema. The description adds no parameter-level guidance (e.g. how quality or variations affect the quoted credits), so this is 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 the specific verb and resource ('The exact credits for a Spotify Canvas') plus the precise output ('quote_id, credits and a breakdown'), which immediately separates it from create_canvas and the other quote_* siblings.

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

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

'Always quote first and tell the user the credits before creating' gives an explicit sequencing rule that selects this tool over the create path. It does not name create_canvas or state any case where quoting should be skipped, so it stops short of full alternative coverage.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, yet the description still adds real context: the returned fields (quote_id, credits, credits_per_video, breakdown), the expiry window, and the crucial charging model (reserved at creation, charged on delivery) that explains why quoting matters. It omits any statement that the quote must be repeated with identical parameters at creation time, which is left to the schema.

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

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

Three short sentences, front-loaded with the purpose and followed by the workflow rule and the expiry — no filler. Minor deduction for the missing sentence break after 'before anything is charged Returns quote_id', which runs two thoughts together and slightly hurts scannability.

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

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

For an 8-parameter tool with deep nested objects and no output schema, the description covers purpose, return shape, cost semantics and quote lifetime, which is most of what an agent needs. The remaining gap is that parameter parity between the quote and the eventual create call is only documented inside individual schema properties, not at the description 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?

The description says nothing about any of the 8 parameters (song_id, look, trim, display, variations, aspect_ratios, metadata, callback_url) — all of that meaning lives in the schema, which has 100% coverage including a very detailed nested look/display description. Baseline 3 is correct when the schema carries the full parameter burden.

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 ('the exact credits for a lyric video') and its temporal scope ('before anything is charged'), which separates it from create_lyric_video and from the sibling quote_music_video/quote_canvas pricing tools. It never names a sibling explicitly, but the pricing-versus-creation distinction 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?

Gives an explicit directive: 'Always quote first and tell the user the credits before creating.' That not only says when to call it but states the prerequisite workflow and the required user-facing step, and the 30-minute validity tells the agent how long the result can be acted on.

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=true, so the safety profile is covered; the description adds genuinely new behavior — the price tracks the trimmed section length (~15-second clips), credits are reserved at creation and charged only on delivery, and quoting itself charges nothing. That billing lifecycle is the key context an agent needs and is not derivable from 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?

Three sentences, front-loaded with purpose, then return values, then the pricing constraint and the mandatory quote-before-create rule. There is a readability defect: a missing period between 'before anything is charged' and 'Returns quote_id', which briefly garbles the second clause.

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

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

For a 24-parameter tool with no output schema, the description still covers the essentials: what is returned, what the quote costs and how price scales, the character prerequisite, and the quote-then-create sequencing. Optional paths (plan_id vs design_shoot, refinish, callback_url) are left to very thorough schema descriptions, which is acceptable.

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 96%, so the schema already documents cast, trim, model, takes, on_screen and the rest in detail. The description adds only two pieces of meaning — trim length drives price and the artist's character is required — which is the expected baseline when the schema does the heavy lifting across 24 parameters.

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

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

The opening states a specific verb and resource — quoting (pricing) an AI music video before charging — and lists the return payload (quote_id, credits, breakdown). It implicitly separates itself from create_music_video via 'before anything is charged', though it never names that sibling 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 an explicit workflow rule: 'Always quote first and tell the user the credits before creating.' It also states a prerequisite (the song's artist needs a character via start_character). It stops short of naming create_music_video or describing any case where quoting should be skipped.

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.