AINSOF

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

The annotations carry the safety profile (destructiveHint=false, openWorldHint=false), and the description usefully clarifies the nature of the return content as informational rather than a search result set. However, readOnlyHint=false and idempotentHint=false are unusual for a pure informational getter and the description never reconciles or explains that mismatch, so a gap remains.

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, and the disambiguating 'not a music search' clause is placed last as a natural guard against misrouting. The first sentence is a long enumeration, but each listed topic is a legitimate coverage claim rather than padding.

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

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

With no parameters and no output schema, the description has to carry the return-content burden, and it does so by listing the categories of information returned plus the explicit non-search disclaimer. Nothing further is needed for an agent to call a zero-argument informational 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?

The tool takes zero parameters, which is the baseline-4 case; there is nothing for the description to disambiguate. The description correctly implies no input is required to retrieve the service information.

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 ('Get information supplied by AINSOF') and enumerates the exact subject matter covered (catalog, composers, technology, licensing, privacy, deletion requests, official profiles). The closing clause 'Returns service information, not a music search' cleanly distinguishes it from the many music-retrieval siblings like search_music and find_soundtrack.

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

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

'Use when the user asks about AINSOF or how its service works' gives a clear triggering condition, and the negative 'not a music search' implicitly routes music queries to the search/listen siblings. It does not name an explicit alternative tool, so it stops short of full when/when-not routing.

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

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

Annotations say destructiveHint=true and share almost nothing else, yet the description discloses the concrete side effect (an expired temporary AINSOF-uploaded source copy may be deleted; the local original is unchanged), the 30-day retention of storyboard images, transcript, user_request and review copy, and the fetch of an external file (openWorldHint). It also reconciles the non-readOnly flag by explicitly denying any edit or scoring of the video.

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 mandatory auth step, which is the right priority, and most sentences carry distinct information about returns, timing and retention. It is dense to the point of being a wall of text, and 'creates or reuses an analysis job, stores analysis results and records operational activity' is implementation boilerplate that could be cut.

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 destructive/openWorld annotations, the description carries the full burden and does: it enumerates the returned fields (film classification, music fit including music.search, duration, frame rate, resolution, audio presence, cut timestamps, pace metrics), the up-to-12 storyboard limits, and transcript truncation caveats. An agent can invoke and interpret this without opening anything else.

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, but the description adds workflow meaning beyond the schema: sign_in_code is a per-conversation credential to pass to every video tool and is the key to clearing sign_in_required, and user_request is the phrasing that gets retained for 30 days. It does not add syntax or constraints for music_intent/project_type.

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 ('Analyze a downloadable video'), bounds it ('up to 15 minutes'), and carves out scope explicitly ('for soundtrack planning without editing or scoring it'), which separates it from scoring/edit siblings. It also names the artifact it produces ('film').

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 operational guidance: sign in once, expect sign_in_required without a code, re-call with the same arguments plus sign_in_code, and re-call on still_running. It implies the alternative (scoring/editing tools) via the exclusion but never names a sibling tool such as score_my_video or cue_sheet.

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

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

The description frames a pure retrieval ("Get the CUE SHEET", "Hand this over"), yet the annotations declare readOnlyHint=false and idempotentHint=false, i.e. a state-changing, non-repeatable operation. That directly contradicts the read-only nature the description asserts. The provenance sentence ("AINSOF controls master and publishing, so these are stated facts, not estimates") is genuinely useful context, but the annotation mismatch is a hard rule violation.

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

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

Three sentences, front-loaded with the payload contents, then the usage trigger, then the provenance caveat. Every sentence earns its place and nothing is repeated from the schema or annotations.

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

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

With no output schema, the description usefully enumerates the returned fields and their authority, which is exactly what the agent needs to decide whether this tool answers the user's question. It omits failure behaviour (e.g. unknown track) and any note about the identifier form, keeping it just short of 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 only one parameter and the schema describes it fully ("a track_id, or the track's title"), so the baseline is 3. The description adds nothing about the accepted identifier forms, so it neither compensates nor detracts.

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

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

The description gives a specific verb and resource ("Get the CUE SHEET for a track") and then enumerates exactly what the sheet contains — album, catalog number, ISRC, tempo, key, publisher, writers with IPI/society/share. That is far more specific than the neighbouring get_track/search_music, so an agent can distinguish it 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?

