LyricVideoGenerator

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

Annotations already declare this is a non-destructive, closed-world mutation, so the description doesn't need to restate safety. It usefully adds that the export is free, capped at 720p, and rendered client-side rather than server-side. It omits the reservation lifecycle (whether the reservation expires, and that finish_local_export must follow), which is the behavior an agent most 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?

A single front-loaded sentence with no filler, with the constraint ('Widget only') placed before the action. It is efficient, though banking heavily on the reader knowing what a 'Widget' context 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?

This is the first step in a multi-tool flow (begin → upload/finish), has no output schema, and the description never explains the sequence or what the reservation returns to feed the next call. Combined with a mutation annotation, that leaves the agent under-informed about how to use the tool correctly end-to-end.

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

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

One parameter with 100% schema description coverage, and the schema already explains that projectId comes from create_lyric_video. The description adds nothing about the parameter, which is acceptable given full schema coverage but is the baseline rather than added value.

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

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

States a specific verb ('reserve'), resource ('a free 720p export'), and location ('render in the browser'), plus a scope gate ('Widget only'). It does not name the contrasting siblings (export_video, export_hd_video) or the follow-up tool, so the differentiation is implied rather than 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?

'Widget only' gives a genuine applicability condition, which is more than most tools offer. However, it never states what to do after reserving (finish_local_export / upload_local_export) or when an agent should pick export_video or export_hd_video instead.

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

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

Annotations declare a non-read-only, non-destructive mutation, and the description adds the key consequence beyond that: any edits made to the current style are replaced. It does not cover permissions, recoverability, or the result, but the overwrite disclosure is the behavior an agent most 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 action and scope, followed immediately by the destructive side effect. Nothing 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?

There is no output schema and no annotation detail about effects, so the description could say more: what the video looks like afterward, whether the change is undoable, and what precondition produces the three proposals (a sibling tool). It is adequate but leaves real gaps for a mutating 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 50%: projectId is documented in the schema, while option only has numeric bounds there. The description supplies the missing meaning by saying the values 1-3 correspond to the three proposed style options, but it doesn't say where those proposals come from or what happens with an out-of-range value.

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

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

States a specific verb and resource: applies one of three proposed style options to the lyric video. That is clearly distinct from siblings like export_video or edit_lyrics, though it does not name update_style explicitly to draw the contrast.

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 (pick one of the three proposed options) and the replacement warning gives a reason to be careful, but there is no explicit when-to-use vs update_style or 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?

Adds meaningful behavior beyond annotations: latency ('10–40 seconds'), side effect ('Creates a new project each call'), and automatic transcription fallback when lyrics are absent. Annotations already cover mutation/safety profile, so this adds useful operational context without 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?

Four tight sentences, front-loaded with the core action, then latency and side-effect details. Every sentence earns its place with no redundancy.

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 only partially covers returns by mentioning 'three visual styles' without describing response structure or pointing to choose_style as the next step. It otherwise gives enough for correct invocation, including the new-project side effect.

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 adds value by explaining that lyrics are optional and will be transcribed from audio if omitted, and it clarifies the expected audio formats (MP3/WAV), supplementing the nested audio object schema.

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

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

States a specific verb ('Turns') and resource ('a song ... into a word-synced lyric video'), plus the immediate output ('proposes three visual styles'). It clearly distinguishes creation from sibling retrieval/export tools like get_lyric_video or export_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?

Usage is implied by 'a song the user attached', but there is no explicit when-to-use versus alternatives (e.g., get_lyric_video, edit_lyrics) and no exclusions. Parameter-level guidance is present for lyrics, but the overall usage context is left to inference.

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

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

Annotations already declare this is a mutation that is not destructive, so the bar is lower; the description usefully adds that timing is preserved and that only one line's text changes. It does not say what happens on an out-of-range line number or whether the updated line must be re-fetched.

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

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

Two tight sentences, the mutation semantics front-loaded and the usage hint second; nothing is redundant with the name or title.

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

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

For a 3-required-parameter mutation with annotations and no output schema, the definition covers what changes, what is preserved, and how lines are addressed. Missing only edge-case behavior (invalid line, response shape), which are minor here.

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

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

Schema coverage is only 33% (only projectId is documented), so the description must compensate; it does by explaining that 'line' is 1-based and indexed the same way as the output of get_lyric_video, which is real meaning beyond the schema's minimum: 1. 'text' is described only as replacement text, leaving length/format limits to the schema.

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

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

States a specific verb and resource ('Replaces the text of one lyric line'), scopes it to a single line, and distinguishes itself from the read-oriented sibling by pointing at get_lyric_video for line numbering. An agent can identify the operation without opening the schema.

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

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

Gives a concrete use case ('fix misheard or misspelled words') and implicitly routes reading to get_lyric_video. It lacks explicit exclusions (e.g. what to use for re-timing or adding/removing lines), so it stops short of full when/when-not guidance.

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

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

