Creatify Ad Agent

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

Goes beyond the readOnly/openWorld annotations by naming what is rejected (status, budget, bids, campaign creation) and stating the return is the platform's raw JSON, which tells the agent to analyse the payload elsewhere. Doesn't mention rate limits or the per-platform pagination/merge behaviour that the schema carries.

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, front-loaded with the core action, then the reference pointer, then the write rejection. Nothing is repeated or padding.

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 9-parameter, open-world passthrough tool with no output schema, the description supplies the essential mental model: one request, raw platform JSON, writes are refused, consult the reference tool. Missing only rate-limit/error behaviour and the out/project_id persistence workflow, the latter being covered by the schema.

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

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

Schema coverage is 78% and the schema itself documents platform bases, GAQL for Google, body for POST-style reads, and cursor paging, so the description needs little more. It adds no parameter-level meaning of its own beyond implying platform-specific endpoint choice via the reference tool.

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 one read-only request against a connected ad account and returns the platform's JSON'), and explicitly names the sibling composer_ads_reference as the source of endpoints/fields, which separates this tool from documentation lookup.

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 routing rule to composer_ads_reference for endpoints and fields, plus a hard exclusion ('Writes ... are rejected'). It doesn't cover the account-discovery prerequisite (that lives only in the account_id schema) or comparisons against other siblings, but the when-to-use guidance is clear.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), and the description adds real context: the references were written for Creatify's own agent, so where they use `requests` or the google-ads library with a token from context.json, the same method/path/params (Google: the GAQL) go through composer_ads_read with the token omitted. It also discloses that write/launch/action requests are unsupported. Minor gap: no indication of reference size or how to enumerate topics.

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

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

The purpose and the pre-query instruction come first, followed by the token/method translation rule and the limitation. Dense but each sentence carries work; the middle sentence is long and slightly tangled, which keeps it below 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?

For a single-optional-parameter documentation-retrieval tool with annotations and no output schema, this covers purpose, preconditions (read SKILL.md first), how to apply what is returned, and what cannot be done. An agent has enough to call it correctly and know what to do with 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 coverage is 100% and the topic parameter is already documented with an example path and default. The description mentions 'a path from `topics`' and the SKILL.md default but adds no format or discovery 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 resource: returns Creatify's ad-platform API reference (endpoints, fields, enums, pitfalls). It also explicitly contrasts with the sibling composer_ads_read, which is the tool that performs the actual queries, so the two are distinguishable 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?

Gives explicit when-to-use ('read SKILL.md and the platform's read reference before the first query') and when-not-to-use ('Writes, launches and action requests are not available here yet'), plus named alternatives (offer advice to the user, or point to Creatify's Ad Agent). Nothing about routing to this tool vs. composer_ads_read 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 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true) the description discloses the async task model, credit consumption, and the fact that the CDN URL arrives only in the finished task's result. It does not say whether credits are spent on failure or how long tasks may take.

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 clauses: what it does first, then what it returns. No padding, no restated parameter list, and the async/return information is front-loaded where an agent will read it.

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 mutation tool with no output schema, the description supplies the essential missing piece, the return shape (task_id, credit cost, eventual CDN URL). It stops short of describing the follow-up polling step or partial-failure behavior, which would round it out.

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 nearly every parameter is already documented, and the mode-to-model mapping in the description largely duplicates the schema's own 'mode' description. It adds only the 5-15 s duration bound, 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 one clip (5-15 s) into the project as an async task'), names the models used per mode, and names the return artifacts. An agent can separate this from composer_generate_music or composer_voice_line without reading the schema.

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

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

The mode-to-model routing (Boreal H3 for r2v/t2v/i2v, Aurora 2.0 for a2v) gives clear usage context and the mention of the finished task implies the polling path. However, it never explicitly says when to prefer a sibling such as composer_generate_music or how to chain to 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 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, destructiveHint=false, and closed-world scope, so safety is covered. The description adds that results are scoped to the user's workspace and discloses the returned fields (platform, account_id, currency, timezone), which is useful beyond 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 sentences: the first states the resource and its contents, the second gives the downstream action. Nothing redundant, and the key information leads.

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 parameters, no output schema, and annotations covering the safety profile, the description supplies everything an agent needs: what is listed, what fields come back, and how to use them next.

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 schema is empty and fully described. The description still clarifies what each returned account entry carries, which is the only semantics that matter 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 (Lists) plus resource (ad accounts connected to the user's Creatify workspace), and it enumerates the supported platforms so the agent knows the scope. It is clearly distinct from read/reference siblings because it is the discovery/listing endpoint.

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

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

Explicitly tells the agent to feed an account's platform and account_id into composer_ads_read, which establishes the natural workflow. It does not state exclusions or contrast with composer_ads_reference, but no sibling competes for the same listing job.

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?

Annotations only declare write + openWorld + non-destructive; the description adds substantive behavior: per-line output file naming (out_1.wav, out_2.wav vs. out), a transcription-based verification pass, a failure mode that lists missed lines, and a returned task_id with credit cost. The one notable omission is that it doesn't tell the agent the call is asynchronous and should be polled via composer_task_status.

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

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

Four short sentences, each carrying distinct information, front-loaded with the core action and voice-source constraint. No filler or restatement of the tool name.

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 9 parameters, no output schema, and a task-based return, the description covers outputs, cost, and verification adequately, but it never states the async lifecycle (poll composer_task_status) or what the returned task_id is used for. That is the main gap an agent would hit at invocation time.

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: how the `out` path fans out into numbered files for multiple lines, and that 'describe' is unconditionally rejected. That is genuine clarification beyond the field descriptions.

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?

"Speaks one or more lines using exactly one provider voice_id or authorized like samples" gives a concrete verb (speak/render audio), resource (voice lines), and scope (one voice source per call). The clause 'No voice design' additionally excludes a neighboring capability, though no sibling tool is named by name (e.g. composer_generate_music or composer_generate_clip).

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 routes the agent to composer_list_voices for the voice_id and states the mutual exclusivity of voice_id vs. like, plus that 'describe' is rejected before charging. It does not say when to prefer this over composer_generate_clip or composer_generate_music, so the when-not guidance is incomplete rather than absent.

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.