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

Annotations already disclose idempotency and destructiveness, but the description adds meaningful context beyond them: the quota refund effect, the retry safety, and the specific terminal-state errors. This gives the agent a realistic model of side effects without contradicting the annotations.

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

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

Three short sentences, each adding distinct information: what it does, retry behavior, and failure conditions. No filler or repetition; the critical action is front-loaded.

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

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

For a one-parameter cancellation tool with annotations covering idempotency and destructiveness, the description is functionally complete. It covers preconditions, side effects, and error states. The only minor gap is the lack of any statement about what a successful response looks like, but that is not critical with no output schema.

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 'id' is already well described as the job id from katto_create_clip_job. The description adds little parameter-level meaning 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?

Description uses a specific verb ('Cancel') and precise resource ('still-running job'), plus a clear outcome ('refund the video back to your monthly quota'). This distinguishes it cleanly from sibling tools like get_job, list_jobs, and create_clip_job.

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 clearly states when to use the tool: for jobs in queued/processing state. It also explains the boundary condition by listing when it will error (finished, failed, cancelled), which implicitly tells the agent not to call it in those states. It does not explicitly name an alternative, but the usage context is clear.

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

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

Annotations only state readOnlyHint=false and idempotentHint=false, so the description carries the burden of explaining effects. It clearly discloses that the call consumes 1 video from monthly quota, is asynchronous, returns a job id, and fails on unsupported URLs or videos over 90 minutes.

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 sentences with no filler. It front-loads the core purpose, then adds quota, async behavior, polling, and failure conditions in a logical order.

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 async creation tool with no output schema, the description covers the essential operational details: what is submitted, quota consumption, how the result is returned (job id), how to check completion, and key failure modes. An agent has enough to invoke it correctly and manage the follow-up workflow.

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%, giving baseline credit for parameter clarity. The description adds meaningful context for the 'url' parameter by enumerating supported platforms and imposing the 90-minute limit, though it does not elaborate on the optional 'config' object beyond what the schema already provides.

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

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

The description states a specific action and resource: 'Submit a long video ... for clipping' and names the supported platforms. It clearly distinguishes itself from sibling tools like katto_get_job and katto_cancel_job by describing the creation flow that returns a job id.

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?

Provides explicit workflow guidance: check katto_get_usage before calling, and poll katto_get_job after. It also notes constraints like unsupported URLs and the 90-minute limit, but does not explicitly describe when to prefer this over related tools like katto_rerender_clip or katto_dub_clip.

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

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

With annotations that are all negative hints (readOnly/openWorld/idempotent/destructive all false), the description carries the behavioral burden — and it delivers: it discloses that the operation is free and does NOT use video quota, that each call starts a fresh render (elaborating idempotentHint=false), and that the caller must poll katto_get_rerender for the result. No contradiction with annotations; the description adds genuine context beyond 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?

Four compact sentences, each contributing a distinct fact: purpose and languages, cost/quota behavior, non-idempotency, and the poll-for-result contract. There is minor redundancy — the language list echoes the schema enum and '(not idempotent)' restates idempotentHint=false — but overall the description is tight and front-loaded with the core purpose.

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

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

For a 3-parameter, all-required, async tool with no output schema, the description covers the essential call flow an agent cannot infer: the call returns a rerender_id and requires polling katto_get_rerender, and it consumes no video quota. The main gap is the unaddressed relationship with the closely named katto_rerender_clip, leaving a selection ambiguity for the agent.

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 documents id ('Job id') and clip_index ('0-based clip index') but leaves languages with only an enum and no prose. The description compensates by enumerating the 8 languages and specifying 'one or more,' and it adds meaning to the other parameters by establishing that they refer to a finished clip. At 67% schema coverage, the description bridges the gap in the least-documented 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 action — re-rendering a finished clip with a dub in one or more of 8 named languages — and adds distinctive constraints (free, not idempotent, returns rerender_id). This clearly identifies the tool's job, though it stops short of explicitly contrasting with the sibling katto_rerender_clip, so sibling differentiation is by implication rather than by name.

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

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

The phrase 'one finished clip' implies a precondition: the tool operates only on completed clips, which gives the agent some usage context. However, the description never states when to prefer this over katto_rerender_clip or katto_create_clip_job, nor does it name alternatives or exclusions — the key sibling distinction 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?

The description's 'Read-only' matches the readOnlyHint, idempotentHint, and destructiveHint annotations, and it adds useful behavioral context beyond those annotations: the tool reports the account tied to the key, the key's scopes, and specific quota fields. No extra side-effect warnings are needed for a read-only getter.

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. It opens with the most important operational fact ('Read-only'), then compactly enumerates the exact information returned: plan, scopes, and monthly quota with named subfields. There is no filler or repetition.

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, idempotent tool with no output schema, the description is complete. It tells the agent what will be returned and in what shape, and the annotations cover the safety profile. There are no missing prerequisites, inputs, or side-effect concerns.

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?