Annotations flag a non-read-only, destructive call, but the description carries the meaningful economics: one credit consumed, free for previously unlocked songs, refunded on render failure. It also discloses the asynchronous contract (returns an exportId, progress and download link surface in the widget), which 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?

Four tight sentences, front-loaded with what is produced, then prerequisites/cost, then return behavior. Every sentence carries information; only the aspect-ratio restatement mildly duplicates the schema.

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

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

No output schema exists, and the description compensates by explaining the exportId return and where progress/download appear. The one gap is that it does not tell the agent to poll with get_export after the render starts, leaving the follow-up step implicit.

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

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

Schema coverage is 100% and the enum descriptions already explain 16:9 for YouTube and 9:16 for TikTok/Reels/Shorts. The description's restatement of landscape/vertical adds only mild clarification and says nothing about projectId beyond implying the video is identified by it.

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

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

States a specific verb and artifact: renders the lyric video at 1080p, watermark-free, in one of two aspect ratios. That is clearly distinguishable in substance from generic siblings like export_video, but the description never names a sibling or explains what makes this the 'HD' variant versus the others.

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

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

It gives a real precondition (a LyricVideoGenerator account with credits, or a previously unlocked song) which tells the agent when the call will succeed. But with export_video and begin_local_export/finish_local_export in the sibling list, there is no explicit statement of when to prefer this tool over those.

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

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

Goes well beyond the readOnlyHint/destructiveHint/false annotations: explains rendering happens client-side (~song length), that the tool only shows the widget and starts the export, that the user downloads the MP4 afterward, and what happens when rendering is unsupported. This is exactly the behavioral context annotations cannot convey and also explains why readOnlyHint=true is consistent (no server-side write).

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

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

Three compact sentences, front-loaded with the output spec, then the rendering location, then the fallback. Slightly verbose on the widget/download flow but every sentence carries information.

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

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

With no output schema, the description correctly carries the return-path burden by telling the agent the MP4 is downloaded from the widget rather than returned. Combined with the fallback behavior, nothing an agent needs to call and explain the tool 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?

Only one parameter and schema description coverage is 100%, with the schema already stating projectId comes from create_lyric_video. The description adds no additional meaning about the parameter, 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 plus the exact output spec (720p, 16:9 MP4, watermark, 2.5s end card), and the leading word 'Free' implicitly distinguishes it from the HD export sibling. An agent can tell what it produces 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?

Gives clear context for use (free export path, renders in the widget on the user's machine) and a fallback condition (if the ChatGPT app can't render video, the widget offers browser opening). It does not explicitly name export_hd_video as the paid alternative, so the when-not 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 this is a non-read-only, non-destructive, closed-world operation. The description adds that the tool can complete or fail an export depending on the error input, but it does not explain side effects, idempotency, or what completion entails.

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 text. The Widget-only constraint and the complete-or-fail behavior are both stated immediately.

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 three-parameter mutation tool with no output schema, the description covers the basic workflow stage and the error-failure path. It does not describe return behavior, result signals, or how assetId and exportId relate to the upload step, leaving gaps an agent would need to infer.

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 0%, so the description must carry parameter meaning. It loosely connects the operation to a prior upload and mentions failing with an error, but it does not explain exportId or assetId semantics, leaving two of three parameters ambiguous.

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 action pair: complete a browser-rendered export after upload, or fail it with an error. It also constrains the use case to Widget, distinguishing it from generic export tools. However, it does not name sibling tools or explicitly contrast itself with begin_local_export or upload_local_export.

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 provides implied usage context: it is Widget-only and applies after an upload has occurred. It also indicates the fail path via an error. It does not explicitly state when not to use the tool or name alternatives, so usage guidance is present but 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 already declare the tool is read-only, non-destructive, and closed-world. The description adds valuable behavioral context beyond that by explaining that the response includes status and only returns the MP4 URL when the export has finished.

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. It efficiently conveys the resource, the status behavior, and the conditional download URL.

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-only status tool with no output schema, the description explains the key return behavior: status plus MP4 URL when complete. It could optionally enumerate possible status values, but it is sufficient for an agent to invoke 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 description coverage is 100%, so the single exportId parameter is already documented in the schema. The description does not add syntax, format, or validation details beyond identifying that the tool operates on a video export.

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: returns the status of a video export and its MP4 download URL when finished. It is clear and distinguishable from export-creation siblings, though it does not explicitly name which sibling to use instead.

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 as checking an export's progress and retrieving the URL once complete, but the description does not explicitly state when to use this tool versus the export_video or export_hd_video siblings, nor does it specify any exclusions.

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

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

