Say It Again

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

Annotations declare the mutation/destructive/openWorld profile, and the description goes well beyond them: it discloses that team credits are spent, that the price is whatever get_video lists in after_steps (with a separate voiced price for voiced languages), that it is refunded on failure, and that it is a fire-and-poll async operation returning an id. That is exactly the context an agent needs before committing credits.

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?

Compact at three sentences with the action front-loaded and no filler. The prose is somewhat convoluted ('its voiced price for a voiced language'), but every sentence carries a distinct, useful fact about cost, constraints, or follow-up.

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, no-output-schema tool this covers the essentials: what it returns (an id), how to track it (get_video polling), the credit/refund model, and the language constraint. The only real gap is the missing explicit differentiation from change_video.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics: 'credits' must equal the listed price or be refused, 'language' must be one after_steps offers, and idempotency_key makes a repeat call return the first answer without further spend. That is more than the structured fields convey on their own.

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: 'Make one finished video again in another language, its own script and presenter, into a new video beside it.' The 'new video beside it' phrasing cleanly separates it from an in-place edit, but it never names the sibling it is closest to (change_video), so an agent must infer the boundary.

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 constrains the language to one 'after_steps lists for it' and explains the post-call workflow (poll get_video about once a minute until ready or failed), which is genuine operational guidance. However, it never says when to choose this over the sibling change_video, so usage selection is only implied.

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

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

Annotations only declare write/destructive/idempotent-false; the description goes well beyond them by disclosing the credit cost source (the price get_video lists in after_steps), the refund-on-failure behavior, the content validation rules (no price, no fabricated presenter history), and the asynchronous id-return-with-polling contract. These are exactly the operational facts an agent needs before calling a costly 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?

