Creatify Ad Agent

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 real value by enumerating what the call surfaces (credits, watermark state, tool prices), which matters because there is no output schema. It stops short of noting snapshot freshness, units, or auth expectations.

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

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

A single front-loaded sentence with no filler; the three returned items are listed compactly and every clause carries information.

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

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

With no output schema and no parameters, the description has to carry the return-value burden, and it names three concrete payload fields. It is nearly complete for a trivial read tool, missing only format/units of the credit figure and whether values are workspace-scoped or per-user.

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?

Zero parameters, so there is nothing to disambiguate; the baseline for a no-arg tool applies. Schema description coverage is 100% and no additional parameter meaning is possible.

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 ('Returns') and an exact resource set: remaining credits, watermark status for free plans, and per-tool pricing. Nothing in the sibling list (file/image/exec/project tools) overlaps, so an agent can identify it immediately 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?

No explicit when-to-use or when-not-to-use statement and no named alternatives. Usage is only implied by the content itself — an agent can infer it is the budget/quota check to run before paid generation calls. Adequate but leaves 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, destructiveHint=true and openWorldHint=false, so the mutation risk is covered structurally. The description adds a genuinely useful behavioral rule (old_string must match exactly once unless replace_all is set), but says nothing about failure behavior, whether the file must already exist, or whitespace/encoding handling.

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

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

Two short sentences, zero filler, and the core replacement behavior plus its key constraint are both front-loaded. Nothing can be removed without losing 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?

For a destructive edit tool with full schema coverage and annotations carrying the safety profile, the description supplies the one gotcha an agent most needs (single-occurrence matching). It is nearly complete, with only error/edge-case behavior left implicit.

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

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

Schema description coverage is 100% and every parameter, including replace_all and the uniqueness constraint on old_string, is already documented in the schema. The description repeats that constraint rather than adding new semantics such as format, encoding, or size limits.

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

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

States a specific verb and resource ('Replaces exact text in a project file'), which distinguishes it from a whole-file operation. It does not name the nearest siblings (composer_write_file, composer_read_file) to route the agent explicitly, so it falls 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 guidance on when to choose this over composer_write_file or how it relates to composer_read_file, which the schema itself references. The uniqueness rule is an operational constraint, not a when-to-use instruction, so the agent must infer the 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 already declare mutation (readOnlyHint=false) and openWorldHint=true. The description adds valuable context—async execution, returns task_id and credit cost, and the model used—but doesn't cover rate limits or how to retrieve the result.

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

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

Two tight sentences, front-loaded with the core action and model, then the return behavior. No wasted text.

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 burden of describing returns, which it partially does (task_id and credit cost). However, it omits how the async task is completed/polled, which is essential for an agent to use the result.

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 six parameters including the seed idempotency note and aspect default are documented in the schema. The description adds nothing about parameters, so 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+resource (composes/edits keyframe image), names the model and resolution (GPT Image 2.5, 2K), and notes it's async. It doesn't differentiate from siblings like composer_generate_clip, but the purpose is unambiguous.

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 on when to use this vs composer_generate_clip or other image tools, and no explicit instruction to follow up with composer_task_status. The phrase 'as an async task' hints at polling but leaves it 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?

Goes well beyond the annotations by disclosing billing (0.1 credit/minute, 0.1 minimum per command), that the timeout is held as credits up front, that long runs flip to an async task_id after roughly 50 s, and that files written persist to the project. These are behavioral traits the destructiveHint/readOnlyHint annotations cannot 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?

Three tight sentences, front-loaded with the core action and sandbox constraints, with cost and return behavior following logically. Nothing is redundant and every clause carries information.

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

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

