Alpy

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

Goes well beyond the annotations (readOnlyHint=false, openWorldHint=true): it discloses that calling spends the creator's video minutes, that a creator without minutes instead gets one free 10-second preview, a 10-per-day rate limit, and an auth requirement. That is exactly the cost/authorization context an agent needs before invoking a non-idempotent, open-world mutation.

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

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

Six dense sentences with the core purpose front-loaded, followed by prerequisites, cost behavior, limits, and auth. No filler and no repetition of schema-declared enums, default values, or annotation flags.

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 six-parameter, cost-incurring generation tool, the description covers purpose, prerequisites, async polling pattern, rate limits, and authorization. An output schema exists, yet it still adds the useful 'returns a video id' pointer, so nothing material 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 baseline is 3, but the description adds real meaning beyond the schema: the script is the spoken narration only and should be 110-2700 words (a constraint absent from the schema's maxLength/minLength). Other parameters (tone, voice, character_id) are already well documented by the schema, so it earns a 4 rather than a 5.

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: turning a script into a hand-drawn Alpy video with AI narration. It also names the upstream (write_youtube_script) and downstream (get_video) siblings, but never explains how it differs from the closely-named make_full_video sibling, leaving one differentiation gap.

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

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

Explicit workflow guidance: write the script first with write_youtube_script, confirm the creator authorizes spending minutes before calling, then poll get_video every minute. Prerequisites (connected Alpy account or API key) and the daily cap of 10 are stated outright, so an agent knows exactly when this call is appropriate.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower and the description adds real context on top: the returned links expire after an hour, and the call requires an authenticated account or API key. It does not mention rate limits or behavior for unknown/expired ids, so it falls short of a 5.

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

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

Two compact sentences, front-loaded with what is returned before the access prerequisite. The phrasing is slightly awkward ('and, once made, links to...') but nothing is wasted.

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

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

With an output schema present, return values need not be spelled out, yet the description still anchors the key payload (status, progress, links) and flags link expiry and auth needs. Complete enough for a one-parameter status tool; only the relationship to sibling list/creation tools is unaddressed.

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

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

The single id parameter is fully documented in the schema (100% coverage, including the hint that it comes from create_video), so the baseline is 3. The description adds no additional parameter detail and does not need to.

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 resource and verb-equivalent: it reports 'where a video is', its status and progress, and available links. An agent can tell this apart from create_video/make_full_video from the wording, though it never explicitly names a sibling or contrasts with list_videos.

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

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

It states a prerequisite (a connected Alpy account or API key) and implies the post-creation polling flow via 'Says what to do next', but there is no explicit when-to-use versus list_videos or how this fits the create_video -> get_video sequence. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds value beyond them by disclosing the auth requirement (connected account or API key), which an agent needs before invoking. It does not describe pagination or result size, but the safety/behavior profile is well covered.

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, front-loaded with what the tool returns, then how to use the result and the auth prerequisite. No filler or redundant restatement of the title.

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

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

An output schema exists, so return values need not be spelled out, and the description covers purpose, downstream usage, and auth. It omits any pagination or ordering hints, which is a minor gap for a zero-parameter list tool.

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

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

The tool takes no parameters, so the baseline is 4. The description mentions that returned characters carry an 'id' and 'source', which adds useful meaning about the payload shape beyond the empty 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 clearly identifies the resource: the two categories of characters (Alpy's own cast and the creator's saved characters) that a video can be drawn with. The name carries the 'list' verb, and the mention of create_video distinguishes it from sibling tools. It stops just short of an explicit verb-and-scope sentence but is easy to select correctly.

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

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

It gives clear downstream context ('Pass a character's id and source to create_video') and a prerequisite (connected Alpy account or API key). It doesn't state when not to use it or name an alternative listing tool, but the usage context is unambiguous.

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

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

Annotations already establish readOnly, idempotent, non-destructive and non-open-world behavior, so the description only needs to add context. It does: the auth requirement (connected account or API key) and the scoping/ordering rule are genuine additions beyond the structured fields.

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

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

Two short sentences, no filler, with the resource and ordering stated before the prerequisite. 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?

With an output schema present, return values need no explanation, and the description covers scope, ordering, auth, and the status field. Only the limit default/ceiling is left wholly to the schema, which is appropriate.

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

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

There is a single optional parameter with 100% schema description coverage, including its range and ordering semantics, so the schema carries the load. The description's 'newest first' reinforces but does not extend 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 gives a specific verb and resource ('list ... Alpy videos') plus scope ('the creator's most recent', 'newest first') and returned field ('with their status'). It implicitly separates itself from get_video by emphasizing a plurality of recent items, but it never names a sibling explicitly.

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

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

It states a prerequisite ('Needs a connected Alpy account or an Alpy API key'), which is useful usage context, but gives no when-to-use/when-not guidance and does not contrast with siblings like get_video for retrieving a single video.

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

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

Goes well beyond the annotations by disclosing the cost model (one video minute per started minute), the required user confirmation, the failure mode when minutes are exhausted, and the auth requirement (connected account or API key). None of that is inferable from readOnlyHint/destructiveHint/idempotentHint.

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

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

Three short sentences, each doing distinct work: trigger, cost plus confirmation warning, auth/failure conditions. The most important constraint (minute spend) is placed early.

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 an output schema present, return values need no explanation, and the description covers the remaining agent-critical facts: cost, auth, and the unavailable-feature outcome. Nothing needed to invoke it safely 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?

The single 'id' parameter is fully documented in the schema (100% coverage), so the schema carries the burden. The description adds no syntax or format detail for id, which is expected here; baseline 3.

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

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

States a specific verb and resource ('makes the whole video') and scopes it to the post-preview stage, which separates it from create_video and get_video. It does not explicitly name a sibling to avoid, so it falls short of the top mark.

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

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

Gives a clear trigger condition ('After the free preview') and a prerequisite interaction rule ('confirm with them first'). It names no explicit alternative or exclusion, so usage is clear but not fully routed against the siblings.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so 'Reads nothing and changes nothing' largely restates structured data. The real added value is the non-obvious two-step contract: the tool returns a brief the agent must then follow rather than producing the script, and 'the brief asks for the rest' signals the return will drive a follow-up prompt.

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

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

Three tight sentences with no waste; the most decision-relevant fact (this returns a brief, not a script) is front-loaded immediately after the entry-point cue.

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?

Output schema exists so return-format detail is unnecessary, and annotations cover the safety profile. For a zero-required-param, read-only brief tool the description supplies everything an agent needs: when to call it, what it returns, and how to proceed afterward.

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

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

Schema coverage is 100%, so the schema documents all four params including tone/character enumerations, setting the baseline at 3. The description adds genuine usage meaning by explaining the fill-what-you-have pattern and that the brief will elicit the remainder, which the schema alone 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?

States a specific verb+resource ('Returns Alpy's YouTube scriptwriting brief') and crucially corrects the name's implication that this tool writes a script itself. The contract is unambiguous. It never names a sibling (create_video, make_full_video) explicitly, so it stops short of full sibling differentiation.

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

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

'Start here for any Alpy script' gives a clear entry-point condition, and the guidance to pass only the fields the creator already supplied tells the agent how to invoke it under partial information. There is no explicit when-not or named alternative for other outcomes.

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