This tool has zero parameters, so the baseline is 4. The description contributes no parameter-specific information, but none is needed; the only contextual element, 'this key', refers to the implicit authentication context rather than a call 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 identifies a specific resource—the account behind the current API key—and names the returned data: plan, scopes, and monthly quota. The verb is only implied by the tool name/title and 'Read-only', but the resource is concrete and distinct from the sibling tools that deal with jobs, clips, or sources.

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

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

No guidance is given about when to use this tool versus alternatives. It does not mention that get_usage or other siblings might be better for particular quota questions, and it provides no explicit context like 'use this to inspect the current key's account.' The intended usage is inferable but not 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?

The annotations already declare read-only, idempotent, and non-destructive behavior, and the description merely repeats 'Read-only' without adding extra context such as authentication needs or rate limits. It does not contradict the annotations, but it also does not enrich behavioral understanding beyond what is already provided.

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, terse sentence that conveys all necessary information without redundancy or filler. It is well-structured for quick comprehension and does not waste words.

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

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

Despite the absence of an output schema, the description adequately specifies what will be returned (the brand kits and their key attributes). It lacks details on error handling or response format, but for a simple read-only getter, the provided context is sufficient for most use cases.

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?

Since the tool accepts no parameters, the baseline score of 4 applies. There are no parameter descriptions needed, and the score reflects that the lack of parameters is fully appropriate for this simple read operation.

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 states that this tool retrieves saved brand kits and enumerates their contents (colors, caption font, position, default layout, watermark URL). The resource type is explicit and unambiguous, making the tool's purpose immediately understandable.

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 no guidance on when to use this tool over similar getter tools (e.g., get_account, get_webhook_secret). It relies entirely on the resource name to imply its use case, with no explicit differentiation or selection criteria.

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

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

Annotations already declare read-only/idempotent/non-destructive behavior, and the description adds valuable behavioral details: the response shape, score-based ranking, the hd=true/false distinction for render readiness, and the empty-until-ready behavior. No contradiction with annotations.

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

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

Three compact sentences front-load the core purpose ('Read-only convenience: the clips of a job...') and each sentence carries essential information: output fields, ranking, HD semantics, and the empty-until-ready state. 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 single-parameter read-only tool with no output schema, the description is complete: it defines what is returned, how it is ordered, what hd means, and when the response is empty. The annotations cover the safety profile, and no critical call-time behavior is missing for the given complexity.

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%: the single 'id' parameter is already described as 'Job id from katto_create_clip_job.' The description only reinforces that this is a job's clips without adding new parameter-specific syntax or format, 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 ('get') and resource ('the clips of a job'), and goes further by enumerating the exact returned fields and their ordering ('ranked by score'). This makes it easy to distinguish from job-status, transcript, or listing tools even without reading 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?

The description gives clear context: it is a read-only convenience for retrieving the clips of a job, and it warns that results are 'Empty until the first clip is ready,' which signals when the tool becomes useful. It does not explicitly name alternatives or exclusion conditions, so it falls just short of a 5.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, and the description adds significant context: clip ordering by virality score, the hd=false nuance (URL works, 1080p still rendering), hd_ready flag semantics, and 404 on unknown id. This goes well beyond the structured metadata.

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 first sentence states the core purpose, and each subsequent sentence adds necessary behavioral nuance without fluff. The length is justified by the semantic complexity of the hd and hd_ready flags, and the error behavior is clearly front-loaded after the main description.

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?

Despite no output schema, the description fully specifies the returned clip fields, ranking order, status semantics, hd behavior, and error handling. An agent can correctly invoke the tool and interpret its results without any missing essential information.

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 only parameter id is already described as coming from katto_create_clip_job. The description adds no further parameter-level details beyond 'by id' and the 404 behavior, so the baseline of 3 applies.

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

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

States a specific verb and resource: 'Get the status, progress and clips of a job by id.' This clearly identifies the tool's function and the id parameter, distinguishing it from listing tools like katto_list_jobs and the clip-focused katto_get_clips.

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

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

The description implies usage by mentioning the job id from katto_create_clip_job and the 404 for unknown ids, but it never explicitly states when to use this tool over siblings like katto_get_clips or katto_list_jobs. There are no when-not or alternative routing cues.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior. The description adds useful behavioral detail beyond that: it reveals the return shape and the important null-until-completed semantics of clip_url. This helps the agent interpret polling results correctly.

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 no wasted words. The read-only safety marker is front-loaded, followed by the polling purpose and the return contract. Every sentence earns its place.

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

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