Purpose is front-loaded, but the prose is dense and repetitive ('as the person asks, made again into a new video beside it, as the app's Change does'), and the credit/polling details are packed into the same paragraph. Every sentence carries information, but the wording taxes readability.

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 5-parameter, no-output-schema mutation tool, the description covers prerequisites, cost and refund, validation limits, and how to retrieve the result. It stops short of clarifying the 'part' parameter's role or what the returned id is for beyond polling, but nothing critical to correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: it explains that 'credits' must match the after_steps price (a different figure is refused) and constrains 'change' with the app's validation rules beyond the schema's 'in the person's words'. It still does not clarify the 'part' selector, which the schema handles.

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: it changes one finished video into a new video alongside it, explicitly tied to the app's 'Change' operation. It also names its precondition ('Only for a video whose after_steps offers it') and its follow-up sibling (get_video), so an agent can separate it from make_video and list_videos. The phrasing is awkward and roundabout ('as the person asks, made again into a new video beside it'), which keeps it short of a 5.

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 an explicit eligibility condition ('Only for a video whose after_steps offers it') and the follow-up loop ('call get_video with it about once a minute until its status is ready or failed'). It does not name make_video or other alternatives as the when-to-use comparison, so it stops short of full alternative routing.

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

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

Annotations only say readOnlyHint=false, destructiveHint=false, openWorldHint=false; the description adds what the annotations cannot — quota cost and refund behavior, and the asynchronous id-then-poll contract. These are the two facts an agent most needs to avoid wasting a drawing or misreading an immediate empty response.

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 dense paragraph, but front-loaded with the purpose and with no filler sentences — quota, refund, and polling all earn their place. The archaic, clause-heavy phrasing costs a little readability compared with a plainly structured version, keeping it short of a 5.

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 supplies the return contract (an id) and the completion protocol through get_described. Combined with quota/refund semantics and a fully documented schema, an agent has everything needed to call and follow up on this 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 100% (both params documented, including the 24-char name and 300-char description limits), which sets a baseline of 3. The description goes beyond that by implying the description parameter is subject to content review ('a description refused'), telling the agent its input can be rejected, and by noting the invented-adult constraint on what may be described.

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 ('Draw a presenter ... from a description of how they look') and constrains the output ('an adult, invented, not a real person or a character'). That constraint alone separates it from sibling tools and from a generic image-generation call, so an agent knows exactly what artifact this produces.

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 the operational context clearly: it is free but counted against a daily quota of 5, a refused description or failed drawing refunds the quota, and the call returns an id that must be polled via get_described 'every few seconds until its status is ready or refused'. It names the follow-up sibling and the polling cadence, though it never states an explicit when-not-to-use case (e.g. reuse an existing presenter via list_presenters/keep_presenter 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 already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds value the annotations do not: that this call is 'Free' (consumes no credits), which matters in a credit-metered system, plus it names the quota counter scripts_left.

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 sentence, front-loaded with the primary resource and immediately followed by the specific fields and the cost note. Nothing extraneous.

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 carries the burden of explaining return values, and it does list the key fields (credits, plan, scripts_left). It stops short of describing types, units, or format, but for a zero-parameter read tool it is essentially 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?

The tool takes zero parameters, so the baseline of 4 applies. The description spends its words on output semantics instead (scripts_left tied to write_scripts), which is the relevant information for a no-arg call.

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

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

The description names a specific resource (the team's credits/balance) and enumerates exactly what is returned: credits, plan, and scripts_left. It also hints at a relationship to the write_scripts sibling, though it doesn't explicitly contrast itself with it.

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 only implied — an agent can infer this is the tool to check remaining write_scripts quota or credits before spending them, but the description states no explicit when/when-not condition or alternative tool. The trailing 'Free' hints at cost but is not framed as usage 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 and non-destructive, so the safety profile is covered. The description goes beyond them by disclosing the possible statuses, that a ready result has exactly 3 numbered pictures, that each link expires in an hour, that a voice may be returned if the description specified one, that refusal includes a reason, and that the call is free – all meaningful operational context.

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

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

It is a single short passage, so length is fine, but it is an unstructured run-on that begins with the vague lead-in 'How a drawing ... is going' rather than front-loading the actual operation. The embedded workflow and output details earn their place, but the sentence structure makes them hard to extract.

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 tool has one fully documented parameter, annotations covering safety, and no output schema, so the description must carry the return semantics – which it partially does via the statuses, the 3 numbered pictures, the link hour, and the voice/refusal branches. It stops short of describing the actual response shape or how the caller should poll, leaving noticeable gaps for a tool 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 description coverage is 100% and the single id is documented as 'The id describe_presenter answered.' The description corroborates this by tying the drawing to describe_presenter, but adds no format or sourcing detail beyond the schema. Baseline 3 applies when the schema does the heavy lifting for one 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 conveys that this reports on the state ('checking, drawing, ready') of a drawing job started by describe_presenter, and it names siblings describe_presenter and keep_presenter, which aids differentiation. However, the verb is buried in the colloquial phrase 'How a drawing ... is going' – there is no crisp statement like 'get the status of a drawing job', so the agent must infer the core action.

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 lifecycle is implied: you call this after describe_presenter, the person chooses one of the numbered pictures, and keep_presenter keeps it. That sequence tells the agent where this fits, but no explicit when-to-use or when-not-to-use condition is stated, and the 'or refused with why' branch is only hinted at.

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 closed-world, so the safety profile is covered. The description adds genuinely useful context beyond that: the lifecycle states a script can be in and the fact that the call is free, which tells an agent it can safely poll.

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 compact sentence, front-loaded with the resource and provenance, with zero 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?

With no output schema, the description has to convey return content, and it does outline the statuses plus the shots and lines each ready script carries. It stops short of describing the exact return shape or pagination, but is adequate for correct invocation.

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 parameter with 100% schema description coverage ('The id write_scripts answered'), so the schema already defines it fully. The description adds nothing about the id's origin beyond repeating the write_scripts linkage, matching the baseline for a well-covered 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 names the exact resource (scripts), its provenance (written by write_scripts), and the states they can be in (queued, in_progress, ready, failed), which cleanly separates it from the sibling write_scripts. The retrieval verb is only implicit, but an agent can tell what it returns 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?

Tying the tool to write_scripts implies the usage context: fetch the results/status of a prior write_scripts call. The trailing 'Free' hints that polling is cheap, but there is no explicit when-to-use, when-not, or alternative named.

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

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

Beyond the readOnly annotations, it discloses the status states, that after_steps include prices in credits, and that download_url is regenerated per answer with an expiry window. It also states the operation is free and explains how to get a new link later.

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?

It front-loads the status-checking purpose, then covers only materially useful details: statuses, after_steps pricing, link expiry, re-call behavior, and cost. 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?

No output schema exists, but the description explains the status values and key returned fields such as after_steps, download_url, and download_expires_in_seconds. That is enough for an agent to call and interpret 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 coverage is 100%, and the id field already documents that it comes from make_video. The description reinforces the source but adds no syntax or format details 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 specifies that this retrieves the status of a video produced by make_video or a subsequent step, enumerating the possible states and post-ready artifacts. It clearly implies a singular lookup by id, but it does not explicitly distinguish this tool from 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?

The description tells the agent to call this after make_video and to call again for a later download link, giving clear usage context. It does not name explicit when-not conditions or alternatives such as list_videos.

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=false and destructiveHint=false, so the agent knows this is a non-destructive write. The description adds genuine context beyond that - it is 'Free' and it 'Answers the presenter's id' - but says nothing about idempotency, whether an existing presenter is replaced, or permissions.

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, front-loaded with the action, and each sentence contributes something (purpose, return value, cost). The second sentence's clause 'for presenters in the other tools' is a bit tangled but nothing is padded.

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, yet the description covers the return ('Answers the presenter's id'), the cost ('Free'), and the effect, while annotations handle the safety profile and the schema fully documents the inputs. Only finer write semantics are absent.

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 all three params (id, voice, picture) are already documented in the schema, which the description merely mirrors ('one picture', 'the voice the person chose'). Baseline 3 applies since the schema carries the 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?

States a specific verb and resource: keep a picture of a drawing as one of the team's presenters, with the chosen voice. The phrasing ('one picture of a drawing', 'team's presenters') is slightly awkward but an agent can tell this registers a presenter, distinct from list_presenters/describe_presenter. It could name the relevant sibling more 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?

Usage is only implied: 'Answers the presenter's id, for presenters in the other tools' suggests this is the creation step whose output other tools consume, and the id param points at describe_presenter. There is no explicit when-to-use or when-not vs set_presenter_voice or list_presenters.

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, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds genuinely useful context beyond that: 'Free, and nothing is looked up' confirms no external Ad Library call and no cost, consistent with openWorldHint=false. It does not, however, describe pagination or ordering 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?

It is a single overlong run-on sentence with broken syntax, and the key operational fact ('Free, and nothing is looked up') is tacked on at the end rather than front-loaded. The source list and return fields are crammed into the same clause, hurting readability.

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 compensates by enumerating the returned fields (id, advertiser, title, days running, whether it is a video) and the three sources, and it discloses the free/no-lookup behavior. For a low-complexity, read-only, 2-param tool this is close to complete, missing only explicit guidance on choosing it over siblings.

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 already documents limit and source, including the enum. The description does loosely map the three sources ('Competitors, the Winning ads of its kind and the library links it pasted') to the competitors/winning/pasted enum values, adding marginal meaning, but never mentions the limit parameter. 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 name/title and the noun phrase 'The Meta Ad Library ads the team's store already holds' convey the resource, and 'to build a video like one' hints at the use case. However, the sentence is a garbled run-on ('to build a video like one with ad: its Competitors, the Winning ads...') that never states a clean verb and takes real effort to decode. It is distinguishable from list_videos/list_presenters by the ad/Ad Library framing, but the wording fights the reader.

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 an implied context ('to build a video like one') but no explicit when-to-use, when-not-to-use, or comparison against siblings like get_video, make_video or list_videos. The agent must infer the selection condition from a garbled clause rather than being told it.

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 adds two useful behavioral facts beyond that: the listing is free of charge, and it spans both owned and team-described presenters. It says nothing about ordering or result limits, so it is not rich.

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 compact sentence with no filler; the scope and the 'Free' note are front-loaded. The 'by id' fragment is slightly cryptic but costs little space.

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

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

With no output schema and no parameters, the description carries the burden of explaining what is returned. It says 'by id' and distinguishes owned vs team-described presenters, which partially covers the return, but omits ordering, pagination, or how many results to expect.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. The description adds no parameter detail because none exist; 'by id' faintly signals the return shape but does not affect invocation.

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

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

The description names the resource (presenters usable to make a video) and its scope (ours plus team-described ones), so the agent can infer this is a listing tool. However, it lacks a clean verb+resource framing and does not explicitly contrast with siblings like describe_presenter or keep_presenter, leaving differentiation to inference.

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 explicit when-to-use guidance or mention of alternatives. The word 'Free' hints at a cost consideration but the description never states when to call this versus describe_presenter, keep_presenter, or set_presenter_voice.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior: each answer mints a fresh download_url valid for one hour, download_expires_in_seconds reflects remaining time, and the call is free. It does not cover pagination behavior, keeping it from 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?

Front-loaded with the resource and ordering, then a focused explanation of link expiry. Every sentence carries information relevant to correct use, with no filler, though the download-expiry detail is slightly dense for a list tool.

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

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

With no output schema, the description usefully explains the key returned field (download_url) and its companion (download_expires_in_seconds), and the schema covers pagination. An agent has enough to call and interpret the tool, though return shape beyond the URL field is unstated.

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 both 'after' and 'limit' are already documented in the schema. The description adds nothing about these parameters, 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+resource ('list' the team's UGC videos) plus ordering ('newest first'), which is clear and distinguishable from unrelated siblings. It does not explicitly differentiate itself from the other list_* siblings (list_ads, list_presenters), so it stops short of a 5.

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 explicit 'use this when...' guidance for listing videos. The one routing hint ('For a later download, call get_video again for a new link') addresses a follow-up download action rather than when to choose this tool over an alternative, so usage is only implied.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the bar is lower; the description still adds real behavior — credit spend, refund-on-failure, async job semantics, and the polling cadence. It does not say what the underlying source video's fate is beyond implying preservation via 'a new video beside it'.

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 is front-loaded, which is good, but the prose is tangled with comma splices and dense clauses ('its take carried on with new lines written from the product page, into a new video beside it'). Roughly four sentences, and each covers a distinct point, so length is defensible even if readability suffers.

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 carries the burden well: it explains that the call returns an id immediately and how to poll it to completion, plus the credit and eligibility constraints. A mutation of this weight arguably warrants a note on failure modes or what happens to the original video, which is the only real gap.

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

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

Schema description coverage is 100%, so the schema already documents id, part, credits, and idempotency_key; per the rubric that sets a baseline of 3. The description's note about the price get_video lists in after_steps mostly restates what the credits parameter description already says, adding little beyond 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?

Names a specific verb+resource ('make one finished video longer') and distinguishes the output ('into a new video beside it'), plus references the app behavior it emulates. It's clear what the tool does, though the run-on phrasing takes work to parse and it doesn't explicitly contrast with siblings like change_video or other_sizes.

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 an explicit precondition ('Only for a video whose after_steps offers it'), states the cost and refund policy, and prescribes the follow-up loop ('call get_video with it about once a minute until its status is ready or failed'). It doesn't name an alternative tool for when this isn't appropriate, but the eligibility gate is unusually precise.

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?

Annotation-flags destructive, openWorld and non-idempotent are all backed with concrete behavior: it spends the team's credits, the amount is the quote quote_video gave for the same choices, and it is refunded if the video fails. It also discloses that the call returns immediately with an id rather than the finished video, that generation takes a few minutes, and how to poll — the exact context 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?

Three sentences, cost first, then the async return and polling instructions — well front-loaded with no filler. The phrasing is verging on over-compressed ('Answers an id at once, and with languages an id for each language in ids'), which costs a little readability.

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 21-parameter, no-output-schema generation tool, the description covers the two things the schema cannot: the credit cost/refund model and the asynchronous handoff to get_video. The many parameter interactions (ad/angle/lines/script_id exclusions, language vs languages) are left entirely to the schema, which is acceptable given 100% coverage but leaves the description thin for a tool this complex.

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 each of the 21 parameters carries its own rules, so the schema does the heavy lifting. The description only adds that 'the same choices' must match the quote and that `languages` yields one id per language; it adds no further syntax or mutual-exclusion guidance beyond what the schema already states.

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?

Opens with a concrete verb and resource ('Make a UGC video of a product'), which immediately separates it from siblings like change_video, make_longer, quote_video and get_video. The agent knows exactly what artifact this 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?

It names quote_video as the source of the credit figure and get_video as the polling path with a cadence ('about once a minute'), so the surrounding workflow is clear. It stops short of explicit exclusions such as when to prefer change_video or make_longer over a fresh generation, leaving some routing 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 readOnlyHint=false, idempotentHint=true and destructiveHint=false, and the description adds genuinely new operational context: the call is asynchronous and returns an id immediately, requiring get_video polling until status is ready or failed, and the 'Free' cost signal. It also concretizes idempotency – 'The same size asked again answers the one already made or being made' – which gives the annotation practical meaning.

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?

Purpose is front-loaded, then constraints, then the polling workflow – a sensible ordering. But the opening clause is redundant and awkwardly phrased ('the same video cut for that frame, as the app's Other sizes does'), and the terse 'Free.' fragment sits oddly. It is neither padded nor crisp.

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 carries the return-value burden and does so: it explains that an id comes back immediately and must be polled via get_video until ready or failed, and that repeats return the existing job. Eligibility conditions are also stated. Only the alternative-tool path is left uncovered.

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

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

Schema description coverage is 100%, so the schema already documents both parameters and their enum, establishing a baseline of 3. The description adds one real constraint beyond the schema: the chosen size must be one the video's after_steps actually lists, not merely any enum value. That is a useful eligibility note but not a format or syntax elaboration.

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 – producing an additional size rendition of an existing finished video – and pins it to the app's 'Other sizes' feature. It is distinguishable from siblings like change_video or another_language, though it never names the closest analogue (another_language) explicitly, so routing relies on the agent inferring the parallel.

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 hard precondition: 'Only for a video whose after_steps lists other_sizes, in a size it lists.' That is a clear when-to-use gate rather than vague context. It does not, however, name the alternative tool to use when that precondition fails (e.g. another_language for a different language cut), so the routing is incomplete on the exclusion side.

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=true, so the safety profile is covered. The description adds a genuinely decision-relevant trait not in the annotations: the call itself is 'Free', and it returns a balance-coverage verdict rather than performing the action. It does not address the openWorld implication of looking up unseen library ad links, but against an already-covered safety profile this is a solid addition.

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

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

Two sentences, zero waste, with the core purpose front-loaded and the cost trait isolated for emphasis. Nothing is repeated from the schema or annotations.

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

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

For a 15-parameter, zero-required tool the schema carries nearly all the load, and with no output schema the description usefully states what is returned (cost in credits plus a balance-coverage verdict). The only real gap is sibling routing: it never tells the agent this is the non-committal step before make_video.

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 15 parameter descriptions are unusually rich (defaults, mutual exclusions, per-param behavior). The description adds no parameter-level meaning beyond 'these choices', so the baseline 3 for a fully documented schema is correct.

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

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

The description names a concrete function: it computes the credit cost of a video built from the given choices and reports whether the team's balance covers it. That is a specific verb+resource, not a restatement of the name. It does not, however, name or contrast itself with the obvious sibling make_video, so the agent must infer the quote-vs-execute distinction.

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 single word 'Free' strongly implies this is a zero-cost preview to run before make_video, which is usable implied guidance. But there is no explicit when-to-use, no 'use this before X', and no exclusion statement, so the routing to make_video or get_balance 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 the safety profile (destructiveHint=false, idempotentHint=true, openWorldHint=true), so the bar is lower, and the description adds genuinely new context: the call is 'Free, and counted against the team's product reads,' i.e. it is metered against a quota. That quota note also explains the otherwise puzzling readOnlyHint=false for a 'read' tool, since the call decrements team state. It omits rate limits and failure behavior, so not 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?

Front-loaded with the verb and resource, then the returned fields, then cost/quota in a short trailing fragment. Every clause carries information, though the middle enumeration is a dense run-on list that could be trimmed slightly.

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

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

With no output schema, the description usefully enumerates the returned fields (name, price, description, benefits, photos, angles, id) and discloses the metered cost, which is what an agent needs before calling. A one-parameter read tool with these details is adequately covered, though error/pagination behavior 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?

There is a single parameter with 100% schema description coverage ('The product's link'), so the schema already carries the semantics. The description's 'from its link' adds no syntax, format, or example beyond what the schema states, which is the expected baseline when the schema does the heavy lifting.

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

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

The description names a specific verb and resource ('Read a product's page from its link') and then enumerates the payload (name, price, description, benefits, photos, video angles, id), so the agent knows exactly what it gets back. It also positions the tool as an entry point by noting the returned id feeds 'the other tools.' It stops short of naming any sibling to differentiate from, but no sibling is a product reader, so confusion risk is low.

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 only implied: the phrase 'an id to use in the other tools' suggests this is the prerequisite step before make_video/write_scripts, but the description never states when to call this versus alternatives or any exclusion. It gives enough for an agent to infer the entry-point role but no explicit routing guidance.

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

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

Annotations already declare mutation (readOnlyHint=false), idempotence, and non-destructiveness, so the bar is lower. The description adds non-obvious context — that the operation is 'Free' and that it answers a value make_video requires — which structured fields don't convey.

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?

It is a single sentence but heavily nested and grammatically tangled, so the purpose is not cleanly front-loaded. The 'Free' note is useful but tacked on awkwardly.

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 two-parameter, fully-schema-documented, annotated tool with no output schema, the description covers purpose, trigger, cost, and consumer. Only the confusing phrasing slightly undercuts usability.

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% with an enum for voice, so the schema does the heavy lifting. The description adds only the hint that voice is a human choice not inferable from the presenter's picture, which is marginal 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?

States a specific verb (say/change) and resource (a described presenter's voice), and ties it to the describe_presenter/list_presenters family. Distinguishes it from make_video by naming the dependency, though the awkward grammar ('the voice ... speaks in, which make_video asks for') slows parsing.

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: use it before an Arabic video when a presenter has no assigned voice, with make_video named as the consumer. No explicit 'when not to use' or alternative tool, which keeps it below 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 only mark it as a non-read-only open-world write. The description adds real behavioral context beyond that: the operation is free but consumes a quota shown by get_balance as scripts_left, the scripts are authored by the provider's own writer and held to the product facts, and the call is asynchronous, returning an id immediately with a ~1-minute polling cadence against get_scripts. That is exactly the cost, provenance, and async-lifecycle information an agent needs.

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

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

Four sentences, front-loaded with the purpose, then provenance, cost, and the async follow-up in that order. Nothing is padded, though the second and third sentences could be tighter and the key polling instruction sits at the very end.

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 14-parameter, no-output-schema tool, the description covers the essential lifecycle: what it produces, that it is quota-metered, and that results must be fetched via get_scripts rather than returned inline. It does not describe what the returned scripts contain, but that gap is largely covered by the schema's lines rules and the get_scripts sibling.

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 every one of the 14 parameters is already documented in the schema, including the mutually exclusive constraints on ad/angle/lines/script_id. The description adds only the loose note that scripts derive from the read_product read; it adds little parameter meaning beyond the schema, 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: write three scripts for a UGC video of a product. It also positions itself relative to siblings, naming read_product as the fact source and get_scripts as the status poller, so an agent can separate it from the read and fetch tools 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?

"to read before making one" gives clear sequencing guidance (run this before make_video), and the follow-up instruction to poll get_scripts about once a minute until ready or failed is explicit. It stops short of naming when to prefer alternatives such as change_video or another_language, so it is clear context without exclusions.

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