Veltake Design

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, but the description adds the crucial asynchronous pattern ('Answers at once with the kit building; poll get_brand_kit') and the cost ('Free'), neither of which is in the annotations. It omits permissions and what happens to the source logo.

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

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

Three short sentences, front-loaded with the purpose and ending with the follow-up tool. 'Free.' is a useful standalone signal, though the phrase 'Answers at once with the kit building' is slightly awkward and could be tighter.

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 async job with no output schema, the description covers what is produced and how to retrieve it. It could say more about poll timing or when the kit is ready, but nothing essential for a correct invocation is missing.

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

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

Schema coverage is 100% and the schema already describes logo_id as coming from create_logo or list_logos, so the description's only added nuance is the 'finished' qualifier. With a single fully documented parameter, 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 ('Turn ... into a brand kit') and resource, and enumerates the concrete outputs (colour palette with roles, vector version, favicons, app icons, lockups). An agent can distinguish this from create_logo and get_brand_kit without opening any 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 gives the entry condition ('a finished logo') and explicitly routes the agent to get_brand_kit for polling, plus notes the call is free. It does not state any when-not-to-use condition or prerequisites for the source logo, so it stops 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.

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description goes beyond them by disclosing the concrete consequences: held coins are returned and partial work is discarded. It adds no auth or rate-limit context, but the effect disclosure is genuinely useful.

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 followed immediately by consequences. No filler or redundancy.

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

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

For a single-parameter destructive operation with no output schema, the description covers the essential outcomes (coins returned, work discarded) and is consistent with the annotations. Only a note on post-cancellation state or error cases 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 a single required breakdown_id, so the schema already carries the parameter semantics. The description restates the applicable state but adds no format, lookup, or identifier guidance beyond the schema.

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

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

States a specific verb (stop/cancel) and resource (breakdown) plus the applicable states (queued or running), which distinguishes it from start_breakdown and get_breakdown. Sibling differentiation is implicit rather than explicit, so it falls just 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?

The phrase 'queued or running' gives an implied precondition for use, but there is no explicit when-not guidance, no mention of alternatives (e.g. get_breakdown to inspect first), and no warning about calling it on already-completed breakdowns.

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 safety (readOnlyHint=false, destructiveHint=false), but the description adds the critical non-annotated behavior: the call SPENDS the user's coins, price-change protection, idempotency expectations, privacy ('logos stay private to the account'), and asynchronous polling. This is exactly the behavioral context an agent needs before invoking a paid mutation.

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

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

Roughly three dense sentences, front-loaded with purpose, then cost behavior, then next steps. No filler; every clause carries an actionable fact (cost, guard, privacy, polling, follow-on tool).

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

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

With no output schema, the description compensates well by telling the agent to poll get_logo for the image and mentioning the build_brand_kit follow-on. It does not explicitly state what create_logo itself returns (e.g. a logo id), but the workflow implies it and leaves little ambiguity.

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; the description goes further by tying expected_total and model to list_logo_models and mapping the brief components to parameters. It adds workflow linkage rather than raw field definitions, which is genuinely useful even if the schema already documents each field.

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 ('Design a logo from a brief') and enumerates the brief inputs (brand name, mark depiction, type, style, detail, colours), so an agent knows exactly what the tool produces. It is clearly distinguishable from siblings like get_logo (retrieval) and build_brand_kit (asset packaging).

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 routes the workflow: get coins from list_logo_models and pass them as expected_total, poll get_logo for the finished image, and use build_brand_kit for the asset pack. It also names a key precondition/guard ('if the price changed, nothing is spent').

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, and the description reinforces this with 'Free, changes nothing' — consistent, not contradictory. It goes further by enumerating what the call returns (clip length and frame size, per-model read costs, transcript add-on cost, and payer resolution), which is valuable since no output schema exists.

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 core action ('Measure a video clip and price...') before elaborating on outputs. The dense middle sentence listing return values is information-rich rather than padded, though it is long enough to test readability.

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

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