For a simple polling tool, the description covers purpose, initiating tools, return shape, and the key null behavior. Annotations provide the safety profile, and the schema documents both required parameters. Nothing essential is missing.

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

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

The input schema already describes both parameters fully, with 100% schema description coverage. The description adds minimal new parameter-level detail, though it does clarify that rerender_id comes from the rerender/dub response. 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 ('poll'), a specific resource ('re-render'), and explicitly names the tools that start it. This clearly distinguishes it from sibling tools like katto_get_job and katto_cancel_job.

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 clearly implies when to use the tool: after calling katto_rerender_clip or katto_dub_clip. It does not explicitly mention which sibling alternatives to avoid, but the context is unambiguous enough for an agent to select it appropriately.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral detail beyond that: the 404 error during processing and the timestamped segment return format. This is sufficient context for a simple read-only tool.

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

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

The description is two sentences with no filler. It front-loads the read-only nature, then gives the output shape and the key error condition. Every sentence 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, the description is complete: it explains what the tool returns, the data shape, and the failure mode while the job is processing. There is no output schema, but the description compensates by describing the return structure.

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

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

Schema description coverage is 100%, and the only parameter 'id' is already described as 'Job id from katto_create_clip_job.' The description adds no additional parameter-level meaning, so the baseline score 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 clearly specifies that the tool returns the transcript of a completed job as timestamped segments with the shape [{ start, end, text }]. This distinguishes it from sibling getter tools like katto_get_job and katto_get_clips by naming the exact resource and output format.

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 states this is for completed jobs and explicitly notes that a 404 is returned while the job is still processing, giving a clear condition for when to use it. It does not name alternative tools for checking job status, but the usage context is clear enough.

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 and idempotentHint=true, so the read-only behavior is covered. The description adds the actual return fields as a lightweight output contract, which is valuable given there is no output 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?

Two tight sentences: the first covers the operation and output fields, the second gives direct guidance tied to a sibling. No filler or repetition of annotation data.

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 tool, the description is complete: it identifies the resource, the returned values, and the action that should follow. No output schema exists, so the inline field list is a reasonable substitute.

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 there is nothing for the description to compensate for. No parameter documentation is needed, and the description correctly focuses on the return payload instead.

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 read-only operation (get current plan and monthly video quota) and names the exact fields returned. It also ties the tool to katto_create_clip_job, which distinguishes it from the other katto siblings.

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

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

It explicitly instructs the agent to call this tool before katto_create_clip_job to confirm remaining quota. This gives a concrete trigger condition and relationship to a sibling tool.

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

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

Explicitly states 'Read-only' and warns about not displaying or logging the secret, adding important security context beyond the annotations. Also explains the returned verification method.

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?

Single sentence with em-dash pauses is somewhat dense but remains clear and efficient. No redundant 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?

Even without an output schema, it explains what is returned (secret and verification steps) and how the secret is used (webhook_url on jobs), covering essential context for the caller.

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?

No parameters exist (schema coverage 100%), so there is nothing to add. The description is clear and consistent with the empty input 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?

Clearly states it returns the webhook signing secret and provides verification instructions. Distinct from sibling tools as it is the only one dealing with webhook security.

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?

Provides practical context by mentioning 'Pass webhook_url on a job to receive them' and security advice ('treat it as a credential'), but does not explicitly contrast with alternative tools or state when not to use.

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 and idempotentHint, and the description adds useful behavioral context: the response contains id + label pairs, and the values are valid presets for a specific downstream tool. The example further clarifies what kind of data to expect. No side effects or hidden behaviors are omitted.

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, front-loaded sentences with no filler. The read-only declaration leads, then the purpose, then the usage guidance. Every sentence adds value; even the read-only reminder is harmless reinforcement.

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, no-output-schema tool, the description is complete. It tells the agent what the tool returns, why it matters, when to call it, and gives a concrete example. An agent can invoke it correctly without needing additional information.

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 and 100% schema description coverage, so the base score is 4. The description does not need to explain inputs. It instead clarifies what the returned values represent, which is sufficient.

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: lists the valid caption_style preset names for katto_rerender_clip. The example 'hormozi' and mention of id + label make the purpose concrete. It is clearly distinct from sibling tools like katto_list_sources or katto_list_clip_lengths.

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

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

Explicitly instructs the agent to call this before re-rendering so it passes a real preset instead of guessing. This gives clear timing and rationale, though it does not enumerate alternative tools or when not to use this tool. The dependency on katto_rerender_clip provides adequate context.

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

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

The description adds context beyond the annotations by explicitly stating 'Read-only' and the immutability note. This aligns with the readOnlyHint and idempotentHint annotations, providing the agent with a clear behavioral model without any contradictions.

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 long, focused, and free of redundant information. It delivers the key facts (read-only, valid values, immutability) without any fluff, making it easy to parse and act upon.

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

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