"Hand this over when the user needs delivery paperwork, rights information, or asks who wrote it" is an explicit when-to-use trigger tied to user intent. It stops short of naming a when-not condition or an alternative sibling, so it is clear context rather than full routing guidance.

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

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

The description carries real behavioral context beyond the annotations: the sign-in_required flow, the fact that a signed-in account with download access is needed to fetch the zip, and the guarantee that it never re-cuts anything (so the render is reused deterministically). It adds no rate-limit or failure-mode detail, and its read-only-sounding delivery behavior sits somewhat awkwardly beside readOnlyHint=false, but nothing is affirmatively contradicted.

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 sign-in instructions are stated twice ('signs in once on ainsof.io (Google or email)' and the closing 'sign in on ainsof.io with Google or email'), which is pure redundancy. The most important fact - the return payload - is placed after the auth preamble rather than front-loaded, hurting 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?

With no output schema, the description fully specifies the return value (zip with scored video, per-section MP3s at 192k named by timecode, plus a cue sheet) and the workflow around it. For a delivery tool with auth gating, nothing an agent needs to invoke 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 only 50%, so the description must compensate, and it does: it explains that video_url/brief/version/music_offset_db must mirror the score_my_video call (that is how the right render is found) and describes the sign_in_code round-trip semantics. It still leaves some params (sections, silences, track_id) unexplored in prose.

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 concrete verb+resource (hands over the finished score as files) and enumerates exactly what the delivered zip contains, which distinguishes it from siblings like cue_sheet and score_my_video. However the purpose is buried behind two sentences of sign-in preamble, so the agent must read a while before learning what the tool actually does.

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 explicitly when to call (once the user is happy with the score), how to call (with THE SAME arguments passed to score_my_video), and the exact auth loop (call, get sign_in_required plus a link, retry with the same arguments plus sign_in_code). The alternative/precondition is spelled out rather than inferred.

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

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

Although annotations already flag this as destructive, open-world, and non-idempotent, the description adds meaningful behavioral context beyond them: a mandatory user-consent gate, the fact that un-consented reactions stay in the conversation, and the prohibition on inventing complaints or sending feedback the user never gave. This is substantial disclosure that the structured fields cannot carry.

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

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

The consent requirement is front-loaded and the prose is largely action-oriented, but there is mild redundancy ('ASK THEM FIRST, every time' reinforced later by 'send only if they say yes'), and one sentence could be trimmed without loss.

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 consent-gated fire-and-forget feedback tool with no output schema, the description covers the full calling contract: preconditions, the consent field value, exact quoting, and the no-fabrication rule. Nothing an agent needs 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 baseline is 3, but the description adds real semantic guidance beyond the schema: set consented only after asking, quote the user EXACTLY in in_their_words, and pass the concerning tool plus track_id or brief. It clarifies intent for several parameters rather than restating their definitions.

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+resource ('Send AINSOF what the user thought of an answer') with concrete examples of the feedback content, and it is clearly distinguishable from siblings like search_music or score_my_video, which it references. An agent knows exactly what this tool does without opening the schema.

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

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

It gives explicit when-to-use and when-NOT-to-use guidance: ask the user first every time, send only if they consent, and if they decline or don't answer, do not call the tool at all. The consent protocol sets consented to true is spelled out, leaving nothing to inference.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), and the description does not contradict them. It adds one useful piece of return context — "Each result names the matching passage inside it" — which matters since there is no output schema. However it says nothing about result count, top_k behavior, or why a lookup is flagged non-read-only, leaving the behavioral picture thin.

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

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

Three sentences, front-loaded with the core purpose and ending with the routing exclusion where an agent needs it. The "cues that sound like an AINSOF cue" construction is slightly circular and the 5–60 s range duplicates the schema, 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 read-style similarity search with no output schema, the description covers input framing (whole cue vs passage), the identifier source (track_id or title), a concrete example, and the shape of results. The only gap is result-volume behavior (top_k default 8, max 25), which is a minor omission.

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 75% and the schema already explains from/to seconds, the whole-cue default when from is omitted, and that track_id accepts a title. The description largely restates the 5–60 s passage constraint and the track_id-or-title option rather than adding new semantics, and top_k is never mentioned in either place.

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 and resource ("Find AINSOF cues that sound like an AINSOF cue") and immediately scopes it to whole-cue or sub-passage queries. It explicitly distinguishes itself from search_by_reference, so an agent can route without opening either schema.

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

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