No output schema exists, so the description carries the return contract — length, frame size, per-model costs, transcript cost, payer/coin balance — and it does so thoroughly. Combined with the safety annotations, an agent has everything needed to call and interpret it.

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?

With a single parameter and 100% schema description coverage, the schema already documents video_url fully (https direct link, ≤300s). The description adds no format, size, or sourcing detail beyond that, 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 specific verbs (measure, price) on a specific resource (a video clip broken into a shot list), which is clearly distinct from the sibling start_breakdown, get_breakdown, and label_breakdown. An agent can tell immediately this is the non-committing pricing/estimation step.

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?

Ends with an explicit routing instruction, 'Use before start_breakdown,' placing it correctly in the workflow ahead of the actual breakdown. It gives clear context but names no when-not conditions or other alternatives (e.g. when to skip straight to start_breakdown).

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world. The description adds useful behavioral context beyond that: it enumerates the kit statuses (building, ready, failed), the palette structure with colour roles and readable text colour, preview images, and pack files. It does not discuss auth or failure behavior, but for a read-only tool this is a solid addition.

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

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

Front-loads the action and retrieval options, then lists the return payload and closes with a direct 'Pass logo_id or kit_id' instruction. One sentence plus a short imperative, 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?

Given a simple two-parameter read tool with rich annotations and no output schema, the description covers purpose, retrieval options, and return contents (status, palette, previews, files). Nothing material for correct invocation appears to be missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by noting that a team's kit is read by its id, which helps an agent choose between kit_id and logo_id. It does not add syntax or format details, so 4 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 and resource ('Read a brand kit') and immediately distinguishes the two retrieval keys (logo_id or kit_id). It also names the sibling list_brand_kits as the source of kit_id, so the agent can differentiate it from list/build tools 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?

Provides clear context: pass logo_id for the logo a kit was built from, or kit_id from list_brand_kits, with the added note that a team's kit is read by its id. It names the alternative source list_brand_kits and implies the choice condition, but does not explicitly state when not to use this tool or the trade-off between the two keys.

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

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

Annotations already cover read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description adds genuinely new context: the download is gated behind a membership benefit and accounts without one receive an explanatory response rather than a link.

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 with the core action front-loaded and the key requirement last. Slightly awkward phrasing ('Answer the download link') but no padding 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 two-parameter lookup with no output schema, the description covers the input keys, the id source, and the entitlement failure mode. It leaves minor gaps such as whether the returned link expires, but nothing essential to correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a real semantic point the schema omits: the tool accepts either logo_id or kit_id as an alternate key, even though the schema declares no required parameters.

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

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

States a specific verb and resource: retrieves the download link for a ready brand kit's zip file. It also names the two lookup keys and points at list_brand_kits as the id source, which separates it cleanly from get_brand_kit and list_brand_kits.

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?

Explains that the caller passes either logo_id or kit_id and where those ids come from, and the word 'ready' implies the kit must be finished. It does not explicitly say when to prefer this over get_brand_kit or what happens for a not-yet-ready kit, so it stops 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.

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

Annotations already cover readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds real behavior: the status lifecycle (queued, in_progress, succeeded, failed, canceled) and the fact that heavy payload parts only materialize once succeeded and are opt-in. It does not mention auth or rate limits, keeping it short of a 5.

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

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

Two dense sentences, front-loaded with purpose and result content before the paging caveat. The status enumeration is somewhat list-heavy but every clause carries selection-relevant 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 carries the return-value burden and does so by naming the returned sections and their state-dependent availability, plus paging behavior. Missing only operational context like auth or size limits.

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

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

Schema coverage is 100%, so the schema already documents limit, offset, include and breakdown_id in detail; baseline is 3. The description's 'Long parts are opt-in through include; the table pages with offset and limit' reinforces intent but adds no format or constraint detail beyond the schema.

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

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