With no output schema, the description correctly explains the return contract ('output, or a task_id'), which is exactly what an agent needs. The only gap is that it doesn't point to composer_task_status for retrieving async results, a minor omission for a tool that can return early.

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: the ~50 s threshold explains when the async task_id path (and thus the timeout parameter's practical effect) kicks in, and the credit billing clarifies the cost of longer timeouts. Command and project_id get no extra explanation, hence not a 5.

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

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

States a specific verb and resource ('Runs a shell command in the project's network-isolated sandbox') and enumerates the in-sandbox tooling, which cleanly separates it from siblings like composer_edit_file, composer_write_file, and composer_read_file. An agent can identify the tool's scope without inspecting 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 establishes context (network-isolated sandbox, no network, files saved to the project) that implies when the tool is appropriate, but never states when to prefer it over composer_read_file/composer_write_file or how to follow up on a returned task_id. Usage is inferable rather than explicit.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so safety direction is partly covered. The description goes further by disclosing genuinely non-obvious behavior: execution is asynchronous, the call returns a task_id and a credit cost, and the completed task's result carries the CDN URL. What it omits — failure handling, whether the credit is refunded on failure — is minor against that.

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 filler. It front-loads what the tool does, then immediately answers the two things an agent most needs to know afterwards (async task, credit cost) plus where the artifact ends up. Nothing could be cut without losing 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?

For a 14-param async generation tool with no output schema, the description compensates well by describing the return shape (task_id, credit cost, CDN URL on completion). It is not fully complete: it never names composer_task_status as the polling counterpart, which is the natural next step an agent must take.

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 93%, so the schema already documents mode, seed idempotency, resolution cost tiers, path formats and frame fields in detail. The description adds only the 5-15 s duration bound, which is already encoded in the schema's min/max, so it does not meaningfully exceed the schema here.

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?

Specific verb + resource: 'Generates one Boreal-H3 clip (5-15 s) into the project as an async task.' The named artifact (a video clip of a bounded duration) naturally separates it from siblings like composer_generate_music or composer_voice_line. It stops short of 5 because it never explicitly contrasts itself with those 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?

Usage is implied rather than stated: the async framing and 'task_id' return signal that this is a long-running generation step whose output must be polled. There is no explicit when-to-use/when-not, no mention of composer_task_status for following up, and no prerequisite guidance beyond project_id being a required param.

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 the safety profile (not read-only, open-world, non-destructive), so the description carries real weight here and does add value: it discloses async execution, the returned task_id, and a credit cost, none of which the annotations cover. It still omits failure behavior, polling expectations, and where the rendered file lands relative to 'out'.

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 filler, and the key facts (what it produces, the model, async, return shape) are front-loaded. Nothing is redundant with 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 5-parameter, credit-consuming async generation tool with no output schema, the description covers the return payload at a high level but leaves the async lifecycle unexplained – no pointer to composer_task_status, no note on failure/refund behavior, and no statement of where the artifact is written.

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% – prompt, out, seed, duration and project_id are all documented in-schema, including the seed dedupe window and Lyria's duration overshoot behavior. The description adds no parameter meaning whatsoever, 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 ('Generates a music track'), names the underlying model (Lyria 3 Pro), and flags the async execution mode. It does not explicitly distinguish itself from the closest siblings (composer_generate_clip, composer_voice_line), 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 when-to-use guidance at all: nothing says when to pick this over composer_generate_clip or composer_voice_line, and no prerequisites are stated beyond the schema's reference to composer_project_create. The async note implies a follow-up poll but never names composer_task_status.

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 cover the safety profile (openWorldHint=true, destructiveHint=false), and with no output schema the description usefully discloses that it returns a media probe and preview image plus writes into assets/. However it omits fetch failure modes, size/type limits, and whether existing assets are overwritten.

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

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

Two short sentences, front-loaded with the action and destination followed by the return value. No redundant or filler text.

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 return-value sentence compensates for the absent output schema, which is the right call. But for a write-ish, open-world network fetch, nothing is said about permissions, failure handling, or asset-naming collisions, leaving a gap an agent would want covered.

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 url, name, and project_id are already documented. The description adds no syntax, naming, or format detail 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 destination resource: 'Downloads a reference file into assets/'. An agent can distinguish it from upload_file and composer_generate_* siblings, though no sibling is named 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?

There is no statement of when to use this tool versus alternatives such as upload_file or composer_edit_image. The only contextual hint ('an upload_file cdn_url, a Drive export, a product image') lives in the schema parameter, not in the description.

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 destructiveHint=false, so safety is covered; the description restates that and adds the useful 'no generation or credits' cost context. It says nothing about pagination behavior (limit/offset exist) or result ordering, so the added behavioral value beyond annotations is modest.

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, zero filler, and the core capability is front-loaded before the handoff instruction. 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 paginated list tool with no output schema and six parameters, the description never addresses pagination, defaults, or the filters an agent would likely want. The handoff and cost notes are valuable, but key operational details are missing.

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

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

Schema description coverage is only 33% (search and language only), so the description must compensate, but it explains none of limit, offset, gender, or the source enum values. 'Library or this workspace's voices' loosely gestures at source and 'languages' at the language filter, but four of six parameters remain undocumented in both places.

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 ... voices') and delimits scope to 'eligible library or this workspace's voices', while naming the returned fields (provider voice_id, languages, previews). That is enough to separate it from all siblings, including composer_voice_line which it explicitly hands off to.

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 unambiguous workflow: 'Select a voice with the user; pass its voice_id to composer_voice_line, never a record UUID.' It names the downstream tool plus the exact value to supply and one explicit pitfall (don't pass a record UUID). Little 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 fix the safety profile (readOnly=false, destructive=false, openWorld=false), so the bar is lower. The description adds real context the annotations don't: the created artifact is a persistent working copy with a known file layout, and the call returns a project_id. It stops short of noting idempotency, error behavior, or permission 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?

One tight sentence with the scoping detail parenthesized, plus a short return-value clause. Front-loaded and free of filler, though the file-list parenthetical is the only mildly expendable element.

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 creation tool with 100% schema coverage and no output schema, the description covers what it makes and what it returns. Missing only peripheral information such as error conditions when a project already exists or required context/permissions.

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

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

Schema description coverage is 100% with all three parameters fully documented (duration tolerance, resolution, aspect ratio default), so the schema carries the semantics. The description adds nothing about parameters, which is the expected baseline 3.

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

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

States a specific verb+resource ('Creates an Ad Agent project') and elaborates on what that means concretely (assets/, gen/, index.html, stage.js). It also names the return value. It does not explicitly contrast itself with composer_project_get/list, but the create-vs-read distinction is self-evident.

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: 'kept across conversations' hints that this is for work that must persist, but there is no explicit when-to-use, when-not-to-use, or mention of the sibling project tools. An agent can infer intent but is given no 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 establish the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the description is not burdened with that. It does add useful behavioral context by naming the return payload, which matters since no output schema exists, but it says nothing about pagination, ordering, or what 'take count' means.

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

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

A single front-loaded sentence that states the resource first and the returned payload second, with 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 one-parameter read-only lookup with no output schema, the description covers the essential need by listing what comes back. Minor gaps remain around the meaning of 'take count' and result volume, but nothing blocking.

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 project_id parameter is already documented as originating from composer_project_create. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

The description uses a concrete verb-resource pair ('Returns a project's...') and enumerates the returned content (files, take count, recent tasks, running tasks), which distinguishes it from composer_project_list and composer_project_create. It stops short of explicitly contrasting with those siblings, and 'take count' is unexplained jargon.

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 statement of when to use this tool versus composer_project_list or composer_task_status, and no prerequisites mentioned. The agent must infer that this is the single-project detail fetch.

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 fully covered without the description. The description does add one genuinely useful behavioral fact beyond the annotations: results are sorted by most recent activity. It says nothing about the limit default, truncation, or pagination behavior, which keeps this at a 3.

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 sentence, zero waste, with the resource and the sort order front-loaded. Nothing to trim and nothing buried.

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

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

This is a simple read-only listing tool with an output schema present, so return-value documentation is unnecessary, and annotations cover safety. The description is complete enough to call correctly; the only minor gap is the absence of any hint about the default page size or what to do when more projects exist than are returned.

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

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

There is a single optional 'limit' parameter and schema description coverage is 100%, so the schema already documents it ('How many projects.'). The description adds no meaning about the parameter, such as what happens when the limit is exceeded or how ordering interacts with it. Baseline 3 is appropriate when the schema does the work.

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

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

The description gives a specific verb ('Lists') and resource ('this workspace's Ad Agent projects'), which clearly separates it from composer_project_get and composer_project_create. It also discloses the ordering ('most recently active first'). It stops short of naming a sibling or restating scope exclusions, so it is clear but not maximally differentiated.

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

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

There is no when-to-use or when-not-to-use guidance. The description never mentions composer_project_get for fetching a single project, nor any condition under which listing is preferred over another tool. Usage is only inferable from the verb.

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 genuine context beyond that: output is line-numbered and restricted to text files. It stays silent on truncation, what happens past EOF, or how missing/binary files are reported, so it adds only moderate value.

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

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

Two short sentences, front-loaded with the core behavior and immediately followed by the key constraint. Nothing is wasted and there is no filler.

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

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

For a simple read operation with no output schema and annotations covering the safety profile, the description says enough to call it: what is returned, its format, and the file-type restriction. Minor gaps remain around large-file truncation and error behavior, but nothing an agent needs to make the call is missing.

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

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

Schema description coverage is 100%, with path, limit, offset and project_id all self-documented, so the baseline is 3. The description adds no parameter-level detail beyond echoing that content is line-numbered, which loosely relates to offset/limit but does not enrich their 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 ('Returns a text file from the project') and gives concrete examples (index.html, stage.js), so the agent knows exactly what comes back. It also scopes the tool with 'Text files only', but it does not explicitly contrast with close siblings like composer_view or composer_exec, which also surface project content.

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 'Text files only' restriction tells the agent this is not for binary/asset paths, but no alternative is named and no condition (e.g. 'use composer_view for rendered output') is given. The agent must infer when to pick this over composer_view or composer_exec.

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, destructiveHint=false and openWorldHint=false, so the write-but-not-destructive profile is covered. The description adds genuinely useful behavioral context - the returned URL and the free-plan watermarking side effect - but says nothing about share visibility, URL expiry, or whether re-sharing the same path is idempotent.

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 with no filler; the primary outcome (upload and URL return) is front-loaded and the plan caveat follows as a secondary warning.

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, non-destructive share tool with no output schema, stating the return value (URL) and the watermark caveat is enough to call it correctly. Minor gaps remain around URL lifetime/visibility, but nothing blocking.

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 parameters are documented in the schema itself (path is project-relative, project_id comes from composer_project_create). The description adds nothing beyond reinforcing that the file lives inside the project, which is the baseline expectation when the schema does the work.

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 (uploads), the resource (image, video or audio file from the project) and the result (returns its URL). It implicitly distinguishes itself from upload_file/upload_file_widget by scoping the source to files already in the project, but it never names those siblings 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: an agent can infer this is for turning an existing project asset into a shareable URL, since 'from the project' signals the file must already exist. There is no when-to-use vs. when-not guidance and no mention of the upload_file alternatives that look similar.

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 give the safety profile (readOnlyHint=false, openWorldHint=true, destructiveHint=false); the description adds genuinely useful behavior: it is async, costs 1 credit, the credit is refunded if the gate fails, and it names the result fields. It still omits how to retrieve the async result (presumably composer_task_status) and what the ship gate checks.

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 dense sentences with no filler; the action pipeline is front-loaded and the cost/refund and return-shape details follow immediately. Every clause carries information the agent needs.

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 result fields (video_url, take, library_url) and covers cost and async semantics. The remaining gap is that it does not say how or when to poll for the async task's completion, which an agent would need to actually finish the 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 description coverage is 100%, so project_id, duration and ship_failed_gate are already documented in the schema with defaults and provenance. The description mentions the gate and the take but adds no syntax or format detail beyond the structured fields, so the baseline of 3 applies.

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

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

The description names the concrete actions (renders index.html, runs the ship gate, uploads the take) and the async delivery model, which is a specific verb+resource statement. It is clearly distinct from read-oriented siblings like composer_view or composer_read_file, though it does not explicitly contrast itself with any sibling.

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 pipeline wording implies this is the final publish/ship step and it references the ship gate as a precondition, but there is no explicit when-to-use vs when-not statement or pointer to alternatives such as composer_exec or composer_share. Usage is inferable rather than stated.

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

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

Annotations already establish this is a safe, non-destructive, non-open-world read. The description adds genuinely useful behavior: the call blocks for up to `wait` seconds, and show_sheet=true attaches an image to the response. That blocking semantics is exactly the kind of trait an agent needs to plan around and is not derivable from 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?

Two compact sentences with no waste. The core action and its blocking behavior come first, and the finished-clip result details follow. Every clause carries information.

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

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

With no output schema, the description must carry the return contract, and it only partially does so: it names probe and a contact sheet path for finished clips but never describes the status field itself (e.g. pending/running/failed) or what an incomplete result looks like. Adequate for a simple poll, but an agent cannot fully anticipate the response shape.

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 all three parameters (wait as long-poll seconds, task_id format, show_sheet effect). The description largely restates wait and show_sheet rather than adding new semantics; baseline 3 is appropriate 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?

States a specific verb and resource: returns an Ad Agent task's status. The long-poll behavior and the finished-clip result contents (probe, sheet path) further pin down what the tool actually does. It does not explicitly name a sibling alternative, but no sibling provides task polling, so differentiation is not a real risk.

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

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

Usage is implied rather than stated: the description describes waiting for a task to finish, which suggests it is polled after a start tool, and the schema notes task_id comes 'from a start tool'. There is no explicit when-to-use/when-not guidance, no mention of retry or polling cadence, and no stated alternative.

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 it is a non-read-only, non-destructive, open-world operation, so the safety profile is covered. The description adds genuinely new behavioral context: it runs as an async task, produces word timings and script-difference output, and carries explicit cost (0.05 credit/min, 0.1 minimum) – pricing and async semantics that annotations cannot 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?

Two tightly packed sentences with no filler: the core operation and output are front-loaded, followed by the cost detail. Every clause carries information an agent needs.

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 tool with full schema coverage and no output schema, the description covers operation, output shape, async nature, and pricing. The one gap is not indicating how the async result is retrieved (e.g., via composer_task_status), but this is a minor omission rather than a blocking one.

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 five parameters are already documented in the schema. The description adds only indirect meaning (script diffs, word timings) and does not elaborate on parameter syntax or formats beyond the schema. 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?

States a specific verb (Transcribes) and resource (clip or track), names the engine (ElevenLabs Scribe), and specifies the deliverable (word timings plus script diffs). An agent can distinguish this from siblings like composer_voice_line or composer_generate_clip 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?

Usage is implied by the phrasing ("when one is given" for scripts), but it never states when to choose this over alternatives such as composer_voice_line, nor any prerequisite like providing a voiceover first. Adequate context, no explicit exclusions.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false, so safety is covered. The description still adds genuinely useful behavior: a video path yields the first frame rather than an error or a video, and the output is downscaled to max_edge. That is real context beyond the structured fields.

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

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

A single tight sentence with the core action front-loaded and the parenthetical edge case placed immediately after it. Nothing is wasted.

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

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

With no output schema, the description's claim that it 'returns an image' leaves the return encoding (inline image content vs. URL vs. file reference) unspecified, which matters for a binary-returning tool. It is otherwise adequate for a 3-parameter read 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%, so path, max_edge (default 1024, range 256-2048) and project_id are already documented in the schema. The description only re-references max_edge and the video-first-frame behavior, adding no format or syntax detail beyond the schema baseline.

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 ('Returns an image from the project') plus a non-obvious capability: extracting a video's first frame. An agent can distinguish it from text-reading siblings like composer_read_file and from mutation siblings like composer_edit_image, though it never names an alternative 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?

There is no when-to-use or when-not-to-use guidance, no prerequisites (e.g. that project_id must come from composer_project_create), and no mention of alternatives. Usage is only inferable from the verb.

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 annotations (which only mark it as non-read-only, non-destructive, open-world), the description discloses the concrete side effects: files written to the project path and their naming (out_1.wav, out_2.wav, ... or out), plus the returned task_id and credit cost. It doesn't quantify credit cost or describe failure/retry behavior, so it is strong but not exhaustive.

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 dense sentences that front-load the core action and the voice source, then the output-file convention, then the return values. No filler and nothing redundant with the schema.

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

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

With no output schema, the description correctly covers return values (task_id, credit cost) and file side effects, and it flags the dead describe parameter. It leaves the multi-line/out interaction lightly sketched and says nothing about task polling, which an agent would need to resolve via composer_task_status.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: the mutual exclusivity of voice_id and like, that voice_id is a provider id rather than a record UUID, and that the out path is mutated per line when multiple lines are supplied. That clarifies fields whose schema text alone leaves the interaction between them ambiguous.

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

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

States a specific verb and resource ("Speaks one or more lines") with the exact voice sources it accepts, which makes TTS distinct from siblings like composer_generate_music or composer_generate_clip. It does not explicitly name or contrast those siblings, so routing still requires the agent to infer from names.

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

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

Gives clear operating constraints: "use exactly one provider voice_id or authorized like samples", "No voice design", and that describe is rejected before charging. It routes to composer_list_voices for voice_id. It stops short of an explicit when-to-use-this-vs-alternative statement for the surrounding generation tools.

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, destructiveHint=true, and openWorldHint=false, so the overwrite hazard is partly covered for the agent. The description's 'or overwrites' corroborates the destructive hint and adds the useful qualifier that the target is a text file (versus binary assets handled by upload/import siblings). It says nothing about whether parent directories are created, encoding, size limits, or what is returned.

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

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

A single front-loaded sentence with no filler, and the destructive verb is introduced first. It is efficient, though arguably under-specified rather than truly concise.

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

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

For a three-required-parameter mutation tool with annotations but no output schema, the definition covers the basics and correctly signals text-file scope. It omits the create-versus-overwrite semantics that matter most, plus any note on path handling or return value, leaving meaningful gaps an agent must guess at.

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 67%, mid-range: path carries an example, project_id cross-references composer_project_create, and content is undescribed. The description adds nothing about any parameter, so the undocumented content field is left entirely to inference (presumably the file body). Baseline 3 is appropriate at this coverage level.

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 pair (creates or overwrites) and a specific resource (a text file in the project), which is enough to distinguish it from composer_read_file and composer_edit_file. It stops short of explicitly naming the sibling it differs from or clarifying the create-vs-overwrite 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?

No when-to-use guidance, no conditions, no alternative named. With composer_edit_file in the sibling list, an agent gets no signal about when to write a whole file versus edit one in place, which is the exact decision this tool forces.

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, non-destructive write; the description adds far more: the presigned vs inline mode mechanics, the returned field sets, the ~1.5 MB inline cap and transport size limit, and the critical warning that cdn_url is dead until the PUT completes. It also warns that fabricated base64 from chat-visible images will fail.

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 gating capability and the two modes clearly delimited. It is wordy and repeats the 'call upload_file_widget instead' fallback three times, and the closing note about mirroring ApiUploadView is implementation detail of little decision value.

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 steps in and documents the return payloads for both modes. For a multi-mode, side-effecting upload tool this covers everything an agent needs to invoke it correctly.

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

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

Schema coverage is 100%, so the schema already documents filename, content_type, and base64_content. The description nonetheless adds non-obvious semantics: base64_content's presence toggles the two execution modes, and content_type is signed into the presigned URL so the PUT must match it.

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

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

States a specific verb + resource ('Upload a file to the workspace CDN') and immediately scopes it to callers that can send HTTP requests. It sharply distinguishes itself from sibling upload_file_widget by naming the exact capability that selects each tool.

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

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

Explicit when-to-use and when-not: use this if you can run shell/HTTP, otherwise call upload_file_widget. It also gives mode-selection guidance keyed on base64_content and explains which path to pick by size and origin of the bytes.

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

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

Annotations already establish that this is a non-read-only, non-destructive operation. The description adds real behavioral context beyond them: it opens a UI panel, the upload is performed from the browser, and the resulting file URL is posted into the chat. It does not mention auth or size limits, but the added interaction detail is valuable.

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, front-loaded with the core purpose followed by mechanism and usage condition. Mostly efficient, though the final clause 'including files attached to the chat' is grammatically awkward and slightly obscures its meaning.

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 widget tool with no output schema, the description covers what happens (panel opens, browser-side upload, URL posted to chat) and when to use it. It is nearly complete, missing only an explicit pointer to the sibling 'upload_file' alternative.

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 and the schema is trivially complete, so there is nothing for the description to disambiguate. The 0-parameter baseline of 4 applies.

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

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

The description states a specific action and mechanism: it 'opens a panel where the user can pick a local file to upload to their workspace' and posts the URL into the chat. This clearly conveys a distinct interaction model, though it does not explicitly name or contrast with the sibling 'upload_file'.

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 concrete condition for use: 'For clients that cannot send HTTP requests.' This is a clear when-to-use signal that implicitly distinguishes it from an HTTP-based upload path, but it never names the alternative tool explicitly, so it falls short of full routing guidance.

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