Gives explicit when-to-use (whole cue, or a passage marked with from/to, e.g. the hook or the bar before the drop) and a when-not-to-use with the named alternative ("For a song by another artist ... use search_by_reference instead"). Both the positive and negative routing conditions are stated.

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

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

Beyond the annotations it discloses result count (eight cues), selection preference (playable versions fitting duration), what happens on a near miss ('for_your_video explains the required edit'), payload contents (composer, publisher, preview), and that calls are self-contained so refinements must restate requirements. It also defines failure semantics ('an unavailable search is a technical failure, not an empty catalog'), though it omits rate limits or auth expectations.

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 routing condition, which is good, but the description repeats itself: the when-to-use condition appears twice ('when the user wants music for a specific video and its length is known' and 'when someone asks for music or a soundtrack for a video and its exact duration is available'), and 'Find music for a video' duplicates the title. Several sentences could be merged without losing content.

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 takes on the return-value burden and does it well (cue count, metadata per result, preview, edit explanation on length mismatch), and it covers refinements and failure cases. Minor gaps remain around the optional scope/product/cuts_per_min parameters and what an 'evaluated match' versus an 'alternative' looks like.

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 83%, so the schema already carries the baseline, but the description adds real meaning the schema does not: pass the user's request in their original language, preserve exclusions and durations, and do not invent instruments, genres, moods, energy, or vocal restrictions. It also excludes chat transcripts and assistant replies from the description field, which is guidance the schema's 'Describe the video...' text does not convey.

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 ('Find music for a video', returns cues from the AINSOF catalog) and explicitly distinguishes itself from the sibling search_music by the known-vs-unknown duration condition. An agent can route between find_soundtrack and search_music without opening either schema.

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

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

It names the alternative (search_music) and the exact condition that selects it (length unknown), then adds a full refinement protocol ('for a refinement, describe the current musical requirements including the latest change'), rules for what NOT to include, and an explicit retry policy for unavailable searches. When-to-use, when-not-to-use, and alternatives are all present.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false and idempotentHint=false but say nothing operational. The description fills that gap: results expire after 7 days, returns a listen link plus MP3 192k mix and stems zip, processing status must reach 'ready' before claiming success, and retry arguments should be reused. This is substantially more than the annotations provide.

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

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