States a specific verb and resource ('Read one breakdown') and enumerates exactly what it returns: status, shot table, overview, summary, statistics and structure. This cleanly distinguishes it from siblings like list_breakdowns (plural listing) and start_breakdown (creation).

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 'once succeeded' framing and the breakdown_id note pointing back to start_breakdown/list_breakdowns, but the description never says when to choose this over list_breakdowns or estimate_breakdown, nor any prerequisites. Adequate but with a clear gap.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds real value beyond that by disclosing what is returned at each stage: status, and the image URL and size only once finished. It does not cover failure/not-found behavior or polling cadence, keeping it short of a 5.

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

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

A single front-loaded sentence with no filler; the status list and the conditional return fields are expressed compactly. Every clause earns its place.

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

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

With no output schema, the description carries the burden of explaining returns, and it does so well (status plus image URL and size when finished). It is complete for a simple read tool, though it omits what an agent should expect for an unknown logo_id or how to handle a long-running in_progress state.

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

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

Schema coverage is 100% and the single parameter logo_id is already described in the schema ('from create_logo or list_logos'). The description adds no syntax, format, or constraint information beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb ('Read') and a precisely scoped resource ('one logo'), which cleanly separates it from the sibling list_logos and create_logo. It also enumerates the status values returned, so an agent knows exactly what operation it is invoking.

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 status enum (queued, in_progress, succeeded, failed) hints that this is a polling tool after create_logo, but the description never says when to call it versus list_logos or what to do if the logo is still in progress. The only routing hint ('from create_logo or list_logos') lives in the schema, not 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 only say readOnlyHint=false and openWorldHint=true; they say nothing about cost. The description adds the crucial trait that this SPENDS the user's coins and that expected_total acts as a price-change guard, plus the transcribe surcharge. That is exactly the behavioral context annotations cannot carry.

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, zero padding, cost warning front-loaded ahead of the pricing procedure. Every clause carries operational information an agent needs before invoking.

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?

Covers prerequisites, cost, and where to read the result (poll get_breakdown), which partly compensates for the absent output schema. It stops short of covering repeat invocation, what 'finished' means operationally, or error modes beyond the price-change case.

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 baseline is 3, but the description goes further by explaining where expected_total comes from and what happens if it mismatches, and by tying breakdown_id to a 'finished'/'no AI read yet' state. It does not add anything for funding, purpose, prompt_lang or label_model beyond the schema.

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

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

Specific verb+resource: 'Add the AI read of every shot to a finished free breakdown.' It also differentiates itself from siblings by naming estimate_breakdown, get_breakdown and list_breakdowns and describing the exact relation to each. An agent can place this tool precisely without opening another 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?

Explicit workflow: price first with estimate_breakdown on the breakdown's source_url from get_breakdown or list_breakdowns, pass that total as expected_total, then poll get_breakdown. The failure mode ('if the price changed, nothing is spent') is stated outright, so the guard condition is unambiguous.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds real context beyond them: results are ordered newest first, scoped to 'ready' kits, and each entry carries palette and logo previews. It omits pagination or result-count limits for a list operation.

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. Ordering and return contents are packed in without waste, which is exactly what a no-parameter list tool 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 present, the description compensates by naming what each item contains (palette, logo preview) and the ordering, so an agent knows what it will receive. Nothing essential for calling a zero-argument read tool 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?