Annotations already declare this is a non-destructive read (readOnlyHint=true, destructiveHint=false), so the safety profile is covered. The description adds value by disclosing what the response contains (status, three style options, current style, numbered lyric lines) since there is no output schema. It does not disclose status value semantics or whether the result changes over time, which matters for a 'processing status' read.

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 tightly packed sentence with no filler, front-loaded with the verb and resource. The return-value enumeration is dense but each item earns its place given 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 read tool with full annotation coverage and a single fully documented parameter, the main missing piece is behavioral: an agent does not learn whether status can be pending and should be re-polled, or what the style options mean for follow-up calls to choose_style/update_style. The return-field list is a good start but leaves the lifecycle unclear.

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 projectId parameter, and the schema even names its provenance ('returned by create_lyric_video'). The description adds nothing about the identifier, so the baseline 3 applies.

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

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

The description opens with a specific verb and resource ('Returns a lyric video project's ...') and enumerates the payload, making it clearly distinct from create_lyric_video, choose_style, and edit_lyrics. It is clear what the tool produces, though it never says 'retrieve a project' explicitly enough to route an agent unambiguously against get_export.

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

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

There is no when-to-use or when-not-to-use guidance, no mention of polling repeatedly until processing completes, and no reference to alternatives such as get_export or choose_style. The only implied usage comes indirectly from the schema's mention of create_lyric_video, not from the description 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 readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description usefully adds the transient 'short-lived link' behavior and that export happens in the browser, but it does not say whether the link is returned to the caller or opened server-side, nor how long it lasts.

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

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

A single front-loaded sentence with the scope constraint first and zero redundant text. Every clause earns its place.

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

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

For a one-parameter, read-only tool with no output schema, the description covers the action, the constraint and the outcome. The one residual gap is whether the tool returns a URL or performs a browser action, which matters given the 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?

Schema coverage is 100% and projectId is fully described, including its origin from create_lyric_video. The description adds no parameter detail beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific effect: producing a short-lived link that opens the project in the user's browser for export. It also names a scope constraint ('Widget only'), which helps separate it from the export-family siblings, though it doesn't explicitly contrast with export_video or begin_local_export.

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?

'Widget only' gives an implied usage context and excludes non-widget callers. However, it does not state when to prefer this over export_video/export_hd_video or what precondition (beyond having a projectId) must hold.

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 non-read-only, non-destructive mutation, and the description adds meaningful behavioral context: partial updates are supported, colors must be in #RRGGBB format, and invalid font or color choices are either corrected or rejected with a reason. It does not cover permissions, reversibility, or success behavior, but it adds substantial value 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 description is three compact sentences, front-loads the core mutation purpose, and each sentence adds useful information: scope, partial-update behavior, formatting, and validation. 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 nested, mutation-style tool with no output schema, the description covers the essential behavior, partial-update semantics, and validation. It leaves some context implicit, such as how the 'current' style is selected and how this relates to choose_style, but it is largely sufficient.

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 moderate at 50%, and the description adds important meaning beyond the schema by clarifying that changes is a patch-style object where only fields to change should be sent. It also reinforces color formatting and validation behavior, though it does not explain every nested 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 specific verb and resource: it changes the look of the current lyric video style, and it enumerates the affected areas such as layout, animation, colors, font, background, and chorus emphasis. It clearly implies an update operation on an existing style, though it does not explicitly distinguish itself from the sibling choose_style tool.

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 useful partial-update instruction, "Send only the fields to change," and frames the operation around the current style. However, it does not state when to use this versus choose_style or create_lyric_video, nor does it mention prerequisites such as needing an existing style.

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 establish this is a non-read-only, non-destructive, closed-world write, but the description does not add the context an agent needs: what is actually being written, whether it overwrites an existing target, whether the export must exist beforehand, or what happens on size violation. 'Storage upload target' is a label, not a 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 text is short with no filler, and the 'Widget only' qualifier is front-loaded. However, it is a noun phrase rather than a structured statement, and its brevity comes from omission rather than discipline.

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?

A two-required-parameter write tool with zero schema description coverage, no output schema, and a one-line fragment is not sufficiently specified. An agent has no basis for constructing a correct call beyond guessing from parameter 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 0% for two required parameters, so the description carries the full burden and supplies nothing. Crucially, it does not explain that 'bytes' is an integer bound at 524288000 — an agent cannot tell whether this is a payload, a byte count, or an offset — and 'exportId' is left entirely undefined.

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 is effectively a rephrasing of the tool name: 'upload_local_export' becomes 'storage upload target'. It adds two fragments of information ('Widget only', 'browser-rendered MP4') but never states the operation as a verb+resource, and it does not distinguish this tool from begin_local_export or finish_local_export, whose sequencing it clearly participates in.

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?

'Widget only' is a scoping constraint, not usage guidance. There is no statement of when this tool is required versus begin_local_export/finish_local_export, no precondition that an export must be begun first, and no exclusion of other export paths such as export_video or export_hd_video.

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