The core purpose is front-loaded in the first sentence, but the body is a long policy wall with loops of instruction, some of which duplicates the enum descriptions already in the schema. Much of it earns its place as workflow guidance, yet it is denser and longer than needed for selection and invocation.

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 return contract itself and does so fully: listen link, downloadable zip, audio format, retention window, and async status handling. An agent has everything required to call it and report back 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 already 100%, so the baseline is 3, but the description adds outcome-level meaning the schema lacks: the musical-quantization behavior ('ask for 5 and you may get 6-8 seconds'), the final-hit-before-last-frame behavior for kind='video', hit_at placing the climax on a given second, and the directive to preserve the chosen version (e.g. NO_VOCALS) rather than defaulting to MAIN.

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 ('Cut one catalog cue to the length you need') and immediately scopes it against the nearest misconception: 'It edits the composer's own recording; it does not generate new music.' It is easily distinguished from siblings like search_music or deliver_score.

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 rules: kind='length' for ordinary requests, kind='video' only when a video duration is supplied or exactness is demanded, kind='loop' for loops, and it names the fallback (search first if no cue is chosen). It also states an anti-pattern ('Do not carry a previous test's exact-length setting into a new request') and what to do during async processing.

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

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

Annotations already declare the safety profile (destructiveHint=false, openWorldHint=false), and the description adds valuable return-shape context, which matters because there is no output schema. However, the annotations oddly declare readOnlyHint=false and idempotentHint=false for what reads as a pure fetch, and the description never explains what side effects or state changes a 'get' could cause — a meaningful gap given that inconsistency.

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 compact sentences with the returned-field inventory front-loaded and the argument note second. The long enumeration of fields is dense but each item earns its place by telling the agent what the call yields in the absence of an output schema.

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

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

For a one-parameter retrieval tool with no output schema, listing returned fields plus the title-as-identifier option covers the essentials. It still leaves unexplained why the operation is flagged non-read-only/non-idempotent, and says nothing about result size or behavior for ambiguous titles.

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 already carries an example ('AIN-CAT 031_002' or 'Shine On Today'), so the baseline is 3. The description restates that a title is acceptable as the identifier and adds the 'call it by name' tip, which is mildly useful but largely duplicates what the schema example already demonstrates.

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

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

The description gives a specific verb (retrieves one cue in full) and enumerates the returned facets — album, catalog number, composer IPI, publisher, tempo, key, versions/stems — which is far more informative than the bare name. It implies distinction from bulk siblings like search_music or cue_sheet by emphasizing 'one cue in full', but it never names those siblings to make the boundary explicit.

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

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

'call it by name when the user names a cue' is genuine invocation guidance, but it only covers argument form, not when to choose this tool over search_music, find_soundtrack, or cue_sheet. No exclusions or prerequisite context are given, so usage is only implied.

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

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

Annotations only declare the safety profile (not read-only, not idempotent, not destructive, closed-world); the description adds the operational detail that matters: it returns upload_page plus video_url, the page requires Google/email sign-in, agents may PUT to upload_url only when present, and the agent must wait for user confirmation before scoring. This is substantial context beyond structured fields.

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

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

Front-loads the trigger condition and keeps every sentence tied to a real failure mode (don't paste terminal commands, don't send YouTube links, wait for completion). It is longer and more conversational than necessary, with some redundancy between the upload-link and skip instructions, but little is truly wasted.

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

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

No output schema exists, and the description compensates by naming the returned artifacts (upload_page, video_url, upload_url) and the auth prerequisite. For a one-parameter link-generation tool, an agent has everything needed to call it and to handle the follow-up step 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?

Only one parameter and schema description coverage is 100% ('their file's name, for the link'), so the schema already carries the semantics. The description adds no format or constraint detail about filename, 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 action (create an upload link for a video the user has locally) and the exact trigger condition ('video is ON THEIR COMPUTER rather than at a link'). It explicitly separates itself from sibling score_my_video and from the cases where score_my_video should be called directly, so an agent can route without opening either schema.

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

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

Gives explicit when-to-use (local file, no direct URL), when-not-to-use (direct video-file URL, Dropbox/Google Drive share links, YouTube/Vimeo/Dailymotion/Twitch), and the alternative to call in each case (score_my_video). It even sequences the follow-up call and the condition for the agent-PUT 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 non-read-only, non-idempotent, non-destructive behavior, so the bar is lower; the description still adds real lifecycle context by explaining the link is a temporary storage address that is refreshed on open and expires when the preview is no longer available. That accounts for the fresh-address, non-idempotent semantics better than the hints alone. It does not cover auth requirements or rate limits, but the expiry model is the key behavioral fact an agent needs.

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

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

Two short sentences, front-loaded with the outcome (a link to hear a full preview) before the lifecycle caveat. No filler, though the phrase 'while that preview is available' is slightly vague about what ends availability.

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

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

There is no output schema, and the description usefully compensates by characterizing what the returned link is and how long it stays valid. For a two-parameter, single-purpose tool that is nearly complete; it only lacks the link format or any note on failure when a preview is unavailable.

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 track_id and version both documented including an example ID/title format and the MAIN/CUT_30/CUT_15 values, so the baseline is 3. The description adds no parameter-level detail beyond the schema, but nothing is left undocumented.

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: obtain a link that plays a full track preview, with the track identified by the required track_id. It is distinguishable from get_upload_link (different direction of transfer) but never explicitly contrasts itself with get_track or deliver_score, so sibling 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?

It never says when to reach for this tool versus get_track, get_upload_link, or deliver_score, and gives no prerequisites or conditions. The only guidance is implicit in 'hear a complete track preview' – the agent must infer that this is for auditioning rather than downloading or delivering.

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 (destructiveHint=true, idempotentHint=false), the description discloses a lot of behavior an agent cannot infer: the sign-in/auth flow, private job creation with stored outputs, deletion of the temporary uploaded source copy after verified storage, asynchronous 'still_running' returns, reuse of recent identical work, and terminal failures returning a reason. The deletion of the temporary copy is consistent with destructiveHint=true. The statement that recent identical requests reuse existing work sits in mild tension with idempotentHint=false, but it describes caching rather than true idempotency, so it is not a 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?

Dense but nearly every sentence carries operational information: auth flow, output shape, source restrictions, cleanup, async behavior, error mode. The one structural weakness is front-loading the sign-in precondition ahead of the core purpose statement, which pushes 'Create a music-scored MP4...' into the middle of a long opening 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?

No output schema exists, but the description compensates by describing the return payload (video download/watch links, chosen cues, mix details, duration and shot-count summary). Combined with source restrictions, auth requirements, async semantics, cleanup behavior and failure reporting, an agent has everything needed to call it correctly and interpret results.

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

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

Schema description coverage is 100%, so the schema already documents all 11 parameters and the baseline is 3. The description adds value by framing the three mutually alternative ways to specify music (brief vs. explicit track_id vs. timed sections), how sections/silences map to cues and stems, and an explicit negative constraint ('does not support per-section volume automation'). It does not add syntax or format detail for individual scalars like music_offset_db.

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 a music-scored MP4 from a supported video URL and an English music brief, an explicit catalog track, or timed sections' — and names the three input modes up front. It explicitly distinguishes itself from analyze_video ('Detailed cut timestamps, storyboard frames and transcripts are provided by analyze_video, not this tool') and from deliver_score, so an agent can separate it from siblings without reading 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 explicit when-to-use routing: analyze_video for cut timestamps/frames/transcripts, deliver_score for completed delivery packages. It also states prerequisites (sign-in on ainsof.io, sign_in_code passed to every video tool), the retry protocol after signing in, and unsupported sources (stream-only YouTube, Vimeo, Dailymotion, Twitch). Nothing 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?

Discloses behavior the annotations cannot convey: the first reply is often 'still_running' because the reference is resolved through metadata and compared by preview clip, and re-calling with the same link resumes the running search. It also warns that candidates are unverified sound-alikes and that other artists' records cannot be licensed, which is high-value operational context.

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 when-to-use condition, which is good, but the middle repeats the purpose twice ('Find AINSOF music that SOUNDS LIKE a reference' then 'Use it when the user asks for AINSOF music similar to that reference'), and the SoundCloud/TikTok rationale is longer than the decision it supports.

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

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

For a non-idempotent, open-world search with no output schema, the description covers everything an agent needs: input formats, unsupported sources, optional refinement fields, the asynchronous still_running polling pattern, and the caveat that results are not verified sound-alikes. No material gap remains.

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

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

The schema describes three of four parameters (75% coverage), and the description adds what the schema lacks: accepted link sources (YouTube, Spotify, Apple Music, Deezer) and the guidance to supply musical_description only when supported and to omit it when uncertain. top_k is left entirely to the schema, which is acceptable given its inline description.

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

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

States a specific verb and resource — 'Find AINSOF music that SOUNDS LIKE a reference' — and explicitly scopes out identification, playback and download of the reference recording. It does not name or contrast the close siblings (find_similar, search_music, find_soundtrack), so the agent must infer the distinction from the reference-vs-catalog framing.

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 ('user wants licensable music that sounds like a song they name or link'), when-not ('not to identify, play or download the reference'), and a concrete fallback for unsupported sources (SoundCloud/TikTok → ask for artist and title instead). The conditions that select this tool are fully 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?

Beyond the annotations, the description discloses important operating behavior: calls are self-contained, refinements must combine prior requirements with the latest change, unavailable searches are technical failures rather than empty catalogs, and automatic repetition or broadening is discouraged. These are substantial behavioral details not conveyed by the structured hints.

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 purpose and exclusions, but it is long and repetitive, especially around refinements and preserving the user's original wording. Several sentences could be merged without losing guidance.

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 search tool with no output schema, the description covers brief construction, name lookup, failure handling, refinement behavior, and how to use returned understanding/followups/previews. It is complete enough for an agent to invoke and present 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 100%, so the baseline is 3. The description meaningfully enriches the brief parameter by specifying that the user's original language and musical intent must be preserved, that exclusions and durations should be included, and that exact names, album titles, catalog numbers, and composers are valid inputs.

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: find/search AINSOF music and sound effects from a written brief, including exact track/album/composer lookup. It clearly excludes generation, lyric writing, song identification, and playing commercial releases, though it does not explicitly distinguish itself from sibling search tools such as search_by_reference or find_similar.

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, when-not-to-use exclusions, and examples of acceptable briefs. It also specifies how to handle refinements, retries, and technical failures versus empty results, leaving little to inference.

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