There are zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly implies no filtering arguments are accepted.

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 ('List the account's ready brand kits') and adds scope ('ready') plus ordering ('newest first'). The list-vs-get distinction against get_brand_kit/build_brand_kit is implied by the verb, but 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?

The 'ready' qualifier implies this is the browse/inventory view versus get_brand_kit for a single kit, but the description never states when to choose this over siblings or what conditions exclude a kit from the list. 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 declare the safe read-only, idempotent, closed-world profile, so the description is free to add behavior beyond that: results are ordered newest-first and tables are deliberately omitted, meaning the payload is a lightweight summary. It doesn't mention pagination behaviour even though a limit param exists, which keeps it short of a 5.

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

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

One sentence, no filler, with the resource and ordering front-loaded before the payload caveat. 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?

For a simple, fully-annotated list tool with a fully documented single parameter and no output schema, the description covers resource, scope, ordering, and payload shape. A note on pagination or total counts would close the remaining gap.

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

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

Schema coverage is 100% and the single limit parameter (default 20, max 50) is fully documented in the schema, so the baseline is 3. The description adds no parameter-level detail beyond the schema.

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

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

States a specific verb+resource (list breakdowns), the scope (the account's), the ordering (newest first), and a distinguishing payload property (without their tables). That implicitly separates it from get_breakdown, 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?

Usage is only implied: 'without their tables' hints that get_breakdown is the alternative when table data is needed, but the description never states when to choose this tool or any exclusions. No explicit routing guidance is given.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds real substance: the payer dimension (personal coin balance vs team pool) and the renders_text reliability flag, both of which shape downstream decisions.

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 what is listed and followed by the practical meaning of the renders_text field. Dense but every clause carries information; no filler or restatement of the 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 no output schema, the description must carry the return-value burden, and it does: it explains coin cost, payer semantics with balances, and the renders_text marker. For a zero-parameter listing tool with no output schema, nothing essential is missing.

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

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

Zero parameters, so the baseline is 4. There is nothing for the description to clarify on inputs, and it does not waste space inventing parameter details.

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 (List) plus a precise resource (image models that can design a logo), and it enumerates the returned attributes (coin cost, payer, renders_text) so an agent knows this is a model catalog, not a list of created logos — distinguishing it from the sibling list_logos.

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

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

The description gives model-selection advice (prefer renders_text models for combination, wordmark, monogram, emblem marks) but never states when to call this tool versus alternatives such as list_logos or create_logo. Usage is only implied by the return content.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds ordering semantics ('newest first') and the shape of each returned record (id, brand name, status, image), which is real context beyond the annotations, though it says nothing about pagination behavior or volume.

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 dense sentence, front-loaded with the verb and resource, with the id/field detail and the downstream-consumer hint appended after the dash. 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?

With no output schema, the description carries the burden of describing return values and does so (id, brand name, status, image) in addition to ordering. Pagination is handled by the schema, so nothing an agent needs to call and consume this tool 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%, so limit and offset are already fully documented with defaults and caps. The description only implies ordering via 'newest first' and adds nothing about limit/offset semantics, so 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 (list) and resource (account's logos), plus ordering ('newest first') and the fields returned. The dash clause naming get_logo and build_brand_kit makes it easy to distinguish from siblings like list_logo_models and list_brand_kits.

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?

Explains the tool's role in a workflow by stating the returned ids are what get_logo and build_brand_kit consume, which tells an agent when this list is the right entry point. It gives no explicit when-not condition or exclusion against the other list_* siblings, so it stops 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.

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

Annotations only declare readOnlyHint=false, destructiveHint=false, openWorldHint=true. The description goes well beyond: it discloses that the paid path SPENDS the user's coins, that expected_total must match the estimate or nothing is spent, that the job runs in the background, and that idempotency prevents a double charge. This is exactly the behavioral context an agent needs.

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

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

Dense but front-loaded: purpose first, then cost mechanics, then background/polling. Every sentence carries meaning, though the coin/estimate/transcribe detail packs several clauses into one long sentence, slightly straining readability.

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

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

For an 11-parameter, no-output-schema start tool, the description covers the crucial unknowns: free vs paid, coin spending, price-guard behavior, background execution, and idempotency. No output schema is needed since get_breakdown is named as the retrieval path.

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 value beyond the schema by tying expected_total to estimate_breakdown's quote ("pass expected_total exactly as estimate_breakdown priced it") and by framing the label/transcribe cost interaction. Most other parameters remain schema-only, so it stays short of 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?

Opens with a specific verb and resource ("Start a shot breakdown of a video clip") and immediately distinguishes the free measured mode from the paid AI-read mode. It visibly separates itself from siblings estimate_breakdown (pricing), get_breakdown (polling), and label_breakdown (post-hoc labeling).

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 states when each mode applies (label:true vs false), directs the agent to estimate_breakdown for the price and to poll get_breakdown after starting, and explains the transcribe prerequisite (needs label). The alternatives and their selecting conditions are named, not inferred.

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