Given the tool's simple nature (no parameters, no output schema), the description fully covers what an agent needs to know: what it lists, why it matters, and a critical constraint. No additional details are necessary for correct usage.

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?

This tool has zero parameters, so there is no parameter information to convey. The description's mention of config.clipLength refers to the create tool's parameter, which provides useful context without adding confusion about this tool's own parameters.

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

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

The description clearly states the tool's purpose: listing valid values for the optional config.clipLength field used in katto_create_clip_job. It also notes the read-only nature and the field's immutability after creation, making it unambiguous what this tool 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?

The description explicitly says 'Read-only' and explains that clipLength is fixed at creation and cannot be changed by re-render, which guides the agent on when to use this tool (before creation) and when not to use it (during rerender). The context of sibling tools (create, rerender) reinforces this guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the 'Read-only' label adds no new safety info. However, the description adds useful behavioral detail beyond annotations: newest-first ordering, cursor-based pagination mechanics, the optional status filter, and the exact response 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 concise sentences, front-loading the most important facts (read-only, list recent jobs, ordering) and compactly covering pagination, filtering, and return shape. No filler or redundant elaboration; every phrase 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 read-only list operation with no required parameters, a full output schema, and strong annotations, the description provides everything needed to call the tool correctly: ordering, pagination contract, filter option, and return structure. Missing details like full status enums or rate limits are minor and covered by examples and schema.

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 parameters are already well documented. The description adds a small amount of context by explaining the pagination flow ('pass the previous next_cursor') and noting status is optional, but it mostly paraphrases the schema rather than revealing new parameter semantics.

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

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

The description states a specific verb ('List') and resource ('your recent jobs'), with ordering ('newest first'), and is clearly distinct from siblings like katto_get_job, which suggests retrieving a single job. It also names the read-only nature upfront, leaving no ambiguity about what the tool 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?

The description gives clear usage context: list recent jobs, paginate using cursor, optionally filter by status. It does not explicitly contrast with alternatives like katto_get_job or katto_cancel_job, but the listing scope and optional filter are enough to guide selection in most cases.

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 annotation already declares readOnlyHint and destructiveHint, so the description's statement 'Read-only' adds no new behavioral information. It does mention that each platform has an example URL, which slightly clarifies the output, but this is minor compared to what is already disclosed by 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 concise, consisting of two short sentences that efficiently convey the tool's purpose and usage. It avoids unnecessary detail and is well-structured for quick comprehension.

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

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

The description provides sufficient context: it explains what the tool returns (platforms with example URLs), its read-only nature, and its relationship to katto_create_clip_job. While it does not enumerate the specific platforms or the response schema, this level of detail is adequate for an agent to understand when and why to call the 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 has zero parameters, and the schema coverage is complete (no params to describe). Per the baseline rule for 0 params, a score of 4 is appropriate, as there is no parameter information that the description needs to supplement.

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 states that the tool lists video platforms supported by Katto, each with an example URL, and explicitly distinguishes it from other tools by mentioning its read-only nature and its role in confirming URL support before calling katto_create_clip_job.

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 explicit guidance on when to use this tool: to confirm a URL is supported before invoking katto_create_clip_job. This makes the usage context unambiguous and actionable for an agent.

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 goes well beyond annotations by explicitly disclosing that the call is free and does not consume video quota, that it starts a new render and is not idempotent, and that the original clip is preserved. It also explains the return value and the required follow-up polling step.

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

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

The description is compact and front-loaded, with every sentence contributing distinct information: what the tool does, its cost characteristics, its behavioral guarantees, and the expected result/next step. There is no repetition of schema details 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?

For a moderate-complexity tool with no output schema, the description provides enough information to invoke the tool correctly and understand the outcome: it returns a rerender_id and the caller must poll katto_get_rerender. Combined with the detailed input schema and sibling tool names, the context is complete.

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

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

Schema coverage is 75%, so the schema already documents most parameters. The description adds value by clarifying that layout and caption style can be combined ('and/or'), and by directing users to katto_list_caption_styles for valid caption_style values, which supplements the enum list.

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 states a specific action ('Re-render') on a specific resource ('one already-finished clip') and names the exact dimensions being changed ('new reframe layout and/or caption style'). It distills katto_rerender_clip from siblings like katto_create_clip_job by emphasizing the clip is already finished.

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

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

The description gives clear usage context: valid caption styles come from katto_list_caption_styles, and callers should poll katto_get_rerender for the URL. It implies this is for existing clips rather than new job creation, though it does not explicitly state when not to use the tool or name conflicting alternatives.

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