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

With no annotations supplied, the description carries the full burden and does so: it discloses the asynchronous contract (returns job_id immediately, work takes minutes, slower without an NVIDIA GPU), the required polling loop, that files land under the ShortsFlow folder and nothing is uploaded, and the optional-API-key behavior. These are exactly the operational facts an agent needs and none of them are inferable from the schema.

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

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

Dense but well ordered: what it does, how it runs, what it costs/requires, where output goes, and the alternative sibling, in that sequence. Every sentence carries information, though the single unbroken paragraph makes it slightly harder to scan than a short bulleted split would 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 7-parameter, long-running, no-output-schema tool, the description covers the async return value, the polling path, runtime expectations, and side effects (local files, no uploads). The only thin spot is what the completed job actually yields beyond 'shorts' — number of files, naming, or format — which the agent must discover from get_render_status.

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 per-parameter enum and default meanings are already documented and the baseline is 3. The description still adds framing value by tying the parameters together — 'crops to 9:16 with face tracking' contextualizes smart_crop/layout, and 'burns in animated captions' plus the Whisper/scoring mention explains why clip_count and caption styling exist.

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

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

States a concrete verb and resource ('Cut the best moments out of a long video ... into captioned vertical shorts') and then enumerates the pipeline steps: Whisper transcription, moment scoring, 9:16 face-tracked crop, burned-in animated captions. It explicitly names the sibling generate_short as the tool for a different task, so the agent can distinguish the two 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 routing: use this for clipping an existing video, use generate_short to create a video from a topic. It also tells the agent the follow-up workflow (poll get_render_status until 'completed' or 'failed') and states the prerequisite context that clipping works without an API key while an AI key only improves scoring and titles.

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 no annotations supplied, the description carries the full burden and does so: it discloses that the tool is asynchronous, returns a job_id immediately, takes minutes, requires the user's own keys from the ShortsFlow .env, writes only inside the ShortsFlow folder, and never uploads or posts. Async semantics, credential sourcing and side-effect boundaries are exactly the facts an agent needs before firing an expensive render.

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

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

Four sentences, each load-bearing: purpose, async contract, side effects/credentials, then routing to the alternative. The most decision-critical facts (what it makes, that it is backgrounded) are front-loaded with no filler.

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

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

For an 11-parameter, long-running generation tool with no output schema, the description covers the return contract (job_id plus polling), the operational constraints (local render, user keys, no upload), and the sibling alternative. 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 description coverage is 100%, with all 11 parameters and 6 enums documented inline, so the schema already does the heavy lifting. The description adds only the loose framing of topic/idea and does not explain how mode, vibe, or caption_style interact with the render; 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 states a specific verb and resource ("Create an original vertical short video from an idea") and enumerates the pipeline components it produces: AI script, voice-over, stock footage, music, animated captions. It also explicitly distinguishes itself from the sibling extract_clips, 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?

It gives an explicit when-to-use rule ("Use this to make a new short from a topic") paired with the alternative and its condition ("use extract_clips instead to cut shorts out of an existing video"). It also prescribes the follow-up workflow: poll get_render_status until 'completed' or 'failed'.

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

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

With no annotations, the description carries the full behavioral burden and does well: it discloses synchronous execution, that the configured AI model is used, and that an unreachable model yields a generic template that should be checked. It omits cost/rate characteristics, but the key failure mode an agent must know about is stated.

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

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

Four short sentences, front-loaded with the deliverable, then the synchronous behavior, the fallback, and the scope limit. Minimal waste; the fallback sentence is the only one that could be tightened.

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-param generation tool with no output schema, the description names the returned artifacts and the degraded-mode behavior, which is what an agent needs to call and trust the result. Missing only explicit contrast with generate_short and any note on how required topic interacts with mode.

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 mode, topic and category are already documented in the schema. The description adds no meaning about how mode or category influence the generated text, leaving it at the baseline for a fully documented schema.

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

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

The description opens with a specific verb and output set: writes title, description, hashtags and caption for YouTube Shorts, TikTok and Instagram Reels. This clearly separates it from a renderer like generate_short, though it never names that sibling, so the distinction 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 line 'It does not publish anything' and 'answers immediately (no job)' implicitly scope usage against async/publishing siblings, but there is no explicit when-to-use or when-not guidance and no alternative is named. An agent must infer routing from the sibling list.

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

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

With no annotations supplied, the description carries the full burden and does so: it declares the tool changes nothing, discloses the crucial lifetime constraint ("Jobs are remembered only while this server is running"), which explains how 'not_found' arises, and enumerates the exact return fields including that the error message is the tail of the log.

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 sibling linkage are front-loaded, and every sentence contributes either scope, return shape, lifetime caveat, or polling cadence. It is slightly dense in one paragraph, 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?

There is no output schema, so the description must explain returns, and it does so completely: status values, progress range, log lines, and error semantics. Combined with the polling guidance and job-lifetime caveat, nothing an agent needs to call this 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% and the single parameter's description already says it is the job_id returned by generate_short or extract_clips, which is essentially what the prose repeats. The description adds no format, validation, or edge-case detail (e.g. what a malformed or stale id yields) 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 opens with a specific verb and resource ("Check a background job") and immediately ties it to the two sibling tools that create jobs, generate_short and extract_clips, so an agent can tell it apart from every generator in the set 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 an explicit polling contract: call every 20-30 seconds and stop when status is no longer 'processing'. Combined with the note that the job must have been started by generate_short or extract_clips, the when-to-use condition is fully specified 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?

With no annotations provided, the description carries the behavioral burden and discloses that the tool is instant, read-only, and takes no input. These are meaningful traits beyond the empty input schema, though it does not describe pagination, authentication needs, or the exact return shape.

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

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

The description is two sentences, front-loads the core purpose, and adds the usage suggestion without unnecessary wording. Every clause contributes either scope, behavior, or invocation 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 zero-parameter, read-only lookup tool with no output schema, the description is complete enough: it says what will be listed, which sibling's options are included, and when to call it. No additional detail is necessary for an agent to invoke 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?

The tool has zero parameters, so parameter semantics are minimal by design. The description reinforces this by stating it takes no input, which aligns with the empty schema and gives the agent baseline clarity.

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 uses a specific verb ('List') and resource ('options the other tools accept'), then enumerates the option categories such as content modes, caption styles, voice-over engines, aspect ratios, and sound-effect presets. It also ties content modes to the sibling tool generate_short, making the tool's scope clear without needing to inspect any schema.

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

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

It explicitly says to call it first when unsure which value to pass, which gives clear usage context and positions it as a prerequisite lookup tool. It does not state when not to use it or name every sibling that benefits from it, but the guidance is sufficient for the intended workflow.

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